1 | # rollup-plugin-typescript2
|
2 |
|
3 | [![npm-version](https://img.shields.io/npm/v/rollup-plugin-typescript2.svg?maxAge=259200)](https://npmjs.org/package/rollup-plugin-typescript2)
|
4 | [![npm-monthly-downloads](https://img.shields.io/npm/dm/rollup-plugin-typescript2.svg?maxAge=259200)](https://npmjs.org/package/rollup-plugin-typescript2)
|
5 | [![Node.js CI](https://github.com/ezolenko/rollup-plugin-typescript2/workflows/Node.js%20CI/badge.svg)](https://github.com/ezolenko/rollup-plugin-typescript2/actions?query=workflow%3A"Node.js+CI")
|
6 |
|
7 | Rollup plugin for typescript with compiler errors.
|
8 |
|
9 | This is a rewrite of the [original](https://github.com/rollup/rollup-plugin-typescript/tree/v0.8.1) `rollup-plugin-typescript`, starting and borrowing from [this fork](https://github.com/alexlur/rollup-plugin-typescript).
|
10 |
|
11 | This version is somewhat slower than the original, but it will print out TypeScript syntactic and semantic diagnostic messages (the main reason for using TypeScript after all).
|
12 |
|
13 | ## Installation
|
14 |
|
15 | ```bash
|
16 | # with npm
|
17 | npm install rollup-plugin-typescript2 typescript tslib --save-dev
|
18 | # with yarn
|
19 | yarn add rollup-plugin-typescript2 typescript tslib --dev
|
20 | ```
|
21 |
|
22 | ## Usage
|
23 |
|
24 | ```js
|
25 | // rollup.config.js
|
26 | import typescript from 'rollup-plugin-typescript2';
|
27 |
|
28 | export default {
|
29 | input: './main.ts',
|
30 |
|
31 | plugins: [
|
32 | typescript(/*{ plugin options }*/)
|
33 | ]
|
34 | }
|
35 | ```
|
36 |
|
37 | This plugin inherits all compiler options and file lists from your `tsconfig.json` file.
|
38 | If your `tsconfig` has another name or another relative path from the root directory, see `tsconfigDefaults`, `tsconfig`, and `tsconfigOverride` options below.
|
39 | This also allows for passing in different `tsconfig` files depending on your build target.
|
40 |
|
41 | ### Some compiler options are forced
|
42 |
|
43 | * `noEmitHelpers`: false
|
44 | * `importHelpers`: true
|
45 | * `noResolve`: false
|
46 | * `noEmit`: false (Rollup controls emit)
|
47 | * `noEmitOnError`: false (Rollup controls emit. See [#254](https://github.com/ezolenko/rollup-plugin-typescript2/issues/254) and the `abortOnError` plugin option below)
|
48 | * `inlineSourceMap`: false (see [#71](https://github.com/ezolenko/rollup-plugin-typescript2/issues/71))
|
49 | * `outDir`: `./placeholder` in cache root (see [#83](https://github.com/ezolenko/rollup-plugin-typescript2/issues/83) and [Microsoft/TypeScript#24715](https://github.com/Microsoft/TypeScript/issues/24715))
|
50 | * `declarationDir`: Rollup's `output.file` or `output.dir` (*unless `useTsconfigDeclarationDir` is true in the plugin options*)
|
51 | * `allowNonTsExtensions`: true to let other plugins on the chain generate typescript; update plugin's `include` filter to pick them up (see [#111](https://github.com/ezolenko/rollup-plugin-typescript2/issues/111))
|
52 |
|
53 | ### Some compiler options have more than one compatible value
|
54 |
|
55 | * `module`: defaults to `ES2015`. Other valid values are `ES2020`, `ES2022` and `ESNext` (required for dynamic imports, see [#54](https://github.com/ezolenko/rollup-plugin-typescript2/issues/54)).
|
56 |
|
57 | * `moduleResolution`: defaults to `node10` (same as `node`), but value from tsconfig is used if specified. Other valid (but mostly untested) values are `node16`, `nodenext` and `bundler`. If in doubt, use `node10`.
|
58 | * `classic` is [deprecated](https://www.typescriptlang.org/docs/handbook/module-resolution.html) and changed to `node10`. It also breaks this plugin, see [#12](https://github.com/ezolenko/rollup-plugin-typescript2/issues/12) and [#14](https://github.com/ezolenko/rollup-plugin-typescript2/issues/14).
|
59 |
|
60 | ### Some options need additional configuration on plugin side
|
61 |
|
62 | * `allowJs`: lets TypeScript process JS files as well. If you use it, modify this plugin's `include` option to add `"*.js+(|x)", "**/*.js+(|x)"` (might also want to `exclude` `"**/node_modules/**/*"`, as it can slow down the build significantly).
|
63 |
|
64 | ### Compatibility
|
65 |
|
66 | #### @rollup/plugin-node-resolve
|
67 |
|
68 | Must be before `rollup-plugin-typescript2` in the plugin list, especially when the `browser: true` option is used (see [#66](https://github.com/ezolenko/rollup-plugin-typescript2/issues/66)).
|
69 |
|
70 | #### @rollup/plugin-commonjs
|
71 |
|
72 | See the explanation for `rollupCommonJSResolveHack` option below.
|
73 |
|
74 | #### @rollup/plugin-babel
|
75 |
|
76 | This plugin transpiles code, but doesn't change file extensions. `@rollup/plugin-babel` only looks at code with these extensions [by default](https://github.com/rollup/plugins/tree/master/packages/babel#extensions): `.js,.jsx,.es6,.es,.mjs`. To workaround this, add `.ts` and `.tsx` to its list of extensions.
|
77 |
|
78 | ```js
|
79 | // ...
|
80 | import { DEFAULT_EXTENSIONS } from '@babel/core';
|
81 | // ...
|
82 | babel({
|
83 | extensions: [
|
84 | ...DEFAULT_EXTENSIONS,
|
85 | '.ts',
|
86 | '.tsx'
|
87 | ]
|
88 | }),
|
89 | // ...
|
90 | ```
|
91 |
|
92 | See [#108](https://github.com/ezolenko/rollup-plugin-typescript2/issues/108)
|
93 |
|
94 | ### Plugin options
|
95 |
|
96 | * `cwd`: `string`
|
97 |
|
98 | The current working directory. Defaults to `process.cwd()`.
|
99 |
|
100 | * `tsconfigDefaults`: `{}`
|
101 |
|
102 | The object passed as `tsconfigDefaults` will be merged with the loaded `tsconfig.json`.
|
103 | The final config passed to TypeScript will be the result of values in `tsconfigDefaults` replaced by values in the loaded `tsconfig.json`, replaced by values in `tsconfigOverride`, and then replaced by forced `compilerOptions` overrides on top of that (see above).
|
104 |
|
105 | For simplicity and other tools' sake, try to minimize the usage of defaults and overrides and keep everything in a `tsconfig.json` file (`tsconfig`s can themselves be chained with [`extends`](https://www.typescriptlang.org/tsconfig#extends), so save some turtles).
|
106 |
|
107 | ```js
|
108 | let defaults = { compilerOptions: { declaration: true } };
|
109 | let override = { compilerOptions: { declaration: false } };
|
110 |
|
111 | // ...
|
112 | plugins: [
|
113 | typescript({
|
114 | tsconfigDefaults: defaults,
|
115 | tsconfig: "tsconfig.json",
|
116 | tsconfigOverride: override
|
117 | })
|
118 | ]
|
119 | ```
|
120 |
|
121 | This is a [deep merge](https://lodash.com/docs/4.17.4#merge): objects are merged, arrays are merged by index, primitives are replaced, etc.
|
122 | Increase `verbosity` to `3` and look for `parsed tsconfig` if you get something unexpected.
|
123 |
|
124 | * `tsconfig`: `undefined`
|
125 |
|
126 | Path to `tsconfig.json`.
|
127 | Set this if your `tsconfig` has another name or relative location from the project directory.
|
128 |
|
129 | By default, will try to load `./tsconfig.json`, but will not fail if the file is missing, unless the value is explicitly set.
|
130 |
|
131 | * `tsconfigOverride`: `{}`
|
132 |
|
133 | See `tsconfigDefaults`.
|
134 |
|
135 | * `check`: true
|
136 |
|
137 | Set to false to avoid doing any diagnostic checks on the code.
|
138 | Setting to false is sometimes referred to as `transpileOnly` by other TypeScript integrations.
|
139 |
|
140 | * `verbosity`: 1
|
141 |
|
142 | - 0 -- Error
|
143 | - 1 -- Warning
|
144 | - 2 -- Info
|
145 | - 3 -- Debug
|
146 |
|
147 | * `clean`: false
|
148 |
|
149 | Set to true to disable the cache and do a clean build.
|
150 | This also wipes any existing cache.
|
151 |
|
152 | * `cacheRoot`: `node_modules/.cache/rollup-plugin-typescript2`
|
153 |
|
154 | Path to cache.
|
155 | Defaults to a folder in `node_modules`.
|
156 |
|
157 | * `include`: `[ "*.ts+(|x)", "**/*.ts+(|x)", "**/*.cts", "**/*.mts" ]`
|
158 |
|
159 | By default compiles all `.ts` and `.tsx` files with TypeScript.
|
160 |
|
161 | * `exclude`: `[ "*.d.ts", "**/*.d.ts", "**/*.d.cts", "**/*.d.mts" ]`
|
162 |
|
163 | But excludes type definitions.
|
164 |
|
165 | * `abortOnError`: true
|
166 |
|
167 | Bail out on first syntactic or semantic error.
|
168 | In some cases, setting this to false will result in an exception in Rollup itself (for example, unresolvable imports).
|
169 |
|
170 | * `rollupCommonJSResolveHack`: false
|
171 |
|
172 | _Deprecated_. OS native paths are now _always_ used since [`0.30.0`](https://github.com/ezolenko/rollup-plugin-typescript2/releases/0.30.0) (see [#251](https://github.com/ezolenko/rollup-plugin-typescript2/pull/251)), so this no longer has any effect -- as if it is always `true`.
|
173 |
|
174 | * `objectHashIgnoreUnknownHack`: false
|
175 |
|
176 | The plugin uses your Rollup config as part of its cache key.
|
177 | `object-hash` is used to generate a hash, but it can have trouble with some uncommon types of elements.
|
178 | Setting this option to true will make `object-hash` ignore unknowns, at the cost of not invalidating the cache if ignored elements are changed.
|
179 |
|
180 | Only enable this option if you need it (e.g. if you get `Error: Unknown object type "xxx"`) and make sure to run with `clean: true` once in a while and definitely before a release.
|
181 | (See [#105](https://github.com/ezolenko/rollup-plugin-typescript2/issues/105) and [#203](https://github.com/ezolenko/rollup-plugin-typescript2/pull/203))
|
182 |
|
183 | * `useTsconfigDeclarationDir`: false
|
184 |
|
185 | If true, declaration files will be emitted in the [`declarationDir`](https://www.typescriptlang.org/tsconfig#declarationDir) given in the `tsconfig`.
|
186 | If false, declaration files will be placed inside the destination directory given in the Rollup configuration.
|
187 |
|
188 | Set to false if any other Rollup plugins need access to declaration files.
|
189 |
|
190 | * `typescript`: peerDependency
|
191 |
|
192 | If you'd like to use a different version of TS than the peerDependency, you can import a different TypeScript module and pass it in as `typescript: require("path/to/other/typescript")`.
|
193 |
|
194 | You can also use an alternative TypeScript implementation, such as [`ttypescript`](https://github.com/cevek/ttypescript), with this option.
|
195 |
|
196 | Must be TS 2.0+; things might break if the compiler interfaces changed enough from what the plugin was built against.
|
197 |
|
198 | * `transformers`: `undefined`
|
199 |
|
200 | **experimental**, TypeScript 2.4.1+
|
201 |
|
202 | Transformers will likely be available in `tsconfig` eventually, so this is not a stable interface (see [Microsoft/TypeScript#14419](https://github.com/Microsoft/TypeScript/issues/14419)).
|
203 |
|
204 | For example, integrating [kimamula/ts-transformer-keys](https://github.com/kimamula/ts-transformer-keys):
|
205 |
|
206 | ```js
|
207 | const keysTransformer = require('ts-transformer-keys/transformer').default;
|
208 | const transformer = (service) => ({
|
209 | before: [ keysTransformer(service.getProgram()) ],
|
210 | after: []
|
211 | });
|
212 |
|
213 | // ...
|
214 | plugins: [
|
215 | typescript({ transformers: [transformer] })
|
216 | ]
|
217 | ```
|
218 |
|
219 | ### Declarations
|
220 |
|
221 | This plugin respects [`declaration: true`](https://www.typescriptlang.org/tsconfig#declaration) in your `tsconfig.json` file.
|
222 | When set, it will emit `*.d.ts` files for your bundle.
|
223 | The resulting file(s) can then be used with the `types` property in your `package.json` file as described [here](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html).<br />
|
224 | By default, the declaration files will be located in the same directory as the generated Rollup bundle.
|
225 | If you want to override this behavior and instead use [`declarationDir`](https://www.typescriptlang.org/tsconfig#declarationDir), set `useTsconfigDeclarationDir: true` in the plugin options.
|
226 |
|
227 | The above also applies to [`declarationMap: true`](https://www.typescriptlang.org/tsconfig#declarationMap) and `*.d.ts.map` files for your bundle.
|
228 |
|
229 | This plugin also respects [`emitDeclarationOnly: true`](https://www.typescriptlang.org/tsconfig#emitDeclarationOnly) and will only emit declarations (and declaration maps, if enabled) if set in your `tsconfig.json`.
|
230 | If you use `emitDeclarationOnly`, you will need another plugin to compile any TypeScript sources, such as `@rollup/plugin-babel`, `rollup-plugin-esbuild`, `rollup-plugin-swc`, etc.
|
231 | When composing Rollup plugins this way, `rollup-plugin-typescript2` will perform type-checking and declaration generation, while another plugin performs the TypeScript to JavaScript compilation.<br />
|
232 | Some scenarios where this can be particularly useful: you want to use Babel plugins on TypeScript source, or you want declarations and type-checking for your Vite builds (**NOTE**: this space has not been fully explored yet).
|
233 |
|
234 | ### Watch mode
|
235 |
|
236 | The way TypeScript handles type-only imports and ambient types effectively hides them from Rollup's watch mode, because import statements are not generated and changing them doesn't trigger a rebuild.
|
237 |
|
238 | Otherwise the plugin should work in watch mode. Make sure to run a normal build after watch session to catch any type errors.
|
239 |
|
240 | ### Requirements
|
241 |
|
242 | * TypeScript `2.4+`
|
243 | * Rollup `1.26.3+`
|
244 | * Node `6.4.0+` (basic ES6 support)
|
245 |
|
246 | ### Reporting bugs and Contributing
|
247 |
|
248 | See [CONTRIBUTING.md](./CONTRIBUTING.md)
|