diff --git a/README.md b/README.md index ffb930d..8e922d3 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,8 @@ You want to avoid this strategy if: ## ESM only -If you want to **only** release as ESM just set `"module": "ES6"` in your `tsconfig.json` (and remove `esModuleInterop`). +If you want to **only** release as ESM just set `"module": "ES6"` in your `tsconfig.json` (and remove `esModuleInterop`). +You can remove [the listing of your export](https://github.com/garronej/ts-ci/blob/16dbde73a52ea7750a39f0179f121dd8927c1ee5/package.json#L21-L25) in the package.json it's not of any use. You want to avoid this strategy if: - You want your module to be usable with node. The ESM distribution produced by TypeScript is an ESM distribution @@ -94,7 +95,8 @@ If you publish scripts (your `package.json` has a `bin` property) you'll need to - Have a `tsconfig.json` that targets CSM (as by default): [example](https://github.com/garronej/tss-react/blob/main/tsconfig.json) - Perform two build, one for CJS, one for ESM. [example](https://github.com/garronej/tss-react/blob/3cab4732edaff7ba41e3f01b7524b8db47cf7f25/package.json#L43) -- Explicitly list your exports in your `package.json`, [example](https://github.com/garronej/tss-react/blob/52ee92df56ef9fc82c0608deb4c35944b82b7b74/package.json#L11-L52). +- Explicitly list your exports in your `package.json`, `"module"` the condition for bundlers +`"default"` is what will be picked up by node. [example](https://github.com/garronej/tss-react/blob/52ee92df56ef9fc82c0608deb4c35944b82b7b74/package.json#L11-L52). You want to avoid this strategy if: - You use `export default` and you want to support node in `type: module` mode. @@ -104,6 +106,20 @@ You want to avoid this strategy if: Regardless of the scenario you opt for you can always release for Deno using [Denoify](https://denoify.dev). +## CJS + A real ESM distribution, fully compliant with the standard + +Pursuing a fully compliant CJS + ESM distribution comes with caveats. It only works well if all your dependencies are adherent to the standard, a condition that [most modules fail to meet](https://github.com/mui/material-ui/issues/37335). + +This method introduces the risk of your package being simultaneously loaded in both CJS and ESM in a single application. It also poses a similar risk to your dependencies. + +Thus, proceed with this option only if it's necessary for your lazy imports to actually be lazy when your code runs on Node.js. + +- To transpile in ESM, use [`js2mjs`](https://github.com/garronej/js2mjs) to ensure your ESM distribution generated by TypeScript is fully compliant with the standard ([An external script should not be required for this!](https://github.com/microsoft/TypeScript/issues/18442)). [See Example](https://github.com/garronej/tsafe/blob/6d08839c3b0695edbc3443d21b256043cd98787b/package.json#L10-L12) +- Declare your exports using both `require` and `import`. [See Example](https://github.com/garronej/tsafe/blob/6d08839c3b0695edbc3443d21b256043cd98787b/package.json#L64-L78). + +Checkout the full example with [tsafe](https://github.com/garronej/tsafe/tree/6d08839c3b0695edbc3443d21b256043cd98787b) (use the specifically this link, the current version doesn't release an +ESM distribution anymore, it doesn't need to). + ## I have questions If you find your self thinking: @@ -115,6 +131,8 @@ If you find your self thinking: Just [start a discussion](https://github.com/garronej/ts-ci/discussions) or hit [my Twitter DM](https://twitter.com/GarroneJoseph) I'll be happy to provide further guidance. + + # FAQ