postcss-loader

Отказ от ответственности: postcss-loader — это пакет сторонних разработчиков, поддерживаемый участниками сообщества. Возможно, он не имеет такой же поддержки, политики безопасности или лицензии, как webpack, и не поддерживается webpack.

Обсуждение Webpack:

Чат PostCSS:

Загрузчик для обработки CSS с PostCSS.

Начало работы

Вам необходим webpack v5 для использования последней версии. Для Webpack v4 необходимо установить postcss-loader v4.

Для начала необходимо установить postcss-loader и postcss:

npm install --save-dev postcss-loader postcss

или

yarn add -D postcss-loader postcss

или

pnpm add -D postcss-loader postcss

Затем добавьте плагин в вашу конфигурацию webpack. Например:

В следующей конфигурации используется плагин postcss-preset-env, который не устанавливается по умолчанию.

file.js

import css from "file.css";

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  [
                    "postcss-preset-env",
                    {
                      // Options
                    },
                  ],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};

Альтернативное использование с файлами конфигурации:

postcss.config.js

module.exports = {
  plugins: [
    [
      "postcss-preset-env",
      {
        // Options
      },
    ],
  ],
};

Загрузчик автоматически ищет файлы конфигурации.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader", "postcss-loader"],
      },
    ],
  },
};

И запустите webpack с помощью предпочитаемого вами метода.

`execute`

Тип:

type execute = boolean;

По умолчанию: undefined

Включить поддержку парсера PostCSS в CSS-in-JS. Если вы используете JS-стили, используйте парсер postcss-js, добавив параметр execute.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.style.js$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                parser: "postcss-js",
              },
              execute: true,
            },
          },
        ],
      },
    ],
  },
};

`postcssOptions`

См. файл https://github.com/webpack-contrib/postcss-loader/blob/master/src/config.d.ts.

Тип:

import type { Config as PostCSSConfig } from "postcss-load-config";
import type { LoaderContext } from "webpack";

type PostCSSLoaderContext = LoaderContext<PostCSSConfig>;

interface PostCSSLoaderAPI {
  mode: PostCSSLoaderContext["mode"];
  file: PostCSSLoaderContext["resourcePath"];
  webpackLoaderContext: PostCSSLoaderContext;
  env: PostCSSLoaderContext["mode"];
  options: PostCSSConfig;
}

export type PostCSSLoaderOptions =
  | PostCSSConfig
  | ((api: PostCSSLoaderAPI) => PostCSSConfig);

По умолчанию: undefined

Позволяет установить PostCSS options и плагины.

Поддерживаются все PostCSS параметры. Существует специальный параметр config для файлов конфигурации. Как он работает и как его можно настроить, описано ниже.

Мы рекомендуем не указывать from, to и map параметры, так как это может привести к неправильному пути в картах исходных данных. Если вам необходимы карты исходных данных, пожалуйста, используйте параметр sourcemap.

Для больших проектов для оптимизации производительности загрузчика лучше указать postcssOptions в конфигурации загрузчика и указать config: false. Это подход устраняет необходимость многократного поиска и загрузки внешних файлов конфигурации во время компиляции.

`object`

Настройка plugins:

webpack.config.js (рекомендуется)

const myOtherPostcssPlugin = require("postcss-my-plugin");

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            plugins: [
              "postcss-import",
              ["postcss-short", { prefix: "x" }],
              require.resolve("my-postcss-plugin"),
              myOtherPostcssPlugin({ myOption: true }),
              // Deprecated and will be removed in the next major release
              { "postcss-nested": { preserveEmpty: true } },
            ],
          },
        },
      },
    ],
  },
};

webpack.config.js (устарело, будет удалено в следующей основной версии)

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            plugins: {
              "postcss-import": {},
              "postcss-short": { prefix: "x" },
            },
          },
        },
      },
    ],
  },
};

Настройка syntax:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            // Can be `string`
            syntax: "sugarss",
            // Can be `object`
            syntax: require("sugarss"),
          },
        },
      },
    ],
  },
};

