Add dynamicImportFunction option (#2723)

* feat: add dynamicImportFunction option This option allows users of `es` format to rename the `import()` function, which right now has mixed support in browsers. By allowing this function to be renamed we can have polyfills (which cannot use the reserved `import` keyword but could go by a different name like `importModule`). * docs: add dynamicImportFunction docs * feat: warn when using dynamicImportFunction in non-esm format * Add functional tests and align warning messages * Fix merge * Add dynamicImportFunction to two more places and fix sorting
rollup · Mar 1, 2019 · 91ce981 · 91ce981
1 parent 7c141d2
commit 91ce981
Show file tree

Hide file tree

Showing 40 changed files with 206 additions and 46 deletions.
diff --git a/bin/src/help.md b/bin/src/help.md
@@ -25,6 +25,7 @@ Basic options:
 --chunkFileNames <pattern>  Name pattern for emitted secondary chunks
 --compact                   Minify wrapper code
 --context <variable>        Specify top-level `this` value
+--dynamicImportFunction <name>         Rename the dynamic `import()` function
 --entryFileNames <pattern>  Name pattern for emitted entry chunks
 --environment <values>      Settings passed to config file (see example)
 --no-esModule               Do not add __esModule property

diff --git a/docs/01-command-line-reference.md b/docs/01-command-line-reference.md
@@ -85,6 +85,7 @@ export default { // can be an array (for multiple inputs)
 
     // danger zone
     amd,
+    dynamicImportFunction,
     esModule,
     exports,
     freeze,

diff --git a/docs/02-javascript-api.md b/docs/02-javascript-api.md
@@ -134,6 +134,7 @@ const outputOptions = {
 
     // danger zone
     amd,
+    dynamicImportFunction,
     esModule,
     exports,
     freeze,

diff --git a/docs/999-big-list-of-options.md b/docs/999-big-list-of-options.md
@@ -667,6 +667,13 @@ Default: `true`
 
 Whether to include the 'use strict' pragma at the top of generated non-ESM bundles. Strictly-speaking, ES modules are *always* in strict mode, so you shouldn't disable this without good reason.
 
+#### output.dynamicImportFunction
+Type: `string`<br>
+CLI: `--dynamicImportFunction <name>`<br>
+Default: `import`
+
+This will rename the dynamic import function to the chosen name when outputting ESM bundles. This is useful for generating code that uses a dynamic import polyfill such as [this one](https://github.com/uupaa/dynamic-import-polyfill).
+
 #### preserveSymlinks
 Type: `boolean`<br>
 CLI: `--preserveSymlinks`<br>

diff --git a/src/Chunk.ts b/src/Chunk.ts
@@ -435,6 +435,7 @@ export default class Chunk {
 
 		const renderOptions: RenderOptions = {
 			compact: options.compact,
+			dynamicImportFunction: options.dynamicImportFunction,
 			format: options.format,
 			freeze: options.freeze !== false,
 			indent: this.indentString,
@@ -545,7 +546,13 @@ export default class Chunk {
 				code: 'INVALID_OPTION',
 				message: `Invalid format: ${options.format} - valid options are ${Object.keys(
 					finalisers
-				).join(', ')}`
+				).join(', ')}.`
+			});
+		}
+		if (options.dynamicImportFunction && options.format !== 'es') {
+			this.graph.warn({
+				code: 'INVALID_OPTION',
+				message: '"output.dynamicImportFunction" is ignored for formats other than "esm".'
 			});
 		}
 

diff --git a/src/ast/nodes/Import.ts b/src/ast/nodes/Import.ts
@@ -11,10 +11,10 @@ interface DynamicImportMechanism {
 	right: string;
 }
 
-const getDynamicImportMechanism = (format: string, compact: boolean): DynamicImportMechanism => {
-	switch (format) {
+const getDynamicImportMechanism = (options: RenderOptions): DynamicImportMechanism => {
+	switch (options.format) {
 		case 'cjs': {
-			const _ = compact ? '' : ' ';
+			const _ = options.compact ? '' : ' ';
 			return {
 				interopLeft: `Promise.resolve({${_}default:${_}require(`,
 				interopRight: `)${_}})`,
@@ -23,9 +23,9 @@ const getDynamicImportMechanism = (format: string, compact: boolean): DynamicImp
 			};
 		}
 		case 'amd': {
-			const _ = compact ? '' : ' ';
-			const resolve = compact ? 'c' : 'resolve';
-			const reject = compact ? 'e' : 'reject';
+			const _ = options.compact ? '' : ' ';
+			const resolve = options.compact ? 'c' : 'resolve';
+			const reject = options.compact ? 'e' : 'reject';
 			return {
 				interopLeft: `new Promise(function${_}(${resolve},${_}${reject})${_}{${_}require([`,
 				interopRight: `],${_}function${_}(m)${_}{${_}${resolve}({${_}default:${_}m${_}})${_}},${_}${reject})${_}})`,
@@ -38,6 +38,11 @@ const getDynamicImportMechanism = (format: string, compact: boolean): DynamicImp
 				left: 'module.import(',
 				right: ')'
 			};
+		case 'es':
+			return {
+				left: `${options.dynamicImportFunction || 'import'}(`,
+				right: ')'
+			};
 	}
 };
 
@@ -72,7 +77,7 @@ export default class Import extends NodeBase {
 			return;
 		}
 
-		const importMechanism = getDynamicImportMechanism(options.format, options.compact);
+		const importMechanism = getDynamicImportMechanism(options);
 		if (importMechanism) {
 			const leftMechanism =
 				(this.resolutionInterop && importMechanism.interopLeft) || importMechanism.left;

diff --git a/src/finalisers/iife.ts b/src/finalisers/iife.ts
@@ -50,7 +50,7 @@ export default function iife(
 	if (hasExports && !name) {
 		error({
 			code: 'INVALID_OPTION',
-			message: `You must supply output.name for IIFE bundles`
+			message: `You must supply "output.name" for IIFE bundles.`
 		});
 	}
 

diff --git a/src/finalisers/umd.ts b/src/finalisers/umd.ts
@@ -45,7 +45,7 @@ export default function umd(
 	if (hasExports && !options.name) {
 		error({
 			code: 'INVALID_OPTION',
-			message: 'You must supply output.name for UMD bundles'
+			message: 'You must supply "output.name" for UMD bundles.'
 		});
 	}
 

diff --git a/src/rollup/index.ts b/src/rollup/index.ts
@@ -28,14 +28,14 @@ import {
 function checkOutputOptions(options: OutputOptions) {
 	if (<string>options.format === 'es6') {
 		error({
-			message: 'The `es6` output format is deprecated – use `esm` instead',
+			message: 'The "es6" output format is deprecated – use "esm" instead',
 			url: `https://rollupjs.org/guide/en#output-format`
 		});
 	}
 
 	if (!options.format) {
 		error({
-			message: `You must specify output.format, which can be one of 'amd', 'cjs', 'system', 'esm', 'iife' or 'umd'`,
+			message: `You must specify "output.format", which can be one of "amd", "cjs", "system", "esm", "iife" or "umd".`,
 			url: `https://rollupjs.org/guide/en#output-format`
 		});
 	}
@@ -88,37 +88,37 @@ function getInputOptions(rawInputOptions: GenericConfigObject): any {
 		if (inputOptions.preserveModules)
 			error({
 				code: 'INVALID_OPTION',
-				message: `preserveModules does not support the inlineDynamicImports option.`
+				message: `"preserveModules" does not support the "inlineDynamicImports" option.`
 			});
 		if (inputOptions.manualChunks)
 			error({
 				code: 'INVALID_OPTION',
-				message: '"manualChunks" option is not supported for inlineDynamicImports.'
+				message: '"manualChunks" option is not supported for "inlineDynamicImports".'
 			});
 
 		if (inputOptions.experimentalOptimizeChunks)
 			error({
 				code: 'INVALID_OPTION',
-				message: '"experimentalOptimizeChunks" option is not supported for inlineDynamicImports.'
+				message: '"experimentalOptimizeChunks" option is not supported for "inlineDynamicImports".'
 			});
 		if (
 			(inputOptions.input instanceof Array && inputOptions.input.length > 1) ||
 			(typeof inputOptions.input === 'object' && Object.keys(inputOptions.input).length > 1)
 		)
 			error({
 				code: 'INVALID_OPTION',
-				message: 'Multiple inputs are not supported for inlineDynamicImports.'
+				message: 'Multiple inputs are not supported for "inlineDynamicImports".'
 			});
 	} else if (inputOptions.preserveModules) {
 		if (inputOptions.manualChunks)
 			error({
 				code: 'INVALID_OPTION',
-				message: 'preserveModules does not support the manualChunks option.'
+				message: '"preserveModules" does not support the "manualChunks" option.'
 			});
 		if (inputOptions.experimentalOptimizeChunks)
 			error({
 				code: 'INVALID_OPTION',
-				message: 'preserveModules does not support the experimentalOptimizeChunks option.'
+				message: '"preserveModules" does not support the "experimentalOptimizeChunks" option.'
 			});
 	}
 
@@ -290,7 +290,7 @@ export default function rollup(rawInputOptions: GenericConfigObject): Promise<Ro
 						if (!outputOptions || (!outputOptions.dir && !outputOptions.file)) {
 							error({
 								code: 'MISSING_OPTION',
-								message: 'You must specify output.file or output.dir for the build.'
+								message: 'You must specify "output.file" or "output.dir" for the build.'
 							});
 						}
 						return generate(outputOptions, true).then(bundle => {
@@ -305,17 +305,17 @@ export default function rollup(rawInputOptions: GenericConfigObject): Promise<Ro
 								if (outputOptions.sourcemapFile)
 									error({
 										code: 'INVALID_OPTION',
-										message: '"sourcemapFile" is only supported for single-file builds.'
+										message: '"output.sourcemapFile" is only supported for single-file builds.'
 									});
 								if (typeof outputOptions.file === 'string')
 									error({
 										code: 'INVALID_OPTION',
 										message:
-											'When building multiple chunks, the output.dir option must be used, not output.file.' +
+											'When building multiple chunks, the "output.dir" option must be used, not "output.file".' +
 											(typeof inputOptions.input !== 'string' ||
 											inputOptions.inlineDynamicImports === true
 												? ''
-												: ' To inline dynamic imports set the inlineDynamicImports: true option.')
+												: ' To inline dynamic imports, set the "inlineDynamicImports" option.')
 									});
 							}
 							return Promise.all(
@@ -436,19 +436,19 @@ function normalizeOutputOptions(
 			error({
 				code: 'INVALID_OPTION',
 				message:
-					'You must set either output.file for a single-file build or output.dir when generating multiple chunks.'
+					'You must set either "output.file" for a single-file build or "output.dir" when generating multiple chunks.'
 			});
 		if (inputOptions.preserveModules) {
 			error({
 				code: 'INVALID_OPTION',
 				message:
-					'You must set output.dir instead of output.file when using the preserveModules option.'
+					'You must set "output.dir" instead of "output.file" when using the "preserveModules" option.'
 			});
 		}
 		if (typeof inputOptions.input === 'object' && !Array.isArray(inputOptions.input))
 			error({
 				code: 'INVALID_OPTION',
-				message: 'You must set output.dir instead of output.file when providing named inputs.'
+				message: 'You must set "output.dir" instead of "output.file" when providing named inputs.'
 			});
 	}
 
@@ -461,7 +461,8 @@ function normalizeOutputOptions(
 		if (typeof outputOptions.file === 'string')
 			error({
 				code: 'INVALID_OPTION',
-				message: 'You must set output.dir instead of output.file when generating multiple chunks.'
+				message:
+					'You must set "output.dir" instead of "output.file" when generating multiple chunks.'
 			});
 	}
 

diff --git a/src/rollup/types.d.ts b/src/rollup/types.d.ts
@@ -294,6 +294,7 @@ export interface OutputOptions {
 	compact?: boolean;
 	// only required for bundle.write
 	dir?: string;
+	dynamicImportFunction?: string;
 	entryFileNames?: string;
 	esModule?: boolean;
 	exports?: 'default' | 'named' | 'none' | 'auto';

diff --git a/src/utils/mergeOptions.ts b/src/utils/mergeOptions.ts
@@ -238,6 +238,7 @@ function getOutputOptions(
 		chunkFileNames: getOption('chunkFileNames'),
 		compact: getOption('compact', false),
 		dir: getOption('dir'),
+		dynamicImportFunction: getOption('dynamicImportFunction'),
 		entryFileNames: getOption('entryFileNames'),
 		esModule: getOption('esModule', true),
 		exports: getOption('exports'),

diff --git a/src/utils/renderHelpers.ts b/src/utils/renderHelpers.ts
@@ -4,6 +4,7 @@ import { treeshakeNode } from './treeshakeNode';
 
 export interface RenderOptions {
 	compact: boolean;
+	dynamicImportFunction: string;
 	format: string;
 	freeze: boolean;
 	indent: string;

diff --git a/test/chunking-form/samples/dynamic-import-name/_config.js b/test/chunking-form/samples/dynamic-import-name/_config.js
@@ -0,0 +1,15 @@
+module.exports = {
+	description: 'allows specifying a custom importer function',
+	options: {
+		input: 'main.js',
+		onwarn() {},
+		plugins: {
+			resolveDynamicImport() {
+				return false;
+			}
+		},
+		output: {
+			dynamicImportFunction: 'foobar'
+		}
+	}
+};
diff --git a/test/chunking-form/samples/dynamic-import-name/_expected/amd/main.js b/test/chunking-form/samples/dynamic-import-name/_expected/amd/main.js
@@ -0,0 +1,5 @@
+define(['require'], function (require) { 'use strict';
+
+	new Promise(function (resolve, reject) { require(['./foo.js'], resolve, reject) }).then(result => console.log(result));
+
+});
diff --git a/test/chunking-form/samples/dynamic-import-name/_expected/cjs/main.js b/test/chunking-form/samples/dynamic-import-name/_expected/cjs/main.js
@@ -0,0 +1,3 @@
+'use strict';
+
+Promise.resolve(require('./foo.js')).then(result => console.log(result));
diff --git a/test/chunking-form/samples/dynamic-import-name/_expected/es/main.js b/test/chunking-form/samples/dynamic-import-name/_expected/es/main.js
@@ -0,0 +1 @@
+foobar('./foo.js').then(result => console.log(result));
diff --git a/test/chunking-form/samples/dynamic-import-name/_expected/system/main.js b/test/chunking-form/samples/dynamic-import-name/_expected/system/main.js
@@ -0,0 +1,10 @@
+System.register([], function (exports, module) {
+	'use strict';
+	return {
+		execute: function () {
+
+			module.import('./foo.js').then(result => console.log(result));
+
+		}
+	};
+});
diff --git a/test/chunking-form/samples/dynamic-import-name/main.js b/test/chunking-form/samples/dynamic-import-name/main.js
@@ -0,0 +1 @@
+import('./foo.js').then(result => console.log(result));
diff --git a/test/function/samples/dynamic-import-name-warn/_config.js b/test/function/samples/dynamic-import-name-warn/_config.js
@@ -0,0 +1,32 @@
+const assert = require('assert');
+
+module.exports = {
+	description: 'warns when specifying a custom importer function for formats other than "esm"',
+	context: {
+		require(path) {
+			assert.equal(path, './foo.js');
+			return 42;
+		}
+	},
+	options: {
+		input: 'main.js',
+		plugins: {
+			resolveDynamicImport() {
+				return false;
+			}
+		},
+		output: {
+			dynamicImportFunction: 'myImporter',
+			format: 'cjs'
+		}
+	},
+	exports(exports) {
+		return exports.fromFoo.then(value => assert.strictEqual(value, 42));
+	},
+	warnings: [
+		{
+			code: 'INVALID_OPTION',
+			message: '"output.dynamicImportFunction" is ignored for formats other than "esm".'
+		}
+	]
+};
diff --git a/test/function/samples/dynamic-import-name-warn/_expected/amd/main.js b/test/function/samples/dynamic-import-name-warn/_expected/amd/main.js
@@ -0,0 +1,5 @@
+define(['require'], function (require) { 'use strict';
+
+	new Promise(function (resolve, reject) { require(['./foo.js'], resolve, reject) });
+
+});
diff --git a/test/function/samples/dynamic-import-name-warn/_expected/cjs/main.js b/test/function/samples/dynamic-import-name-warn/_expected/cjs/main.js
@@ -0,0 +1,3 @@
+'use strict';
+
+Promise.resolve(require('./foo.js'));
diff --git a/test/function/samples/dynamic-import-name-warn/_expected/es/main.js b/test/function/samples/dynamic-import-name-warn/_expected/es/main.js
@@ -0,0 +1 @@
+foobar('./foo.js');
diff --git a/test/function/samples/dynamic-import-name-warn/_expected/system/main.js b/test/function/samples/dynamic-import-name-warn/_expected/system/main.js
@@ -0,0 +1,10 @@
+System.register([], function (exports, module) {
+	'use strict';
+	return {
+		execute: function () {
+
+			module.import('./foo.js');
+
+		}
+	};
+});
diff --git a/test/function/samples/dynamic-import-name-warn/main.js b/test/function/samples/dynamic-import-name-warn/main.js
@@ -0,0 +1 @@
+export const fromFoo = import('./foo.js');