sass-loader

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

Загружает файл Sass/SCSS и компилирует его в CSS.

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

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

npm install sass-loader sass webpack --save-dev

или

yarn add -D sass-loader sass webpack

или

pnpm add -D sass-loader sass webpack

[!ПРИМЕЧАНИЕ]
Чтобы включить обработку CSS в вашем проекте, вам нужно установить style-loader и css-loader с помощью npm i style-loader css-loader.

sass-loader требует от вас установки либо Dart Sass, либо Node Sass самостоятельно (более подробная информация приведена ниже) или Sass Embedded.

Это позволяет вам контролировать версии всех зависимостей и выбирать используемую реализацию Sass.

[!ПРИМЕЧАНИЕ]
Мы настоятельно рекомендуем использовать Sass Embedded или Dart Sass.

[!ПРЕДУПРЕЖДЕНИЕ]
Node Sass не работает с Yarn PnP и не поддерживает @use rule.

Присоедините sass-loader к css-loader и style-loader, чтобы сразу применить все стили к DOM, или к mini-css-extract-plugin, чтобы извлечь их в отдельный файл.

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

app.js

import "./style.scss";

style.scss

$body-color: red;

body {
  color: $body-color;
}

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          // Creates `style` nodes from JS strings
          "style-loader",
          // Translates CSS into CommonJS
          "css-loader",
          // Compiles Sass to CSS
          "sass-loader",
        ],
      },
    ],
  },
};

Наконец, запустите webpack с помощью вашего предпочтительного метода.

Опции `style` (новый API, по умолчанию с версии 16) и `outputStyle` (старый API) в режиме `production`

Для режима production, опции style (новый API, по умолчанию с версии 16) и outputStyle (старый API) устанавливаются по умолчанию в значение compressed, если не указано иное в sassOptions.

Разрешение `import` и `use` в at-правилах

Webpack предоставляет расширенный механизм для разрешения файлов.

sass-loader использует функцию пользовательского импортера Sass для передачи всех запросов в движок разрешения webpack, что позволяет импортировать модули Sass из node_modules.

@import "bootstrap";

Использование ~ устарело и должно быть удалено из вашего кода, но мы всё ещё поддерживаем его по историческим причинам. Почему вы можете его удалить? Загрузчик сначала попытается разрешить @import как относительный путь. Если его нельзя разрешить, тогда загрузчик попытается разрешить @import внутри node_modules.

Добавление модульных путей с ~ говорит webpack, что он должен искать в node_modules.

@import "~bootstrap";

Важно, чтобы путь был преобразован только с ~, так как ~/ разрешается до домашней директории. Webpack должен отличать bootstrap от ~bootstrap, поскольку файлы CSS и Sass не имеют специального синтаксиса для импорта относительных файлов. Запись @import "style.scss" эквивалентна @import "./style.scss";

Проблемы с `url(...)`

Поскольку реализации Sass не обеспечивают перезапись URL, все связанные ресурсы должны быть относительными к выводу.

Если вы передаёте сгенерированный CSS в css-loader, все URL должны быть относительными к файлу входа (например, main.scss).
Если вы просто генерируете CSS без передачи его в css-loader, он должен быть относительным к вашей корневой директории веб-сайта.

Вы можете быть удивлены этой первой проблемой, так как естественно ожидать, что относительные ссылки будут разрешены относительно файла .sass/.scss , в котором они указаны (как и в обычных файлах .css).

К счастью, есть два решения этой проблемы:

Добавьте недостающую перезапись URL с помощью resolve-url-loader. Разместите его перед sass-loader в цепочке загрузчиков.
Авторы библиотек обычно предоставляют переменную для изменения пути к ресурсам. Например, bootstrap-sass имеет $icon-font-path.

`implementation`

Тип:

type implementation = object | string;

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

Специальная опция implementation определяет, какую реализацию Sass использовать.

По умолчанию загрузчик определяет реализацию на основе ваших зависимостей. Просто добавьте нужную реализацию в свой package.json (пакет sass, sass-embedded, или node-sass ) и установите зависимости.

Пример, где загрузчик sass-loader использует реализацию sass (dart-sass):

package.json

{
  "devDependencies": {
    "sass-loader": "^7.2.0",
    "sass": "^1.22.10"
  }
}

Пример, где загрузчик sass-loader использует реализацию node-sass:

package.json

{
  "devDependencies": {
    "sass-loader": "^7.2.0",
    "node-sass": "^5.0.0"
  }
}

Пример, где загрузчик sass-loader использует реализацию sass-embedded:

package.json

{
  "devDependencies": {
    "sass-loader": "^7.2.0",
    "sass": "^1.22.10"
  },
  "optionalDependencies": {
    "sass-embedded": "^1.70.0"
  }
}

[!ПРИМЕЧАНИЕ]
Использование optionalDependencies означает, что sass-loader может откатиться к sass, при запуске на операционной системе, не поддерживаемой sass-embedded

Обратите внимание на порядок, в котором sass-loader будет определять реализацию:

sass-embedded
sass
node-sass

Вы можете указать конкретную реализацию, используя опцию implementation, которая принимает одно из вышеперечисленных значений.

