WIP (example) Core: Define the `exports` & `module` fields in package.json by mgol · Pull Request #5122 · jquery/jquery

mgol · 2022-09-21T17:07:51Z

Summary

module is needed for Parcel which still doesn't support exports: parcel-bundler/parcel#4155

I prepared this after reading https://nodejs.org/api/packages.html and https://webpack.js.org/guides/package-exports/. Important information is:

jQuery can be loaded & used both in the browser and in Node.js
jQuery is stateful so we need to make sure it's not loaded twice by accident (vide the Dual package hazard section from Node.js docs)
Bundling using popular bundlers (Webpack, Parcel, Vite, Browserify, etc.) should be possible

This draft contains files as they'd exist in a final package. Of course, the final PR would be different, files would be generated during the build and only included in published packages but I included them in the PR so that it can be experimented with.

Ref gh-4592

Checklist

New tests have been added to show the fix or feature works
Grunt build and unit tests pass locally with these changes
If needed, a docs issue/PR was created at https://github.com/jquery/api.jquery.com

`module` is needed for Parcel which still doesn't support `exports`: parcel-bundler/parcel#4155

mgol · 2022-09-21T17:08:41Z

An example script showing how it works in Node.js:

'use strict';

// Get a `window` implementation from jsdom and assign it to the global.
import jsdom from 'jsdom';
const { JSDOM } = jsdom;
const { window } = new JSDOM(`<!DOCTYPE html><p>Hello world</p>`);
globalThis.window = window;

// Log the jQuery slim version
const jQuerySlim = (await import('jquery/slim')).default;
console.log('jQuery slim version:', jQuerySlim?.fn?.jquery);

// Log the contents of the internal cssExpand array.
const cssExpand = (await import('jquery/src/css/var/cssExpand.js')).default;
console.log('jQuery cssExpand array:', cssExpand);

To run this example, save it as test.js in an npm project, install jsdom as a dependency and link node_modules/jquery to a clone of this branch - and run node test.js in a console.

mgol · 2022-09-21T17:15:36Z

+    "./amd/*.js": "./amd/*.js"
+  },
  "main": "dist/jquery.js",
+  "module": "dist/jquery.mjs",


Parcel doesn't support package.json exports so this field is still needed:
parcel-bundler/parcel#4155

mgol · 2022-09-21T17:20:19Z

+    "./src/*.js": "./src/*.js",
+    "./amd/*.js": "./amd/*.js"


These entries are tricky. Technically, we don't guarantee anything about files in those directories, they can come and go even in patch releases. On the other hand, we've been telling people that for advanced cases they can use our modules, taking into account these restrictions.

src contains jQuery source written in ES modules, amd those modules transpiled to AMD as jQuery 3.x & older used AMD as the source format and we wanted to still make it available to people.

The modules in src are compatible with direct usage in a browser without any bundler as well:

<script type="module"> import jQuery from "./src/jquery.js"; /* do someting with jQuery */ </script>

mgol · 2022-09-21T17:21:51Z

+    ".": {
+      "node": {
+        "module": "./dist/jquery.mjs",
+        "import": "./dist/jquery-node-wrapper.mjs",
+        "default": "./dist/jquery.js"
+      },
+      "browser": "./dist/jquery.mjs"
+    },
+    "./slim": {
+      "node": {
+        "module": "./dist/jquery.slim.mjs",
+        "import": "./dist/jquery-node-wrapper.slim.mjs",
+        "default": "./dist/jquery.slim.js"
+      },
+      "browser": "./dist/jquery.slim.mjs"
+    },


This part mostly corresponds with a recommendation from Webpack from:
https://webpack.js.org/guides/package-exports/#providing-commonjs-and-esm-version-stateful

mgol · 2022-09-21T17:33:27Z

@guybedford @jkrems @MylesBorins could you have a look?

aduh95 · 2022-09-21T17:48:45Z

+        "import": "./dist/jquery-node-wrapper.mjs",
+        "default": "./dist/jquery.js"
+      },
+      "browser": "./dist/jquery.mjs"


You probably want to add the require and default in case, that should cover most cases. I'm not sure if "browser" is needed if you already have default, but also can't hurt.

Suggested change

"browser": "./dist/jquery.mjs"

"require": "./dist/jquery.js",

"browser": "./dist/jquery.mjs",

"default": "./dist/jquery.mjs"

I would also recommend flipping around the file extensions. Use .cjs for the CommonJS version and .js for all other versions, and add "type": "module" to the package.json. I think it’s still the case that many servers/CDNs don’t serve the proper MIME type for .mjs files, so the browser version of jQuery (even the browser ESM version) should absolutely have a .js file extension for maximum compatibility.

I think it’s still the case that many servers/CDNs don’t serve the proper MIME type for .mjs files

It's been years since I've since this issue, not sure if it's worth it. (One could argue that we should be using .mjs to maximize compatibility because Node.js v10.x never got support for "type": "module"). Note that the .js files are not CJS but AMD FWIW.

