css-загрузчик

Интерпретатор css-loader обрабатывает @import и url() как import/require() и разрешит их.

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

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

npm install --save-dev css-loader

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

file.js

import css from 'file.css';

webpack.config.js

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

Хорошими загрузчиками для использования ваших ресурсов являются file-loader и url-loader, которые необходимо указать в вашей конфигурации (см. ниже).

И запустите webpack выбранным вами способом.

`toString`

Также можно использовать результаты css-loader непосредственно как строку, например, в стиле компонента Angular.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['to-string-loader', 'css-loader'],
      },
    ],
  },
};

или

const css = require('./test.css').toString();

console.log(css); // {String}

Если есть SourceMaps, они также будут включены в строку результата.

Если по какой-либо причине вам необходимо извлечь CSS как обычный строковый ресурс (т.е. не заключённый в модуль JS), вы можете ознакомиться с extract-loader. Он полезен, когда, например, вам нужно обработать CSS как строку.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          'handlebars-loader', // handlebars loader expects raw resource string
          'extract-loader',
          'css-loader',
        ],
      },
    ],
  },
};

Параметры

Имя	Тип	Значение по умолчанию	Описание
`url` `{Boolean\\|Function}`	`{Boolean\\|Function}`	`true`	Включает/отключает обработку функций `url` / `image-set`
`import` `{Boolean\\|Function}`	`{Boolean\\|Function}`	`true`	Включает/отключает обработку атрибутов `@import`
`modules` `{Boolean\\|String\\|Object}`	`{Boolean\\|String\\|Object}`	`false`	Включает/отключает CSS Modules и их конфигурацию
`sourceMap` `{Boolean}`	`{Boolean}`	`false`	Включает/отключает генерацию source map
`importLoaders` `{Number}`	`{Number}`	`0`	Включает/отключает или настраивает количество загрузчиков, применяемых перед CSS-загрузчиком
`localsConvention` `{String}`	`{String}`	`asIs`	Стиль экспортируемых имён классов
`onlyLocals` `{Boolean}`	`{Boolean}`	`false`	Экспортировать только локальные имена

`url`

Тип: Boolean|Function Значение по умолчанию: true

Включает/отключает обработку функций url/image-set. Управление разрешением url(). Абсолютные и относительные ссылки к корню не разрешаются.

Примеры разрешения:

url(image.png) => require('./image.png')
url('image.png') => require('./image.png')
url(./image.png) => require('./image.png')
url('./image.png') => require('./image.png')
url('http://dontwritehorriblecode.com/2112.png') => require('http://dontwritehorriblecode.com/2112.png')
image-set(url('image2x.png') 1x, url('image1x.png') 2x) => require('./image1x.png') and require('./image2x.png')

Для импорта ресурсов из пути node_modules (включая resolve.modules) и для alias, добавьте префикс ~:

url(~module/image.png) => require('module/image.png')
url('~module/image.png') => require('module/image.png')
url(~aliasDirectory/image.png) => require('otherDirectory/image.png')

`Boolean`

Включить/выключить разрешение url().

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          url: true,
        },
      },
    ],
  },
};

`Function`

Разрешить фильтрацию url(). Все отфильтрованные url() не будут разрешаться (останутся в коде как есть).

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          url: (url, resourcePath) => {
            // resourcePath - path to css file

            // Don't handle `img.png` urls
            if (url.includes('img.png')) {
              return false;
            }

            return true;
          },
        },
      },
    ],
  },
};

`import`

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

Включает/отключает обработку атрибутов @import. Управление разрешением @import. Абсолютные ссылки в @import будут перенесены в код во время выполнения.

Примеры разрешения:

@import 'style.css' => require('./style.css')
@import url(style.css) => require('./style.css')
@import url('style.css') => require('./style.css')
@import './style.css' => require('./style.css')
@import url(./style.css) => require('./style.css')
@import url('./style.css') => require('./style.css')
@import url('http://dontwritehorriblecode.com/style.css') => @import url('http://dontwritehorriblecode.com/style.css') in runtime

Для импорта стилей из пути node_modules (включая resolve.modules) и для alias, добавьте префикс ~:

@import url(~module/style.css) => require('module/style.css')
@import url('~module/style.css') => require('module/style.css')
@import url(~aliasDirectory/style.css) => require('otherDirectory/style.css')

`Boolean`

Включить/выключить разрешение @import.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          import: true,
        },
      },
    ],
  },
};

`Function`

Разрешить фильтрацию @import. Все отфильтрованные @import не будут разрешаться (останутся в коде как есть).

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          import: (parsedImport, resourcePath) => {
            // parsedImport.url - url of `@import`
            // parsedImport.media - media query of `@import`
            // resourcePath - path to css file

            // Don't handle `style.css` import
            if (parsedImport.url.includes('style.css')) {
              return false;
            }

            return true;
          },
        },
      },
    ],
  },
};

`modules`

Тип: Boolean|String|Object Значение по умолчанию: false

