@rollup/plugin-commonjs 14.0.0 → 17.0.0

package/types/index.d.ts

@@ -1,58 +1,145 @@
 import { FilterPattern } from '@rollup/pluginutils';
 import { Plugin } from 'rollup';
 
+type RequireReturnsDefaultOption = boolean | 'auto' | 'preferred' | 'namespace';
+
 interface RollupCommonJSOptions {
   /**
-   * non-CommonJS modules will be ignored, but you can also
-   * specifically include/exclude files
+   * A minimatch pattern, or array of patterns, which specifies the files in
+   * the build the plugin should operate on. By default, all files with
+   * extension `".cjs"` or those in `extensions` are included, but you can narrow
+   * this list by only including specific files. These files will be analyzed
+   * and transpiled if either the analysis does not find ES module specific
+   * statements or `transformMixedEsModules` is `true`.
    * @default undefined
    */
   include?: FilterPattern;
   /**
-   * non-CommonJS modules will be ignored, but you can also
-   * specifically include/exclude files
+   * A minimatch pattern, or array of patterns, which specifies the files in
+   * the build the plugin should _ignore_. By default, all files with
+   * extensions other than those in `extensions` or `".cjs"` are ignored, but you
+   * can exclude additional files. See also the `include` option.
    * @default undefined
    */
   exclude?: FilterPattern;
   /**
-   * search for files other than .js files (must already
-   * be transpiled by a previous plugin!)
+   * For extensionless imports, search for extensions other than .js in the
+   * order specified. Note that you need to make sure that non-JavaScript files
+   * are transpiled by another plugin first.
    * @default [ '.js' ]
    */
-  extensions?: ReadonlyArray<string | RegExp>;
+  extensions?: ReadonlyArray<string>;
   /**
-   * if true then uses of `global` won't be dealt with by this plugin
+   * If true then uses of `global` won't be dealt with by this plugin
    * @default false
    */
   ignoreGlobal?: boolean;
   /**
-   * if false then skip sourceMap generation for CommonJS modules
+   * If false, skips source map generation for CommonJS modules. This will improve performance.
    * @default true
    */
   sourceMap?: boolean;
   /**
-   * Instructs the plugin whether or not to enable mixed module transformations. This is useful in scenarios with mixed ES and CommonJS modules. Set to `true` if it's known that `require` calls should be transformed, or `false` if the code contains env detection and the `require` should survive a transformation.
+   * Instructs the plugin whether to enable mixed module transformations. This
+   * is useful in scenarios with modules that contain a mix of ES `import`
+   * statements and CommonJS `require` expressions. Set to `true` if `require`
+   * calls should be transformed to imports in mixed modules, or `false` if the
+   * `require` expressions should survive the transformation. The latter can be
+   * important if the code contains environment detection, or you are coding
+   * for an environment with special treatment for `require` calls such as
+   * ElectronJS. See also the `ignore` option.
    * @default false
    */
   transformMixedEsModules?: boolean;
   /**
-   * sometimes you have to leave require statements
-   * unconverted. Pass an array containing the IDs
-   * or a `id => boolean` function. Only use this
-   * option if you know what you're doing!
+   * Sometimes you have to leave require statements unconverted. Pass an array
+   * containing the IDs or a `id => boolean` function.
+   * @default []
+   */
+  ignore?: ReadonlyArray<string> | ((id: string) => boolean);
+  /**
+   * Controls how to render imports from external dependencies. By default,
+   * this plugin assumes that all external dependencies are CommonJS. This
+   * means they are rendered as default imports to be compatible with e.g.
+   * NodeJS where ES modules can only import a default export from a CommonJS
+   * dependency.
+   *
+   * If you set `esmExternals` to `true`, this plugins assumes that all
+   * external dependencies are ES modules and respect the
+   * `requireReturnsDefault` option. If that option is not set, they will be
+   * rendered as namespace imports.
+   *
+   * You can also supply an array of ids to be treated as ES modules, or a
+   * function that will be passed each external id to determine if it is an ES
+   * module.
+   * @default false
+   */
+  esmExternals?: boolean | ReadonlyArray<string> | ((id: string) => boolean);
+  /**
+   * Controls what is returned when requiring an ES module from a CommonJS file.
+   * When using the `esmExternals` option, this will also apply to external
+   * modules. By default, this plugin will render those imports as namespace
+   * imports i.e.
+   *
+   * ```js
+   * // input
+   * const foo = require('foo');
+   *
+   * // output
+   * import * as foo from 'foo';
+   * ```
+   *
+   * However there are some situations where this may not be desired.
+   * For these situations, you can change Rollup's behaviour either globally or
+   * per module. To change it globally, set the `requireReturnsDefault` option
+   * to one of the following values:
+   *
+   * - `false`: This is the default, requiring an ES module returns its
+   *   namespace. This is the only option that will also add a marker
+   *   `__esModule: true` to the namespace to support interop patterns in
+   *   CommonJS modules that are transpiled ES modules.
+   * - `"namespace"`: Like `false`, requiring an ES module returns its
+   *   namespace, but the plugin does not add the `__esModule` marker and thus
+   *   creates more efficient code. For external dependencies when using
+   *   `esmExternals: true`, no additional interop code is generated.
+   * - `"auto"`: This is complementary to how `output.exports: "auto"` works in
+   *   Rollup: If a module has a default export and no named exports, requiring
+   *   that module returns the default export. In all other cases, the namespace
+   *   is returned. For external dependencies when using `esmExternals: true`, a
+   *   corresponding interop helper is added.
+   * - `"preferred"`: If a module has a default export, requiring that module
+   *   always returns the default export, no matter whether additional named
+   *   exports exist. This is similar to how previous versions of this plugin
+   *   worked. Again for external dependencies when using `esmExternals: true`,
+   *   an interop helper is added.
+   * - `true`: This will always try to return the default export on require
+   *   without checking if it actually exists. This can throw at build time if
+   *   there is no default export. This is how external dependencies are handled
+   *   when `esmExternals` is not used. The advantage over the other options is
+   *   that, like `false`, this does not add an interop helper for external
+   *   dependencies, keeping the code lean.
+   *
+   * To change this for individual modules, you can supply a function for
+   * `requireReturnsDefault` instead. This function will then be called once for
+   * each required ES module or external dependency with the corresponding id
+   * and allows you to return different values for different modules.
+   * @default false
    */
-  ignore?: ReadonlyArray<string | ((id: string) => boolean)>;
+  requireReturnsDefault?:
+    | RequireReturnsDefaultOption
+    | ((id: string) => RequireReturnsDefaultOption);
   /**
-   * 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.
+   * 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.
    *
-   * 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/"` -> `"/"`.
+   * 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/"` -> `"/"`.
    */
   dynamicRequireTargets?: string | ReadonlyArray<string>;
 }