Skip to content

Commit c1ab0e0

Browse files
evilebottnawievilebottnawi
authored
Merge branch 'master' into fix-support-webpack@5
2 parents 53d255a + 4498ed0 commit c1ab0e0

File tree

5 files changed

+225
-36
lines changed

5 files changed

+225
-36
lines changed

‎README.md

+214-34
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
<div align="center">
2-
<!-- replace with accurate logo e.g from https://worldvectorlogo.com/ -->
32
<img width="200" height="200" src="https://cdn.worldvectorlogo.com/logos/javascript.svg">
43
<a href="https://webpack.js.org/">
54
<img width="200" height="200" vspace="" hspace="25" src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon-square-big.svg">
@@ -8,10 +7,14 @@
87
</div>
98

109
[![npm][npm]][npm-url]
10+
[![node][node]][node-url]
1111
[![deps][deps]][deps-url]
1212
[![tests][tests]][tests-url]
1313
[![coverage][cover]][cover-url]
1414
[![chat][chat]][chat-url]
15+
[![size][size]][size-url]
16+
17+
# mini-css-extract-plugin
1518

1619
This plugin extracts CSS into separate files. It creates a CSS file per JS file which contains CSS. It supports On-Demand-Loading of CSS and SourceMaps.
1720

@@ -24,24 +27,132 @@ Compared to the extract-text-webpack-plugin:
2427
- Easier to use
2528
- Specific to CSS
2629

27-
<h2 align="center">Install</h2>
30+
## Getting Started
31+
32+
To begin, you'll need to install `mini-css-extract-plugin`:
2833

2934
```bash
3035
npm install --save-dev mini-css-extract-plugin
3136
```
3237

33-
<h2 align="center">Usage</h2>
38+
It's recommended to combine `mini-css-extract-plugin` with the [`css-loader`](https://github.com/webpack-contrib/css-loader)
39+
40+
Then add the loader and the plugin to your `webpack` config. For example:
41+
42+
**style.css**
43+
44+
```css
45+
body {
46+
background: green;
47+
}
48+
```
49+
50+
**component.js**
51+
52+
```js
53+
import './style.css';
54+
```
55+
56+
**webpack.config.js**
57+
58+
```js
59+
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
60+
61+
module.exports = {
62+
plugins: [new MiniCssExtractPlugin()],
63+
module: {
64+
rules: [
65+
{
66+
test: /\.css$/i,
67+
use: [MiniCssExtractPlugin.loader, 'css-loader'],
68+
},
69+
],
70+
},
71+
};
72+
```
3473

35-
### Configuration
74+
## Options
3675

37-
#### `publicPath`
76+
### `publicPath`
3877

3978
Type: `String|Function`
4079
Default: the `publicPath` in `webpackOptions.output`
4180

4281
Specifies a custom public path for the target file(s).
4382

44-
#### `esModule`
83+
#### `String`
84+
85+
**webpack.config.js**
86+
87+
```js
88+
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
89+
90+
module.exports = {
91+
plugins: [
92+
new MiniCssExtractPlugin({
93+
// Options similar to the same options in webpackOptions.output
94+
// both options are optional
95+
filename: '[name].css',
96+
chunkFilename: '[id].css',
97+
}),
98+
],
99+
module: {
100+
rules: [
101+
{
102+
test: /\.css$/,
103+
use: [
104+
{
105+
loader: MiniCssExtractPlugin.loader,
106+
options: {
107+
publicPath: '/public/path/to/',
108+
},
109+
},
110+
'css-loader',
111+
],
112+
},
113+
],
114+
},
115+
};
116+
```
117+
118+
#### `Function`
119+
120+
**webpack.config.js**
121+
122+
```js
123+
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
124+
125+
module.exports = {
126+
plugins: [
127+
new MiniCssExtractPlugin({
128+
// Options similar to the same options in webpackOptions.output
129+
// both options are optional
130+
filename: '[name].css',
131+
chunkFilename: '[id].css',
132+
}),
133+
],
134+
module: {
135+
rules: [
136+
{
137+
test: /\.css$/,
138+
use: [
139+
{
140+
loader: MiniCssExtractPlugin.loader,
141+
options: {
142+
publicPath: (resourcePath, context) => {
143+
return path.relative(path.dirname(resourcePath), context) + '/';
144+
},
145+
},
146+
},
147+
'css-loader',
148+
],
149+
},
150+
],
151+
},
152+
};
153+
```
154+
155+
### `esModule`
45156

