@rollup/plugin-commonjs 21.0.1 → 22.0.0-3

package/README.md

@@ -42,15 +42,34 @@ export default {
 
 Then call `rollup` either via the [CLI](https://www.rollupjs.org/guide/en/#command-line-reference) or the [API](https://www.rollupjs.org/guide/en/#javascript-api).
 
+When used together with the node-resolve plugin
+
 ## Options
 
+### `strictRequires`
+
+Type: `"auto" | boolean | "debug" | string[]`<br>
+Default: `"auto"`
+
+By default, this plugin will try to hoist `require` statements as imports to the top of each file. While this works well for many code bases and allows for very efficient ESM output, it does not perfectly capture CommonJS semantics as the initialisation order of required modules will be different. The resultant side effects can include log statements being emitted in a different order, and some code that is dependent on the initialisation order of polyfills in require statements may not work. But it is especially problematic when there are circular `require` calls between CommonJS modules as those often rely on the lazy execution of nested `require` calls.
+
+Setting this option to `true` will wrap all CommonJS files in functions which are executed when they are required for the first time, preserving NodeJS semantics. This is the safest setting and should be used if the generated code does not work correctly with `"auto"`. Note that `strictRequires: true` can have a small impact on the size and performance of generated code, but less so if the code is minified.
+
+The default value of `"auto"` will only wrap CommonJS files when they are part of a CommonJS dependency cycle, e.g. an index file that is required by some of its dependencies, or if they are only required in a potentially "conditional" way like from within an if-statement or a function. All other CommonJS files are hoisted. This is the recommended setting for most code bases. Note that the detection of conditional requires can be subject to race conditions if there are both conditional and unconditional requires of the same file, which in edge cases may result in inconsistencies between builds. If you think this is a problem for you, you can avoid this by using any value other than `"auto"` or `"debug"`.
+
+`false` will entirely prevent wrapping and hoist all files. This may still work depending on the nature of cyclic dependencies but will often cause problems.
+
+You can also provide a [minimatch pattern](https://github.com/isaacs/minimatch), or array of patterns, to only specify a subset of files which should be wrapped in functions for proper `require` semantics.
+
+`"debug"` works like `"auto"` but after bundling, it will display a warning containing a list of ids that have been wrapped which can be used as minimatch pattern for fine-tuning or to avoid the potential race conditions mentioned for `"auto"`.
+
 ### `dynamicRequireTargets`
 
 Type: `string | string[]`<br>
 Default: `[]`
 
 Some modules contain dynamic `require` calls, or require modules that contain circular dependencies, which are not handled well by static imports.
-Including those modules as `dynamicRequireTargets` will simulate a CommonJS (NodeJS-like) environment for them with support for dynamic and circular dependencies.
+Including those modules as `dynamicRequireTargets` will simulate a CommonJS (NodeJS-like) environment for them with support for dynamic dependencies. It also enables `strictRequires` for those modules, see above.
 
 _Note: In extreme cases, this feature may result in some paths being rendered as absolute in the final bundle. The plugin tries to avoid exposing paths from the local machine, but if you are `dynamicRequirePaths` with paths that are far away from your project's folder, that may require replacing strings like `"/Users/John/Desktop/foo-project/"` -> `"/"`._
 
@@ -71,6 +90,13 @@ commonjs({
 });
 ```
 
+### `dynamicRequireRoot`
+
+Type: `string`<br>
+Default: `process.cwd()`
+
+To avoid long paths when using the `dynamicRequireTargets` option, you can use this option to specify a directory that is a common parent for all files that use dynamic require statements. Using a directory higher up such as `/` may lead to unnecessarily long paths in the generated code and may expose directory names on your machine like your home directory name. By default it uses the current working directory.
+
 ### `exclude`
 
 Type: `string | string[]`<br>
@@ -125,15 +151,17 @@ Sometimes you have to leave require statements unconverted. Pass an array contai
 Type: `boolean | 'remove' | string[] | ((id: string) => boolean)`<br>
 Default: `true`
 
-In most cases, where `require` calls are inside a `try-catch` clause, they should be left unconverted as it requires an optional dependency that may or may not be installed beside the rolled up package.
+In most cases, where `require` calls to external dependencies are inside a `try-catch` clause, they should be left unconverted as it requires an optional dependency that may or may not be installed beside the rolled up package.
 Due to the conversion of `require` to a static `import` - the call is hoisted to the top of the file, outside of the `try-catch` clause.
 
-- `true`: All `require` calls inside a `try` will be left unconverted.
-- `false`: All `require` calls inside a `try` will be converted as if the `try-catch` clause is not there.
-- `remove`: Remove all `require` calls from inside any `try` block.
+- `true`: All external `require` calls inside a `try` will be left unconverted.
+- `false`: All external `require` calls inside a `try` will be converted as if the `try-catch` clause is not there.
+- `remove`: Remove all external `require` calls from inside any `try` block.
 - `string[]`: Pass an array containing the IDs to left unconverted.
 - `((id: string) => boolean|'remove')`: Pass a function that control individual IDs.
 
+Note that non-external requires will not be ignored by this option.
+
 ### `ignoreDynamicRequires`
 
 Type: `boolean`
@@ -361,7 +389,7 @@ export default {
     format: 'iife',
     name: 'MyModule'
   },
-  plugins: [resolve(), commonjs()]
+  plugins: [commonjs(), resolve()]
 };
 ```