sass-loader

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

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

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

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

sass-loader требует установки либо Node Sass, либо Dart Sass (дополнительная документация приведена ниже). Это позволит вам контролировать версии всех зависимостей и выбирать используемую реализацию Sass.

Присоедините 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 любым удобным способом.

Разрешение правил импорта `import`

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

sass-loader использует функцию пользовательского импортера Sass для передачи всех запросов к движку разрешения Webpack. Таким образом, вы можете импортировать модули Sass из node_modules. Просто добавьте префикс ~ перед ними, чтобы указать Webpack, что это не относительный импорт:

@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`

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

По умолчанию загрузчик определяет реализацию на основе зависимостей. Просто добавьте необходимую реализацию в package.json (пакет node-sass или 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": "^4.0.0"
  }
}

Будьте осторожны, если установлены node-sass и sass. По умолчанию sass-loader предпочитает node-sass. Чтобы избежать этой ситуации, используйте параметр implementation.

Параметр implementation принимает либо node-sass, либо sass (Dart Sass) в качестве модуля.

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

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

Обратите внимание, что при использовании sass (Dart Sass) синхронная компиляция по умолчанию в два раза быстрее, чем асинхронная, из-за накладных расходов асинхронных обратных вызовов. Чтобы избежать этих накладных расходов, вы можете использовать пакет fibers для вызова асинхронных импортеров из синхронного потока кода.

Мы автоматически встраиваем пакет fibers (настройка sassOptions.fiber) если это возможно (т.е. вам нужно установить пакет fibers).

package.json

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

Вы можете отключить автоматическое внедрение пакета fibers, передав значение false для параметра sassOptions.fiber.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              implementation: require('sass'),
              sassOptions: {
                fiber: false,
              },
            },
          },
        ],
      },
    ],
  },
};

Также вы можете передать значение fiber с помощью этого кода:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              implementation: require('sass'),
              sassOptions: {
                fiber: require('fibers'),
              },
            },
          },
        ],
      },
    ],
  },
};

`sassOptions`

Тип: Object|Function

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

ℹ️ Параметр indentedSyntax имеет значение true для расширения sass.

ℹ️ Параметры, такие как file и outFile недоступны.

ℹ️ Мы рекомендуем не использовать параметры sourceMapContents, sourceMapEmbed, sourceMapRoot, так как sass-loader автоматически устанавливает эти параметры.

Существует небольшое различие между параметрами node-sass и sass (Dart Sass). Пожалуйста, ознакомьтесь с документацией перед их использованием:

Документация Node Sass по всем доступным параметрам node-sass.
Документация Dart Sass по всем доступным параметрам 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: {
                indentWidth: 4,
                includePaths: ['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 {
                    includePaths: ['absolute/path/c', 'absolute/path/d'],
                  };
                }

                return {
                  includePaths: ['absolute/path/a', 'absolute/path/b'],
                };
              },
            },
          },
        ],
      },
    ],
  },
};

`prependData`

Тип: String|Function По умолчанию: undefined

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

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

ℹ️ Поскольку вы вставляете код, это нарушит сопоставления исходного кода в вашем файле входа. Часто есть более простое решение, например, несколько файлов входа Sass.

`String`

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

`Function`

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              prependData: (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;';
                }

                return '$value: 200px;';
              },
            },
          },
        ],
      },
    ],
  },
};

`sourceMap`

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

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

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

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 может выводить неверные карты исходного кода (это ошибка node-sass). Чтобы избежать этого, вы можете попробовать обновить node-sass до последней версии или установить параметр outputStyle в значение compressed.

`webpackImporter`

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

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

Это может улучшить производительность в некоторых случаях. Используйте с осторожностью, так как псевдонимы и правила @import начиная с ~ не будут работать. Вы можете передать собственный 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,
            },
          },
        ],
      },
    ],
  },
};

Примеры

Выделение CSS в отдельные файлы

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

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

mini-css-extract-plugin (используйте этот метод при использовании конфигурации webpack 4. Работает во всех случаях)
extract-loader (проще, но специализируется на выводе css-loader)

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',
    }),
  ],
};

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

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

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

webpack.config.js

module.exports = {
  devtool: 'source-map', // any "source-map"-like devtool is possible
  module: {
    rules: [
      {
        test: /\.scss$/,
        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://v4.webpack.js.org/loaders/sass-loader

sass-loader

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

Разрешение правил импорта import

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

Параметры

implementation

sassOptions

Object

Function

prependData

String

Function

sourceMap

webpackImporter

Примеры

Выделение CSS в отдельные файлы

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

Участие

Лицензия

Разрешение правил импорта `import`

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

`implementation`

`sassOptions`

`Object`

`Function`

`prependData`

`String`

`Function`

`sourceMap`

`webpackImporter`