Настройка parser:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            // Can be `string`
            parser: "sugarss",
            // Can be `object`
            parser: require("sugarss"),
            // Can be `function`
            parser: require("sugarss").parse,
          },
        },
      },
    ],
  },
};

Настройка stringifier:

webpack.config.js

const Midas = require("midas");
const midas = new Midas();

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            // Can be `string`
            stringifier: "sugarss",
            // Can be `object`
            stringifier: require("sugarss"),
            // Can be `function`
            stringifier: midas.stringifier,
          },
        },
      },
    ],
  },
};

`function`

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(css|sss)$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: (loaderContext) => {
            if (/\.sss$/.test(loaderContext.resourcePath)) {
              return {
                parser: "sugarss",
                plugins: [
                  ["postcss-short", { prefix: "x" }],
                  "postcss-preset-env",
                ],
              };
            }

            return {
              plugins: [
                ["postcss-short", { prefix: "x" }],
                "postcss-preset-env",
              ],
            };
          },
        },
      },
    ],
  },
};

`config`

Тип:

type config = boolean | string;

По умолчанию: true

Позволяет задавать параметры с помощью файлов конфигурации. Параметры, указанные в файле конфигурации, объединяются с параметрами, переданными загрузчику, параметры загрузчика перезаписывают параметры из конфигурации.

Файлы конфигурации

Загрузчик будет искать конфигурацию в следующих местах, поднимаясь по дереву каталогов:

свойство postcss в package.json
файл .postcssrc в формате JSON или YAML
файл .postcssrc.json, .postcssrc.yaml, .postcssrc.yml, .postcssrc.js, или .postcssrc.cjs
файл postcss.config.js или postcss.config.cjs CommonJS-модуль, экспортирующий объект (рекомендуется)

Примеры файлов конфигурации

Использование object нотации:

postcss.config.js (рекомендуется)

module.exports = {
  // You can specify any options from https://postcss.org/api/#processoptions here
  // parser: 'sugarss',
  plugins: [
    // Plugins for PostCSS
    ["postcss-short", { prefix: "x" }],
    "postcss-preset-env",
  ],
};

Использование function нотации:

postcss.config.js (рекомендуется)

module.exports = (api) => {
  // `api.file` - path to the file
  // `api.mode` - `mode` value of webpack, please read https://webpack.js.org/configuration/mode/
  // `api.webpackLoaderContext` - loader context for complex use cases
  // `api.env` - alias `api.mode` for compatibility with `postcss-cli`
  // `api.options` - the `postcssOptions` options

  if (/\.sss$/.test(api.file)) {
    return {
      // You can specify any options from https://postcss.org/api/#processoptions here
      parser: "sugarss",
      plugins: [
        // Plugins for PostCSS
        ["postcss-short", { prefix: "x" }],
        "postcss-preset-env",
      ],
    };
  }

  return {
    // You can specify any options from https://postcss.org/api/#processoptions here
    plugins: [
      // Plugins for PostCSS
      ["postcss-short", { prefix: "x" }],
      "postcss-preset-env",
    ],
  };
};

postcss.config.js (устарело, будет удалено в следующей основной версии)

module.exports = {
  // You can specify any options from https://postcss.org/api/#processoptions here
  // parser: 'sugarss',
  plugins: {
    // Plugins for PostCSS
    "postcss-short": { prefix: "x" },
    "postcss-preset-env": {},
  },
};

Каскад конфигураций

Вы можете использовать разные файлы конфигурации в разных каталогах. Поиск конфигурации начинается с path.dirname(file) и поднимается по дереву файлов до тех пор, пока не будет найден файл конфигурации.

|– components
| |– component
| | |– index.js
| | |– index.png
| | |– style.css (1)
| | |– postcss.config.js (1)
| |– component
| | |– index.js
| | |– image.png
| | |– style.css (2)
|
|– postcss.config.js (1 && 2 (recommended))
|– webpack.config.js
|
|– package.json

После настройки postcss.config.js, добавьте postcss-loader в свою конфигурацию webpack.config.js. Вы можете использовать его автономно или в сочетании с css-loader (рекомендуется).

