feat: added insert option

Author: cap-Bernardito

README.md

@@ -80,6 +80,7 @@ module.exports = {
 |      **[`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}` |     `undefined`     | Inserts `<link>` at the given position                   |
 
 #### `filename`
 
@@ -109,6 +110,57 @@ Default: `false`
 Remove Order Warnings.
 See [examples](#remove-order-warnings) below for details.
 
+#### `insert`
+
+Type: `String|Function`
+Default: `undefined`
+
+By default, the `extract-css-chunks-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 instertion.
+For example this is the case when you asynchronously load styles for an application that runs inside of an iframe.
+In such cases `insert` can be configured to be a function or a custom selector.
+
+If you target an [iframe](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement) make sure that the parent document has sufficient access rights to reach into the frame document and append elements to it.
+
+##### `String`
+
+Allows to setup custom [query selector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector).
+A new `<link>` element will be inserted after the found item.
+
+**webpack.config.js**
+
+```js
+new MiniCssExtractPlugin({
+  insert: '#some-element',
+});
+```
+
+A new `<link>` element will be inserted after the element with id `some-element`.
+
+##### `Function`
+
+Allows to override default behavior and insert styles at any position.
+
+> ⚠ Do not forget that this code will run in the browser alongside your application. Since not all browsers support latest ECMA features like `let`, `const`, `arrow function expression` and etc we recommend you to use only ECMA 5 features and syntax.
+
+> > ⚠ The `insert` function is serialized to string and passed to the plugin. This means that it won't have access to the scope of the webpack configuration module.
+
+**webpack.config.js**
+
+```js
+new MiniCssExtractPlugin({
+  insert: function insert(linkTag) {
+    const reference = document.querySelector('#some-element');
+    if (reference) {
+      reference.parentNode.insertBefore(linkTag, reference);
+    }
+  },
+});
+```
+
+A new `<link>` element will be inserted before the element with id `some-element`.
+
 ### Loader Options
 
 |              Name               |         Type         |              Default               | Description                                                                       |

package-lock.json

@@ -69,6 +69,7 @@
     "file-loader": "^6.1.0",
     "husky": "^4.3.0",
     "jest": "^26.5.2",
+    "jsdom": "^16.4.0",
     "lint-staged": "^10.4.0",
     "memfs": "^3.0.2",
     "npm-run-all": "^4.1.5",

package.json

@@ -36,12 +36,27 @@ class MiniCssExtractPlugin {
       baseDataPath: 'options',
     });
 
+    const insert =
+      typeof options.insert !== 'undefined'
+        ? typeof options.insert === 'function'
+          ? Template.asString([options.insert, 'insert(linkTag);'])
+          : Template.asString([
+              `var target = document.querySelector("${options.insert}");`,
+              "if (!target) {throw new Error(\"Couldn't find a style target. This probably means that the value for the 'insert' parameter is invalid.\")}",
+              `target.parentNode.insertBefore(linkTag, target.nextSibling);`,
+            ])
+        : Template.asString([
+            'var head = document.getElementsByTagName("head")[0];',
+            'head.appendChild(linkTag);',
+          ]);
+
     this.options = Object.assign(
       {
         filename: DEFAULT_FILENAME,
         ignoreOrder: false,
       },
-      options
+      options,
+      { insert }
     );
 
     if (!this.options.chunkFilename) {
@@ -392,8 +407,7 @@ class MiniCssExtractPlugin {
                           '}',
                         ])
                       : '',
-                    'var head = document.getElementsByTagName("head")[0];',
-                    'head.appendChild(linkTag);',
+                    this.options.insert,
                   ]),
                   '}).then(function() {',
                   Template.indent(['installedCssChunks[chunkId] = 0;']),

src/index.js

@@ -24,6 +24,17 @@
     },
     "ignoreOrder": {
       "type": "boolean"
+    },
+    "insert": {
+      "description": "Inserts `<link>` at the given position (https://github.com/webpack-contrib/mini-css-extract-plugin#insert).",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "instanceof": "Function"
+        }
+      ]
     }
   }
 }

src/plugin-options.json

@@ -0,0 +1,55 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`insert option should work when insert option is function: DOM 1`] = `
+"<!DOCTYPE html><html><head>
+  <title>style-loader test</title>
+  <link rel=\\"stylesheet\\" type=\\"text/css\\" href=\\"simple.css\\"><style id=\\"existing-style\\">.existing { color: yellow }</style>
+<script charset=\\"utf-8\\" src=\\"simple.bundle.js\\"></script></head>
+<body>
+  <h1>Body</h1>
+  <div class=\\"target\\"></div>
+  <iframe class=\\"iframeTarget\\"></iframe>
+
+
+</body></html>"
+`;
+
+exports[`insert option should work when insert option is function: errors 1`] = `Array []`;
+
+exports[`insert option should work when insert option is function: warnings 1`] = `Array []`;
+
+exports[`insert option should work when insert option is string: DOM 1`] = `
+"<!DOCTYPE html><html><head>
+  <title>style-loader test</title>
+  <style id=\\"existing-style\\">.existing { color: yellow }</style><link rel=\\"stylesheet\\" type=\\"text/css\\" href=\\"simple.css\\">
+<script charset=\\"utf-8\\" src=\\"simple.bundle.js\\"></script></head>
+<body>
+  <h1>Body</h1>
+  <div class=\\"target\\"></div>
+  <iframe class=\\"iframeTarget\\"></iframe>
+
+
+</body></html>"
+`;
+
+exports[`insert option should work when insert option is string: errors 1`] = `Array []`;
+
+exports[`insert option should work when insert option is string: warnings 1`] = `Array []`;
+
+exports[`insert option should work without insert option: DOM 1`] = `
+"<!DOCTYPE html><html><head>
+  <title>style-loader test</title>
+  <style id=\\"existing-style\\">.existing { color: yellow }</style>
+<link rel=\\"stylesheet\\" type=\\"text/css\\" href=\\"simple.css\\"><script charset=\\"utf-8\\" src=\\"simple.bundle.js\\"></script></head>
+<body>
+  <h1>Body</h1>
+  <div class=\\"target\\"></div>
+  <iframe class=\\"iframeTarget\\"></iframe>
+
+
+</body></html>"
+`;
+
+exports[`insert option should work without insert option: errors 1`] = `Array []`;
+
+exports[`insert option should work without insert option: warnings 1`] = `Array []`;

test/__snapshots__/insert-option.test.js.snap

@@ -22,3 +22,33 @@ exports[`validate options should throw an error on the "ignoreOrder" option with
 "Invalid options object. Mini CSS Extract Plugin has been initialized using an options object that does not match the API schema.
  - options.ignoreOrder should be a boolean."
 `;
+
+exports[`validate options should throw an error on the "insert" option with "{}" value 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 (https://github.com/webpack-contrib/mini-css-extract-plugin#insert).
+   Details:
+    * options.insert should be a string.
+    * options.insert should be an instance of function."
+`;
+
+exports[`validate options should throw an error on the "insert" option with "1" value 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 (https://github.com/webpack-contrib/mini-css-extract-plugin#insert).
+   Details:
+    * options.insert should be a string.
+    * options.insert should be an instance of function."
+`;
+
+exports[`validate options should throw an error on the "insert" option with "true" value 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 (https://github.com/webpack-contrib/mini-css-extract-plugin#insert).
+   Details:
+    * options.insert should be a string.
+    * options.insert should be an instance of function."
+`;

test/__snapshots__/validate-plugin-options.test.js.snap

@@ -0,0 +1,4 @@
+body {
+  background: red;
+}
+