Налаштування CSS-препроцесорів для проекту сайту

Настройка CSS-препроцесорів для проекту сайту

Вибір препроцесора та його правильна настройка з першого дня — фундамент підтримуваної CSS-архітектури. Неправильна конфігурація приводить до дублювання імпортів, повільної збірки, конфліктів між інструментами. Ця робота виконується один раз та визначає зручність розробки на весь час життя проекту.

Вибір інструмента

Рекомендація: SCSS для класичних проектів, Tailwind для React/Vue, PostCSS як обов'язковий шар поверх будь-якого.

Настройка у Vite

# SCSS
npm install -D sass

# LESS
npm install -D less

# PostCSS та плагіни
npm install -D postcss autoprefixer postcss-preset-env cssnano postcss-import

// vite.config.ts — повна конфігурація
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@styles': path.resolve(__dirname, 'src/styles'),
    },
  },
  css: {
    preprocessorOptions: {
      scss: {
        // Автоматично інджектировать змінні та миксини
        additionalData: `
          @use "@styles/abstracts/variables" as v;
          @use "@styles/abstracts/mixins" as m;
          @use "sass:math";
          @use "sass:color";
          @use "sass:map";
        `,
        // Використовувати сучасний Dart Sass API
        api: 'modern-compiler',
        // Подавити застарілі попередження
        silenceDeprecations: ['legacy-js-api'],
      },
    },
    // CSS Modules
    modules: {
      localsConvention: 'camelCase',
      generateScopedName:
        process.env.NODE_ENV === 'production'
          ? '[hash:base64:8]'
          : '[name]__[local]__[hash:base64:4]',
    },
    // PostCSS застосовується до всього CSS після компіляції препроцесора
    postcss: './postcss.config.js',
    // Source maps у розробці
    devSourcemap: true,
  },
});

// postcss.config.js
const isProd = process.env.NODE_ENV === 'production';

module.exports = {
  plugins: [
    require('postcss-import'),
    require('postcss-nested'),
    require('postcss-custom-media'),
    require('autoprefixer'),
    require('postcss-preset-env')({
      stage: 2,
      features: {
        'nesting-rules': true,
        'custom-properties': false,
      },
    }),
    ...(isProd
      ? [require('cssnano')({ preset: ['default', { discardComments: { removeAll: true } }] })]
      : []),
  ],
};

Настройка у Webpack

// webpack.config.js
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.(sa|sc)ss$/,
        use: [
          isProd ? MiniCssExtractPlugin.loader : 'style-loader',
          {
            loader: 'css-loader',
            options: {
              modules: {
                localIdentName: isProd
                  ? '[hash:base64:8]'
                  : '[name]__[local]--[hash:base64:4]',
                auto: /\.module\.(sa|sc)ss$/,  // Тільки *.module.scss
              },
              importLoaders: 2,
              sourceMap: !isProd,
            },
          },
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                config: './postcss.config.js',
              },
            },
          },
          {
            loader: 'sass-loader',
            options: {
              implementation: require('sass'),
              sassOptions: { outputStyle: 'compressed' },
              additionalData: `@use "@/styles/abstracts" as *;`,
            },
          },
        ],
      },
    ],
  },
  plugins: [
    ...(isProd ? [new MiniCssExtractPlugin({
      filename: 'assets/[name].[contenthash:8].css',
      chunkFilename: 'assets/[id].[contenthash:8].css',
    })] : []),
  ],
};

Структура файлів препроцесора

src/styles/
  abstracts/
    _variables.scss
    _functions.scss
    _mixins.scss
    _placeholders.scss
    _index.scss         ← @forward все
  base/
    _reset.scss         ← modern-normalize або custom
    _typography.scss
    _root.scss          ← :root { --змінні }
  components/           ← стилі для кожного компонента
  layout/               ← header, footer, grid, sidebar
  themes/
    _light.scss
    _dark.scss
  vendors/              ← переопередження сторонніх бібліотек
    _swiper.scss
    _leaflet.scss
  main.scss             ← точка входу

Linting: Stylelint

npm install -D stylelint stylelint-config-standard-scss stylelint-order

// .stylelintrc.js
module.exports = {
  extends: [
    'stylelint-config-standard-scss',
  ],
  plugins: ['stylelint-order'],
  rules: {
    // Порядок властивостей
    'order/properties-order': [
      'content',
      'position', 'top', 'right', 'bottom', 'left', 'z-index',
      'display', 'flex', 'flex-direction', 'flex-wrap', 'gap',
      'align-items', 'justify-content',
      'grid', 'grid-template', 'grid-area',
      'width', 'min-width', 'max-width',
      'height', 'min-height', 'max-height',
      'margin', 'padding',
      'background', 'color', 'font', 'font-size', 'font-weight',
      'border', 'border-radius',
      'box-shadow', 'opacity', 'transform', 'transition', 'animation',
    ],
    // SCSS-специфічні
    'scss/at-rule-no-unknown': true,
    'scss/no-duplicate-mixins': true,
    'scss/no-global-function-names': true,
    // Заборона вкладеності глибше 3 рівнів
    'max-nesting-depth': 3,
    // Заборона !important крім винятків
    'declaration-no-important': [true, { severity: 'warning' }],
  },
};

// package.json scripts
{
  "scripts": {
    "lint:css": "stylelint \"src/**/*.{css,scss}\"",
    "lint:css:fix": "stylelint \"src/**/*.{css,scss}\" --fix"
  }
}

Browserslist

Autoprefixer та postcss-preset-env читають список цільових браузерів:

// .browserslistrc
[production]
> 0.5%
last 2 versions
Firefox ESR
not dead
not IE 11

[development]
last 1 chrome version
last 1 firefox version
last 1 safari version

Або в package.json:

{
  "browserslist": {
    "production": ["> 0.5%", "last 2 versions", "not dead"],
    "development": ["last 1 chrome version", "last 1 firefox version"]
  }
}

Терміни

Повна початкова настройка CSS-інфраструктури (препроцесор + PostCSS + CSS Modules + Stylelint + Browserslist): 4–8 годин. Настройка для існуючого проекту з міграцією: 1–2 дні. Ця робота окупається за перший же місяць розробки за рахунок одноманітності коду та виключення типових помилок.