Включает/отключает CSS Modules и их конфигурацию.

Параметр modules включает/выключает спецификацию CSS Modules и настраивает базовое поведение.

Использование значения false повышает производительность, так как мы избегаем анализа функций CSS Modules. Это будет полезно для разработчиков, использующих обычный CSS или другие технологии.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: true,
        },
      },
    ],
  },
};

`Features`

`Scope`

Использование значения local требует указания :global классов. Использование значения global требует указания :local классов.

Дополнительную информацию можно найти здесь.

Стили могут быть локально ограничены, чтобы избежать глобального влияния.

Синтаксис :local(.className) может использоваться для объявления className в локальной области видимости. Локальные идентификаторы экспортируются модулем.

С :local (без скобок) локальный режим можно включить для этого селектора. Нотация :global(.className) может использоваться для объявления явного глобального селектора. С :global (без скобок) глобальный режим можно включить для этого селектора.

Загрузчик заменяет локальные селекторы уникальными идентификаторами. Выбранные уникальные идентификаторы экспортируются модулем.

:local(.className) {
  background: red;
}
:local .className {
  color: green;
}
:local(.className .subClass) {
  color: green;
}
:local .className .subClass :global(.global-class-name) {
  color: blue;
}

._23_aKvs-b8bW2Vg3fwHozO {
  background: red;
}
._23_aKvs-b8bW2Vg3fwHozO {
  color: green;
}
._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 {
  color: green;
}
._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 .global-class-name {
  color: blue;
}

ℹ️ Идентификаторы экспортируются

exports.locals = {
  className: '_23_aKvs-b8bW2Vg3fwHozO',
  subClass: '_13LGdX8RMStbBE9w-t0gZ1',
};

Рекомендуется использовать CamelCase для локальных селекторов. Они проще в использовании внутри импортированного JS-модуля.

Можно использовать :local(#someId), но это не рекомендуется. Используйте классы вместо идентификаторов.

`Composing`

При объявлении локального имени класса можно составить локальный класс из другого локального имени класса.

:local(.className) {
  background: red;
  color: yellow;
}

:local(.subClass) {
  composes: className;
  background: blue;
}

Это не приводит к каким-либо изменениям в самом CSS, но экспортирует несколько имён классов.

exports.locals = {
  className: '_23_aKvs-b8bW2Vg3fwHozO',
  subClass: '_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO',
};

._23_aKvs-b8bW2Vg3fwHozO {
  background: red;
  color: yellow;
}

._13LGdX8RMStbBE9w-t0gZ1 {
  background: blue;
}

`Importing`

Для импорта локального имени класса из другого модуля.

:local(.continueButton) {
  composes: button from 'library/button.css';
  background: red;
}

:local(.nameEdit) {
  composes: edit highlight from './edit.css';
  background: red;
}

Для импорта из нескольких модулей используйте несколько правил composes:.

:local(.className) {
  composes: edit hightlight from './edit.css';
  composes: button from 'module/button.css';
  composes: classFromThisModule;
  background: red;
}

`Values`

Можно использовать @value для задания значений, которые будут повторно использоваться по всему документу.

Рекомендуется использовать префикс v- для значений, s- для селекторов и m- для правил media.

@value v-primary: #BF4040;
@value s-black: black-selector;
@value m-large: (min-width: 960px);

.header {
  color: v-primary;
  padding: 0 10px;
}

.s-black {
  color: black;
}

@media m-large {
  .header {
    padding: 0 20px;
  }
}

`Boolean`

Включить функции CSS Modules.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: true,
        },
      },
    ],
  },
};

`String`

Включить функции CSS Modules и настроить mode.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          // Using `local` value has same effect like using `modules: true`
          modules: 'global',
        },
      },
    ],
  },
};

`Object`

Включить функции CSS Modules и настроить параметры.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            mode: 'local',
            localIdentName: '[path][name]__[local]--[hash:base64:5]',
            context: path.resolve(__dirname, 'src'),
            hashPrefix: 'my-custom-hash',
          },
        },
      },
    ],
  },
};

`mode`

Тип: String Значение по умолчанию: local

Настройка параметра mode . Можно опустить значение, если нужно использовать режим local.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            mode: 'global',
          },
        },
      },
    ],
  },
};

`localIdentName`

Тип: String Значение по умолчанию: [hash:base64]

Можно настроить сгенерированный идентификатор с помощью параметра запроса localIdentName . См. документацию loader-utils для получения дополнительной информации о параметрах.

Рекомендации:

использовать [path][name]__[local] для разработки
использовать [hash:base64] для производства

Заполнитель [local] содержит оригинальный класс.

Примечание: все зарезервированные (<>:"/\|?*) и управляющие символы файловой системы (исключая символы в заполнении [local] ) будут преобразованы в -.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            localIdentName: '[path][name]__[local]--[hash:base64:5]',
          },
        },
      },
    ],
  },
};

`context`

