Core: Provide a package.json exports setup inspired by jQuery Core

The Migrate setup is simpler than Core as it doesn't have the slim or factory
versions, but the core ideas are similar.

Fixes gh-524
Closes gh-566
Ref jquery/jquery#5255
Ref jquery/jquery#5429

Author: mgol

.github/workflows/browser-tests.yml

@@ -43,10 +43,7 @@ jobs:
         run: npm install
 
       - name: Run tests
-        run: |
-          npm run pretest
-          npm run test:unit -- -c jtr-local.yml \
-            --headless -b ${{ matrix.BROWSER }} -f plugin=${{ matrix.MIGRATE_VERSION }}
+        run: npm run test:browser -- -f plugin=${{ matrix.MIGRATE_VERSION }}
 
   ie:
     runs-on: windows-latest

.github/workflows/browserstack.yml

@@ -58,6 +58,9 @@ jobs:
       - name: Install dependencies
         run: npm install
 
+      - name: Build jQuery
+        run: npm run build:all
+
       - name: Pretest script
         run: npm run pretest
 

.github/workflows/node.js.yml

@@ -5,32 +5,39 @@ on:
   push:
     branches-ignore: "dependabot/**"
 
-env:
-  NODE_VERSION: 22.x
-
 jobs:
-  node-smoke-test:
+  build-and-test:
     runs-on: ubuntu-latest
-    name: Node smoke tests
+    name: ${{ matrix.NPM_SCRIPT }} - ${{ matrix.NAME }} (${{ matrix.NODE_VERSION }})
+    strategy:
+      fail-fast: false
+      matrix:
+        NAME: ["Node"]
+        NODE_VERSION: [18.x, 20.x, 22.x, 23.x]
+        NPM_SCRIPT: ["test:browserless"]
+        include:
+          - NAME: "Node"
+            NODE_VERSION: "22.x"
+            NPM_SCRIPT: "lint"
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Use Node.js ${{ env.NODE_VERSION }}
         uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
         with:
-          node-version: ${{ env.NODE_VERSION }}
+          node-version: ${{ matrix.NODE_VERSION }}
 
       - name: Cache
         uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
         with:
           path: ~/.npm
-          key: ${{ runner.os }}-node-${{ env.NODE_VERSION }}-npm-lock-${{ hashFiles('**/package-lock.json') }}
+          key: ${{ runner.os }}-node-${{ matrix.NODE_VERSION }}-npm-lock-${{ hashFiles('**/package-lock.json') }}
           restore-keys: |
-            ${{ runner.os }}-node-${{ env.NODE_VERSION }}-npm-lock-
+            ${{ runner.os }}-node-${{ matrix.NODE_VERSION }}-npm-lock-
 
       - name: Install dependencies
         run: npm install
 
-      - name: Run Node smoke tests
-        run: npm run test:node_smoke_tests
+      - name: Run tests
+        run: npm run ${{ matrix.NPM_SCRIPT }}

.gitignore

@@ -11,9 +11,16 @@ CDN
 .eslintcache
 
 # Ignore built files in `dist` folder