It’s been years since I’ve since this issue, not sure if it’s worth it.

I think jQuery’s enormous scope justifies being careful. There’s no benefit to .mjs/.js over .cjs/.js. Node 10 doesn’t support "exports" at all; if you want to explicitly provide a Node 10-and-below ESM build, an .mjs file somewhere just for those consumers could be included. I would still save all the others as .js files as .js works everywhere.

The only reason we test on Node 10 is our Jenkins instance cannot handle anything newer. I'd like to get us away from it, though, so that shouldn't hopefully be a blocker.

Our goal is to only support Node.js versions that are supported by upstream, i.e. now 14+.

@GeoffreyBooth I'd like to understand where every entry comes from. Why do we need require, browser & default for non-Node.js cases?

I’d like to understand where every entry comes from

They’re documented here: https://nodejs.org/api/packages.html#conditional-exports

Why do we need require, browser & default for non-Node.js cases?

Others should chime in, especially @guybedford, but my understanding is that while Node reads the conditions as appropriate at runtime, the other conditions (such as "browser") are intended for bundlers. So when a build tool is creating a browser build, it’ll use the jQuery file listed under the "browser" field.

Build tools can also build for Node, of course, in which case they’ll read the other conditions too. When preparing a Node build, if jQuery is referenced via a require() call, the "require" condition will be chosen, and so on. When nothing more specific matches, "default" is chosen (which is why it must always be last).

Why do we need require […] for non-Node.js cases?

E.g. if someone uses require() to write browser focused code. If you set browser to point to the ESM file, depending on the builder it may or may not work (i.e. it would work only if the bundler supports requiring ES modules).

aduh95 · 2022-09-21T17:52:50Z

+        "import": "./dist/jquery-node-wrapper.slim.mjs",
+        "default": "./dist/jquery.slim.js"
+      },
+      "browser": "./dist/jquery.slim.mjs"


Same here.

Suggested change

"browser": "./dist/jquery.slim.mjs"

"require": "./dist/jquery.slim.js",

"browser": "./dist/jquery.slim.mjs",

"default": "./dist/jquery.slim.mjs"

ollie-iterators · 2023-04-07T14:49:51Z

Shouldn't this be put in the 4.0.0 milestone?

mgol · 2023-04-14T15:54:05Z

@ollie-iterators We have #4592 for tracking purposes; this PR is a POC of what the compiled bundles could look like; the final code will not include any built files and will need code to actually generate them so it will be a different PR.

mgol · 2023-05-22T15:39:23Z

I created a PR adding exports support & the ESM build at #5255. This WIP is no longer needed, the PR contains all the relevant details with test cases.

One important change from this POC is that I ended up just defining a single entry point for Node.js. This is because our compiled ESM version still only has a default export with the value of module.exports from the regular file - which is just what Node.js does natively if you import a CommonJS module from an ESM one. Using a single file allows to avoid the dual package hazard altogether.

WIP Core: Define the exports & module fields in package.json

16d9289

`module` is needed for Parcel which still doesn't support `exports`: parcel-bundler/parcel#4155

mgol changed the title ~~Core: Define the exports & module fields in package.json~~ WIP (example) Core: Define the exports & module fields in package.json Sep 21, 2022

mgol commented Sep 21, 2022

View reviewed changes

mgol added the Needs review label Sep 21, 2022

mgol mentioned this pull request Sep 21, 2022

ESM distribution / exports in package.json #4592

Closed

mgol requested review from dmethvin, gibson042 and timmywil September 21, 2022 17:42

aduh95 reviewed Sep 21, 2022

View reviewed changes

mgol added Core and removed Needs review Core labels Jan 15, 2023

mgol mentioned this pull request May 22, 2023

Build: Add exports to package.json, export slim & esm builds #5255

Merged

3 tasks

mgol closed this May 22, 2023

mgol deleted the package-exports-example branch July 10, 2023 18:02

github-actions Bot locked as resolved and limited conversation to collaborators Sep 24, 2025

-      "browser": "./dist/jquery.mjs"
+      "require": "./dist/jquery.js",
+      "browser": "./dist/jquery.mjs",
+      "default": "./dist/jquery.mjs"

-      "browser": "./dist/jquery.slim.mjs"
+      "require": "./dist/jquery.slim.js",
+      "browser": "./dist/jquery.slim.mjs",
+      "default": "./dist/jquery.slim.mjs"

Conversation

mgol commented Sep 21, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Checklist

Uh oh!

mgol commented Sep 21, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mgol Sep 21, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mgol commented Sep 21, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aduh95 Sep 21, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ollie-iterators commented Apr 7, 2023

Uh oh!

mgol commented Apr 14, 2023

Uh oh!

mgol commented May 22, 2023

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

mgol commented Sep 21, 2022 •

edited

Loading

mgol commented Sep 21, 2022 •

edited

Loading

mgol Sep 21, 2022 •

edited

Loading

aduh95 Sep 21, 2022 •

edited

Loading