Используйте его перед css-loader и style-loader, но после других препроцессорных загрузчиков, таких как, например, sass|less|stylus-loader, если вы используете какие-либо (так как загрузчики webpack оцениваются справа налево/снизу вверх).

webpack.config.js (рекомендуется)

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              importLoaders: 1,
            },
          },
          "postcss-loader",
        ],
      },
    ],
  },
};

`boolean`

Включает/выключает автоматическую загрузку конфигурации.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            config: false,
          },
        },
      },
    ],
  },
};

Строка

Позволяет указать путь к файлу конфигурации.

webpack.config.js

const path = require("path");

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            config: path.resolve(__dirname, "custom.config.js"),
          },
        },
      },
    ],
  },
};

`sourceMap`

Тип:

type sourceMap = boolean;

По умолчанию: зависит от значения compiler.devtool

По умолчанию, генерация карт исходных данных зависит от параметра devtool. Все значения, кроме eval и false значение, разрешают генерацию карт исходных данных.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader", options: { sourceMap: true } },
          { loader: "postcss-loader", options: { sourceMap: true } },
          { loader: "sass-loader", options: { sourceMap: true } },
        ],
      },
    ],
  },
};

Альтернативная настройка:

webpack.config.js

module.exports = {
  devtool: "source-map",
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
          { loader: "postcss-loader" },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};

`implementation`

Тип:

type implementation = object;

тип implementation должен быть таким же, как в postcss.d.ts

По умолчанию: postcss

Специальный параметр implementation определяет, какую реализацию PostCSS использовать. Перезаписывает локально установленную peerDependency версию postcss.

Этот параметр действительно полезен только для авторов инструментов нижнего уровня, чтобы облегчить переход с PostCSS 7 на 8.

`function`

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
          {
            loader: "postcss-loader",
            options: { implementation: require("postcss") },
          },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};

Строка

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
          {
            loader: "postcss-loader",
            options: { implementation: require.resolve("postcss") },
          },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};

Примеры

SugarSS

Вам необходимо установить sugarss:

npm install --save-dev sugarss

Использование синтаксиса SugarSS.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: { importLoaders: 1 },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                parser: "sugarss",
              },
            },
          },
        ],
      },
    ],
  },
};

Autoprefixer

Вам необходимо установить autoprefixer:

npm install --save-dev autoprefixer

Добавление префиксов браузеров к правилам CSS с помощью autoprefixer.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: { importLoaders: 1 },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  [
                    "autoprefixer",
                    {
                      // Options
                    },
                  ],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};

[!ВНИМАНИЕ]

postcss-preset-env включает autoprefixer, поэтому добавление его отдельно не требуется, если вы уже используете пресет. Более информации

PostCSS Preset Env

Вам необходимо установить postcss-preset-env:

npm install --save-dev postcss-preset-env

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: { importLoaders: 1 },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  [
                    "postcss-preset-env",
                    {
                      // Options
                    },
                  ],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};

CSS Modules

Что такое CSS Modules? Пожалуйста, прочтите.

На стороне postcss-loader дополнительных параметров не требуется. Чтобы они работали должным образом, добавьте параметр css-loader’s importLoaders.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              modules: true,
              importLoaders: 1,
            },
          },
          "postcss-loader",
        ],
      },
    ],
  },
};

CSS-в-JS и `postcss-js`

Вам необходимо установить postcss-js:

npm install --save-dev postcss-js

Если вы хотите обработать стили, написанные на JavaScript, используйте парсер postcss-js.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.style.js$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              importLoaders: 2,
            },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                parser: "postcss-js",
              },
              execute: true,
            },
          },
          "babel-loader",
        ],
      },
    ],
  },
};

В результате вы сможете писать стили следующим образом

import colors from "./styles/colors";

export default {
  ".menu": {
    color: colors.main,
    height: 25,
    "&_link": {
      color: "white",
    },
  },
};

[!ВНИМАНИЕ]

Если вы используете Babel, вам нужно сделать следующее, чтобы настройка работала

