From 550c1f59e62f29084e134fc8a822171d1b5c7dfa Mon Sep 17 00:00:00 2001 From: Eli <88557639+lishaduck@users.noreply.github.com> Date: Sun, 24 Nov 2024 20:25:54 -0600 Subject: [PATCH] docs: update website I was intending on clarifying #885, but then just kept editing. --- docs/README.md | 36 ++++++++++++++++-------------------- 1 file changed, 16 insertions(+), 20 deletions(-) diff --git a/docs/README.md b/docs/README.md index 46449dd86..99ef8c957 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 ` 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 ` 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