actions/ts-ci
2
0
Fork 0
mirror of https://github.com/garronej/ts-ci.git synced 2025-11-30 21:43:05 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Explain how to release a real ESM dist

Browse source
This commit is contained in:
garronej 2023-05-21 10:52:07 +02:00
parent 16dbde73a5
commit c87d40ce2d
1 changed files with 20 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

20
README.md
View file

@ -81,6 +81,7 @@ 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`).
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
<details>