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

Update Website Docs #1252

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+16 −20
Open

Update Website Docs #1252

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
36 changes: 16 additions & 20 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -18,7 +18,7 @@ Bundle your TypeScript library with no config, powered by [esbuild](https://gith

## What can it bundle?

Anything that's supported by Node.js natively, namely `.js`, `.json`, `.mjs`. And TypeScript `.ts`, `.tsx`. [CSS support is experimental](#css-support).
Anything that's supported by Node.js natively, namely `.js`, `.json`, `.mjs`; TypeScript `.ts`, `.tsx`; and experimental [CSS support](#css-support).

## Install

@@ -191,11 +191,11 @@ tsup index.ts --dts

This will emit `./dist/index.js` and `./dist/index.d.ts`. When emitting multiple [bundle formats](#bundle-formats), one declaration file per bundle format is generated. This is required for consumers to get accurate type checking with TypeScript. Note that declaration files generated by any tool other than `tsc` are not guaranteed to be error-free, so it's a good idea to test the output with `tsc` or a tool like [@arethetypeswrong/cli](https://www.npmjs.com/package/@arethetypeswrong/cli) before publishing.

If you have multiple entry files, each entry will get a corresponding `.d.ts` file. So when you only want to generate declaration file for a single entry, use `--dts <entry>` format, e.g. `--dts src/index.ts`.
If you have multiple entry files, each entry will get a corresponding `.d.ts` file. So when you only want to generate declaration file for a single entry, use `--dts <entry>` format, e.g., `--dts src/index.ts`.

Note that `--dts` does not resolve external (aka in `node_modules`) types used in the `.d.ts` file, if that's somehow a requirement, try the experimental `--dts-resolve` flag instead.

Since tsup version 8.0.0, you can also use `--experimental-dts` flag to generate declaration files. This flag use [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) to generate declaration files, which is more reliable than the previous `--dts` flag. It's still experimental and we are looking for feedbacks.
Since tsup version 8.0.0, you can also use `--experimental-dts` flag to generate declaration files. This flag use [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) to generate declaration files, which is more reliable than the previous `--dts` flag. It's still experimental, and doesn't support all of the options of the standard `--dts` flag. Please share your feedback!

To use `--experimental-dts`, you would need to install `@microsoft/api-extractor`, as it's a peer dependency of tsup:

@@ -211,13 +211,9 @@ The `--dts-only` flag is the equivalent of the `emitDeclarationOnly` option in `

#### Generate TypeScript declaration maps (.d.ts.map)

TypeScript declaration maps are mainly used to quickly jump to type definitions in the context of a monorepo (see [source issue](https://github.com/Microsoft/TypeScript/issues/14479) and [official documentation](https://www.typescriptlang.org/tsconfig/#declarationMap)).
TypeScript declaration maps are used to jump to the actual source instead of declaration files (see the [source issue](https://github.com/Microsoft/TypeScript/issues/14479) and [official documentation](https://www.typescriptlang.org/tsconfig/#declarationMap)).

They should not be included in a published NPM package and should not be confused with sourcemaps.

[Tsup is not able to generate those files](https://github.com/egoist/tsup/issues/564). Instead, you should use the TypeScript compiler directly, by running the following command after the build is done: `tsc --emitDeclarationOnly --declaration`.

You can combine this command with Tsup [`onSuccess`](https://tsup.egoist.dev/#onsuccess) callback.
[tsup is not able to generate those files](https://github.com/egoist/tsup/issues/564). Instead, you should use the TypeScript compiler directly, by running the following command after the build is done: `tsc --emitDeclarationOnly --declaration`. If you want to run this as part of your tsup invocation, you can leverage the [`onSuccess`](https://tsup.egoist.dev/#onsuccess) option.

### Generate sourcemap file

@@ -235,7 +231,7 @@ If you want to inline sourcemap, you can try:
tsup index.ts --sourcemap inline
```

> Warning: Note that inline sourcemap is solely used for development, e.g. when developing a browser extension and the access to `.map` file is not allowed, and it's not recommended for production.
> Warning: Note that inline sourcemaps are solely used for development, e.g., for when developing a browser extension and the access to the `.map` file is not allowed, and it's not recommended for production.

> Warning: Source map is not supported in `--dts` build.

@@ -269,7 +265,7 @@ dist

Read more about [`esm` support in Node.js](https://nodejs.org/api/esm.html#esm_enabling).

If you don't want extensions like `.mjs` or `.cjs`, e.g. you want your library to be used in a bundler (or environment) that doesn't support those, you can enable `--legacy-output` flag:
If you don't want extensions like `.mjs` or `.cjs`, e.g., you want your library to be used in a bundler (or environment) that doesn't support those, you can enable `--legacy-output` flag:

```bash
tsup src/index.ts --format esm,cjs,iife --legacy-output
@@ -509,29 +505,29 @@ Additionally, if you want type checking at build time, you can enable `--dts`, w

### CSS support

esbuild has [experimental CSS support](https://esbuild.github.io/content-types/#css), and tsup allows you to use PostCSS plugins on top of native CSS support.
esbuild has [experimental CSS support](https://esbuild.github.io/content-types/#css), and tsup allows you to use PostCSS plugins on top of it.

To use PostCSS, you need to install PostCSS:
To use PostCSS, you'll need to separately install PostCSS:

```bash
npm i postcss -D
npm install -D postcss
# Or Yarn
yarn add postcss --dev
yarn add --dev postcss
```

..and populate a `postcss.config.js` in your project
...and populate a `postcss.config.js` in your project

```js
module.exports = {
plugins: [require('tailwindcss')(), require('autoprefixer')()],
}
module.exports = /** @satisfies {import('postcss-load-config').Config} */ ({
plugins: [require('postcss-preset-env')],
})
```

### Metafile

Passing `--metafile` flag to tell esbuild to produce some metadata about the build in JSON format. You can feed the output file to analysis tools like [bundle buddy](https://www.bundle-buddy.com/esbuild) to visualize the modules in your bundle and how much space each one takes up.

The file outputs as `metafile-{format}.json`, e.g. `tsup --format cjs,esm` will generate `metafile-cjs.json` and `metafile-esm.json`.
The file outputs as `metafile-{format}.json`, e.g., `tsup --format cjs,esm` will generate `metafile-cjs.json` and `metafile-esm.json`.

### Custom esbuild plugin and options