Compile and manage your TypeScript project


Grunt-ts is an npm package that handles TypeScript compilation work in GruntJS build scripts. It provides a Grunt-compatible wrapper for the tsc command-line compiler, and provides some additional functionality that improves the TypeScript development workflow. Grunt-ts supports compiling against tsconfig.json or even a Visual Studio project directly. Grunt-ts is itself written in TypeScript.

Latest release is 5.2.0, which supports TypeScript 1.6 and contains bugfixes.

Full changelog is here.

If you've never used GruntJS on your computer, you should follow the detailed instructions here to get Node.js and the grunt-cli working. If you're a Grunt expert, simply follow these steps:

  • Run npm install grunt-ts in your project directory; this will install grunt-ts, TypeScript, and GruntJS.
  • Add the ts task in your Gruntfile.js (see below for a minimalist one).
  • Run grunt at the command line in your project folder to compile your TypeScript code.

This minimalist Gruntfile.js will compile *.ts files in all subdirectories of the project folder, excluding anything under node_modules:

module.exports = function(grunt) {
    ts: {
      default : {
        src: ["**/*.ts", "!node_modules/**/*.ts"]
  grunt.registerTask("default", ["ts"]);

A more extensive sample Gruntfile.js is available here.

  • Allows use of all standard GruntJS functionality such as use of customizable task targets, globbing, use of the files object (for instantiating multiple independent tsc runs in a single target), etc.
  • Allows the developer to select a custom TypeScript compiler version for their project, or even use a custom (in-house) version.
  • Supports most switches of the tsc TypeScript Compiler via options in the gruntfile ts task, and also supports switch overrides per-target.
  • Supports Visual Studio Projects as a compile target for identifying TypeScript files, setting up compile configuration, or both.
  • Supports TypeScript Projects via tsconfig.json when used with TypeScript 1.5 or higher.
  • Provides a transforms feature that eases code refactoring by taking the burden of relative path maintenance off the developer. If the paths to a set of files changes, grunt-ts will regenerate the relevant sections. This feature supports:
  • Allows concatenation where supported by the TypeScript compiler's --out switch
  • Encodes HTML files as TypeScript variables (for HTML templating engines)
  • Performs live file watching (compile on save)
  • Enables "Fast" compile when using external modules

Grunt-ts provides explicit support for most tsc switches. Any arbitrary switches can be passed to tsc via the additionalFlags feature.

tsc switchname in grunt-tsdescription
--declarationdeclarationGenerates a .d.ts definitions file for compiled TypeScript files
--emitDecoratorMetadataemitDecoratorMetadataEmit metadata for type/parameter decorators.
--experimentalAsyncFunctionsexperimentalAsyncFunctionsEnables experimental support for ES7 async functions
--experimentalDecoratorsexperimentalDecoratorsEnables experimental support for ES7 decorators
--inlineSourceMapinlineSourceMapEmit a single file that includes source maps instead of emitting a separate file.
--inlineSourcesinlineSourcesEmit the TypeScript source alongside the sourcemaps within a single file; requires --inlineSourceMap to be set.
--isolatedModulesisolatedModulesEnsures that the output is safe to only emit single files by making cases that break single-file transpilation an error
--jsxjsxSpecifies the JSX code generation style: 'preserve' or 'react'
--mapRoot LOCATIONmapRootSpecifies the location where debugger should locate map files instead of generated locations.
--module KINDmoduleSpecify module style for code generation
--moduleResolution KINDmoduleResolutionSpecifies module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6).
--newLinenewLineExplicitly specify newline character (CRLF or LF); if omitted, uses OS default.
--noEmitnoEmitCheck, but do not emit JS, even in the absence of errors.
--noEmitHelpersnoEmitHelpersDo not generate custom helper functions like __extends in compiled output.
--noEmitOnErrornoEmitOnErrorDo not emit JavaScript if there is a compilation error
--noImplicitAnynoImplicitAnyWarn on expressions and declarations with an implied any type.
--noResolvenoResolveDo not add triple-slash references or module import targets to the compilation context.
--out FILEoutConcatenate and emit output to a single file.
--outDir DIRECTORYoutDirRedirect output structure to the directory.
--preserveConstEnumspreserveConstEnumsConst enums will be kept as enums in the emitted JS.
--removeCommentsremoveCommentsConfigures if comments should be included in the output
--rootDirrootDirAllows override of common root folder calculated by --outDir.
--sourceMapsourceMapGenerates corresponding .map file
--sourceRoot LOCATIONsourceRootSpecifies the location where debugger should locate TypeScript files instead of source locations.
--suppressImplicitAnyIndexErrorssuppressImplicitAnyIndexErrorsSpecifies the location where debugger should locate TypeScript files instead of source locations.
--target VERSIONtargetSpecify ECMAScript target version: 'es3', 'es5', or 'es6'

For file ordering, look at JavaScript Generation.

grunt-ts propertywhere to definedescription
additionalFlagsoptionstring - allows passing arbitrary strings to the compiler. This is intended to enable compatibility with features not supported directly by grunt-ts.
commentsoptiontrue, false (default) - include comments in emitted JS.
compileoptiontrue (default), false - compile TypeScript code.
compileroptionstring - path to custom compiler
declarationoptiontrue, false (default) - indicates that definition files should be emitted.
emitDecoratorMetadataoptiontrue, false (default) - set to true to emit metadata for ES7 decorators (will enable experimentalDecorators)
emitGruntEventsoptiontrue, false (default) - set to true to raise an event in Grunt upon failed builds.
experimentalAsyncFunctionsoptiontrue, false (default) - set to true to enable support for ES7 async functions (in ES6 mode only)
experimentalDecoratorsoptiontrue, false (default) - set to true to enable support for ES7 decorators
failOnTypeErrorsoptiontrue (default), false - fail Grunt pipeline if there is a type error. (See also noEmitOnError)
fastoption'watch' (default), 'always', 'never' - how to decide on a "fast" grunt-ts compile.
filestargetSets of files to compile and optional output destination
htmltargetstring or string[] - glob to HTML templates
htmlModuleTemplateoptionstring - HTML template namespace
htmlOutDiroptionstring - Sets a root for output of transformed-to-TypeScript HTML files
htmlOutDirFlattenoptiontrue, false (default) - Will flatten the transformed HTML files to a single folder
htmlVarTemplateoptionstring - HTML property name
inlineSourceMapoptiontrue, false (default) Emit a single file that includes source maps instead of emitting a separate file; If enabled, will automatically enable sourceMap.
inlineSourcesoptiontrue, false (default) Emit the TypeScript source alongside the sourcemaps within a single file; If enabled, will automatically enable inlineSourceMap and sourceMap.
isolatedModulesoptiontrue, false (default) Ensures that the output is safe to only emit single files by making cases that break single-file transpilation an error.
jsxoption'preserve', 'react', (TypeScript default is 'react'). If 'preserve', TypeScript will emit .jsx; if 'react', TypeScript will transpile and emit .js files.
mapRootoptionstring - root for referencing files in JS
moduleoptiondefault to be nothing, If you want to set it you set it to either 'amd' or 'commonjs'
moduleResolutionoption'classic' or 'node'. This was introduced in TypeScript 1.6. The default is 'node' if not passed. More details here.
newLineoptionCRLF, LF, `` (default) - If passed with a value, TypeScript will use the specified line endings. Also affects grunt-ts transforms.
noEmitoptiontrue, false (default) - If passed as true, TypeScript will not emit even if it compiles cleanly
noEmitHelpersoptiontrue, false (default) - If passed as true, TypeScript will not generate custom helper functions like __extends in compiled output
noEmitOnErroroptiontrue, false (default) - If passed as true, TypeScript will not emit JS if there is an error (see also failOnTypeErrors)
noImplicitAnyoptiontrue, false (default) - enable for stricter type checking
noResolveoptiontrue, false (default) - for deprecated version of TypeScript
outtargetstring - instruct tsc to concatenate output to this file.
outDirtargetstring - instruct tsc to emit JS to this directory.
preserveConstEnumsoptiontrue, false (default) - If true, const enums will be kept as enums in the emitted JS.
referencetargetstring - tells grunt-ts which file to use for maintaining references
removeCommentsoptiontrue (default), false - removes comments in emitted JS
rootDiroptionstring - Allows override of common root folder calculated by --outDir.
sourceRootoptionstring - root for referencing TS files in
sourceMapoptiontrue (default), false - indicates if source maps should be generated (
suppressImplicitAnyIndexErrorsoptionfalse (default), true - indicates if TypeScript should allow access to properties of an object by string indexer when --noImplicitAny is active, even if TypeScript doesn't know about them.
srctargetstring or string[] - glob of TypeScript files to compile.
targetoption'es5' (default), 'es3', or 'es6' - targeted ECMAScript version
tsconfigtargettrue, a string path, or an object. See tsconfig for details.
verboseoptiontrue, false (default) - logs tsc command-line options to console
vstargetstring referencing a .csproj or .vbproj file or, {} (object) (see Visual Studio Projects for details)
watchtargetstring - will watch for changes in the specified directory or below
something elseDon't see the switch you're looking for? Check out additionalFlags

Note: In the above chart, if "where to define" is "target", the property must be defined on a target or on the ts object directly. If "where to define" is "options", then the property must be defined on an options object on ts or on a target under ts.

Grunt-ts does not support the GruntJS standard dest target property. Instead, you should use files, out, or outDir.

Grunt-ts supports use of the GruntJS-centric files property on a target as an alternative to the tsc-centric use of src and out/outDir.


  • The fast grunt-ts option is not supported in this configuration. You should specify fast: 'never' to avoid warnings when files is used.
  • It is not supported to specify an array of values for dest with grunt-ts. A warning will be issued to the console. If a non-empty array is passed, the first element will be used and the rest will be truncated.
  • If the dest parameter ends with ".js", the value will be passed to the --out parameter of the TypeScript compiler. Otherwise, if there is a non-blank value, it will be passed to the --outDir parameter.
  • If you intend to pass the specific value "src" to the TypeScript --outDir parameter, specify it as "src/" in the dest parameter to avoid grunt-ts warnings.

Here are some examples of using the target files property with grunt-ts:

  ts: {
    compileTwoSetsOfFilesUsingArrayStyle: {
      // This will run tsc twice.  The first time, the result of the 'files1/**/*.ts' glob will be 
      // passed to tsc with the --out switch as 'out/ArrayStyle/1.js'. 
      // see 
      files: [{ src: ['files1/**/*.ts'], dest: 'out/ArrayStyle/1.js' },
              { src: ['files2/**/*.ts'], dest: 'out/ArrayStyle/2.js' }],
      options: {
        fast: 'never'
    compileTwoSetsOfFilesToDirUsingArrayStyle: {
      // This will run tsc twice.  The first time, the result of the 'files1/**/*.ts' glob will be 
      // passed to tsc with the --outDir switch as 'out/ArrayStyle'. 
      // see 
      files: [{ src: ['files1/**/*.ts'], dest: 'out/ArrayStyle' },
              { src: ['files2/**/*.ts'], dest: 'out/ArrayStyle' }],
      options: {
        fast: 'never'
    compileTwoSetsOfFilesUsingObjectStyle: {
      // This will run tsc twice.  The first time, the result of the 'files1/**/*.ts' glob will be 
      // passed to tsc with the --out switch as 'out/ObjectStyle/1.js'. 
      // see 
      files: {
        'out/ObjectStyle/1.js': ['files1/**/*.ts'],
        'out/ObjectStyle/2.js': ['files2/**/*.ts']
      options: {
        fast: 'never'
    compileTwoSetsOfFilesToDirUsingObjectStyle: {
      // This will run tsc once.  The result of the globs will be passed to tsc with the 
      // --outDir switch as 'out/ObjectStyle'. 
      // see 
      files: {
        'out/ObjectStyle': ['files1/**/*.ts','files2/**/*.ts']
        options: {
          fast: 'never'

Grunt-ts supports compilation of .html file content to TypeScript variables which is explained in detail here. The html target property acts similarly to src, except that it searches for html files to convert to TypeScript variables. See also htmlModuleTemplate and htmlVarTemplate.

// How to use the html target property (incomplete example) 
  ts: {
    default: {
      html: ["templates/**/*.html"]

Note: the html compilation functionality will not fire if the src property is not specified. If you wish to only have the HTML compile to TypeScript without compiling the resulting .ts files to JavaScript, make sure they're excluded from the src globs, or else specify an empty src array alongside the html task property, and set the target compile option to false:

// Example of how to compile html files to TypeScript without compiling the resulting 
// .ts files to JavaScript. 
  ts: {
    default: {
      html: ["templates/**/*.html"],
      src: [],
      options: {
        compile: false

This section allows global configuration for the grunt-ts task. All target-specific options are supported. If a target also has options set, the target's options override the global task options.