fix: better description for async chunk options

webpack-contrib · Sep 6, 2021 · 34b65ac · 34b65ac
1 parent 885e739
commit 34b65ac
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 15 deletions.
diff --git 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 `<link>` 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 (`<link>` 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 `<link>` 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 `<link>` element.
 
 **webpack.config.js**

diff --git 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 `<link>` 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
@@ -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 \`<link>\` 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 \`<link>\` 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 \`<link>\` 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.