.changesets: add changesets for ESM support

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2024-12-26 21:25:37 +01:00
parent 479f9a068d
commit cb76663f9a
3 changed files with 27 additions and 0 deletions
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/cli-node': patch
---
Added `type` field to `BackstagePackageJson` type.
+17
View File
@@ -0,0 +1,17 @@
---
'@backstage/cli': minor
---
**BREAKING**: Add support for native ESM in Node.js code. This changes the behavior of dynamic import expressions in Node.js code. Typically this can be fixed by replacing `import(...)` with `require(...)`, with an `as typeof import(...)` cast if needed for types. This is because dynamic imports will no longer be transformed to `require(...)` calls, but instead be left as this. This in turn allows you to load ESM modules from CommonJS code using `import(...)`.
This change adds support for the following in Node.js packages, across type checking, package builds, runtime transforms and Jest tests:
- Dynamic imports that load ESM modules from CommonJS code.
- Both `.mjs` and `.mts` files as explicit ESM files, as well as `.cjs` and `.cts` as explicit CommonJS files.
- Support for the `"type": "module"` field in `package.json` to indicate that the package is an ESM package.
There are a few caveats to be aware of:
- Declaring a package as `"type": "module"` in `package.json` is supported, but in tests it will cause all local transitive dependencies to also be treated as ESM, regardless of whether they declare `"type": "module"` or not.
- Node.js has an [ESM interoperability layer with CommonJS](https://nodejs.org/docs/latest-v22.x/api/esm.html#interoperability-with-commonjs) that allows for imports from ESM to identify named exports in CommonJS packages. This interoperability layer is **only** enabled when importing packages with a `.cts` or `.cjs` extension. This is because the interoperability layer is not fully compatible with the NPM ecosystem, and would break package if it was enabled for `.js` files.
- Dynamic imports of CommonJS packages will vary in shape depending on the runtime, i.e. test vs local development, etc. It is therefore recommended to avoid dynamic imports of CommonJS packages and instead use `require`, or to use the explicit CommonJS extensions as mentioned above. If you do need to dynamically import CommonJS packages, avoid using `default` exports, as the shape of them vary across different environments and you would otherwise need to manually unwrap the import based on the shape of the module object.
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/repo-tools': patch
---
Internal refactor to support native ESM.