From 4fe0d0aba1b01201e3e8109b378ae71369c1d777 Mon Sep 17 00:00:00 2001 From: Artem Khodyush Date: Wed, 21 Sep 2022 11:25:50 -0700 Subject: [PATCH 1/2] mention dual ESM/CJS type declarations in extensionless README --- examples/node_modules/extensionless/README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/examples/node_modules/extensionless/README.md b/examples/node_modules/extensionless/README.md index ca2c65e..ce975b1 100644 --- a/examples/node_modules/extensionless/README.md +++ b/examples/node_modules/extensionless/README.md @@ -16,6 +16,12 @@ import "extensionless/two"; Likewise, a non-`exports`-supporting resolver will try `./two`, `./two.js`, and this time move onto `./two/index.js`. +This is the only strategy that supports dual ESM/CJS type declarations, by using [sibling lookup](https://github.com/microsoft/TypeScript/issues/50762#issuecomment-1251293918). It's important when `moduleResolution` is set to `node16` or `nodenext`. The compiler will select appropriate vairant of the type declarations depending on the type of the file (ESM or commonjs) which is importing the library. Other strategies which are using explicit `types` fields can provide only single type declarations for both ESM and commonjs users, and that can be problematic in some cases: + +- sometimes, as has been [warned here](https://github.com/microsoft/TypeScript/issues/50794#issuecomment-1251278131) for example, it's necessary to have different declarations for EMS and commonjs to handle exports correctly + +- if the user code is commonjs, and type declarations are ESM, it will not compile - commonjs code can not use ESM imports (this applies only when `moduleResolution` is `nodenext` or `node16`) + ## Considerations Pros: @@ -23,6 +29,7 @@ Pros: - Well-supported - Simple - No configuration update needed when adding additional subpaths +- Supports dual ESM/CJS type declarations Cons: From 108e20b15a9fbbc2e22bb1ebbbbddea53c98507c Mon Sep 17 00:00:00 2001 From: Artem Khodyush Date: Wed, 21 Sep 2022 11:26:07 -0700 Subject: [PATCH 2/2] add dual ESM/CJS type declarations row to the table --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 5341b8f..d23e723 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,11 @@ Each of the two TypeScript projects successfully type checks with `npm run build Note that the [`types-versions-wildcard`](./examples/node_modules/types-versions-wildcards) fallback strategy is only fallback for TypeScript, so it does not help users who are on Node 11 or other runtimes/bundlers that lack `exports` support. It is included because it is the only method that offers an analog to `*` wildcards in subpath `exports`. | | [`extensionless`](./examples/node_modules/extensionless) | [`package-json-redirects`](./examples/node_modules/package-json-redirects) | [`types-versions-wildcards`](./examples/node_modules/types-versions-wildcards) | -|----------------------------------------|------------------|-----------------|------------------| -| TypeScript `--moduleResolution node16` | ✅ via `exports` | ✅ via `exports` | ✅ via `exports` | -| TypeScript `--moduleResolution node` | ✅ via fallback | ✅ via fallback | ✅ via fallback | -| Node 12+ | ✅ via `exports` | ✅ via `exports` | ✅ via `exports` | -| Node 11 | ✅ via fallback | ✅ via fallback | ❌ | -| Most bundlers | ✅ via `exports` | ✅ via `exports` | ✅ via `exports` | -| Parcel, Browserify | ✅ via fallback | ✅ via fallback | ❌ | +|------------------------------------------------------|-----------------------|------------------|------------------| +| TypeScript `--moduleResolution node16` | ✅ via `exports` | ✅ via `exports` | ✅ via `exports` | +| TypeScript `--moduleResolution node` | ✅ via fallback | ✅ via fallback | ✅ via fallback | +| Supports dual ESM/CJS type declarations for `node16` | ✅ via sibling lookup | no | no | +| Node 12+ | ✅ via `exports` | ✅ via `exports` | ✅ via `exports` | +| Node 11 | ✅ via fallback | ✅ via fallback | ❌ | +| Most bundlers | ✅ via `exports` | ✅ via `exports` | ✅ via `exports` | +| Parcel, Browserify | ✅ via fallback | ✅ via fallback | ❌ |