-# Leave package.json
+# Leave the package.json and wrappers
 /dist/*
 !/dist/package.json
+!/dist/wrappers
+
+# Ignore built files in `dist-module` folder
+# Leave the package.json and wrappers
+/dist-module/*
+!/dist-module/package.json
+!/dist-module/wrappers
 
 /external
 /node_modules

build/command.js

@@ -0,0 +1,45 @@
+import yargs from "yargs/yargs";
+import { build } from "./tasks/build.js";
+
+const argv = yargs( process.argv.slice( 2 ) )
+	.version( false )
+	.command( {
+		command: "[options]",
+		describe: "Build a jQuery Migrate bundle"
+	} )
+	.option( "filename", {
+		alias: "f",
+		type: "string",
+		description:
+			"Set the filename of the built file. Defaults to jquery.js."
+	} )
+	.option( "dir", {
+		alias: "d",
+		type: "string",
+		description:
+			"Set the dir to which to output the built file. Defaults to /dist."
+	} )
+	.option( "version", {
+		alias: "v",
+		type: "string",
+		description:
+			"Set the version to include in the built file. " +
+			"Defaults to the version in package.json plus the " +
+			"short commit SHA and any excluded modules."
+	} )
+	.option( "watch", {
+		alias: "w",
+		type: "boolean",
+		description:
+			"Watch the source files and rebuild when they change."
+	} )
+	.option( "esm", {
+		type: "boolean",
+		description:
+			"Build an ES module (ESM) bundle. " +
+			"By default, a UMD bundle is built."
+	} )
+	.help()
+	.argv;
+
+build( argv );

build/tasks/build-default.js

@@ -22,6 +22,33 @@ async function readJSON( filename ) {
 	return JSON.parse( await read( filename ) );
 }
 
+async function getOutputRollupOptions( {
+	esm = false
+} = {} ) {
+	const wrapperFilePath = path.join( "src", `wrapper${
+		esm ? "-esm" : ""
+	}.js` );
+
+	const wrapperSource = await read( wrapperFilePath );
+
+	// Catch `// @CODE` and subsequent comment lines event if they don't start
+	// in the first column.
+	const wrapper = wrapperSource.split(
+		/[\x20\t]*\/\/ @CODE\n(?:[\x20\t]*\/\/[^\n]+\n)*/
+	);
+
+	return {
+
+		// The ESM format is not actually used as we strip it during the
+		// build, inserting our own wrappers; it's just that it doesn't
+		// generate any extra wrappers so there's nothing for us to remove.
+		format: "esm",
+
+		intro: wrapper[ 0 ].replace( /\n*$/, "" ),
+		outro: wrapper[ 1 ].replace( /^\n*/, "" )
+	};
+}
+
 async function writeCompiled( { code, dir, filename, version } ) {
 	const compiledContents = code
 
@@ -34,12 +61,12 @@ async function writeCompiled( { code, dir, filename, version } ) {
 
 	await writeFile( path.join( dir, filename ), compiledContents );
 	console.log( `[${ getTimestamp() }] ${ filename } v${ version } created.` );
-	await minify( { dir, filename, version } );
 }
 
 export async function build( {
 	dir = "dist",
 	filename = "jquery-migrate.js",
+	esm = false,
 	watch = false,
 	version
 } = {} ) {
@@ -59,24 +86,8 @@ export async function build( {
 		}`;
 	}
 
-	// Catch `// @CODE` and subsequent comment lines event if they don't start
-	// in the first column.
-	const wrapperSrc = await read( "src/wrapper.js" );
-	const wrapper = wrapperSrc.split(
-		/[\x20\t]*\/\/ @CODE\n(?:[\x20\t]*\/\/[^\n]+\n)*/
-	);
-
 	const inputRollupOptions = {};
-	const outputRollupOptions = {
-
-		// The ESM format is not actually used as we strip it during
-		// the build; it's just that it doesn't generate any extra
-		// wrappers so there's nothing for us to remove.
-		format: "esm",
-
-		intro: wrapper[ 0 ].replace( /\n*$/, "" ),
-		outro: wrapper[ 1 ].replace( /^\n*/, "" )
-	};
+	const outputRollupOptions = await getOutputRollupOptions( { esm } );
 	const src = "src/migrate.js";
 
 	inputRollupOptions.input = path.resolve( src );
@@ -122,9 +133,33 @@ export async function build( {
 		} = await bundle.generate( outputRollupOptions );
 
 		await writeCompiled( { code, dir, filename, version } );
+		await minify( { dir, filename, version } );
+	}
+}
 
+export async function buildDefaultFiles( {
+	version = process.env.VERSION,
+	watch
+} = {} ) {
+	await Promise.all( [
+		build( { version, watch } ),
+		build( {
+			dir: "dist-module",
+			filename: "jquery-migrate.module.js",
+			esm: true,
+			version,
+			watch
+		} )
+	] );
+
+	if ( watch ) {
+		console.log( "Watching files..." );
+	} else {
 		return compareSize( {
-			files: [ "dist/jquery-migrate.min.js" ]
+			files: [
+				"dist/jquery-migrate.min.js",
+				"dist-module/jquery-migrate.module.min.js"
+			]
 		} );
 	}
 }

build/tasks/build-watch.js

@@ -0,0 +1,5 @@
+// Node.js is able to import from a CommonJS module in an ESM one.
+import jQuery from "../../dist/jquery-migrate.js";
+
+export { jQuery, jQuery as $ };
+export default jQuery;

build/tasks/build.js

@@ -0,0 +1,5 @@
+"use strict";
+
+// Bundlers are able to synchronously require an ESM module from a CommonJS one.
+const { jQuery } = require( "../../dist-module/jquery-migrate.module.js" );
+module.exports = jQuery;