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 | ❌ | 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: