From 51085e055c04588f764827557809e62139f5d643 Mon Sep 17 00:00:00 2001 From: garronej Date: Sun, 7 Sep 2025 12:09:33 +0200 Subject: [PATCH] Provide more up to date release strategies --- README.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 6916fa0..f751727 100644 --- a/README.md +++ b/README.md @@ -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