From 52f3183abe877c2108ddd2567f9771499de84e7a Mon Sep 17 00:00:00 2001 From: Stephan Schreiber Date: Fri, 2 Feb 2024 08:49:46 +0100 Subject: [PATCH] docs(fast-typescript): Update docs accordingly to recent changes --- README.md | 45 ++++++++++++++++----------------------------- 1 file changed, 16 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index ca4019e..6c16fca 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A plugin that uses esbuild, swc or sucrase (you decide!) for blazing fast TypeScript transpilation, leaving the tree-shaking and bundling tasks to Rollup (see [why](#considerations)). >⚠ Important notice ->- This plugin requires rollup version 3.2.0 or higher. +>- This plugin requires rollup version 4.0.0 or higher. >- This package is ESM-only and can only be used from an ESM configuration file (`rollup.config.mjs` or `rollup.config.js` with `type="module"` in `package.json`. See [Rollup docs](https://rollupjs.org/guide/en/#configuration-files) for more detail). ## Features @@ -41,31 +41,29 @@ import fastTypescript from 'rollup-plugin-fast-typescript' export default { ... plugins: [ - fastTypescript() + fastTypescript('esbuild') // or 'swc' or 'sucrase' ] } ``` -This will load your project's `tsconfig.json` and use `esbuild` to transpile your code to Javascript. +This will load your project's `tsconfig.json` and use the specified transformer to transpile your code to Javascript. ## Options -`rollup-plugin-fast-typescript`'s *parti pris* is to mimic the behavior of the real TypeScript compiler as closely as possible (two obvious exceptions here are type checking and declaration files generation, since none of the supported transpilers support these features), so the plugin doest not offer any option to play with other than the choice of which transpiler to use and which tsconfig file to load. - -There are basically four ways to instantiate the plugin: +`rollup-plugin-fast-typescript`'s *parti pris* is to mimic the behavior of the real TypeScript compiler as closely as possible (two obvious exceptions here are type checking and declaration files generation, since none of the supported transpilers support these features), so the plugin doest not offer any option to play with other than the choice of the transpiler to use and the tsconfig file to load. ```js -// Use the project's tsconfig.json and the default transpiler (esbuild): -fastTypescript() +fastTypescript( + transpilerName : 'esbuild' | 'swc' | 'sucrase', + tsconfig?: boolean | string | TsConfigJson | (() => MaybePromise) +) +``` -// Use the specified tsconfig and the default transpiler (esbuild): -fastTypescript(tsconfig) +### Option: `transpiler` +Type: `'esbuild' | 'swc' | 'sucrase'` -// Use the project's tsconfig.json and the specified transpiler: -fastTypescript(transpiler) +The name of the transpiler to use. -// Use the specified tsconfig and transpiler: -fastTypescript(tsconfig, transpiler) -``` +> Remember that this plugin does not ship with, nor will it install for you, any of these transpilers; it is your responsibility to install the tool you plan to use. ### Option: `tsconfig` Type: `boolean | string | TsConfigJson | (() => MaybePromise)`
@@ -80,23 +78,12 @@ Specifies how to resolve TypeScript options: - an object is assumed to be a [`TsConfigJson`](https://github.com/sindresorhus/type-fest/blob/main/source/tsconfig-json.d.ts) object. - finally, if this parameter is a function, it must return any of the above, or a promise to a any of the above. -### Option: `transpiler` -Type: `'esbuild' | 'swc' | 'sucrase'`
-Optional: yes
-Default: `'esbuild'` - -The name of the transpiler to use. - -> Remember that this plugin does not ship with, nor will it install for you, any of these transpilers; it is your responsibility to install the tool you plan to use. - ## Things you should know - The plugin aims to emit the same code TypeScript's `tsc` would have given the passed tsconfig, no more, no less. Therefore, none of the supported transpilers specificities/unique features are exposed. In the simplest case, the transpiler is just a *"get rid of type annotations"* tool -- and a very fast one, for that matter.
To achieve its goal, the plugin does its best to call the selected transpiler's `transform` API with settings derived from the passed `tsconfig.json`. For example, TypeScript's `target` setting is mapped to the transpiler's corresponding setting.
-There are a few cases where this mapping is not 100% accurate. To continue with the `target` example above, TypeScript defaults to `ES3` if the setting is not specified. This is fine with `swc` and `sucrase`, but not with `esbuild`, who supports ES5+ only. In such cases, a warning is emitted and the nearest setting is selected instead. -- Because Rollup internally works with ESM source files, the transpiler's output is always set to `'esm'`. Still, CommonJS features like `require()`, `__filename` and `__dirname` are left untouched, so you will want to ensure that either `output.format` is set to `'cjs'` in `rollup.config.mjs`, or that appropriate shims are used. +There are a few cases where this mapping is not 100% accurate. To continue with the `target` example, TypeScript defaults to `ES3` if the setting is not specified. This is fine with `swc` and `sucrase`, but not with `esbuild`, who supports ES5+ only. In such cases, a warning is emitted and the nearest setting is selected instead. +- Because Rollup internally works with ESM source files, the transpiler's output is always set to `'esm'`. Still, CommonJS features like `require()`, `__filename` and `__dirname` are left untouched, so you will want to ensure that either `output.format` is set to `'cjs'` in `rollup.config.js`, or that appropriate shims are used. - Likewise, dynamics imports are always left untouched. -- The plugin will only resolve modules with a `.json` extension when `resolveJsonModule` is true and the `module` and `moduleResolution` settings pair resolves to either `node`, `node16` or `nodeNext`.
-Note, that you sill need `@rollup/plugin-json` to bundle json files! ## About warnings @@ -115,7 +102,7 @@ You should also run `tsc --noEmit` sometime in your build steps to double check. ## Considerations Why let Rollup do the tree-shaking and bundling?, you may ask. -IMHO, Rollup is still the best at tree-shaking and bundling: it offers the more control on what can be done and, when configured properly, emits the best code possible with very little if no bloat. +IMHO, Rollup is still the best at tree-shaking and bundling. It offers the more control on what can be done and, when configured properly, emits the best code possible with very little if no bloat. So the choice here is to trade some speed in the bundling phase in exchange for power and precision. I believe this is a reasonable choice.