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)
|
5 | [![Codeship Status](https://app.codeship.com/projects/fe9cf8f0-e8d4-0134-ec88-4e3d33dcd7ed/status?branch=master)](https://app.codeship.com/projects/207445)
|
6 | [![Codacy Badge](https://api.codacy.com/project/badge/Grade/e19b72ab9658405bbfb32dd6d65d1856)](https://www.codacy.com/app/zolenkoe/rollup-plugin-typescript2?utm_source=github.com&utm_medium=referral&utm_content=ezolenko/rollup-plugin-typescript2&utm_campaign=Badge_Grade)
|
7 | [![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")
|
8 |
|
9 | Rollup plugin for typescript with compiler errors.
|
10 |
|
11 | This is a rewrite of original rollup-plugin-typescript, starting and borrowing from [this fork](https://github.com/alexlur/rollup-plugin-typescript).
|
12 |
|
13 | This version is somewhat slower than original, but it will print out typescript syntactic and semantic diagnostic messages (the main reason for using typescript after all).
|
14 |
|
15 | ## Installation
|
16 |
|
17 | ```bash
|
18 | # with npm
|
19 | npm install rollup-plugin-typescript2 typescript tslib --save-dev
|
20 | # with yarn
|
21 | yarn add rollup-plugin-typescript2 typescript tslib --dev
|
22 | ```
|
23 |
|
24 | ## Usage
|
25 |
|
26 | ```js
|
27 | // rollup.config.js
|
28 | import typescript from 'rollup-plugin-typescript2';
|
29 |
|
30 | export default {
|
31 | input: './main.ts',
|
32 |
|
33 | plugins: [
|
34 | typescript(/*{ plugin options }*/)
|
35 | ]
|
36 | }
|
37 | ```
|
38 |
|
39 | The plugin inherits all compiler options and file lists from your `tsconfig.json` file. If your tsconfig has another name or another relative path from the root directory, see `tsconfigDefaults`, `tsconfig` and `tsconfigOverride` options below. 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
|
47 | * `inlineSourceMap`: false (see [#71](https://github.com/ezolenko/rollup-plugin-typescript2/issues/71))
|
48 | * `outDir`: `./placeholder` in cache root, see [83](https://github.com/ezolenko/rollup-plugin-typescript2/issues/83) and [Microsoft/TypeScript/issues/24715](https://github.com/Microsoft/TypeScript/issues/24715)
|
49 | * `declarationDir`: Rollup's `output.file` or `output.dir` (*only if `useTsconfigDeclarationDir` is false in the plugin options*)
|
50 | * `moduleResolution`: `node` (*`classic` is [deprecated](https://www.typescriptlang.org/docs/handbook/module-resolution.html). 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)*)
|
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 value is `ESNext` (required for dynamic imports, see [#54](https://github.com/ezolenko/rollup-plugin-typescript2/issues/54)).
|
56 |
|
57 | #### Some options need additional configuration on plugin side
|
58 |
|
59 | * `allowJs`: lets typescript process js files as well, if you use it, modify plugin's `include` option to add `"*.js+(|x)", "**/*.js+(|x)"` (might want to exclude node_modules, it will slow down the build significantly).
|
60 |
|
61 | ### Compatibility
|
62 |
|
63 | #### rollup-plugin-node-resolve
|
64 |
|
65 | Must be before rollup-plugin-typescript2 in the plugin list, especially when `browser: true` option is used, see [#66](https://github.com/ezolenko/rollup-plugin-typescript2/issues/66)
|
66 |
|
67 | #### rollup-plugin-commonjs
|
68 |
|
69 | See explanation for `rollupCommonJSResolveHack` option below.
|
70 |
|
71 | #### rollup-plugin-babel
|
72 |
|
73 | This plugin transpiles code, but doesn't change file extension. Babel plugin, even though it claims it processes all files, only looks at code with those extensions by default: `.js,.jsx,.es6,.es,.mjs`. To workaround add `ts` and `tsx` to the list of babel extensions.
|
74 |
|
75 | ```js
|
76 | ...
|
77 | import { DEFAULT_EXTENSIONS } from '@babel/core';
|
78 | ...
|
79 | babel({
|
80 | extensions: [
|
81 | ...DEFAULT_EXTENSIONS,
|
82 | '.ts',
|
83 | '.tsx'
|
84 | ]
|
85 | }),
|
86 | ...
|
87 | ```
|
88 |
|
89 | See [#108](https://github.com/ezolenko/rollup-plugin-typescript2/issues/108)
|
90 |
|
91 | ### Plugin options
|
92 |
|
93 | * `cwd`: `string`
|
94 |
|
95 | The current work directory, default `process.cwd()`.
|
96 |
|
97 | * `tsconfigDefaults`: `{}`
|
98 |
|
99 | The object passed as `tsconfigDefaults` will be merged with loaded `tsconfig.json`. Final config passed to typescript will be the result of values in `tsconfigDefaults` replaced by values in loaded `tsconfig.json`, replaced by values in `tsconfigOverride` and then replaced by hard `compilerOptions` overrides on top of that (see above).
|
100 |
|
101 | For simplicity and other tools' sake, try to minimize usage of defaults and overrides and keep everything in `tsconfig.json` file (tsconfigs can themselves be chained, so save some turtles).
|
102 |
|
103 | ```js
|
104 | let defaults = { compilerOptions: { declaration: true } };
|
105 | let override = { compilerOptions: { declaration: false } };
|
106 |
|
107 | // ...
|
108 | plugins: [
|
109 | typescript({
|
110 | tsconfigDefaults: defaults,
|
111 | tsconfig: "tsconfig.json",
|
112 | tsconfigOverride: override
|
113 | })
|
114 | ]
|
115 | ```
|
116 |
|
117 | This is a [deep merge](https://lodash.com/docs/4.17.4#merge) (objects are merged, arrays are concatenated, primitives are replaced, etc), increase `verbosity` to 3 and look for `parsed tsconfig` if you get something unexpected.
|
118 |
|
119 | * `tsconfig`: `undefined`
|
120 |
|
121 | Path to `tsconfig.json`. Set this if your tsconfig has another name or relative location from the project directory. By default will try to load `./tsconfig.json`, but will not fail if file is missing unless the value is set explicitly.
|
122 |
|
123 | * `tsconfigOverride`: `{}`
|
124 |
|
125 | See `tsconfigDefaults`.
|
126 |
|
127 | * `check`: true
|
128 |
|
129 | Set to false to avoid doing any diagnostic checks on the code.
|
130 |
|
131 | * `verbosity`: 1
|
132 |
|
133 | - 0 -- Error
|
134 | - 1 -- Warning
|
135 | - 2 -- Info
|
136 | - 3 -- Debug
|
137 |
|
138 | * `clean`: false
|
139 |
|
140 | Set to true for clean build (wipes out cache on every build).
|
141 |
|
142 | * `cacheRoot`: `node_modules/.cache/rollup-plugin-typescript2`
|
143 |
|
144 | Path to cache. Defaults to a folder in node_modules.
|
145 |
|
146 | * `include`: `[ "*.ts+(|x)", "**/*.ts+(|x)" ]`
|
147 |
|
148 | By default passes all .ts files through typescript compiler.
|
149 |
|
150 | * `exclude`: `[ "*.d.ts", "**/*.d.ts" ]`
|
151 |
|
152 | But excludes type definitions.
|
153 |
|
154 | * `abortOnError`: true
|
155 |
|
156 | Bail out on first syntactic or semantic error. In some cases setting this to false will result in exception in rollup itself (for example for unresolvable imports).
|
157 |
|
158 | * `rollupCommonJSResolveHack`: false
|
159 |
|
160 | On windows typescript resolver favors POSIX path, while commonjs plugin (and maybe others?) uses native path as module id. This can result in `namedExports` being ignored if rollup happened to use typescript's resolution. Set to true to pass resolved module path through `resolve()` to match up with `rollup-plugin-commonjs`.
|
161 |
|
162 | `rollup-plugin-commonjs` fixed this in `10.1.0`, so projects using this option who update to new version will be broken again.
|
163 |
|
164 | This also works around the similar bug affecting code splitting (see [rollup/issues/3094](https://github.com/rollup/rollup/issues/3094)).
|
165 |
|
166 | * `objectHashIgnoreUnknownHack`: false
|
167 |
|
168 | The plugin uses rollup config as part of cache key. `object-hash` is used to generate a hash, but it can have trouble with some uncommon types of elements. Setting this option to true will make `object-hash` ignore unknowns, at the cost of not invalidating the cache if ignored elements are changed. Only enable this if you need it (`Error: Unknown object type "xxx"` for example) and make sure to run with `clean: true` once in a while and definitely before a release. (See [#105](https://github.com/ezolenko/rollup-plugin-typescript2/issues/105) and [#203](https://github.com/ezolenko/rollup-plugin-typescript2/pull/203))
|
169 |
|
170 | * `useTsconfigDeclarationDir`: false
|
171 |
|
172 | If true, declaration files will be emitted in the directory given in the tsconfig. If false, the declaration files will be placed inside the destination directory given in the Rollup configuration.
|
173 |
|
174 | Set to false if any other rollup plugins need access to declaration files.
|
175 |
|
176 | * `typescript`: typescript module installed with the plugin
|
177 |
|
178 | When typescript version installed by the plugin (latest 2.x) is unacceptable, you can import your own typescript module and pass it in as `typescript: require("path/to/other/typescript")`. Must be 2.0+, things might break if transpiler interfaces changed enough from what the plugin was built against.
|
179 |
|
180 | * `transformers`: `undefined`
|
181 |
|
182 | **experimental**, typescript 2.4.1+
|
183 |
|
184 | Transformers will likely be available in tsconfig eventually, so this is not a stable interface, see [Microsoft/TypeScript/issues/14419](https://github.com/Microsoft/TypeScript/issues/14419).
|
185 |
|
186 | For example, integrating [kimamula/ts-transformer-keys](https://github.com/kimamula/ts-transformer-keys):
|
187 |
|
188 | ```js
|
189 | const keysTransformer = require('ts-transformer-keys/transformer').default;
|
190 | const transformer = (service) => ({
|
191 | before: [ keysTransformer(service.getProgram()) ],
|
192 | after: []
|
193 | });
|
194 |
|
195 | // ...
|
196 | plugins: [
|
197 | typescript({ transformers: [transformer] })
|
198 | ]
|
199 | ```
|
200 |
|
201 | ### Declarations
|
202 |
|
203 | This plugin respects `declaration: true` in your `tsconfig.json` file. When set, it will emit `*.d.ts` files for your bundle. 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).
|
204 | By default, the declaration files will be located in the same directory as the generated Rollup bundle. If you want to override this behavior and instead use the declarationDir set `useTsconfigDeclarationDir` to `true` in the plugin options.
|
205 |
|
206 | ### Watch mode
|
207 |
|
208 | The way typescript handles type-only imports and ambient types effectively hides them from rollup watch, because import statements are not generated and changing them doesn't trigger a rebuild.
|
209 |
|
210 | Otherwise the plugin should work in watch mode. Make sure to run a normal build after watch session to catch any type errors.
|
211 |
|
212 | ### Requirements
|
213 |
|
214 | TypeScript `2.4+`
|
215 | Rollup `1.26.3+`
|
216 | Node `6.4.0+` (basic es6 support)
|
217 |
|
218 | ### Reporting bugs
|
219 |
|
220 | Report any bugs on github: <https://github.com/ezolenko/rollup-plugin-typescript2/issues>.
|
221 |
|
222 | Attach your `tsconfig.json`, `package.json` (for versions of dependencies), rollup script and anything else that could influence module resolution, ambient types and typescript compilation.
|
223 |
|
224 | Check if problem is reproducible after running `npm prune` to clear any rogue types from npm_modules (by default typescript grabs all ambient types).
|
225 |
|
226 | Check if you get the same problem with `clean` option set to true (might indicate a bug in the cache).
|
227 |
|
228 | If makes sense, check if running `tsc` directly produces similar results.
|
229 |
|
230 | Attach plugin output with `verbosity` option set to 3 (this will list all files being transpiled and their imports).
|
231 |
|
232 | ### Contributing
|
233 |
|
234 | Use the normal github process of forking, making a branch and creating a PR when ready. Fix all linting problems (run `npm lint`), fix any failed checks that are run on the PR (basically lint right now). Use an editor that supports editorconfig, or match the settings from `.editorconfig` file manually.
|
235 |
|
236 | Fastest way to test changes is to do a self build, the plugin is part of its own build system:
|
237 | - make changes
|
238 | - run `npm build` (uses build committed to master branch)
|
239 | - check that you get expected changes in `dist`
|
240 | - run `npm build-self` (uses fresh local build)
|
241 | - check `dist` for the expected changes
|
242 | - run `npm build-self` _again_ to make sure plugin built by new version can still build itself
|
243 |
|
244 | If `build-self` breaks at some point, fix the problem and restart from `build` step (a known good copy).
|
245 |
|
246 | This repo badly needs unittests and integration tests with various scenarios and expected outcomes though.
|