`object`

Например, чтобы всегда использовать Dart Sass, вы передадите:

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: {
              // Prefer `dart-sass`, even if `sass-embedded` is available
              implementation: require("sass"),
            },
          },
        ],
      },
    ],
  },
};

`string`

Например, чтобы использовать Dart Sass, вы передадите:

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: {
              // Prefer `dart-sass`, even if `sass-embedded` is available
              implementation: require.resolve("sass"),
            },
          },
        ],
      },
    ],
  },
};

`sassOptions`

Тип:

type sassOptions =
  | import("sass").LegacyOptions<"async">
  | ((
      content: string | Buffer,
      loaderContext: LoaderContext,
      meta: any,
    ) => import("sass").LegacyOptions<"async">);

По умолчанию: значения по умолчанию для реализации Sass

Параметры для реализации Dart Sass или Node Sass.

[!ПРИМЕЧАНИЕ]
Опция charset установлена по умолчанию в true для dart-sass, мы настоятельно не рекомендуем устанавливать её в false, потому что webpack не поддерживает файлы, кроме utf-8.

[!ПРИМЕЧАНИЕ]
Опции, такие как data и file недоступны и будут проигнорированы.

ℹ Мы настоятельно не рекомендуем изменять опции sourceMap (новый API, по умолчанию с версии 16), outFile (старый API), sourceMapContents (старый API), sourceMapEmbed (старый API) и sourceMapRoot (старый API), так как sass-loader автоматически устанавливает их, когда опция sourceMap равна true.

[!ПРИМЕЧАНИЕ]
Доступ к контексту загрузчика (контекст загрузчика) внутри пользовательского импортера можно получить с помощью свойства this.webpackLoaderContext.

Существует небольшая разница между параметрами для sass (dart-sass) и node-sass.

Перед использованием ознакомьтесь с соответствующей документацией:

Документация Dart Sass для всех доступных sass параметров.
Документация Sass Embedded для всех доступных sass параметров.
Документация Node Sass для всех доступных node-sass параметров.

`object`

Используйте объект для настройки реализации Sass.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: {
              sassOptions: {
                style: `compressed`,
                loadPaths: ["absolute/path/a", "absolute/path/b"],
              },
            },
          },
        ],
      },
    ],
  },
};

`function`

Позволяет настроить реализацию Sass с различными параметрами на основе контекста загрузчика.

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: {
              sassOptions: (loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === "styles/foo.scss") {
                  return {
                    loadPaths: ["absolute/path/c", "absolute/path/d"],
                  };
                }

                return {
                  loadPaths: ["absolute/path/a", "absolute/path/b"],
                };
              },
            },
          },
        ],
      },
    ],
  },
};

`sourceMap`

Тип:

type sourceMap = boolean;

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

Включает/Отключает генерацию source map.

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

ℹ Если true, опции sourceMap (новый API, по умолчанию с версии 16), outFile (старый API), sourceMapContents (старый API), sourceMapEmbed (старый API) и sourceMapRoot (старый API) из sassOptions будут проигнорированы.

webpack.config.js

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

ℹ В некоторых редких случаях node-sass может генерировать неверные source map (это ошибка в node-sass).
Для решения этой проблемы вы можете попробовать обновить node-sass до последней версии или установить опцию outputStyle в значение compressed внутри sassOptions.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: {
              sourceMap: true,
              sassOptions: {
                outputStyle: "compressed",
              },
            },
          },
        ],
      },
    ],
  },
};

`additionalData`

Тип:

type additionalData =
  | string
  | ((content: string | Buffer, loaderContext: LoaderContext) => string);

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

Добавляет Sass/SCSS код перед самим файлом входа. В этом случае, sass-loader не переопределит опцию data, а просто добавит содержимое входа.

Это особенно полезно, когда некоторые переменные Sass зависят от среды:

`string`

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: {
              additionalData: "$env: " + process.env.NODE_ENV + ";",
            },
          },
        ],
      },
    ],
  },
};

`function`

Синхронный

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: {
              additionalData: (content, loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === "styles/foo.scss") {
                  return "$value: 100px;" + content;
                }

                return "$value: 200px;" + content;
              },
            },
          },
        ],
      },
    ],
  },
};

Асинхронный

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: {
              additionalData: async (content, loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === "styles/foo.scss") {
                  return "$value: 100px;" + content;
                }

                return "$value: 200px;" + content;
              },
            },
          },
        ],
      },
    ],
  },
};

`webpackImporter`

Тип:

type webpackImporter = boolean;

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

Включает/Отключает стандартный импортер webpack.

Это может улучшить производительность в некоторых случаях, но используйте с осторожностью, так как псевдонимы и @import at-правила, начинающиеся с ~, не будут работать. Вы можете передать свой собственный importer для решения этой проблемы (см. importer docs).

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: {
              webpackImporter: false,
            },
          },
        ],
      },
    ],
  },
};

`warnRuleAsWarning`

Тип:

type warnRuleAsWarning = boolean;

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

Обрабатывает правило @warn как предупреждение webpack.

style.scss

$known-prefixes: webkit, moz, ms, o;

