UNPKG

11.1 kBTypeScriptView Raw
1import type { FilterPattern } from '@rollup/pluginutils';
2import type { Plugin } from 'rollup';
3
4type RequireReturnsDefaultOption = boolean | 'auto' | 'preferred' | 'namespace';
5type DefaultIsModuleExportsOption = boolean | 'auto';
6
7interface RollupCommonJSOptions {
8 /**
9 * A picomatch pattern, or array of patterns, which specifies the files in
10 * the build the plugin should operate on. By default, all files with
11 * extension `".cjs"` or those in `extensions` are included, but you can
12 * narrow this list by only including specific files. These files will be
13 * analyzed and transpiled if either the analysis does not find ES module
14 * specific statements or `transformMixedEsModules` is `true`.
15 * @default undefined
16 */
17 include?: FilterPattern;
18 /**
19 * A picomatch pattern, or array of patterns, which specifies the files in
20 * the build the plugin should _ignore_. By default, all files with
21 * extensions other than those in `extensions` or `".cjs"` are ignored, but you
22 * can exclude additional files. See also the `include` option.
23 * @default undefined
24 */
25 exclude?: FilterPattern;
26 /**
27 * For extensionless imports, search for extensions other than .js in the
28 * order specified. Note that you need to make sure that non-JavaScript files
29 * are transpiled by another plugin first.
30 * @default [ '.js' ]
31 */
32 extensions?: ReadonlyArray<string>;
33 /**
34 * If true then uses of `global` won't be dealt with by this plugin
35 * @default false
36 */
37 ignoreGlobal?: boolean;
38 /**
39 * If false, skips source map generation for CommonJS modules. This will
40 * improve performance.
41 * @default true
42 */
43 sourceMap?: boolean;
44 /**
45 * Some `require` calls cannot be resolved statically to be translated to
46 * imports.
47 * When this option is set to `false`, the generated code will either
48 * directly throw an error when such a call is encountered or, when
49 * `dynamicRequireTargets` is used, when such a call cannot be resolved with a
50 * configured dynamic require target.
51 * Setting this option to `true` will instead leave the `require` call in the
52 * code or use it as a fallback for `dynamicRequireTargets`.
53 * @default false
54 */
55 ignoreDynamicRequires?: boolean;
56 /**
57 * Instructs the plugin whether to enable mixed module transformations. This
58 * is useful in scenarios with modules that contain a mix of ES `import`
59 * statements and CommonJS `require` expressions. Set to `true` if `require`
60 * calls should be transformed to imports in mixed modules, or `false` if the
61 * `require` expressions should survive the transformation. The latter can be
62 * important if the code contains environment detection, or you are coding
63 * for an environment with special treatment for `require` calls such as
64 * ElectronJS. See also the `ignore` option.
65 * @default false
66 */
67 transformMixedEsModules?: boolean;
68 /**
69 * By default, this plugin will try to hoist `require` statements as imports
70 * to the top of each file. While this works well for many code bases and
71 * allows for very efficient ESM output, it does not perfectly capture
72 * CommonJS semantics as the order of side effects like log statements may
73 * change. But it is especially problematic when there are circular `require`
74 * calls between CommonJS modules as those often rely on the lazy execution of
75 * nested `require` calls.
76 *
77 * Setting this option to `true` will wrap all CommonJS files in functions
78 * which are executed when they are required for the first time, preserving
79 * NodeJS semantics. Note that this can have an impact on the size and
80 * performance of the generated code.
81 *
82 * The default value of `"auto"` will only wrap CommonJS files when they are
83 * part of a CommonJS dependency cycle, e.g. an index file that is required by
84 * many of its dependencies. All other CommonJS files are hoisted. This is the
85 * recommended setting for most code bases.
86 *
87 * `false` will entirely prevent wrapping and hoist all files. This may still
88 * work depending on the nature of cyclic dependencies but will often cause
89 * problems.
90 *
91 * You can also provide a picomatch pattern, or array of patterns, to only
92 * specify a subset of files which should be wrapped in functions for proper
93 * `require` semantics.
94 *
95 * `"debug"` works like `"auto"` but after bundling, it will display a warning
96 * containing a list of ids that have been wrapped which can be used as
97 * picomatch pattern for fine-tuning.
98 * @default "auto"
99 */
100 strictRequires?: boolean | FilterPattern;
101 /**
102 * Sometimes you have to leave require statements unconverted. Pass an array
103 * containing the IDs or a `id => boolean` function.
104 * @default []
105 */
106 ignore?: ReadonlyArray<string> | ((id: string) => boolean);
107 /**
108 * In most cases, where `require` calls are inside a `try-catch` clause,
109 * they should be left unconverted as it requires an optional dependency
110 * that may or may not be installed beside the rolled up package.
111 * Due to the conversion of `require` to a static `import` - the call is
112 * hoisted to the top of the file, outside the `try-catch` clause.
113 *
114 * - `true`: Default. All `require` calls inside a `try` will be left unconverted.
115 * - `false`: All `require` calls inside a `try` will be converted as if the
116 * `try-catch` clause is not there.
117 * - `remove`: Remove all `require` calls from inside any `try` block.
118 * - `string[]`: Pass an array containing the IDs to left unconverted.
119 * - `((id: string) => boolean|'remove')`: Pass a function that controls
120 * individual IDs.
121 *
122 * @default true
123 */
124 ignoreTryCatch?:
125 | boolean
126 | 'remove'
127 | ReadonlyArray<string>
128 | ((id: string) => boolean | 'remove');
129 /**
130 * Controls how to render imports from external dependencies. By default,
131 * this plugin assumes that all external dependencies are CommonJS. This
132 * means they are rendered as default imports to be compatible with e.g.
133 * NodeJS where ES modules can only import a default export from a CommonJS
134 * dependency.
135 *
136 * If you set `esmExternals` to `true`, this plugin assumes that all
137 * external dependencies are ES modules and respect the
138 * `requireReturnsDefault` option. If that option is not set, they will be
139 * rendered as namespace imports.
140 *
141 * You can also supply an array of ids to be treated as ES modules, or a
142 * function that will be passed each external id to determine whether it is
143 * an ES module.
144 * @default false
145 */
146 esmExternals?: boolean | ReadonlyArray<string> | ((id: string) => boolean);
147 /**
148 * Controls what is returned when requiring an ES module from a CommonJS file.
149 * When using the `esmExternals` option, this will also apply to external
150 * modules. By default, this plugin will render those imports as namespace
151 * imports i.e.
152 *
153 * ```js
154 * // input
155 * const foo = require('foo');
156 *
157 * // output
158 * import * as foo from 'foo';
159 * ```
160 *
161 * However, there are some situations where this may not be desired.
162 * For these situations, you can change Rollup's behaviour either globally or
163 * per module. To change it globally, set the `requireReturnsDefault` option
164 * to one of the following values:
165 *
166 * - `false`: This is the default, requiring an ES module returns its
167 * namespace. This is the only option that will also add a marker
168 * `__esModule: true` to the namespace to support interop patterns in
169 * CommonJS modules that are transpiled ES modules.
170 * - `"namespace"`: Like `false`, requiring an ES module returns its
171 * namespace, but the plugin does not add the `__esModule` marker and thus
172 * creates more efficient code. For external dependencies when using
173 * `esmExternals: true`, no additional interop code is generated.
174 * - `"auto"`: This is complementary to how `output.exports: "auto"` works in
175 * Rollup: If a module has a default export and no named exports, requiring
176 * that module returns the default export. In all other cases, the namespace
177 * is returned. For external dependencies when using `esmExternals: true`, a
178 * corresponding interop helper is added.
179 * - `"preferred"`: If a module has a default export, requiring that module
180 * always returns the default export, no matter whether additional named
181 * exports exist. This is similar to how previous versions of this plugin
182 * worked. Again for external dependencies when using `esmExternals: true`,
183 * an interop helper is added.
184 * - `true`: This will always try to return the default export on require
185 * without checking if it actually exists. This can throw at build time if
186 * there is no default export. This is how external dependencies are handled
187 * when `esmExternals` is not used. The advantage over the other options is
188 * that, like `false`, this does not add an interop helper for external
189 * dependencies, keeping the code lean.
190 *
191 * To change this for individual modules, you can supply a function for
192 * `requireReturnsDefault` instead. This function will then be called once for
193 * each required ES module or external dependency with the corresponding id
194 * and allows you to return different values for different modules.
195 * @default false
196 */
197 requireReturnsDefault?:
198 | RequireReturnsDefaultOption
199 | ((id: string) => RequireReturnsDefaultOption);
200
201 /**
202 * @default "auto"
203 */
204 defaultIsModuleExports?:
205 | DefaultIsModuleExportsOption
206 | ((id: string) => DefaultIsModuleExportsOption);
207 /**
208 * Some modules contain dynamic `require` calls, or require modules that
209 * contain circular dependencies, which are not handled well by static
210 * imports. Including those modules as `dynamicRequireTargets` will simulate a
211 * CommonJS (NodeJS-like) environment for them with support for dynamic
212 * dependencies. It also enables `strictRequires` for those modules.
213 *
214 * Note: In extreme cases, this feature may result in some paths being
215 * rendered as absolute in the final bundle. The plugin tries to avoid
216 * exposing paths from the local machine, but if you are `dynamicRequirePaths`
217 * with paths that are far away from your project's folder, that may require
218 * replacing strings like `"/Users/John/Desktop/foo-project/"` -> `"/"`.
219 */
220 dynamicRequireTargets?: string | ReadonlyArray<string>;
221 /**
222 * To avoid long paths when using the `dynamicRequireTargets` option, you can use this option to specify a directory
223 * that is a common parent for all files that use dynamic require statements. Using a directory higher up such as `/`
224 * may lead to unnecessarily long paths in the generated code and may expose directory names on your machine like your
225 * home directory name. By default, it uses the current working directory.
226 */
227 dynamicRequireRoot?: string;
228}
229
230/**
231 * Convert CommonJS modules to ES6, so they can be included in a Rollup bundle
232 */
233export default function commonjs(options?: RollupCommonJSOptions): Plugin;
234
\No newline at end of file