diff --git a/README.md b/README.md index 16bc674..6395d6f 100644 --- a/README.md +++ b/README.md @@ -4,179 +4,17 @@ Bundle your TypeScript library with no config, powered by [esbuild](https://github.com/evanw/esbuild). -## What can it bundle? - -Anything that's supported by Node.js natively, namely `.js`, `.json`, `.mjs`. And TypeScript `.ts`, `.tsx`. - -This project is designed for bundling Node.js libraries. - -## Install - -Install it locally in your project folder: +## Quick Start ```bash -npm i tsup -D -# Or Yarn -yarn add tsup --dev +tsup ``` -You can also install it globally but it's not recommended. +This will bundle `src/index.ts` to `dist/index.js`. -## Usage +## Documentation -### Bundle files - -```bash -tsup [...files] -``` - -Files are written into `./dist`. - -You can bundle multiple files in one go: - -```bash -tsup src/index.ts src/cli.ts -``` - -This will output `dist/index.js` and `dist/cli.js`. - -Code splitting is enabled by default and supported in `cjs` and `esm` format. - -### Excluding packages - -By default tsup bundles all `import`-ed modules but `dependencies` and `peerDependencies` in your `packages.json` are always excluded, you can also use `--external ` flag to mark other packages as external. - -### Generate declaration file - -```bash -tsup index.ts --dts -``` - -This will emit `./dist/index.js` and `./dist/index.d.ts`. - -If you set multiple entry files, each entry will get a corresponding `.d.ts` file. - -### Generate sourcemap file - -```bash -tsup index.ts --sourcemap -``` - -This will emit `./dist/index.js` and `./dist/index.js.map`. - -If you set multiple entry files, each entry will get a corresponding `.map` file. - -### Bundle formats - -Supported format: `esm`, `cjs`, (default) and `iife`. - -You can bundle in multiple formats in one go: - -```bash -tsup src/index.ts --format esm,cjs,iife -``` - -That will output files in following folder structure: - -```bash -dist -├── index.mjs # esm -├── index.global.js # iife -└── index.js # cjs -``` - -If the `type` field in your `package.json` is set to `module`, the filenames will be slightly different: - -```bash -dist -├── index.js # esm -├── index.global.js # iife -└── index.cjs # cjs -``` - -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: - -```bash -tsup src/index.ts --format esm,cjs,iife --legacy-output -``` - -..which outputs to: - -```bash -dist -├── esm -│ └── index.js -├── iife -│ └── index.js -└── index.js -``` - -### ES5 support - -You can use `--target es5` or `"target": "es5"` in `tsconfig.json` to compile the code down to es5, it's processed by [buble](http://buble.surge.sh/). Some features are NOT supported by this target, namely: `for .. of`. - -### Compile-time environment variables - -You can use `--env` flag to define compile-time environment variables: - -```bash -tsup src/index.ts --env.NODE_ENV production -``` - -### Building CLI app - -When an entry file like `src/cli.ts` contains hashbang like `#!/bin/env node` tsup will automatically make the outout file executable, so you don't have to run `chmod +x dist/cli.js`. - -### Watch mode - -```bash -tsup src/index.ts --watch -``` - -### Minify output - -You can also minify the output, resulting into lower bundle sizes by using the `--minify` flag. - -```bash -tsup src/index.ts --minify -``` - -### What about type checking? - -esbuild is fast because it doesn't perform any type checking, you already get type checking from your IDE like VS Code or WebStorm. - -Additionally, if you want type checking at build time, you can enable `--dts`, which will run a real TypeScript compiler to generate declaration file so you get type checking as well. - -### 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. - -To use PostCSS, you need to install PostCSS: - -```bash -yarn add postcss --dev -``` - -..and populate a `postcss.config.js` in your project - -```js -module.exports = { - plugins: [ - require('tailwindcss')(), - require('autoprefixer')() - ] -} -``` - ---- - -For more details: - -```bash -tsup --help -``` +https://tsup.egoist.sh ## License diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..a409c0f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,179 @@ +Bundle your TypeScript library with no config, powered by [esbuild](https://github.com/evanw/esbuild). + +## What can it bundle? + +Anything that's supported by Node.js natively, namely `.js`, `.json`, `.mjs`. And TypeScript `.ts`, `.tsx`. + +This project is designed for bundling Node.js libraries. + +## Install + +Install it locally in your project folder: + +```bash +npm i tsup -D +# Or Yarn +yarn add tsup --dev +``` + +You can also install it globally but it's not recommended. + +## Usage + +### Bundle files + +```bash +tsup [...files] +``` + +Files are written into `./dist`. + +You can bundle multiple files in one go: + +```bash +tsup src/index.ts src/cli.ts +``` + +This will output `dist/index.js` and `dist/cli.js`. + +Code splitting is enabled by default and supported in `cjs` and `esm` format. + +### Excluding packages + +By default tsup bundles all `import`-ed modules but `dependencies` and `peerDependencies` in your `packages.json` are always excluded, you can also use `--external ` flag to mark other packages as external. + +### Generate declaration file + +```bash +tsup index.ts --dts +``` + +This will emit `./dist/index.js` and `./dist/index.d.ts`. + +If you set multiple entry files, each entry will get a corresponding `.d.ts` file. + +### Generate sourcemap file + +```bash +tsup index.ts --sourcemap +``` + +This will emit `./dist/index.js` and `./dist/index.js.map`. + +If you set multiple entry files, each entry will get a corresponding `.map` file. + +### Bundle formats + +Supported format: `esm`, `cjs`, (default) and `iife`. + +You can bundle in multiple formats in one go: + +```bash +tsup src/index.ts --format esm,cjs,iife +``` + +That will output files in following folder structure: + +```bash +dist +├── index.mjs # esm +├── index.global.js # iife +└── index.js # cjs +``` + +If the `type` field in your `package.json` is set to `module`, the filenames will be slightly different: + +```bash +dist +├── index.js # esm +├── index.global.js # iife +└── index.cjs # cjs +``` + +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: + +```bash +tsup src/index.ts --format esm,cjs,iife --legacy-output +``` + +..which outputs to: + +```bash +dist +├── esm +│ └── index.js +├── iife +│ └── index.js +└── index.js +``` + +### ES5 support + +You can use `--target es5` or `"target": "es5"` in `tsconfig.json` to compile the code down to es5, it's processed by [buble](http://buble.surge.sh/). Some features are NOT supported by this target, namely: `for .. of`. + +### Compile-time environment variables + +You can use `--env` flag to define compile-time environment variables: + +```bash +tsup src/index.ts --env.NODE_ENV production +``` + +### Building CLI app + +When an entry file like `src/cli.ts` contains hashbang like `#!/bin/env node` tsup will automatically make the outout file executable, so you don't have to run `chmod +x dist/cli.js`. + +### Watch mode + +```bash +tsup src/index.ts --watch +``` + +### Minify output + +You can also minify the output, resulting into lower bundle sizes by using the `--minify` flag. + +```bash +tsup src/index.ts --minify +``` + +### What about type checking? + +esbuild is fast because it doesn't perform any type checking, you already get type checking from your IDE like VS Code or WebStorm. + +Additionally, if you want type checking at build time, you can enable `--dts`, which will run a real TypeScript compiler to generate declaration file so you get type checking as well. + +### 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. + +To use PostCSS, you need to install PostCSS: + +```bash +yarn add postcss --dev +``` + +..and populate a `postcss.config.js` in your project + +```js +module.exports = { + plugins: [ + require('tailwindcss')(), + require('autoprefixer')() + ] +} +``` + +--- + +For more details: + +```bash +tsup --help +``` + +## License + +MIT © [EGOIST (Kevin Titor)](https://github.com/sponsors/egoist) diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..55e7d66 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,38 @@ + + + + + + + tsup + + + + + + + + + + + \ No newline at end of file