README
css-loader
A loader for webpack which transforms CSS files into JS module.
The css-loader interprets @import and url() like import/require() and will resolve them.
Good loaders for requiring your assets are the file-loader and the url-loader which you should specify in your config (see below).
Requirements
This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.
Getting Started
To begin, you'll need to install css-loader:
$ npm install css-loader --save-dev
Then add the loader to your webpack config. For example:
file.js
import css from 'file.css';
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: ['style-loader', 'css-loader'],
},
],
},
};
And run webpack via your preferred method.
toString
You can also use the css-loader results directly as string, such as in Angular's component style.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: ['to-string-loader', 'css-loader'],
},
],
},
};
or
const css = require('./test.css').toString();
console.log(css); // {String}
If there are SourceMaps, they will also be included in the result string.
extract-loader
If, for one reason or another, you need to extract CSS as a plain string resource (i.e. not wrapped in a JS module) you might want to check out the extract-loader. It's useful when you, for instance, need to post process the CSS as a string.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [
'handlebars-loader', // handlebars loader expects raw resource string
'extract-loader',
'css-loader',
],
},
],
},
};
Options
url
Type: Boolean
Default: true
Enable/disable url() resolving.
// in your webpack.config.js
{
loader: `css-loader`,
options: {
url: false
}
}
To be compatible with existing css files some url resolved use this logic:
url(image.png) => require('./image.png')
url(~module/image.png) => require('module/image.png')
import
Type: Boolean
Default: true
Enable/disable @import resolving.
{
loader: 'css-loader',
options: {
import: false
}
}
sourceMap
Type: Boolean
Default: false
Enable/Disable source maps.
They are not enabled by default because they expose a runtime overhead and increase in bundle size (JS source maps do not). In addition to that relative paths are buggy and you need to use an absolute public path which include the server URL.
webpack.config.js
{
loader: 'css-loader',
options: {
sourceMap: true
}
}
importLoaders
Type: Number
Default: 0
Option importLoaders allows to configure how many loaders before css-loader should be applied to @imported resources.
webpack.config.js
{
test: /\.css$/,
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'
]
}
This may change in the future, when the module system (i. e. webpack) supports loader matching by origin.
Examples
Assets
The following webpack.config.js can load CSS files, embed small PNG/JPG/GIF/SVG images as well as fonts as Data URLs and copy larger files to the output directory.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: ['style-loader', 'css-loader'],
},
{
test: /\.(png|jpg|gif|svg|eot|ttf|woff|woff2)$/,
loader: 'url-loader',
options: {
limit: 10000,
},
},
],
},
};
Extract
For production builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on. This can be achieved by using the mini-css-extract-plugin to extract the CSS when running in production mode.
webpack.config.js
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
module.exports = {
plugins: [
new MiniCssExtractPlugin({
// Options similar to the same options in webpackOptions.output
// both options are optional
filename: '[name].css',
chunkFilename: '[id].css',
}),
],
module: {
rules: [
{
test: /\.css$/,
use: [
// fallback to style-loader in development
process.env.NODE_ENV !== 'production'
? 'style-loader'
: MiniCssExtractPlugin.loader,
'css-loader',
],
},
],
},
};
PostCSS
To begin, you'll need to install postcss-loader:
$ npm install postcss-loader --save-dev
Visit postcss-loader readme for more information.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: 'css-loader',
},
{
loader: 'postcss-loader',
},
],
},
],
},
};
CSS Modules
To begin, you'll need to install postcss-loader, postcss-icss-values, postcss-icss-selectors, postcss-icss-composes and postcss-icss-keyframes:
$ npm install postcss-loader postcss-icss-values postcss-icss-selectors postcss-icss-composes postcss-icss-keyframes --save-dev
New postcss plugins for css modules use the ICSS specification.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.modules.css$/,
use: [
{
loader: 'css-loader',
options: {
importLoaders: 1,
},
},
{
loader: 'postcss-loader',
options: {
plugins: (loader) => [
require('postcss-icss-values')(),
require('postcss-icss-selectors')({
mode: 'global', // Can be `local`
generateScopedName: require('generic-names')({
hashPrefix: '',
context: loader.rootContext,
})
}),
require('postcss-icss-composes')(),
require('postcss-icss-keyframes')({
generateScopedName: require('generic-names')({
hashPrefix: '',
context: loader.rootContext,
})
}),
],
},
},
],
},
],
},
};
Custom Export
Due to the ICSS specification, you can export any values from your styles.
Just add :export {} with exported values. You can use postcss-loader with own postcss plugin to automate these actions. [Writing a PostCSS Plugin](Writing a PostCSS Plugin).
Example:
style.css
:export {
color: black;
}
file.js
import styles from 'style.css'
console.log(styles.color); // Output `black`
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.