Skip to content

Commit 88f87b1

Browse files
docs: add CJS/ESM emit entry (#986)
## PR Checklist - [x] Addresses an existing open issue: fixes #942 - [x] That issue was marked as [`status: accepting prs`](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22) - [x] Steps in [CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/create-typescript-app/blob/main/.github/CONTRIBUTING.md) were taken ## Overview I'm a little pleasantly surprised to remember that it's only two steps...!
1 parent 76a7518 commit 88f87b1

File tree

2 files changed

+50
-2
lines changed

2 files changed

+50
-2
lines changed

cspell.json

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
"words": [
1212
"allcontributors",
1313
"apexskier",
14+
"arethetypeswrong",
1415
"Codecov",
1516
"codespace",
1617
"commitlint",
@@ -32,7 +33,7 @@
3233
"tada",
3334
"tsup",
3435
"Unstaged",
35-
"wontfix",
36-
"vitest"
36+
"vitest",
37+
"wontfix"
3738
]
3839
}

docs/FAQs.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,53 @@ After you set up a repository, you can substitute in any tools you'd like.
77

88
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.
99

10+
## How can I add dual CommonJS / ECMAScript Modules emit?
11+
12+
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.
13+
14+
Then:
15+
16+
1. In `tsup.config.ts`, change the [tsup `format` option](https://tsup.egoist.dev/#bundle-formats) from `["esm"]` to `["cjs", "esm"]`
17+
2. Add a [`package.json` `"exports"` entry](https://nodejs.org/api/packages.html#subpath-exports) like:
18+
19+
<!-- eslint-disable jsonc/sort-keys -->
20+
21+
```jsonc package.json
22+
{
23+
"exports": {
24+
".": {
25+
"types": {
26+
"import": "./lib/index.d.ts",
27+
"require": "./lib/index.d.cts"
28+
},
29+
"import": "./lib/index.js",
30+
"require": "./lib/index.cjs"
31+
}
32+
}
33+
}
34+
```
35+
36+
<!-- eslint-enable jsonc/sort-keys -->
37+
38+
That should be it!
39+
40+
To be safe, consider checking with [arethetypeswrong](https://arethetypeswrong.github.io):
41+
42+
1. Run `pnpm build`
43+
2. Run `npm pack`
44+
3. Upload that generated `.tgz` file to [arethetypeswrong.github.io](https://arethetypeswrong.github.io)
45+
46+
### Why doesn't `create-typescript-app` have an option to dual emit CJS and ESM?
47+
48+
Dual CJS/ESM emit is a stopgap solution while the JavaScript ecosystem migrates towards full ESM support in most-to-all popular user packages.
49+
Most packages newly created with `create-typescript-app` should target just ESM by default.
50+
51+
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.
52+
That's reasonable.
53+
54+
Unless you know a package needs to support a CJS consumer, please strongly consider keeping it ESM-only (the `create-typescript-app` default).
55+
ESM-only packages have a smaller footprint by virtue of including fewer files.
56+
1057
## Is there a way to pull in template updates to previously created repositories?
1158

1259
Not directly.

0 commit comments

Comments
 (0)