From 5189b0d85c945ada506a3b1048378305591b56eb Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 26 Oct 2023 10:13:18 +0300 Subject: [PATCH 1/4] docs: add CJS/ESM emit entry --- cspell.json | 5 +++-- docs/FAQs.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/cspell.json b/cspell.json index 7dc76f626..386ca4223 100644 --- a/cspell.json +++ b/cspell.json @@ -11,6 +11,7 @@ "words": [ "allcontributors", "apexskier", + "arethetypeswrong", "Codecov", "codespace", "commitlint", @@ -32,7 +33,7 @@ "tada", "tsup", "Unstaged", - "wontfix", - "vitest" + "vitest", + "wontfix" ] } diff --git a/docs/FAQs.md b/docs/FAQs.md index ff8405683..e606b7252 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -7,6 +7,36 @@ After you set up a repository, you can substitute in any tools you'd like. If you think the tool would be broadly useful to most consumers of this template, feel free to [file a feature request](https://github.com/JoshuaKGoldberg/create-typescript-app/issues/new?assignees=&labels=type%3A+feature&projects=&template=03-feature.yml&title=%F0%9F%9A%80+Feature%3A+%3Cshort+description+of+the+feature%3E) to add it in. +## How can I add dual CommonJS / ECMAScript Modules emit? + +First, I'd suggest reading [TypeScript Handbook > Modules - Introduction](https://www.typescriptlang.org/docs/handbook/modules/introduction.html) to understand how CommonJS (CJS) and ECMAScript (ESM) came to be. + +Then: + +1. In `tsup.config.ts`, change the [tsup `format` option](https://tsup.egoist.dev/#bundle-formats) from `["esm"]` to `["cjs", "esm"]` +2. Add a [`package.json` `"exports"` entry](https://nodejs.org/api/packages.html#subpath-exports) like: + + ```jsonc + "exports": { + ".": { + "types": { + "import": "./lib/index.d.ts", + "require": "./lib/index.d.cts" + }, + "import": "./lib/index.js", + "require": "./lib/index.cjs" + } + } + ``` + +That should be it! + +To be safe, consider checking with [arethetypeswrong](https://arethetypeswrong.github.io): + +1. Run `pnpm build` +2. Run `npm pack` +3. Upload that generated `.tgz` file to [arethetypeswrong.github.io](https://arethetypeswrong.github.io) + ## Is there a way to pull in template updates to previously created repositories? Not directly. From 392bed5a9883b6117fc7534da5278a6315c035ce Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 26 Oct 2023 10:32:21 +0300 Subject: [PATCH 2/4] Added sub-FAQ entry --- docs/FAQs.md | 32 +++++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/docs/FAQs.md b/docs/FAQs.md index e606b7252..95c2631c1 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -17,15 +17,18 @@ Then: 2. Add a [`package.json` `"exports"` entry](https://nodejs.org/api/packages.html#subpath-exports) like: ```jsonc - "exports": { - ".": { - "types": { - "import": "./lib/index.d.ts", - "require": "./lib/index.d.cts" - }, - "import": "./lib/index.js", - "require": "./lib/index.cjs" - } + { + "exports": { + ".": { + "types": { + "import": "./lib/index.d.ts", + "require": "./lib/index.d.cts" + }, + // eslint-disable-next-line jsonc/sort-keys + "import": "./lib/index.js", + "require": "./lib/index.cjs" + } + } } ``` @@ -37,6 +40,17 @@ To be safe, consider checking with [arethetypeswrong](https://arethetypeswrong.g 2. Run `npm pack` 3. Upload that generated `.tgz` file to [arethetypeswrong.github.io](https://arethetypeswrong.github.io) +### Why doesn't `create-typescript-app` have an option to dual emit CJS and ESM? + +Dual CJS/ESM emit is a stopgap solution while the JavaScript ecosystem migrates towards full ESM support in most-to-all popular user packages. +Most packages newly created with `create-typescript-app` should target just ESM by default. + +Some packages published with `create-typescript` legitimately need dual CJS/ESM output because they're used by frameworks that don't yet fully support ESM. +That's reasonable. + +Unless you know a package needs to support a CJS consumer, please strongly consider keeping it ESM-only (the `create-typescript-app` default). +ESM-only packages have a smaller footprint by virtue of including fewer files. + ## Is there a way to pull in template updates to previously created repositories? Not directly. From d4b555a38421af3ebdd96f3a7196e82b528a1903 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 26 Oct 2023 10:40:53 +0300 Subject: [PATCH 3/4] Better eslint-disable --- docs/FAQs.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/FAQs.md b/docs/FAQs.md index 95c2631c1..1fe29b1f1 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -16,6 +16,8 @@ Then: 1. In `tsup.config.ts`, change the [tsup `format` option](https://tsup.egoist.dev/#bundle-formats) from `["esm"]` to `["cjs", "esm"]` 2. Add a [`package.json` `"exports"` entry](https://nodejs.org/api/packages.html#subpath-exports) like: + + ```jsonc { "exports": { @@ -24,7 +26,6 @@ Then: "import": "./lib/index.d.ts", "require": "./lib/index.d.cts" }, - // eslint-disable-next-line jsonc/sort-keys "import": "./lib/index.js", "require": "./lib/index.cjs" } @@ -32,6 +33,8 @@ Then: } ``` + + That should be it! To be safe, consider checking with [arethetypeswrong](https://arethetypeswrong.github.io): From 520077010925ece32be579912efec62d7218ec31 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 26 Oct 2023 10:49:32 +0300 Subject: [PATCH 4/4] Add meta even though it's not used --- docs/FAQs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/FAQs.md b/docs/FAQs.md index 1fe29b1f1..217d5e5cc 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -18,7 +18,7 @@ Then: - ```jsonc + ```jsonc package.json { "exports": { ".": {