Тип: String Значение по умолчанию: undefined

Разрешить переопределение базового контекста загрузчика для локального имени идентификатора. По умолчанию используется rootContext загрузчика.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            context: path.resolve(__dirname, 'context'),
          },
        },
      },
    ],
  },
};

`hashPrefix`

Тип: String Значение по умолчанию: undefined

Разрешить добавление настраиваемого хэша для генерации более уникальных классов.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            hashPrefix: 'hash',
          },
        },
      },
    ],
  },
};

`getLocalIdent`

Тип: Function Значение по умолчанию: undefined

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

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            getLocalIdent: (context, localIdentName, localName, options) => {
              return 'whatever_random_class_name';
            },
          },
        },
      },
    ],
  },
};

`localIdentRegExp`

Тип: String|RegExp Значение по умолчанию: undefined

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            localIdentRegExp: /page-(.*)\.css/i,
          },
        },
      },
    ],
  },
};

`sourceMap`

Тип: Boolean Значение по умолчанию: false

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

Для включения карт исходного кода установите опцию sourceMap.

По умолчанию они отключены, так как они увеличивают время выполнения и размер пакета (карты исходного кода JS не увеличивают размер пакета).

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          sourceMap: true,
        },
      },
    ],
  },
};

`importLoaders`

Тип: Number Значение по умолчанию: 0

Включает/выключает или настраивает количество загрузчиков, применяемых перед CSS-загрузчиком.

Опция importLoaders позволяет настроить количество загрузчиков перед css-loader, которые должны быть применены к ресурсам @import.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              importLoaders: 2,
              // 0 => no loaders (default);
              // 1 => postcss-loader;
              // 2 => postcss-loader, sass-loader
            },
          },
          'postcss-loader',
          'sass-loader',
        ],
      },
    ],
  },
};

Это может измениться в будущем, когда система модулей (например, webpack) будет поддерживать сопоставление загрузчиков по происхождению.

`localsConvention`

Тип: String Значение по умолчанию: undefined

Стиль экспортируемых имён классов.

По умолчанию, ключи экспортируемого JSON отражают имена классов (т.е. asIs значение).

Название	Тип	Описание
`'asIs'` `{String}`	`{String}`	Имена классов будут экспортированы как есть.
`'camelCase'` `{String}`	`{String}`	Имена классов будут преобразованы в верблюжьего случая, исходное имя класса не будет удалено из локалей.
`'camelCaseOnly'` `{String}`	`{String}`	Имена классов будут преобразованы в верблюжьего случая, исходное имя класса будет удалено из локалей.
`'dashes'` `{String}`	`{String}`	Только тире в именах классов будут преобразованы в верблюжьего случая.
`'dashesOnly'` `{String}`	`{String}`	Тире в именах классов будут преобразованы в верблюжьего случая, исходное имя класса будет удалено из локалей.

file.css

.class-name {
}

file.js

import { className } from 'file.css';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          localsConvention: 'camelCase',
        },
      },
    ],
  },
};

`onlyLocals`

Тип: Boolean Значение по умолчанию: false

Экспортировать только локальные переменные.

Полезно, когда вы используете модули CSS для предварительной рендеринга (например, SSR). Для предварительной рендеринга с mini-css-extract-plugin вы должны использовать эту опцию вместо style-loader!css-loader **в пакете предварительной рендеринга**. Он не встраивает CSS, а только экспортирует сопоставления идентификаторов.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          onlyLocals: true,
        },
      },
    ],
  },
};

Примеры

Ассеты

Следующие webpack.config.js могут загружать CSS-файлы, встраивать небольшие изображения PNG/JPG/GIF/SVG, а также шрифты в виде Data URL и копировать большие файлы в выходную директорию.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader'],
      },
      {
        test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
        loader: 'url-loader',
        options: {
          limit: 8192,
        },
      },
    ],
  },
};

Извлечь

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

Этого можно достичь, используя mini-css-extract-plugin для извлечения CSS при выполнении в режиме производства.
В качестве альтернативы, если вы ищете лучшую производительность в режиме разработки и вывода CSS, имитирующего производство. extract-css-chunks-webpack-plugin предлагает дружественный к горячей перезагрузке, расширенный вариант mini-css-extract-plugin. HMR реальные CSS-файлы в режиме разработки, работает как mini-css в режиме не разработки

CSS-модули и чистый CSS

Когда у вас есть чистый CSS (без CSS-модулей) и CSS-модули в проекте, вы можете использовать эту настройку:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        // For pure CSS (without CSS modules)
        test: /\.css$/i,
        exclude: /\.module\.css$/i,
        use: ['style-loader', 'css-loader'],
      },
      {
        // For CSS modules
        test: /\.module\.css$/i,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              modules: true,
            },
          },
        ],
      },
      {
        test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
        loader: 'url-loader',
        options: {
          limit: 8192,
        },
      },
    ],
  },
};

Содействие

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

CONTRIBUTING

Лицензия

MIT

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