docs/projects/nextjs-style-guide/canons/applied/postcss.md

title, description, keywords

title	description	keywords
PostCSS	Установка и настройка CSS-процессора в новом проекте.	postcss postcss.config.mjs postcss-custom-media postcss-nesting autoprefixer postcss-global-data csstools @custom-media @nest css-процессор

PostCSS

Установка и настройка CSS-процессора в новом проекте.

Зачем PostCSS

Подключаем ради двух вещей:

• Вложенность — &:hover, &::before, &._active и @media внутри селектора. Без процессора нативный CSS не покрывает всех нужных кейсов вложенности.
• @custom-media — единые breakpoints проекта (@media (--md)) вместо магических min-width. Определяются в одном месте, переиспользуются везде.

Autoprefixer и @csstools/postcss-global-data идут довеском под эти две задачи.

Требования

• Next.js 14+ (App Router).
• Node.js 18+.

CSS Modules поддерживаются Next.js из коробки — отдельной установки не требуют.

Установка

1. Установить PostCSS-плагины как devDependencies:

   npm install -D postcss-custom-media postcss-nesting autoprefixer @csstools/postcss-global-data
   

2. Создать postcss.config.mjs в корне проекта (см. «Конфиг»).

Конфиг

Файл postcss.config.mjs в корне проекта.

// postcss.config.mjs
export default {
  plugins: {
    '@csstools/postcss-global-data': {
      files: ['src/shared/styles/media.css'],
    },
    'postcss-custom-media': {},
    'postcss-nesting': {},
    autoprefixer: {},
  },
}

Разбор плагинов

Плагин	Назначение
@csstools/postcss-global-data	Подгружает определения @custom-media из src/shared/styles/media.css перед обработкой каждого CSS-модуля. Семантика — «глобальный файл определений, который не импортируется в исходники»
postcss-custom-media	Поддержка @custom-media --md (...) и использования @media (--md) {}. Определения берутся из файла, который подгрузил postcss-global-data
postcss-nesting	Нативная CSS-вложенность: &:hover, &::before, &._active
autoprefixer	Добавление вендорных префиксов по browserslist

Почему внешний файл с @custom-media, а не @import

@custom-media — глобальные определения, одинаковые для всего проекта. Держим их в src/shared/styles/media.css. @csstools/postcss-global-data подгружает этот файл перед каждым модулем, а postcss-custom-media заменяет @media (--md) на конкретные @media (min-width: ...) на этапе сборки. Сами определения в бандл не попадают.

Опция importFrom у postcss-custom-media удалена в v10+; её роль теперь выполняет @csstools/postcss-global-data.

Импортировать media.css в файлы компонентов не нужно и запрещено правилами (см. Использование стилей, раздел «Импорт стилей»).