@mixin prefix($property, $value, $prefixes) {
  @each $prefix in $prefixes {
    @if not index($known-prefixes, $prefix) {
      @warn "Unknown prefix #{$prefix}.";
    }

    -#{$prefix}-#{$property}: $value;
  }
  #{$property}: $value;
}

.tilt {
  // Oops, we typo'd "webkit" as "wekbit"!
  @include prefix(transform, rotate(15deg), wekbit ms);
}

Представленный код вызовет предупреждение webpack вместо записи в журнал.

Чтобы проигнорировать ненужные предупреждения, можно использовать опцию ignoreWarnings.

webpack.config.js

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

`api`

Тип:

type api = "legacy" | "modern" | "modern-compiler";

По умолчанию: "modern" для sass (dart-sass) и sass-embedded, или "legacy" для node-sass

Позволяет переключаться между API legacy и modern API. Дополнительную информацию можно найти здесь. Опция modern-compiler включает современный API с поддержкой общих ресурсов.

[!ПРИМЕЧАНИЕ]

Использование modern-compiler и sass-embedded вместе существенно повышает производительность и сокращает время сборки. Их использование настоятельно рекомендуется. Мы включим их по умолчанию в будущей основной версии.

[!ПРЕДУПРЕЖДЕНИЕ]

Опции Sass отличаются для API legacy и modern API. Обратитесь к документации для информации о миграции на современные опции.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: {
              api: "modern-compiler",
              sassOptions: {
                // Your sass options
              },
            },
          },
        ],
      },
    ],
  },
};

Как включить вывод `@debug`

По умолчанию, вывод сообщений @debug отключен. Добавьте следующее в webpack.config.js, чтобы включить их:

module.exports = {
  stats: {
    loggingDebug: ["sass-loader"],
  },
  // ...
};

Примеры

Извлечение CSS в отдельные файлы

Для сборок в продакшен рекомендуется извлекать CSS из вашего пакета, чтобы позже можно было использовать параллельную загрузку ресурсов CSS/JS.

Существует четыре рекомендуемых способа извлечения таблицы стилей из пакета:

1. mini-css-extract-plugin

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          // fallback to style-loader in development
          process.env.NODE_ENV !== "production"
            ? "style-loader"
            : MiniCssExtractPlugin.loader,
          "css-loader",
          "sass-loader",
        ],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // both options are optional
      filename: "[name].css",
      chunkFilename: "[id].css",
    }),
  ],
};

2. Модули ресурсов

webpack.config.js

module.exports = {
  entry: [__dirname + "/src/scss/app.scss"],
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: [],
      },
      {
        test: /\.scss$/,
        exclude: /node_modules/,
        type: "asset/resource",
        generator: {
          filename: "bundle.css",
        },
        use: ["sass-loader"],
      },
    ],
  },
};

3. extract-loader (проще, но специализируется на выводе css-loader)

4. file-loader (устаревший — следует использовать только в webpack v4)

webpack.config.js

module.exports = {
  entry: [__dirname + "/src/scss/app.scss"],
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: [],
      },
      {
        test: /\.scss$/,
        exclude: /node_modules/,
        use: [
          {
            loader: "file-loader",
            options: { outputPath: "css/", name: "[name].min.css" },
          },
          "sass-loader",
        ],
      },
    ],
  },
};

(источник: https://stackoverflow.com/a/60029923/2969615)

Карты исходных кодов

Включает/Отключает генерацию карт исходных кодов.

Чтобы включить карты исходных кодов CSS, необходимо передать опцию sourceMap в sass-loader и css-loader.

webpack.config.js

module.exports = {
  devtool: "source-map", // any "source-map"-like devtool is possible
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              sourceMap: true,
            },
          },
          {
            loader: "sass-loader",
            options: {
              sourceMap: true,
            },
          },
        ],
      },
    ],
  },
};

Если вы хотите редактировать исходные файлы Sass в Chrome, есть хорошая статья в блоге. Посмотрите test/sourceMap для рабочего примера.

Содействие

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

CONTRIBUTING

Лицензия

MIT

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

sass-loader

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

Опции style (новый API, по умолчанию с версии 16) и outputStyle (старый API) в режиме production

Разрешение import и use в at-правилах

Проблемы с url(...)

Опции

implementation

object

string

sassOptions

object

function

sourceMap

additionalData

string

function

Синхронный

Асинхронный

webpackImporter

warnRuleAsWarning

api

Как включить вывод @debug

Примеры

Извлечение CSS в отдельные файлы

1. mini-css-extract-plugin

2. Модули ресурсов

3. extract-loader (проще, но специализируется на выводе css-loader)

4. file-loader (устаревший — следует использовать только в webpack v4)

Карты исходных кодов

Содействие

Лицензия

Опции `style` (новый API, по умолчанию с версии 16) и `outputStyle` (старый API) в режиме `production`

Разрешение `import` и `use` в at-правилах

Проблемы с `url(...)`

`implementation`

`object`

`string`

`sassOptions`

`object`

`function`

`sourceMap`

`additionalData`

`string`

`function`

`webpackImporter`

`warnRuleAsWarning`

`api`

Как включить вывод `@debug`