Provide more up to date release strategies

This commit is contained in:
garronej 2025-09-07 12:09:33 +02:00
parent 4ea81f8826
commit 51085e055c

View file

@ -81,6 +81,13 @@ By default your module release [in CommonJS (CJS)](https://github.com/garronej/t
You want to avoid this strategy if:
- You make use of async imports (`import(...).then(...))`).
- You want your module to be usable in node `type: module` mode *AND* you have some `export default` (if you don't have export default it will work just fine).
- Your lib will be use by Angular, if you only provide CJS you'll get warnings like
"CommonJS or AMD dependencies can cause optimization bailouts."
- Your lib is a libraries of utilities (like [tsafe](https://github.com/garronej/tsafe)) and you would
like to prevent your user from having to cherry pick what they import like: `import { assert } from "tsafe/assert"; import { is } from "tsafe/is";...` and instead enable automatic three shaking when they import
`import { assert, is } from "tsafe";`.
## ESM only
@ -103,12 +110,14 @@ 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`, `"module"` the condition for bundlers
- Explicitly list your exports in your `package.json`, use `"module"`, the condition for bundlers like Vite or Next.js,
`"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.
- You have lazy import (`import(...).then(...)`) and you want them to be lazy not only on the browser but on node too.
- You want automatic tree shaking when importing from index (see explanation above)
- Your package is susceptible to be a peer dependency, you can end up with duplication.
## Deno
@ -120,12 +129,11 @@ Pursuing a fully compliant CJS + ESM distribution comes with caveats. It only wo
This method introduces the risk of your package being simultaneously loaded in both CJS and ESM in a single node 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.
Thus, proceed with this option only if it's necessary for your lazy imports to actually be lazy when your code runs on Node and you want to be able to have tree shaking.
This approach is only risk free if you are not susceptible to be a peer dependency and you have no dependency.
- 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).
- To transpile in ESM using `tsc`, use [`js2mjs`](https://github.com/garronej/js2mjs) and [`ts-add-js-extension`](https://www.npmjs.com/package/ts-add-js-extension) to create a fully compliant ESM distribution. See example [here with tsafe](https://github.com/garronej/tsafe/blob/f97578296b996c7244866087e19877f6cc5cdea5/package.json#L10-L12). (Side note: [An external script should not be required for this!](https://github.com/microsoft/TypeScript/issues/18442)).
- Declare your exports using both `require` and `import`. See example with [the package.js of tsafe](https://www.npmjs.com/package/tsafe?activeTab=code).
## I have questions