Extract text from a bundle, or bundles, into a separate file.
npm install --save-dev extract-text-webpack-plugin # for webpack 2 npm install --save-dev [email protected] # for webpack 1 npm install --save-dev [email protected]
:warning: Since webpack v4 the
extract-text-webpack-plugin
should not be used for css. Use mini-css-extract-plugin instead.
:warning: For webpack v1, see the README in the webpack-1 branch.
const ExtractTextPlugin = require("extract-text-webpack-plugin"); module.exports = { module: { rules: [ { test: /\.css$/, use: ExtractTextPlugin.extract({ fallback: "style-loader", use: "css-loader" }) } ] }, plugins: [ new ExtractTextPlugin("styles.css"), ] }
It moves all the required *.css
modules in entry chunks into a separate CSS file. So your styles are no longer inlined into the JS bundle, but in a separate CSS file (styles.css
). If your total stylesheet volume is big, it will be faster because the CSS bundle is loaded in parallel to the JS bundle.
Advantages | Caveats |
---|---|
Fewer style tags (older IE has a limit) |
Additional HTTP request |
CSS SourceMap (with devtool: "source-map" and extract-text-webpack-plugin?sourceMap ) |
Longer compilation time |
CSS requested in parallel |
No runtime public path modification |
CSS cached separate |
No Hot Module Replacement |
Faster runtime (less code and DOM operations) |
... |
new ExtractTextPlugin(options: filename | object)
Name | Type | Description |
---|---|---|
id |
{String} |
Unique ident for this plugin instance. (For advanced usage only, by default automatically generated) |
filename |
{String|Function} |
Name of the result file. May contain [name] , [id] and [contenthash] |
allChunks |
{Boolean} |
Extract from all additional chunks too (by default it extracts only from the initial chunk(s)) When using CommonsChunkPlugin and there are extracted chunks (from ExtractTextPlugin.extract ) in the commons chunk, allChunks must be set to true |
disable |
{Boolean} |
Disables the plugin |
ignoreOrder |
{Boolean} |
Disables order check (useful for CSS Modules!), false by default |
[name]
name of the chunk[id]
number of the chunk[contenthash]
hash of the content of the extracted file[<hashType>:contenthash:<digestType>:<length>]
optionally you can configurehashType
s, e.g. sha1
, md5
, sha256
, sha512
digestType
s, e.g. hex
, base26
, base32
, base36
, base49
, base52
, base58
, base62
, base64
length
, the length of the hash in chars:warning:
ExtractTextPlugin
generates a file per entry, so you must use[name]
,[id]
or[contenthash]
when using multiple entries.
#extract
ExtractTextPlugin.extract(options: loader | object)
Creates an extracting loader from an existing loader. Supports loaders of type { loader: [name]-loader -> {String}, options: {} -> {Object} }
.
Name | Type | Description |
---|---|---|
options.use |
{String} /{Array} /{Object} |
Loader(s) that should be used for converting the resource to a CSS exporting module (required) |
options.fallback |
{String} /{Array} /{Object} |
loader(e.g 'style-loader' ) that should be used when the CSS is not extracted (i.e. in an additional chunk when allChunks: false ) |
options.publicPath |
{String} |
Override the publicPath setting for this loader |
There is also an extract
function on the instance. You should use this if you have more than one instance of ExtractTextPlugin
.
const ExtractTextPlugin = require('extract-text-webpack-plugin'); // Create multiple instances const extractCSS = new ExtractTextPlugin('stylesheets/[name]-one.css'); const extractLESS = new ExtractTextPlugin('stylesheets/[name]-two.css'); module.exports = { module: { rules: [ { test: /\.css$/, use: extractCSS.extract([ 'css-loader', 'postcss-loader' ]) }, { test: /\.less$/i, use: extractLESS.extract([ 'css-loader', 'less-loader' ]) }, ] }, plugins: [ extractCSS, extractLESS ] };
The configuration is the same, switch out sass-loader
for less-loader
when necessary.
const ExtractTextPlugin = require('extract-text-webpack-plugin'); module.exports = { module: { rules: [ { test: /\.scss$/, use: ExtractTextPlugin.extract({ fallback: 'style-loader', use: ['css-loader', 'sass-loader'] }) } ] }, plugins: [ new ExtractTextPlugin('style.css') //if you want to pass in options, you can do so: //new ExtractTextPlugin({ // filename: 'style.css' //}) ] }
url()
Resolving If you are finding that urls are not resolving properly when you run webpack. You can expand your loader functionality with options. The url: false
property allows your paths resolved without any changes.
const ExtractTextPlugin = require('extract-text-webpack-plugin'); module.exports = { module: { rules: [ { test: /\.scss$/, use: ExtractTextPlugin.extract({ fallback: 'style-loader', use: [ { loader: 'css-loader', options: { // If you are having trouble with urls not resolving add this setting. // See https://github.com/webpack-contrib/css-loader#url url: false, minimize: true, sourceMap: true } }, { loader: 'sass-loader', options: { sourceMap: true } } ] }) } ] } }
filename
parameter could be Function
. It passes getPath
to process the format like css/[name].css
and returns the real file name, css/js/a.css
. You can replace css/js
with css
then you will get the new path css/a.css
.
entry: { 'js/a': "./a" }, plugins: [ new ExtractTextPlugin({ filename: (getPath) => { return getPath('css/[name].css').replace('css/js', 'css'); }, allChunks: true }) ]
Juho Vepsäläinen |
Joshua Wiens |
Kees Kluskens |
Sean Larkin |
© JS Foundation and other contributors
Licensed under the Creative Commons Attribution License 4.0.
https://webpack.js.org/plugins/extract-text-webpack-plugin