Добавьте babel-plugin-add-module-exports в свою конфигурацию.

У модуля стиля должен быть только один основной экспорт.

Извлечение CSS

Используя mini-css-extract-plugin.

webpack.config.js

const isProductionMode = process.env.NODE_ENV === "production";

const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  mode: isProductionMode ? "production" : "development",
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          isProductionMode ? MiniCssExtractPlugin.loader : "style-loader",
          "css-loader",
          "postcss-loader",
        ],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: isProductionMode ? "[name].[contenthash].css" : "[name].css",
    }),
  ],
};

Выдача ресурсов

Для записи ресурса из плагина PostCSS в webpack, необходимо добавить сообщение в result.messages.

Сообщение должно содержать следующие поля:

type = asset - Тип сообщения (обязательно, должно быть равно asset)
file - имя файла (обязательно)
content - содержимое файла (обязательно)
sourceMap - sourceMap
info - информация о ресурсе

webpack.config.js

const postcssCustomPlugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-custom-plugin",
    Once: (root, { result }) => {
      result.messages.push({
        type: "asset",
        file: "sprite.svg",
        content: "<svg>...</svg>",
      });
    },
  };
};

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [postcssCustomPlugin()],
              },
            },
          },
        ],
      },
    ],
  },
};

Добавление зависимостей, contextDependencies, buildDependencies, missingDependencies

Зависимости необходимы для того, чтобы webpack понимал, когда нужно выполнять перекомпиляцию измененных файлов.

Существует два способа добавить зависимости:

(Рекомендуется). Плагин может выводить сообщения в result.messages.

Сообщение должно содержать следующие поля:

type = dependency - Тип сообщения (обязательно, должно быть равно dependency, context-dependency, build-dependency или missing-dependency)
file - абсолютный путь к файлу (обязательно)

webpack.config.js

const path = require("path");

const postcssCustomPlugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-custom-plugin",
    Once: (root, { result }) => {
      result.messages.push({
        type: "dependency",
        file: path.resolve(__dirname, "path", "to", "file"),
      });
    },
  };
};

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [postcssCustomPlugin()],
              },
            },
          },
        ],
      },
    ],
  },
};

Или можно использовать готовый плагин postcss-add-dependencies.

Передайте loaderContext в плагин.

webpack.config.js

const path = require("path");

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                config: path.resolve(__dirname, "path/to/postcss.config.js"),
              },
            },
          },
        ],
      },
    ],
  },
};

postcss.config.js

module.exports = (api) => ({
  plugins: [
    require("path/to/postcssCustomPlugin.js")({
      loaderContext: api.webpackLoaderContext,
    }),
  ],
});

postcssCustomPlugin.js

const path = require("path");

const postcssCustomPlugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-custom-plugin",
    Once: (root, { result }) => {
      opts.loaderContext.addDependency(
        path.resolve(__dirname, "path", "to", "file"),
      );
    },
  };
};

postcssCustomPlugin.postcss = true;
module.exports = postcssCustomPlugin;

Вклад

Пожалуйста, ознакомьтесь с нашими рекомендациями по внесению вклада, если вы этого еще не сделали.

CONTRIBUTING

Лицензия

MIT

© JS Foundation and other contributors
Licensed under the Creative Commons Attribution License 4.0.
https://webpack.js.org/loaders/postcss-loader

postcss-loader

Начало работы

Параметры

execute

postcssOptions

object

function

config

Файлы конфигурации

Примеры файлов конфигурации

Каскад конфигураций

boolean

Строка

sourceMap

implementation

function

Строка

Примеры

SugarSS

Autoprefixer

PostCSS Preset Env

CSS Modules

CSS-в-JS и postcss-js

Извлечение CSS

Выдача ресурсов

Добавление зависимостей, contextDependencies, buildDependencies, missingDependencies

Вклад

Лицензия

`execute`

`postcssOptions`

`object`

`function`

`config`

`boolean`

`sourceMap`

`implementation`

`function`

CSS-в-JS и `postcss-js`