The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: jsnajdr <[email protected]>
Co-authored-by: aduth <[email protected]>
Co-authored-by: youknowriad <[email protected]>
Co-authored-by: anomiex <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

I'm actually a little bit surprised that we have to write it manually ourselves, I've kind expected esbuild (or some plugin) to do it for us already as it feels like a very common thing for folks building packages these days.

You are not alone who is surprised how tough it is to build fully compliant dual CJS/ESM TypeScript packages and how unprepared the common tools are. There are specialized tools like duel or tsup which are rather complex and whose inner workings are non-trivial to reproduce in a build script like ours.

Earlier this year I worked on a dual package in the Jetpack repo. Initially I tried to do my own build script, but eventually gave up and just used duel.

I think ESBuild considers relations between files primarily around bundling, which isn't how we're using it. Although to a some extent, JavaScript / Node.js is shifting toward import paths including file extensions, where this behavior of automatic extension resolution is completely unsupported in ESM (source). So if there was an expectation that the file extensions are included in the source files, we wouldn't need this code (.ts vs. .js notwithstanding).

Size Change: +746 B (+0.03%)

Total Size: 2.58 MB

_{compressed-size-action}

The current state of the PR is quite nice, although CI checks are still failing and attw is not happy 🙂

• import statements are fully resolved, so that importing ./foo is expanded into the full ./foo.js or ./foo/index.mjs or whatever, depending on import and module type
• ESM files in build-module all have .mjs extensions
• specifiers in package.json files all point to build-module/**/*.mjs files (the .mjs extension)

This should produce very nice dual ESM/CJS packages, although attw is very unhappy with the types for reasons I don't understand:

┌───────────────────┬────────────────────────────┬──────────────────────────────┐
│                   │ "@wordpress/ui"            │ "@wordpress/ui/package.json" │
├───────────────────┼────────────────────────────┼──────────────────────────────┤
│ node10            │ ❌ No types                │ 🟢 (JSON)                    │
├───────────────────┼────────────────────────────┼──────────────────────────────┤
│ node16 (from CJS) │ ❌ No types                │ 🟢 (JSON)                    │
│                   │ 🐛 Used fallback condition │                              │
├───────────────────┼────────────────────────────┼──────────────────────────────┤
│ node16 (from ESM) │ ❌ No types                │ 🟢 (JSON)                    │
│                   │ 🐛 Used fallback condition │                              │
├───────────────────┼────────────────────────────┼──────────────────────────────┤
│ bundler           │ ❌ No types                │ 🟢 (JSON)                    │
│                   │ 🐛 Used fallback condition │                              │
└───────────────────┴────────────────────────────┴──────────────────────────────┘

I'll have to debug this further.

An alternative approach would be to use .cjs extensions. There would be type: module declaration in the package.json, all the .mjs files would be .js and all files in build would be .cjs. The upside would be that we're not changing extensions of files that are used 99% of the time, i.e., the ESM ones. Less room for unexpected issues.

Reasons why things fail:

• the eslint rule import/no-unresolved apparently has problems to resolve the build-module/index.mjs files and marks import statements as bad, that's why the eslint CI check fails massively with 5k errors.
• the attw tool fails because npm pack doesn't include the build and build-module folders. There is no files field in most package.json files, and the default is to exclude .gitignored files. So, attw runs on a broken tarball. I wonder what the CI action that published the packages does differently.

I wonder what the CI action that published the packages does differently.

The CI action uses lerna publish to publish the package, and internally it doesn't use npm pack at all, but has its own function packDirectory to produce the package tarball.

We'll have to add files field to all our packages so that the contents of the published package are specified precisely. It will have a nice side-effect, we'll stop publishing the tsconfig.tsbuildinfo files and similar that shouldn't be in published NPM packages.

Some progress I made today:

• added files field to all package.json files so that the package content is exactly specified. Among other things, helps a lot with running attw on the packages.
• switched most packages to "type": "module" and renamed CJS .js files to .cjs. ESM files keep their .js extension.

There are still some wrinkles to iron out with .d.ts files, but the CI checks are green, build succeeds and the PR is mostly ready.

Fixes both #73362 and #73363.

Today I had to solve one more big problem: incompatibility in how esbuild treats default imports from CJS modules.

Consider a CJS module that exports this:

module.exports = {
  __esModule: true,
  default: function foo() { /* ... */ }
};

What happens when you import this CJS module with an ESM import statement and want to use the default export?

import foo from './foo';

The classic webpack/Babel behavior is that you get the function from the default field. That's what the __esModule field is for. It tells the bundler that the default export is not the module.exports object, but its default field. It's a CJS/ESM interop trick.

But Node.js doesn't respect these tricks and will return the module.exports object as the foo value.

What's worse is that esbuild uses the Node.js behavior when there is the type: module field in package.json. And some of our imports will stop working.

One example is

import isShallowEqual from '@wordpress/is-shallow-equal';

The is-shallow-equal package is externalized, and the real content of the module is:

module.exports = window.wp.isShallowEqual;

But the window.wp.isShallowEqual value is { __esModule: true, default: isShallowEqual, /* ... named exports */ }. Suddenly the value of the default import is not the function, it's the object.

I fixed this by adding a named isShallowEqual export to the package. Now the default export can be considered legacy and we use only the named ones. Because default exports don't work reliably when CJS/ESM interop is in play.

Another example is the react-autosize-textarea import:

import TextareaAutosize from 'react-autosize-textarea';

Again, the package exports a { __esModule: true, default } object and it doesn't work any more. I fixed this by using a named export from a sub-path:

import { TextareaAutosize } from 'react-autosize-textarea/lib/TextareaAutosize';

I'm afraid we'll see many more issues like this once we start using type: module.

@anomiex @manzoorwanijk Did you run into similar issues when using type: module in Jetpack? Or is it an esbuild-only problem?

https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/CJSOnlyExportsDefault.md has a detailed writeup on the problem.

#59087 is about the same thing with respect to @wordpress/api-fetch. Other than that, I don't recall having run into it often.

Flaky tests detected in ab6c8b2.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/20147232455
📝 Reported issues:

• [Flaky Test] should open and edit templates correctly when active_templates experiment is enabled #73752 in /test/e2e/specs/site-editor/template-id-format.spec.js