1 | # The best TypeScript loader for Webpack
|
2 |
|
3 | [![Join the chat at https://gitter.im/s-panferov/awesome-typescript-loader](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/s-panferov/awesome-typescript-loader?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
4 | [![Build Status](https://travis-ci.org/s-panferov/awesome-typescript-loader.svg?branch=master)](https://travis-ci.org/s-panferov/awesome-typescript-loader)
|
5 |
|
6 | ## Installation
|
7 |
|
8 | ```
|
9 | npm install awesome-typescript-loader --save-dev
|
10 | ```
|
11 |
|
12 | ## Differences between [`ts-loader`](https://github.com/TypeStrong/ts-loader)
|
13 |
|
14 | `awesome-typescript-loader` loader was created mostly to speed-up compilation in my own projects.
|
15 | Some of them are quite big and I wanted to have full control on how my files are compiled. There are three major points:
|
16 |
|
17 | 1) atl has first-class integration with Babel and enables caching possibilities. This can be useful for those who use Typescript with Babel.
|
18 | When `useBabel` and `useCache` flags are enabled, typescript's emit will be transpiled with Babel and cached.
|
19 | So next time if source file (+environment) has the same checksum we can totally skip typescript's and babel's transpiling.
|
20 | This significantly reduces build time in this scenario.
|
21 |
|
22 | 2) atl is able to fork type-checker and emitter to a separate process, which also speeds-up some development scenarios (e.g. react with react-hot-loader)
|
23 | So your webpack compilation will end earlier and you can explore compiled version in your browser while your files are typechecked.
|
24 |
|
25 | ## Configuration
|
26 |
|
27 | 1. Add `.ts` as a resolvable extension.
|
28 | 2. Configure all files with a `.ts` extension to be handled by `awesome-typescript-loader`.
|
29 |
|
30 | **webpack.config.js**
|
31 |
|
32 | ```javascript
|
33 | // `CheckerPlugin` is optional. Use it if you want async error reporting.
|
34 | // We need this plugin to detect a `--watch` mode. It may be removed later
|
35 | // after https://github.com/webpack/webpack/issues/3460 will be resolved.
|
36 | const { CheckerPlugin } = require('awesome-typescript-loader')
|
37 |
|
38 | module.exports = {
|
39 |
|
40 | // Currently we need to add '.ts' to the resolve.extensions array.
|
41 | resolve: {
|
42 | extensions: ['.ts', '.tsx', '.js', '.jsx']
|
43 | },
|
44 |
|
45 | // Source maps support ('inline-source-map' also works)
|
46 | devtool: 'source-map',
|
47 |
|
48 | // Add the loader for .ts files.
|
49 | module: {
|
50 | loaders: [
|
51 | {
|
52 | test: /\.tsx?$/,
|
53 | loader: 'awesome-typescript-loader'
|
54 | }
|
55 | ]
|
56 | },
|
57 | plugins: [
|
58 | new CheckerPlugin()
|
59 | ]
|
60 | };
|
61 | ```
|
62 |
|
63 | After that, you will be able to build TypeScript files with webpack.
|
64 |
|
65 | ## NodeJS versions
|
66 |
|
67 | **The loader supports NodeJS 4 and newer.**
|
68 |
|
69 | ## tsconfig.json
|
70 |
|
71 | You can use the tsconfig.json file to configure your compiler and loader:
|
72 |
|
73 | ```
|
74 | {
|
75 | "compilerOptions": {
|
76 | "noImplicitAny": true,
|
77 | "removeComments": true
|
78 | },
|
79 | "awesomeTypescriptLoaderOptions": {
|
80 | /* ... */
|
81 | }
|
82 | }
|
83 | ```
|
84 |
|
85 | ## Supported TypeScript
|
86 |
|
87 | `awesome-typescript-loader@2.x` aims to support only `typescript@2.x` and `webpack@2x`, if you need old compilers please use
|
88 | `1.x` or `0.x` versions.
|
89 |
|
90 | ## Advanced path resolution in TypeScript 2.0
|
91 |
|
92 | If you want to use new `paths` and `baseUrl` feature of TS 2.0 please include `TsConfigPathsPlugin`.
|
93 | This feature is available only for `webpack@2.1`.
|
94 |
|
95 | ```
|
96 | var TsConfigPathsPlugin = require('awesome-typescript-loader').TsConfigPathsPlugin;
|
97 |
|
98 | resolve: {
|
99 | plugins: [
|
100 | new TsConfigPathsPlugin(/* { tsconfig, compiler } */)
|
101 | ]
|
102 | }
|
103 | ```
|
104 |
|
105 | ## Loader options
|
106 |
|
107 | ### silent *(boolean) (default=false)*
|
108 |
|
109 | No logging from the checker. Please note that this option disables async error reporting because
|
110 | this option bans `console.log()` usage.
|
111 |
|
112 | ### compiler *(string) (default='typescript')*
|
113 |
|
114 | Allows use of TypeScript compilers other than the official one. Must be
|
115 | set to the NPM name of the compiler, e.g. *ntypescript* or the path to a package folder.
|
116 | Note that the compiler must be installed in **your** project. You can also use
|
117 | nightly versions.
|
118 |
|
119 | ### useTranspileModule (boolean) (default=false)*
|
120 |
|
121 | Use fast `transpileModule` emit mode. Disables automatically when you set compilerOption `declaration: true` ([reference](https://www.typescriptlang.org/docs/handbook/compiler-options.html)).
|
122 |
|
123 | ### instance *(string) (default='at-loader')*
|
124 |
|
125 | Allows the use of several TypeScript compilers with different settings in one app. Override `instance` to initialize another instance.
|
126 |
|
127 | ### configFileName *(string) (default='tsconfig.json')*
|
128 |
|
129 | Specifies the path to a TS config file. This is useful when you have multiple config files. This setting is useless *inside* a TS config file.
|
130 |
|
131 | ### transpileOnly *(boolean) (default=true)*
|
132 |
|
133 | Use this setting to disable type checking.
|
134 |
|
135 | ### ignoreDiagnostics *(number[]) (default=[])*
|
136 |
|
137 | You can squelch certain TypeScript errors by specifying an array of [diagnostic codes](https://github.com/Microsoft/TypeScript/blob/master/src/compiler/diagnosticMessages.json) to ignore.
|
138 | For example, you can transpile [stage 1 properties](https://github.com/jeffmo/es-class-fields-and-static-properties) from `*.js` using `"ignoreDiagnostics": [8014]`.
|
139 |
|
140 | ### useBabel *(boolean) (default=false)*
|
141 |
|
142 | Invoke Babel to transpile files. Useful with ES6 target. Please see `useCache` option
|
143 | which can improve warm-up time.
|
144 |
|
145 | ### babelCore *(string) (default=undefined)*
|
146 |
|
147 | Override the path used to find `babel-core`. Useful if `node_modules` is installed in a non-standard place or webpack is being invoked from a directory not at the root of the project.
|
148 |
|
149 | ### babelOptions *(object) (default=null)*
|
150 |
|
151 | Use this option to pass some options to Babel (e.g. presets). Please note that
|
152 | [`.babelrc` file](https://babeljs.io/docs/usage/babelrc/) is more universal way to do this.
|
153 |
|
154 | ### useCache *(boolean) (default=false)*
|
155 |
|
156 | Use internal file cache. This is useful with Babel, when processing takes a long time to complete. Improves warm-up time.
|
157 |
|
158 | ### usePrecompiledFiles *(boolean) (default=false)*
|
159 |
|
160 | Use pre-compiled files if any. Files must be named as `{filename}.js` and `{filename}.map`.
|
161 |
|
162 | ### cacheDirectory *(string) (default='.awcache')*
|
163 |
|
164 | Directory when cache is stored.
|
165 |
|
166 | ## Compiler options
|
167 |
|
168 | You can pass compiler options inside loader query string or in tsconfig file.
|