magic-comments-loader 1.4.0 → 1.4.2

package/README.md

@@ -17,35 +17,47 @@ All magic comments are supported:
 * `webpackExclude`
 * `webpackExports`
 
-## Usage
+## Getting Started
 
-First `npm install magic-comments-loader`.
+First install `magic-comments-loader`:
 
-Try *not* to have dynamic `import()` statements behind [comments](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#comments). **It is better to remove unused code in production**.
-If you must, e.g. your comment is referencing usage of dynamic imports, then these styles are ok:
+```
+npm install magic-comments-loader
+```
+
+Next add the loader to your `webpack` config:
 
 ```js
-// import('some-ignored-module')
+module: {
+  rules: [
+    {
+      test: /\.js$/,
+      exclude: /node_modules/,
+      use: ['magic-comments-loader']
+    }
+  ]
+}
+```
 
-/* Some comment about a dynamic import('module') */
+Then given a **file.js** with the following import:
 
-/**
- * Some multiline comment, only use one import() per line.
- * Comment about import('module/one')
- * Comment about import('module/two')
- * import('module/three'), etc.
- */
+```js
+const dynamicModule = await import('./path/to/module.js')
 ```
 
-This module uses a RegExp not a parser. If you would like to add better support for ignoring `import()` behind multiline comments please open a pull request.
+While running `webpack` the import inside **file.js** becomes:
+
+```js
+const dynamicModule = await import(/* webpackChunkName: "path-to-module" */ './path/to/module.js')
+```
 
-### Configuration
+## Examples
 
-Add this inside your `webpack.config.js`.
+Below are some basic usage examples for some of the supported magic comments.
 
-#### Without options
+### webpackChunkName
 
-Adds `/* webpackChunkName: "path-to-module" */` to all dynamic imports (same as `webpackChunkName: true` when using options).
+Add `webpackChunkName` magic comments to **all** of your dynamic imports using the hyphenated path as the chunk name.
 
 ```js
 module: {
@@ -59,7 +71,74 @@ module: {
 }
 ```
 
-#### With options
+Or using the configuration options you can change the chunk name to the module's filename (instead of the full hyphenated path).
+
+```js
+module: {
+  rules: [
+    {
+      test: /\.js$/,
+      exclude: /node_modules/,
+      use: {
+        loader: 'magic-comments-loader',
+        options: {
+          webpackChunkName: {
+            config: {
+              basename: true
+            }
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+### webpackIgnore
+
+Have webpack ignore **all** dynamic imports and use the native `import()`, for instance if you wanted to opt out of code-splitting or use native ES Modules.
+
+```js
+module: {
+  rules: [
+    {
+      test: /\.js$/,
+      exclude: /node_modules/,
+      use: {
+        loader: 'magic-comments-loader',
+        options: {
+          webpackIgnore: true
+        }
+      }
+    }
+  ]
+}
+```
+
+Or only for modules in a specific directory.
+
+```js
+module: {
+  rules: [
+    {
+      test: /\.js$/,
+      exclude: /node_modules/,
+      use: {
+        loader: 'magic-comments-loader',
+        options: {
+          webpackIgnore: 'src/esm/**/*.js'
+        }
+      }
+    }
+  ]
+}
+```
+
+## Configuration
+
+The loader supports configuration with options and overrides for each magic comment.
+
+### With options
 
 The loader `options` is an object with keys corresponding to the names of supported magic comments. The following comments have a default behavior and do not require configuration beyond specifying where they should be applied (globally, or to certain files).
 
@@ -87,7 +166,7 @@ module: {
 }
 ```
 
-#### With `config` options
+### With `config` options
 
 For more control, all comments support a configuration object with two supported keys, `config` and `overrides`. The `config` key is an object used to specifiy [comment options](#options). The [`overrides`](#overrides) key is defined below.
 
@@ -130,7 +209,7 @@ module: {
 }
 ```
 
-#### Overrides
+### Overrides
 
 You can also override the configuration passed in the `config` key by using `overrides`. It is an array of objects that look like:
 
@@ -214,33 +293,6 @@ module: {
 }
 ```
 
-## Magic Comments
-
-With loader options configured like
-
-```js
-  {
-    loader: 'magic-comments-loader',
-    options: {
-      webpackChunkName: true,
-      webpackPrefetch: 'src/some/module.js',
-      webpackMode: 'eager'
-    }
-  }
-```
-
-an import statement inside `src/some/module.js` like
-
-```js
-const dynamicModule = await import('./path/to/module.js')
-```
-
-becomes
-
-```js
-const dynamicModule = await import(/* webpackChunkName: "path-to-module", webpackPrefetch: true, webpackMode: "eager" */ './path/to/module.js')
-```
-
 ## Options
 
 These are the options that can be configured under the loader `options`. When using comments with a [`config`](#with-config-options) key, you may also specify [`overrides`](#overrides).
@@ -267,7 +319,7 @@ These are the options that can be configured under the loader `options`. When us
   * `Function`: `(modulePath, importPath) => Boolean`. Returning `false` does not add the comment.
   * `config.active`: Boolean | `(modulePath, importPath) => Boolean`. Returning `false` does not add the comment.
 * `webpackIgnore`
-  * `true`: Adds `webpackIgnore` comments to **all** dynamic imports. **You don't want to do this**.
+  * `true`: Adds `webpackIgnore` comments to **all** dynamic imports.
   * `false`: Disables adding the `webpackIgnore` comment globally. This is the default.
   * `['/src/**/*.js']`: Adds the comment with a value of `true` when the glob(s) match a path from a `match` path.
   * `Function`: `(modulePath, importPath) => Boolean`. Returning `false` does not add the comment.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magic-comments-loader",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Add webpack magic comments to your dynamic imports during build time",
   "main": "index.js",
   "engines": {
@@ -42,7 +42,7 @@
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-jest": "^24.4.0",
     "eslint-plugin-prettier": "^4.0.0",
-    "jest": "^27.1.0",
+    "jest": "^27.1.1",
     "memfs": "^3.2.4",
     "prettier": "^2.3.2",
     "webpack": "^5.52.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magic-comments-loader",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Add webpack magic comments to your dynamic imports during build time",
   "main": "dist",
   "type": "module",
@@ -43,7 +43,7 @@
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-jest": "^24.4.0",
     "eslint-plugin-prettier": "^4.0.0",
-    "jest": "^27.1.0",
+    "jest": "^27.1.1",
     "memfs": "^3.2.4",
     "prettier": "^2.3.2",
     "webpack": "^5.52.0"