Skip to content

Commit

Permalink
docs: add CJS/ESM emit entry (#986)
Browse files Browse the repository at this point in the history
## 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...!
  • Loading branch information
JoshuaKGoldberg committed Oct 26, 2023
1 parent 76a7518 commit 88f87b1
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 2 deletions.
5 changes: 3 additions & 2 deletions cspell.json
Expand Up @@ -11,6 +11,7 @@
"words": [
"allcontributors",
"apexskier",
"arethetypeswrong",
"Codecov",
"codespace",
"commitlint",
Expand All @@ -32,7 +33,7 @@
"tada",
"tsup",
"Unstaged",
"wontfix",
"vitest"
"vitest",
"wontfix"
]
}
47 changes: 47 additions & 0 deletions docs/FAQs.md
Expand Up @@ -7,6 +7,53 @@ 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:

<!-- eslint-disable jsonc/sort-keys -->

```jsonc package.json
{
"exports": {
".": {
"types": {
"import": "./lib/index.d.ts",
"require": "./lib/index.d.cts"
},
"import": "./lib/index.js",
"require": "./lib/index.cjs"
}
}
}
```

<!-- eslint-enable jsonc/sort-keys -->

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)

### 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.
Expand Down

0 comments on commit 88f87b1

Please sign in to comment.