diff --git a/README.md b/README.md index bf483fab..82b07b15 100644 --- a/README.md +++ b/README.md @@ -71,19 +71,21 @@ module.exports = { }; ``` +> ⚠️ Note that if you import CSS from your webpack entrypoint or import styles in the [initial](https://webpack.js.org/concepts/under-the-hood/#chunks) chunk, `mini-css-extract-plugin` will not load this CSS into the page. Please use [`html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin) for automatic generation `link` tags or create `index.html` file with `link` tag. + ## Options ### Plugin Options -| Name | Type | Default | Description | -| :---------------------------------------------------------------: | :------------------: | :-----------------------------------: | :---------------------------------------------------------------------------- | -| **[`filename`](#filename)** | `{String\|Function}` | `[name].css` | This option determines the name of each output CSS file | -| **[`chunkFilename`](#chunkFilename)** | `{String\|Function}` | `based on filename` | This option determines the name of non-entry chunk files | -| **[`ignoreOrder`](#ignoreOrder)** | `{Boolean}` | `false` | Remove Order Warnings | -| **[`insert`](#insert)** | `{String\|Function}` | `document.head.appendChild(linkTag);` | Inserts `` at the given position | -| **[`attributes`](#attributes)** | `{Object}` | `{}` | Adds custom attributes to tag | -| **[`linkType`](#linkType)** | `{String\|Boolean}` | `text/css` | Allows loading asynchronous chunks with a custom link type | -| **[`experimentalUseImportModule`](#experimentalUseImportModule)** | `{Boolean}` | `false` | Use an experimental webpack API to execute modules instead of child compilers | +| Name | Type | Default | Description | +| :---------------------------------------------------------------: | :------------------: | :-----------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------- | +| **[`filename`](#filename)** | `{String\|Function}` | `[name].css` | This option determines the name of each output CSS file | +| **[`chunkFilename`](#chunkFilename)** | `{String\|Function}` | `based on filename` | This option determines the name of non-entry chunk files | +| **[`ignoreOrder`](#ignoreOrder)** | `{Boolean}` | `false` | Remove Order Warnings | +| **[`insert`](#insert)** | `{String\|Function}` | `document.head.appendChild(linkTag);` | Inserts the `link` tag at the given position for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks | +| **[`attributes`](#attributes)** | `{Object}` | `{}` | Adds custom attributes to the `link` tag for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks | +| **[`linkType`](#linkType)** | `{String\|Boolean}` | `text/css` | Allows loading asynchronous chunks with a custom link type | +| **[`experimentalUseImportModule`](#experimentalUseImportModule)** | `{Boolean}` | `false` | Use an experimental webpack API to execute modules instead of child compilers | #### `filename` @@ -118,6 +120,8 @@ See [examples](#remove-order-warnings) below for details. Type: `String|Function` Default: `document.head.appendChild(linkTag);` +> ⚠️ Only for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) chunks. + By default, the `mini-css-extract-plugin` appends styles (`` elements) to `document.head` of the current `window`. However in some circumstances it might be necessary to have finer control over the append target or even delay `link` elements insertion. @@ -169,6 +173,8 @@ A new `` element will be inserted before the element with id `some-element Type: `Object` Default: `{}` +> ⚠️ Only for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) chunks. + If defined, the `mini-css-extract-plugin` will attach given attributes with their values on `` element. **webpack.config.js** diff --git a/src/plugin-options.json b/src/plugin-options.json index 7a4ce2c6..e4f61e0b 100644 --- a/src/plugin-options.json +++ b/src/plugin-options.json @@ -38,7 +38,7 @@ "link": "https://github.com/webpack-contrib/mini-css-extract-plugin#ignoreorder" }, "insert": { - "description": "Inserts `` at the given position.", + "description": "Inserts the `link` tag at the given position for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks.", "link": "https://github.com/webpack-contrib/mini-css-extract-plugin#insert", "anyOf": [ { @@ -50,7 +50,7 @@ ] }, "attributes": { - "description": "Adds custom attributes to tag.", + "description": "Adds custom attributes to the `link` tag for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks.", "link": "https://github.com/webpack-contrib/mini-css-extract-plugin#attributes", "type": "object" }, diff --git a/test/__snapshots__/validate-plugin-options.test.js.snap b/test/__snapshots__/validate-plugin-options.test.js.snap index 8894c2b7..185a3c40 100644 --- a/test/__snapshots__/validate-plugin-options.test.js.snap +++ b/test/__snapshots__/validate-plugin-options.test.js.snap @@ -4,7 +4,7 @@ exports[`validate options should throw an error on the "attributes" option with "Invalid options object. Mini CSS Extract Plugin has been initialized using an options object that does not match the API schema. - options.attributes should be an object: object { … } - -> Adds custom attributes to tag. + -> Adds custom attributes to the \`link\` tag for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks. -> Read more at https://github.com/webpack-contrib/mini-css-extract-plugin#attributes" `; @@ -41,7 +41,7 @@ exports[`validate options should throw an error on the "insert" option with "{}" "Invalid options object. Mini CSS Extract Plugin has been initialized using an options object that does not match the API schema. - options.insert should be one of these: string | function - -> Inserts \`\` at the given position. + -> Inserts the \`link\` tag at the given position for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks. -> Read more at https://github.com/webpack-contrib/mini-css-extract-plugin#insert Details: * options.insert should be a string. @@ -52,7 +52,7 @@ exports[`validate options should throw an error on the "insert" option with "1" "Invalid options object. Mini CSS Extract Plugin has been initialized using an options object that does not match the API schema. - options.insert should be one of these: string | function - -> Inserts \`\` at the given position. + -> Inserts the \`link\` tag at the given position for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks. -> Read more at https://github.com/webpack-contrib/mini-css-extract-plugin#insert Details: * options.insert should be a string. @@ -63,7 +63,7 @@ exports[`validate options should throw an error on the "insert" option with "tru "Invalid options object. Mini CSS Extract Plugin has been initialized using an options object that does not match the API schema. - options.insert should be one of these: string | function - -> Inserts \`\` at the given position. + -> Inserts the \`link\` tag at the given position for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks. -> Read more at https://github.com/webpack-contrib/mini-css-extract-plugin#insert Details: * options.insert should be a string.