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

.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.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"
+			]
 		} );
 	}
 }

dist-module/wrappers/jquery-migrate.node-module-wrapper.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;

dist/wrappers/jquery-migrate.bundler-require-wrapper.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;

eslint.config.js

@@ -12,7 +12,13 @@ export default [
 	},
 
 	{
-		files: [ "eslint.config.js", "build/**" ],
+		files: [
+			"eslint.config.js",
+			".release-it.cjs",
+			"build/**",
+			"test/node_smoke_tests/**",
+			"test/bundler_smoke_tests/**/*"
+		],
 		languageOptions: {
 			ecmaVersion: "latest",
 			globals: {
@@ -60,18 +66,44 @@ export default [
 		}
 	},
 
+	{
+		files: [
+			"src/wrapper.js",
+			"src/wrapper-esm.js",
+			"src/wrapper-factory.js",
+			"src/wrapper-factory-esm.js"
+		],
+		languageOptions: {
+			globals: {
+				jQuery: false
+			}
+		},
+		rules: {
+			"no-unused-vars": "off",
+			indent: [
+				"error",
+				"tab",
+				{
+
+					// This makes it so code within the wrapper is not indented.
+					ignoredNodes: [
+						"Program > FunctionDeclaration > *"
+					]
+				}
+			]
+		}
+	},
+
 	{
 		files: [ "src/wrapper.js" ],
 		languageOptions: {
 			sourceType: "script",
 			globals: {
-				jQuery: false,
 				define: false,
 				module: false
 			}
 		},
 		rules: {
-			"no-unused-vars": "off",
 			indent: [
 				"error",
 				"tab",
@@ -203,5 +235,21 @@ export default [
 			ecmaVersion: 5,
 			sourceType: "script"
 		}
+	},
+
+	{
+		files: [ "dist-module/**" ],
+		languageOptions: {
+			ecmaVersion: 2015,
+			sourceType: "module"
+		}
+	},
+
+	{
+		files: [ "dist/wrappers/*.js" ],
+		languageOptions: {
+			ecmaVersion: 2015,
+			sourceType: "commonjs"
+		}
 	}
 ];