46157
Type: `Boolean`
47158
Default: `false`
@@ -77,7 +188,9 @@ module.exports = {
77188
};
78189
```
79190

80-
#### Minimal example
191+
## Examples
192+
193+
### Minimal example
81194

82195
**webpack.config.js**
83196

@@ -116,12 +229,13 @@ module.exports = {
116229
};
117230
```
118231

119-
#### `publicPath` function example
232+
### The `publicPath` option as function
120233

121234
**webpack.config.js**
122235

123236
```js
124237
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
238+
125239
module.exports = {
126240
plugins: [
127241
new MiniCssExtractPlugin({
@@ -155,7 +269,7 @@ module.exports = {
155269
};
156270
```
157271

158-
#### Advanced configuration example
272+
### Advanced configuration example
159273

160274
This plugin should be used only on `production` builds without `style-loader` in the loaders chain, especially if you want to have HMR in `development`.
161275

@@ -199,16 +313,21 @@ module.exports = {
199313
};
200314
```
201315

202-
#### Hot Module Reloading (HMR)
316+
### Hot Module Reloading (HMR)
203317

204-
extract-mini-css-plugin supports hot reloading of actual css files in development. Some options are provided to enable HMR of both standard stylesheets and locally scoped CSS or CSS modules. Below is an example configuration of mini-css for HMR use with CSS modules.
318+
The `mini-css-extract-plugin` supports hot reloading of actual css files in development.
319+
Some options are provided to enable HMR of both standard stylesheets and locally scoped CSS or CSS modules.
320+
Below is an example configuration of mini-css for HMR use with CSS modules.
205321

206-
While we attempt to hmr css-modules. It is not easy to perform when code-splitting with custom chunk names. `reloadAll` is an option that should only be enabled if HMR isn't working correctly. The core challenge with css-modules is that when code-split, the chunk ids can and do end up different compared to the filename.
322+
While we attempt to hmr css-modules. It is not easy to perform when code-splitting with custom chunk names.
323+
`reloadAll` is an option that should only be enabled if HMR isn't working correctly.
324+
The core challenge with css-modules is that when code-split, the chunk ids can and do end up different compared to the filename.
207325

208326
**webpack.config.js**
209327

210328
```js
211329
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
330+
212331
module.exports = {
213332
plugins: [
214333
new MiniCssExtractPlugin({
@@ -242,14 +361,16 @@ module.exports = {
242361

243362
### Minimizing For Production
244363

245-
To minify the output, use a plugin like [optimize-css-assets-webpack-plugin](https://github.com/NMFR/optimize-css-assets-webpack-plugin). Setting `optimization.minimizer` overrides the defaults provided by webpack, so make sure to also specify a JS minimizer:
364+
To minify the output, use a plugin like [optimize-css-assets-webpack-plugin](https://github.com/NMFR/optimize-css-assets-webpack-plugin).
365+
Setting `optimization.minimizer` overrides the defaults provided by webpack, so make sure to also specify a JS minimizer:
246366

247367
**webpack.config.js**
248368

249369
```js
250370
const TerserJSPlugin = require('terser-webpack-plugin');
251371
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
252372
const OptimizeCSSAssetsPlugin = require('optimize-css-assets-webpack-plugin');
373+
253374
module.exports = {
254375
optimization: {
255376
minimizer: [new TerserJSPlugin({}), new OptimizeCSSAssetsPlugin({})],
@@ -271,25 +392,23 @@ module.exports = {
271392
};
272393
```
273394

274-
### Features
275-
276-
#### Using preloaded or inlined CSS
395+
### Using preloaded or inlined CSS
277396

278397
The runtime code detects already added CSS via `<link>` or `<style>` tag.
279398
This can be useful when injecting CSS on server-side for Server-Side-Rendering.
280399
The `href` of the `<link>` tag has to match the URL that will be used for loading the CSS chunk.
281400
The `data-href` attribute can be used for `<link>` and `<style>` too.
282401
When inlining CSS `data-href` must be used.
283402

284-
#### Extracting all CSS in a single file
403+
### Extracting all CSS in a single file
285404

286-
Similar to what [extract-text-webpack-plugin](https://github.com/webpack-contrib/extract-text-webpack-plugin) does, the CSS
287-
can be extracted in one CSS file using `optimization.splitChunks.cacheGroups`.
405+
Similar to what [extract-text-webpack-plugin](https://github.com/webpack-contrib/extract-text-webpack-plugin) does, the CSS can be extracted in one CSS file using `optimization.splitChunks.cacheGroups`.
288406

289407
**webpack.config.js**
290408

291409
```js
292410
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
411+
293412
module.exports = {
294413
optimization: {
295414
splitChunks: {
@@ -319,13 +438,13 @@ module.exports = {
319438
};
320439
```
321440

322-
#### Extracting CSS based on entry
441+
### Extracting CSS based on entry
323442

324-
You may also extract the CSS based on the webpack entry name. This is especially useful if you import routes dynamically
325-
but want to keep your CSS bundled according to entry. This also prevents the CSS duplication issue one had with the
326-
ExtractTextPlugin.
443+
You may also extract the CSS based on the webpack entry name.
444+
This is especially useful if you import routes dynamically but want to keep your CSS bundled according to entry.
445+
This also prevents the CSS duplication issue one had with the ExtractTextPlugin.
327446

328-
```javascript
447+
```js
329448
const path = require('path');
330449
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
331450

@@ -380,28 +499,83 @@ module.exports = {
380499
};
381500
```
382501

383-
#### Module Filename Option
502+
### Module Filename Option
384503

385504
With the `moduleFilename` option you can use chunk data to customize the filename. This is particularly useful when dealing with multiple entry points and wanting to get more control out of the filename for a given entry point/chunk. In the example below, we'll use `moduleFilename` to output the generated css into a different directory.
386505

387-
```javascript
388-
const miniCssExtractPlugin = new MiniCssExtractPlugin({
389-
moduleFilename: ({ name }) => `${name.replace('/js/', '/css/')}.css`,
390-
});
506+
**webpack.config.js**
507+
508+
```js
509+
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
510+
511+
module.exports = {
512+
plugins: [
513+
new MiniCssExtractPlugin({
514+
moduleFilename: ({ name }) => `${name.replace('/js/', '/css/')}.css`,
515+
}),
516+
],
517+
module: {
518+
rules: [
519+
{
520+
test: /\.css$/,
521+
use: [MiniCssExtractPlugin.loader, 'css-loader'],
522+
},
523+
],
524+
},
525+
};
391526
```
392527

393-
#### Long Term Caching
528+
### Long Term Caching
394529

395530
For long term caching use `filename: "[contenthash].css"`. Optionally add `[name]`.
396531

532+
**webpack.config.js**
533+
534+
```js
535+
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
536+
537+
module.exports = {
538+
plugins: [
539+
new MiniCssExtractPlugin({
540+
filename: '[name].[contenthash].css',
541+
chunkFilename: '[id].[contenthash].css',
542+
}),
543+
],
544+
module: {
545+
rules: [
546+
{
547+
test: /\.css$/,
548+
use: [MiniCssExtractPlugin.loader, 'css-loader'],
549+
},
550+
],
551+
},
552+
};
553+
```
554+
397555
### Remove Order Warnings
398556

399557
For projects where css ordering has been mitigated through consistent use of scoping or naming conventions, the css order warnings can be disabled by setting the ignoreOrder flag to true for the plugin.
400558

401-
```javascript
402-
new MiniCssExtractPlugin({
403-
ignoreOrder: true,
404-
}),
559+
**webpack.config.js**
560+
561+
```js
562+
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
563+
564+
module.exports = {
565+
plugins: [
566+
new MiniCssExtractPlugin({
567+
ignoreOrder: true,
568+
}),
569+
],
570+
module: {
571+
rules: [
572+
{
573+
test: /\.css$/i,
574+
use: [MiniCssExtractPlugin.loader, 'css-loader'],
575+
},
576+
],
577+
},
578+
};
405579
```
406580

407581
### Media Query Plugin
@@ -411,6 +585,12 @@ If you'd like to extract the media queries from the extracted CSS (so mobile use
411585
- [Media Query Plugin](https://github.com/SassNinja/media-query-plugin)
412586
- [Media Query Splitting Plugin](https://github.com/mike-diamond/media-query-splitting-plugin)
413587

588+
## Contributing
589+
590+
Please take a moment to read our contributing guidelines if you haven't yet done so.
591+
592+
[CONTRIBUTING](./.github/CONTRIBUTING.md)
593+
414594
## License
415595

416596
[MIT](./LICENSE)

‎test/cases/composes-async/expected/async-1.css

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.base {
2+
background: blue;
3+
}
4+

0 commit comments

Comments
 (0)