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.

Sign up for GitHub

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

Jump to bottom

docs: add CJS/ESM emit entry #986

Merged
merged 4 commits into from Oct 26, 2023
Merged

docs: add CJS/ESM emit entry #986

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5189b0d
docs: add CJS/ESM emit entry
JoshuaKGoldberg Oct 26, 2023
392bed5
Added sub-FAQ entry
JoshuaKGoldberg Oct 26, 2023
d4b555a
Better eslint-disable
JoshuaKGoldberg Oct 26, 2023
5200770
Add meta even though it's not used
JoshuaKGoldberg Oct 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
5 changes: 3 additions & 2 deletions cspell.json
View file
Open in desktop
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
View file
Open in desktop
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.

eslint/eslint-plugin-markdown#226 for now.


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