Merge pull request #981 from ckeditor/ck/16798

Fix (build-tools): Ability to pass `globals` parameter if necessary for external imports in `umd` bundles. See ckeditor/ckeditor5#16798.

BREAKING CHANGE: Ability to pass `globals` parameter if necessary for external imports in `umd` bundles.

packages/ckeditor5-dev-build-tools/README.md

@@ -142,6 +142,30 @@ The name of the UMD bundle. This name will be used as the global variable name w
 
 This option is required if the `browser' option is enabled.
 
+#### `globals` / `--globals=[moduleID:Global]`
+
+**Type:** `{ [ name: string ]: string } | ( ( name: string ) => string )` | `string[]`
+
+**Default value:** `{}`
+
+Pairs of external package names and associated global variables used in the `umd` build.
+
+The list already contains `ckeditor5` and `ckeditor5-premium-features` which are mapped to `CKEDITOR` and `CKEDITOR_PREMIUM_FEATURES`.
+
+When using the CLI, this option can be used multiple times.
+
+**Example value:** `--globals=external-id:variableName --globals=another-external-id:anotherVariableName`
+
+When using the JavaScript API, the option must be an object.
+
+**Example value:**
+```js
+globals: {
+	'external-id': 'variableName',
+	'another-external-id': 'anotherVariableName'
+}
+```
+
 #### `external` / `--external=[path]`
 
 **Type:** `string[]` | `string`

packages/ckeditor5-dev-build-tools/src/build.ts

@@ -8,7 +8,7 @@ import url from 'url';
 import util from 'util';
 import chalk from 'chalk';
 import path from 'upath';
-import { rollup, type RollupOutput } from 'rollup';
+import { rollup, type RollupOutput, type GlobalsOption } from 'rollup';
 import { getRollupConfig } from './config.js';
 import { getCwdPath, camelizeObjectKeys, removeWhitespace } from './utils.js';
 
@@ -17,6 +17,7 @@ export interface BuildOptions {
 	output: string;
 	tsconfig: string;
 	name: string;
+	globals: GlobalsOption | Array<string>;
 	banner: string;
 	external: Array<string>;
 	rewrite: Array<[string, string]>;
@@ -33,6 +34,7 @@ export const defaultOptions: BuildOptions = {
 	output: 'dist/index.js',
 	tsconfig: 'tsconfig.json',
 	name: '',
+	globals: {},
 	banner: '',
 	external: [],
 	rewrite: [],
@@ -44,6 +46,14 @@ export const defaultOptions: BuildOptions = {
 	browser: false
 };
 
+/**
+ * `ckeditor5` and `ckeditor5-premium-features` globals.
+ */
+const CKEDITOR_GLOBALS: GlobalsOption = {
+	ckeditor5: 'CKEDITOR',
+	'ckeditor5-premium-features': 'CKEDITOR_PREMIUM_FEATURES'
+};
+
 /**
  * Reads CLI arguments and turn the keys into camelcase.
  */
@@ -61,7 +71,8 @@ function getCliArguments(): Partial<BuildOptions> {
 			'minify': { type: 'boolean' },
 			'clean': { type: 'boolean' },
 			'browser': { type: 'boolean' },
-			'name': { type: 'string' }
+			'name': { type: 'string' },
+			'globals': { type: 'string', multiple: true }
 		},
 
 		// Skip `node ckeditor5-build-package`.
@@ -74,6 +85,17 @@ function getCliArguments(): Partial<BuildOptions> {
 	return camelizeObjectKeys( values );
 }
 
+/**
+ * Convert `globals` parameter to object when it's passed via CLI as `<external-id:variableName,another-external-id:anotherVariableName, >`
+ */
+function normalizeGlobalsParameter( globals: GlobalsOption | Array<string> ): GlobalsOption | Array<string> {
+	if ( Array.isArray( globals ) ) {
+		return Object.fromEntries( globals.map( item => item.split( ':' ) ) );
+	}
+
+	return globals;
+}
+
 /**
  * Generates `UMD` build based on previous `ESM` build.
  */
@@ -83,17 +105,18 @@ async function generateUmdBuild( args: BuildOptions, bundle: RollupOutput ): Pro
 	const { dir, name } = path.parse( args.output );
 	const { plugins, ...config } = await getRollupConfig( args );
 	const build = await rollup( config );
+	const globals = {
+		...CKEDITOR_GLOBALS,
+		...args.globals as GlobalsOption
+	};
 
 	const umdBundle = await build.write( {
 		format: 'umd',
 		file: path.join( dir, `${ name }.umd.js` ),
 		assetFileNames: '[name][extname]',
 		sourcemap: args.sourceMap,
 		name: args.name,
-		globals: {
-			ckeditor5: 'ckeditor5',
-			'ckeditor5-premium-features': 'ckeditor5-premium-features'
-		}
+		globals
 	} );
 
 	return {
@@ -137,6 +160,10 @@ async function normalizeOptions( options: Partial<BuildOptions> ): Promise<Build
 		normalized.banner = banner;
 	}
 
+	if ( normalized.globals ) {
+		normalized.globals = normalizeGlobalsParameter( normalized.globals );
+	}
+
 	return normalized;
 }
 

packages/ckeditor5-dev-build-tools/tests/build/arguments.test.ts

@@ -122,6 +122,15 @@ test( '--external', async () => {
 	expect( spy ).toHaveBeenCalledWith( expect.objectContaining( { external: [ 'foo', 'bar' ] } ) );
 } );
 
+test( '--globals', async () => {
+	const spy = getConfigMock();
+
+	mockCliArgs( '--globals=foo:bar', '--globals=baz:faz' );
+	await build();
+
+	expect( spy ).toHaveBeenCalledWith( expect.objectContaining( { globals: { foo: 'bar', baz: 'faz' } } ) );
+} );
+
 test( '--declarations', async () => {
 	const spy = getConfigMock();
 
@@ -212,6 +221,22 @@ test( '.external', async () => {
 	expect( spy ).toHaveBeenCalledWith( expect.objectContaining( { external: [ 'foo', 'bar' ] } ) );
 } );
 
+test( '.globals', async () => {
+	const spy = getConfigMock();
+
+	await build( { globals: { foo: 'bar' } } );
+
+	expect( spy ).toHaveBeenCalledWith( expect.objectContaining( { globals: { foo: 'bar' } } ) );
+} );
+
+test( '.globals (empty object)', async () => {
+	const spy = getConfigMock();
+
+	await build( { globals: {} } );
+
+	expect( spy ).toHaveBeenCalledWith( expect.objectContaining( { globals: {} } ) );
+} );
+
 test( '.rewrite', async () => {
 	const spy = getConfigMock();
 

packages/ckeditor5-dev-build-tools/tests/build/build.test.ts

@@ -310,7 +310,7 @@ test( 'Minify', async () => {
 	expect( output[ 0 ].code ).toContain( 'export{' );
 } );
 
-test( 'Minification doesnt remove banner', async () => {
+test( 'Minification doesn\'t remove banner', async () => {
 	const { output } = await build( {
 		input: 'src/input.js',
 		banner: 'src/banner.js',

packages/ckeditor5-dev-build-tools/tests/config/config.test.ts

@@ -16,6 +16,7 @@ const defaults: Options = {
 	banner: '',
 	external: [],
 	rewrite: [],
+	globals: [],
 	declarations: false,
 	translations: '',
 	sourceMap: false,