search

TypeStrong / tsify

Browserify plugin for compiling TypeScript
344 stars 75 forks source link

readme

tsify

Browserify plugin for compiling TypeScript

NPM version Downloads Build status Dependency status devDependency Status peerDependency Status

Example Usage

Browserify API:

var browserify = require('browserify');
var tsify = require('tsify');

browserify()
    .add('main.ts')
    .plugin(tsify, { noImplicitAny: true })
    .bundle()
    .on('error', function (error) { console.error(error.toString()); })
    .pipe(process.stdout);

Command line:

$ browserify main.ts -p [ tsify --noImplicitAny ] > bundle.js

Note that when using the Browserify CLI, compilation will always halt on the first error encountered, unlike the regular TypeScript CLI. This behavior can be overridden in the API, as shown in the API example.

Also note that the square brackets [ ] in the example above are required if you want to pass parameters to tsify; they don't denote an optional part of the command.

Installation

Just plain ol' npm installation:

1. Install browserify

npm install browserify

2. Install typescript

npm install typescript

3. Install tsify

npm install tsify

For use on the command line, use the flag npm install -g.

Options

Does this work with...

tsconfig.json?

tsify will automatically read options from tsconfig.json. However, some options from this file will be ignored:

Watchify?

Yes! tsify can do incremental compilation using watchify, resulting in much faster incremental build times. Just follow the Watchify documentation, and add tsify as a plugin as indicated in the documentation above.

Gulp?

No problem. See the Gulp recipes on using browserify and watchify, and add tsify as a plugin as indicated in the documentation above.

Grunt?

Use grunt-browserify and you should be good! Just add tsify as a plugin in your Grunt configuration.

IE 11?

The inlined sourcemaps that Browserify generates may not be readable by IE 11 for debugging purposes. This is easy to fix by adding exorcist to your build workflow after Browserify.

ES2015? (formerly known as ES6)

TypeScript's ES2015 output mode should work without too much additional setup. Browserify does not support ES2015 modules, so if you want to use ES2015 you still need some transpilation step. Make sure to add babelify to your list of transforms. Note that if you are using the API, you need to set up tsify before babelify:

browserify()
    .plugin(tsify, { target: 'es6' })
    .transform(babelify, { extensions: [ '.tsx', '.ts' ] })

FAQ / Common issues

SyntaxError: 'import' and 'export' may appear only with 'sourceType: module'

This error occurs when a TypeScript file is not compiled to JavaScript before being run through the Browserify bundler. There are a couple known reasons you might run into this.

Why a plugin?

There are several TypeScript compilation transforms available on npm, all with various issues. The TypeScript compiler automatically performs dependency resolution on module imports, much like Browserify itself. Browserify transforms are not flexible enough to deal with multiple file outputs given a single file input, which means that any working TypeScript compilation transform either skips the resolution step (which is necessary for complete type checking) or performs multiple compilations of source files further down the dependency graph.

tsify avoids this problem by using the power of plugins to perform a single compilation of the TypeScript source up-front, using Browserify to glue together the resulting files.

License

MIT

Changelog