|
1 |
| -# rollup-plugin-typescript2 |
2 |
| - |
3 |
| -[](https://npmjs.org/package/rollup-plugin-typescript2) |
4 |
| - |
5 |
| - |
6 |
| -[](https://app.codeship.com/projects/207445) |
7 |
| -[](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) |
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 |
| -## Usage |
16 |
| - |
17 |
| -```js |
18 |
| -// rollup.config.js |
19 |
| -import typescript from 'rollup-plugin-typescript2'; |
20 |
| - |
21 |
| -export default { |
22 |
| - entry: './main.ts', |
23 |
| - |
24 |
| - plugins: [ |
25 |
| - typescript(/*{ plugin options }*/) |
26 |
| - ] |
27 |
| -} |
28 |
| -``` |
29 |
| - |
30 |
| -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. |
31 |
| - |
32 |
| -#### Some compiler options are forced |
33 |
| - |
34 |
| -* `noEmitHelpers`: false |
35 |
| -* `importHelpers`: true |
36 |
| -* `noResolve`: false |
37 |
| -* `noEmit`: false |
38 |
| -* `inlineSourceMap`: false (see [#71](https://github.com/ezolenko/rollup-plugin-typescript2/issues/71)) |
39 |
| -* `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) |
40 |
| -* `declarationDir`: `process.cwd()` (*only if `useTsconfigDeclarationDir` is false in the plugin options*) |
41 |
| -* `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)*) |
42 |
| - |
43 |
| -#### Some compiler options have more than one compatible value. |
44 |
| - |
45 |
| -* `module`: defaults to `ES2015`, other valid value is `ESNext` (required for dynamic imports, see [#54](https://github.com/ezolenko/rollup-plugin-typescript2/issues/54)). |
46 |
| - |
47 |
| -### Compatibility |
48 |
| - |
49 |
| -#### rollup-plugin-node-resolve |
50 |
| - |
51 |
| -Must be before this plugin in the plugin list, especially when `browser: true` option is used, see [#66](https://github.com/ezolenko/rollup-plugin-typescript2/issues/66) |
52 |
| - |
53 |
| -#### rollup-plugin-commonjs |
54 |
| - |
55 |
| -See explanation for `rollupCommonJSResolveHack` option below. |
56 |
| - |
57 |
| -### Plugin options |
58 |
| - |
59 |
| -* `tsconfigDefaults`: `{}` |
60 |
| - |
61 |
| - 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). |
62 |
| - |
63 |
| - 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). |
64 |
| - |
65 |
| - ```js |
66 |
| - let defaults = { compilerOptions: { declaration: true } }; |
67 |
| - let override = { compilerOptions: { declaration: false } }; |
68 |
| - |
69 |
| - // ... |
70 |
| - plugins: [ |
71 |
| - typescript({ |
72 |
| - tsconfigDefaults: defaults, |
73 |
| - tsconfig: "tsconfig.json", |
74 |
| - tsconfigOverride: override |
75 |
| - }) |
76 |
| - ] |
77 |
| - ``` |
78 |
| - |
79 |
| - 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. |
80 |
| - |
81 |
| -* `tsconfig`: `undefined` |
82 |
| - |
83 |
| - 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. |
84 |
| - |
85 |
| -* `tsconfigOverride`: `{}` |
86 |
| - |
87 |
| - See `tsconfigDefaults`. |
88 |
| - |
89 |
| -* `check`: true |
90 |
| - |
91 |
| - Set to false to avoid doing any diagnostic checks on the code. |
92 |
| - |
93 |
| -* `verbosity`: 1 |
94 |
| - |
95 |
| - - 0 -- Error |
96 |
| - - 1 -- Warning |
97 |
| - - 2 -- Info |
98 |
| - - 3 -- Debug |
99 |
| - |
100 |
| -* `clean`: false |
101 |
| - |
102 |
| - Set to true for clean build (wipes out cache on every build). |
103 |
| - |
104 |
| -* `cacheRoot`: `./.rts2_cache` |
105 |
| - |
106 |
| - Path to cache. Defaults to a folder in the current directory. Can be safely moved out with something like `${require('temp-dir')}/.rpt2_cache`, but watch out for multiple concurrent builds of the same repo. |
107 |
| - |
108 |
| -* `include`: `[ "*.ts+(|x)", "**/*.ts+(|x)" ]` |
109 |
| - |
110 |
| - By default passes all .ts files through typescript compiler. |
111 |
| - |
112 |
| -* `exclude`: `[ "*.d.ts", "**/*.d.ts" ]` |
113 |
| - |
114 |
| - But excludes type definitions. |
115 |
| - |
116 |
| -* `abortOnError`: true |
117 |
| - |
118 |
| - 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). |
119 |
| - |
120 |
| -* `rollupCommonJSResolveHack`: false |
121 |
| - |
122 |
| - 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`. |
123 |
| - |
124 |
| -* `useTsconfigDeclarationDir`: false |
125 |
| - |
126 |
| - 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. |
127 |
| - |
128 |
| -* `typescript`: typescript module installed with the plugin |
129 |
| - |
130 |
| - 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("typescript")`. Must be 2.0+, things might break if transpiler interfaces changed enough from what the plugin was built against. |
131 |
| - |
132 |
| -* `transformers`: `undefined` |
133 |
| - |
134 |
| - **experimental**, typescript 2.4.1+ |
135 |
| - |
136 |
| - 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). |
137 |
| - |
138 |
| - For example, integrating [kimamula/ts-transformer-keys](https://github.com/kimamula/ts-transformer-keys): |
139 |
| - |
140 |
| - ```js |
141 |
| - const keysTransformer = require('ts-transformer-keys/transformer').default; |
142 |
| - const transformer = (service) => |
143 |
| - { |
144 |
| - before: [ keysTransformer(service.getProgram()) ], |
145 |
| - after: [] |
146 |
| - }; |
147 |
| - |
148 |
| - // ... |
149 |
| - plugins: [ |
150 |
| - typescript({ transformers: [transformer] }) |
151 |
| - ] |
152 |
| - ``` |
153 |
| - |
154 |
| -### Declarations |
155 |
| - |
156 |
| -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). |
157 |
| -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. |
158 |
| - |
159 |
| -### Watch mode |
160 |
| - |
161 |
| -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. |
162 |
| - |
163 |
| -Otherwise the plugin should work in watch mode. Make sure to run a normal build after watch session to catch any type errors. |
164 |
| - |
165 |
| -### Version |
166 |
| - |
167 |
| -This plugin currently requires TypeScript `2.4+`. |
168 |
| - |
169 |
| -### Rollup version |
170 |
| - |
171 |
| -This plugin currently requires rollup `0.50+`. |
172 |
| - |
173 |
| -### Reporting bugs |
174 |
| - |
175 |
| -Report any bugs on github: <https://github.com/ezolenko/rollup-plugin-typescript2/issues>. |
176 |
| - |
177 |
| -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. |
178 |
| - |
179 |
| -Check if problem is reproducible after running `npm prune` to clear any rogue types from npm_modules (by default typescript grabs all ambient types). |
180 |
| - |
181 |
| -Check if you get the same problem with `clean` option set to true (might indicate a bug in the cache). |
182 |
| - |
183 |
| -If makes sense, check if running `tsc` directly produces similar results. |
184 |
| - |
185 |
| -Attach plugin output with `verbosity` option set to 3 (this will list all files being transpiled and their imports). |
| 1 | +# rollup-plugin-typescript2 |
| 2 | + |
| 3 | +[](https://npmjs.org/package/rollup-plugin-typescript2) |
| 4 | + |
| 5 | + |
| 6 | +[](https://app.codeship.com/projects/207445) |
| 7 | +[](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) |
| 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 | +## Usage |
| 16 | + |
| 17 | +```js |
| 18 | +// rollup.config.js |
| 19 | +import typescript from 'rollup-plugin-typescript2'; |
| 20 | + |
| 21 | +export default { |
| 22 | + entry: './main.ts', |
| 23 | + |
| 24 | + plugins: [ |
| 25 | + typescript(/*{ plugin options }*/) |
| 26 | + ] |
| 27 | +} |
| 28 | +``` |
| 29 | + |
| 30 | +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. |
| 31 | + |
| 32 | +#### Some compiler options are forced |
| 33 | + |
| 34 | +* `noEmitHelpers`: false |
| 35 | +* `importHelpers`: true |
| 36 | +* `noResolve`: false |
| 37 | +* `noEmit`: false |
| 38 | +* `inlineSourceMap`: false (see [#71](https://github.com/ezolenko/rollup-plugin-typescript2/issues/71)) |
| 39 | +* `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) |
| 40 | +* `declarationDir`: `process.cwd()` (*only if `useTsconfigDeclarationDir` is false in the plugin options*) |
| 41 | +* `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)*) |
| 42 | + |
| 43 | +#### Some compiler options have more than one compatible value. |
| 44 | + |
| 45 | +* `module`: defaults to `ES2015`, other valid value is `ESNext` (required for dynamic imports, see [#54](https://github.com/ezolenko/rollup-plugin-typescript2/issues/54)). |
| 46 | + |
| 47 | +### Compatibility |
| 48 | + |
| 49 | +#### rollup-plugin-node-resolve |
| 50 | + |
| 51 | +Must be before this plugin in the plugin list, especially when `browser: true` option is used, see [#66](https://github.com/ezolenko/rollup-plugin-typescript2/issues/66) |
| 52 | + |
| 53 | +#### rollup-plugin-commonjs |
| 54 | + |
| 55 | +See explanation for `rollupCommonJSResolveHack` option below. |
| 56 | + |
| 57 | +### Plugin options |
| 58 | + |
| 59 | +* `tsconfigDefaults`: `{}` |
| 60 | + |
| 61 | + 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). |
| 62 | + |
| 63 | + 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). |
| 64 | + |
| 65 | + ```js |
| 66 | + let defaults = { compilerOptions: { declaration: true } }; |
| 67 | + let override = { compilerOptions: { declaration: false } }; |
| 68 | + |
| 69 | + // ... |
| 70 | + plugins: [ |
| 71 | + typescript({ |
| 72 | + tsconfigDefaults: defaults, |
| 73 | + tsconfig: "tsconfig.json", |
| 74 | + tsconfigOverride: override |
| 75 | + }) |
| 76 | + ] |
| 77 | + ``` |
| 78 | + |
| 79 | + 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. |
| 80 | + |
| 81 | +* `tsconfig`: `undefined` |
| 82 | + |
| 83 | + 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. |
| 84 | + |
| 85 | +* `tsconfigOverride`: `{}` |
| 86 | + |
| 87 | + See `tsconfigDefaults`. |
| 88 | + |
| 89 | +* `check`: true |
| 90 | + |
| 91 | + Set to false to avoid doing any diagnostic checks on the code. |
| 92 | + |
| 93 | +* `verbosity`: 1 |
| 94 | + |
| 95 | + - 0 -- Error |
| 96 | + - 1 -- Warning |
| 97 | + - 2 -- Info |
| 98 | + - 3 -- Debug |
| 99 | + |
| 100 | +* `clean`: false |
| 101 | + |
| 102 | + Set to true for clean build (wipes out cache on every build). |
| 103 | + |
| 104 | +* `cacheRoot`: `./.rts2_cache` |
| 105 | + |
| 106 | + Path to cache. Defaults to a folder in the current directory. Can be safely moved out with something like `${require('temp-dir')}/.rpt2_cache`, but watch out for multiple concurrent builds of the same repo. |
| 107 | + |
| 108 | +* `include`: `[ "*.ts+(|x)", "**/*.ts+(|x)" ]` |
| 109 | + |
| 110 | + By default passes all .ts files through typescript compiler. |
| 111 | + |
| 112 | +* `exclude`: `[ "*.d.ts", "**/*.d.ts" ]` |
| 113 | + |
| 114 | + But excludes type definitions. |
| 115 | + |
| 116 | +* `abortOnError`: true |
| 117 | + |
| 118 | + 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). |
| 119 | + |
| 120 | +* `rollupCommonJSResolveHack`: false |
| 121 | + |
| 122 | + 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`. |
| 123 | + |
| 124 | +* `useTsconfigDeclarationDir`: false |
| 125 | + |
| 126 | + 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. |
| 127 | + |
| 128 | +* `typescript`: typescript module installed with the plugin |
| 129 | + |
| 130 | + 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("typescript")`. Must be 2.0+, things might break if transpiler interfaces changed enough from what the plugin was built against. |
| 131 | + |
| 132 | +* `transformers`: `undefined` |
| 133 | + |
| 134 | + **experimental**, typescript 2.4.1+ |
| 135 | + |
| 136 | + 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). |
| 137 | + |
| 138 | + For example, integrating [kimamula/ts-transformer-keys](https://github.com/kimamula/ts-transformer-keys): |
| 139 | + |
| 140 | + ```js |
| 141 | + const keysTransformer = require('ts-transformer-keys/transformer').default; |
| 142 | + const transformer = (service) => |
| 143 | + { |
| 144 | + before: [ keysTransformer(service.getProgram()) ], |
| 145 | + after: [] |
| 146 | + }; |
| 147 | + |
| 148 | + // ... |
| 149 | + plugins: [ |
| 150 | + typescript({ transformers: [transformer] }) |
| 151 | + ] |
| 152 | + ``` |
| 153 | + |
| 154 | +### Declarations |
| 155 | + |
| 156 | +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). |
| 157 | +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. |
| 158 | + |
| 159 | +### Watch mode |
| 160 | + |
| 161 | +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. |
| 162 | + |
| 163 | +Otherwise the plugin should work in watch mode. Make sure to run a normal build after watch session to catch any type errors. |
| 164 | + |
| 165 | +### Requirements |
| 166 | + |
| 167 | +TypeScript `2.4+` |
| 168 | +Rollup `0.50+` |
| 169 | +Node `6.4.0+` (basic es6 support) |
| 170 | + |
| 171 | +### Reporting bugs |
| 172 | + |
| 173 | +Report any bugs on github: <https://github.com/ezolenko/rollup-plugin-typescript2/issues>. |
| 174 | + |
| 175 | +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. |
| 176 | + |
| 177 | +Check if problem is reproducible after running `npm prune` to clear any rogue types from npm_modules (by default typescript grabs all ambient types). |
| 178 | + |
| 179 | +Check if you get the same problem with `clean` option set to true (might indicate a bug in the cache). |
| 180 | + |
| 181 | +If makes sense, check if running `tsc` directly produces similar results. |
| 182 | + |
| 183 | +Attach plugin output with `verbosity` option set to 3 (this will list all files being transpiled and their imports). |
0 commit comments