/node_modules/gulp-typescript/readme.md
Markdown | 290 lines | 245 code | 45 blank | 0 comment | 0 complexity | 8ca20a0bb96ebeb4dad0672abea9a008 MD5 | raw file
1gulp-typescript
2===============
3A gulp plugin for handling TypeScript compilation workflow. The plugin exposes TypeScript's compiler options to gulp using TypeScript API.
4
5[](https://travis-ci.org/ivogabe/gulp-typescript)
6
7Features
8--------
9- Incremental compilation (so faster builds)
10- Error reporting
11- Different output streams for .js, .d.ts files.
12- Support for sourcemaps using gulp-sourcemaps
13- Compile once, and filter different targets
14
15How to install
16--------------
17##### 1. Install gulp
18```shell
19npm install --global gulp
20```
21##### 2. Install gulp in the project dependency
22```shell
23npm install gulp
24```
25##### 3. Install gulp-typescript
26```shell
27npm install gulp-typescript
28```
29
30Options
31-------
32Allmost all options from TypeScript are supported.
33- `out` (TS1.5-), `outFile` (TS1.6+) (string) - Generate one javascript and one definition file. Only works when no module system is used.
34- `outDir` (string) - Move output to a different (virtual) directory. Note that you still need `gulp.dest` to write output to disk.
35- `noImplicitAny` (boolean) - Warn on expressions and declarations with an implied 'any' type.
36- `suppressImplicitAnyIndexErrors` (boolean) - Suppress --noImplicitAny errors for indexing objects lacking index signatures.
37- `noLib` (boolean) - Don't include the default lib (with definitions for - Array, Date etc)
38- `target` (string) - Specify ECMAScript target version: 'ES3' (default), 'ES5' or 'ES6'.
39- `module` (string) - Specify module code generation: 'commonjs', 'amd', 'umd' or 'system'.
40- `jsx` (string) - Specify jsx code generation: 'react' or 'preserve' (TS1.6+).
41- `declaration` (boolean) - Generates corresponding .d.ts files. You need to pipe the `dts` streams to save these files.
42- `removeComments` (boolean) - Do not emit comments to output.
43- `emitDecoratorMetadata` (boolean) - Emit design-time metadate for decorated declarations in source.
44- `experimentalAsyncFunctions` (boolean) - Support for ES7-proposed asynchronous functions using the `async`/`await` keywords (TS1.6+).
45- `experimentalDecorators` (boolean) - Enables experimental support for ES7 decorators.
46- `moduleResolution` (string) - Determine how modules get resolved. Either 'node' for Node.js/io.js style resolution, or 'classic' (default) (TS1.6+).
47- `noEmitOnError` (boolean) - Do not emit outputs if any type checking errors were reported.
48- `noEmitHelpers` (boolean) - Do not generate custom helper functions like __extends in compiled output.
49- `preserveConstEnums` (boolean) - Do not erase const enum declarations in generated code.
50- `isolatedModules` (boolean) - Compiles files seperately and doesn't check types, which causes a big speed increase. You have to use gulp-plumber and TypeScript 1.5+.
51- `allowJs` (boolean) - Allow JavaScript files to be compiled.
52- `rootDir` - Specifies the root directory of input files. Only use to control the output directory structure with `outDir`.
53
54See the [TypeScript wiki](http://www.typescriptlang.org/docs/handbook/compiler-options.html) for a complete list.
55These options are not supported:
56- Sourcemap options (`sourceMap`, `inlineSourceMap`, `inlineSources`, `sourceRoot`) - Use [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps) instead.
57- `watch` - Use `gulp.watch` instead. See the paragraph "Incremental compilation".
58- `project` - See "Using `tsconfig.json`".
59- Obvious: `help`, `version`
60
61## Unofficial options
62Besides the official options options, gulp-typescript supports the following options:
63- ```noExternalResolve``` (boolean) - Do not resolve files that are not in the input. Explanation below.
64- ```sortOutput``` (boolean) - Sort output files. Useful if you want to concatenate files (see below).
65- ```typescript``` (object) - Use a different version / fork of TypeScript (see below). Use it like: `typescript: require('typescript')` or `typescript: require('my-fork-of-typescript')`
66
67Basic Usage
68----------
69Below is a minimal `gulpfile.js` which will compile all TypeScript file in folder `src` and emit a single output file called `output.js` in `built/local`. To invoke, simple run `gulp`.
70
71```javascript
72var gulp = require('gulp');
73var ts = require('gulp-typescript');
74
75gulp.task('default', function () {
76 return gulp.src('src/**/*.ts')
77 .pipe(ts({
78 noImplicitAny: true,
79 out: 'output.js'
80 }))
81 .pipe(gulp.dest('built/local'));
82});
83```
84Another example of `gulpfile.js`. Instead of creating default task, the file specifies custom named task. To invoke, run `gulp scripts` instead of `gulp`. As a result, the task will generate both JavaScript files and TypeScript definition files (.d.ts).
85```javascript
86var gulp = require('gulp');
87var ts = require('gulp-typescript');
88var merge = require('merge2'); // Require separate installation
89
90gulp.task('scripts', function() {
91 var tsResult = gulp.src('lib/**/*.ts')
92 .pipe(ts({
93 declaration: true,
94 noExternalResolve: true
95 }));
96
97 return merge([
98 tsResult.dts.pipe(gulp.dest('release/definitions')),
99 tsResult.js.pipe(gulp.dest('release/js'))
100 ]);
101});
102```
103`tsResult` is a object that has a JavaScript stream (`.js`) and a definition file stream (`.dts`).
104You need to set the `declaration` option to get definition files in the `dts` stream.
105If you don't need the definition files, you can use a configuration as seen in the first example.
106
107Incremental compilation
108-----------------------
109Instead of calling ```ts(options)```, you can create a project first, and then call ```ts(project)```. An example:
110```javascript
111var gulp = require('gulp');
112var ts = require('gulp-typescript');
113var merge = require('merge2');
114
115var tsProject = ts.createProject({
116 declaration: true,
117 noExternalResolve: true
118});
119
120gulp.task('scripts', function() {
121 var tsResult = gulp.src('lib/*.ts')
122 .pipe(ts(tsProject));
123
124 return merge([ // Merge the two output streams, so this task is finished when the IO of both operations are done.
125 tsResult.dts.pipe(gulp.dest('release/definitions')),
126 tsResult.js.pipe(gulp.dest('release/js'))
127 ]);
128});
129
130gulp.task('watch', ['scripts'], function() {
131 gulp.watch('lib/*.ts', ['scripts']);
132});
133```
134When you run ```gulp watch```, the source will be compiled as usual. Then, when you make a change and save the file, your TypeScript files will be compiled in about half the time.
135
136You must create the project outside of the task. You can't use the same project in multiple tasks.
137Instead, create multiple projects or use a single task to compile your sources.
138
139Using `tsconfig.json`
140-------------
141To use `tsconfig.json`, you have to use `ts.createProject`:
142```javascript
143var tsProject = ts.createProject('tsconfig.json');
144```
145If you want to add or overwrite certain settings in the `tsconfig.json` file, you can use:
146```javascript
147var tsProject = ts.createProject('tsconfig.json', { sortOutput: true });
148```
149The task will look like:
150```javascript
151gulp.task('scripts', function() {
152 var tsResult = tsProject.src() // instead of gulp.src(...)
153 .pipe(ts(tsProject));
154
155 return tsResult.js.pipe(gulp.dest('release'));
156});
157```
158
159TypeScript version
160------------------
161gulp-typescript uses TypeScript 1.8 by default. You can also use 1.4+ or a nighty version of TypeScript instead.
162You should add the version you want (1.4+) to your package.json file as a devDependency. You can use the a nightly build to get the latest features:
163```
164npm install typescript@next
165```
166And add this to your gulpfile:
167```javascript
168[...].pipe(ts({
169 typescript: require('typescript')
170}));
171```
172Or in combination with a `tsconfig` file:
173```javascript
174var tsProject = ts.createProject('tsconfig.json', {
175 typescript: require('typescript')
176});
177```
178
179It's also possible to use a fork of TypeScript. Add an extra option to the options object like this:
180```javascript
181[...].pipe(ts({
182 typescript: require('my-fork-of-typescript')
183}));
184```
185
186Filters
187-------
188There are two ways to filter files:
189```javascript
190gulp.task('scripts', function() {
191 var tsResult = gulp.src('lib/*.ts')
192 .pipe(ts(tsProject, filterSettings));
193
194 ...
195});
196```
197And
198```javascript
199gulp.task('scripts', function() {
200 var tsResult = gulp.src('lib/*.ts')
201 .pipe(ts(tsProject));
202
203 tsResult.pipe(ts.filter(tsProject, filterSettings));
204});
205```
206The first example doesn't add files (that don't pass the filter) to the compiler, the second one does add them to the compiler,
207but removes them later from the stream.
208You can put as much pipes between compilation and filtering as you want, as long as the filename doesn't change.
209
210At the moment there is only one filter available:
211
212- ```referencedFrom``` (string[]) Only files that are referenced (using ```/// <reference path="..." />```) by the files in this array pass this filter.
213
214Resolving files
215---------------
216By default, gulp-typescript will try to resolve the files you require and reference. These files are parsed, but not emitted (so you will not see them in the output stream).
217
218If you set the option ```noExternalResolve``` to true, gulp-typescript will not resolve all the requires and references. It assumes that all the necessary files are in the input stream. For example, if you have your ```.ts``` files in the ```lib``` folder, and the ```.d.ts``` files in the ```definitions``` folder, you must use ```gulp.src(['lib/**.ts', 'definitions/**.ts'])``` instead of ```gulp.src(['lib/**.ts'])``` in your gulpfile if you use the option ```noExternalResolve```.
219
220Advantage of ```noExternalResolve```: faster compilation.
221Disadvantage of ```noExternalResolve```: won't work when you forgot some input files.
222Advice: turn it on, and make sure you list all the input files.
223
224Files that are resolved when ```noExternalResolve``` is off, won't be pushed to the output stream, unless you are using the `out` option.
225
226Concatenate files
227------------
228The ```tsc``` command has the ability to concatenate using the ```--out``` parameter. There are two approaches to do that in ```gulp-typescript```.
229
230You can use the `out` option. This is fine for small projects, but for big projects it's not always sufficient.
231
232The other option is to use `gulp-concat`. The ```tsc``` command sorts the files using the ```<reference>``` tags. ```gulp-typescript``` does this when you enable the ```sortOutput``` option. You can use the ```referencedFrom``` filter to only include files that are referenced from certain files.
233
234
235Source maps
236----------
237Example of ```gulpfile.js``` which will compile typescript to javascript as well as generate
238associated sourcemap.
239
240```javascript
241var gulp = require('gulp')
242var ts = require('gulp-typescript');
243var concat = require('gulp-concat');
244var sourcemaps = require('gulp-sourcemaps');
245
246gulp.task('scripts', function() {
247 var tsResult = gulp.src('lib/*.ts')
248 .pipe(sourcemaps.init()) // This means sourcemaps will be generated
249 .pipe(ts({
250 sortOutput: true,
251 // ...
252 }));
253
254 return tsResult.js
255 .pipe(concat('output.js')) // You can use other plugins that also support gulp-sourcemaps
256 .pipe(sourcemaps.write()) // Now the sourcemaps are added to the .js file
257 .pipe(gulp.dest('release/js'));
258});
259```
260For more information, see [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps).
261
262Reporters
263---------
264You can specify a custom reporter as the 3rd argument of the main function:
265```javascript
266ts(optionsOrProject, filters, reporter);
267```
268You can set options, project or filter to `undefined` if you don't want to set them. Available reporters are:
269- nullReporter (`ts.reporter.nullReporter()`) - Don't report errors
270- defaultReporter (`ts.reporter.defaultReporter()`) - Report basic errors to the console
271- longReporter (`ts.reporter.longReporter()`) - Extended version of default reporter, intelliJ link functionality + file watcher error highlighting should work using this one
272- fullReporter (`ts.reporter.fullReporter(showFullFilename?: boolean)`) - Show full error messages, with source.
273
274If you want to build a custom reporter, you take a look at `lib/reporter.ts`, in that file is an interface which a reporter should implement.
275
276Build gulp-typescript
277------------
278
2791. Clone this repo
2802. Execute `npm install`
2813. Execute `git submodule update --init` to pull down the TypeScript compiler/services versions used in the test suite.
2824. Ensure the gulp CLI is globally installed (`npm install -g gulp`).
2835. Execute the tests: `gulp`.
284
285The plugin uses itself to compile. There are 2 build directories, ```release``` and ```release-2```. ```release``` must always contain a working build. ```release-2``` contains the last build. When you run ```gulp compile```, the build will be saved in the ```release-2``` directory. ```gulp test``` will compile the source to ```release-2```, and then it will run some tests. If these tests give no errors, you can run ```gulp release```. The contents from ```release-2``` will be copied to ```release```.
286
287
288License
289-------
290gulp-typescript is licensed under the [MIT license](http://opensource.org/licenses/MIT).