Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add CJS/ESM emit entry #986

Merged
merged 4 commits into from
Oct 26, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions cspell.json
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
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 -->
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


```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