Grunt is a JavaScript task runner. It can be installed using NPM, which is used to list all its plugins:

npm install -g grunt-cli

In the case of a new project, make sure that package.json exists in the root of your TypeScript project. You can generate a simple one by using npm init.

Once it is done, you can install Grunt into your project:

npm install grunt --save-dev

Once Grunt is available on your machine and specified in your project, you need to get a TypeScript plugin. Grunt has two plugins named grunt -TypeScript and grunt-TS. The former has not been maintained for a few years and lacks the latest TypeScript compiler configuration. I strongly suggest using the latter:

npm install grunt-ts --save-dev

The last package should be installed as a dev dependency for Grunt to compile TypeScript and to install it locally. Grunt will search for the package locally. Omitting TypeScript as a local dependency will result in the following error when executing Grunt.

Installing TypeScript locally as a dev dependency is easy:

npm install typescript --save-dev

Prior to grunt-ts version 6, TypeScript and Grunt were installed during the installation of grunt-ts. This is not the case anymore, so they must be added manually.

The next step is to configure Grunt to use a TypeScript plugin. If you are not using Grunt, you need to create a Gruntfile.js at the root of your project. Otherwise, you can edit your existing one. The plugin allows you to specify many TypeScript options in the Gruntfile.js, but a good practice is to limit TypeScript options directly in the file and to leverage the TypeScript configuration file. By configuring TypeScript outside Grunt, this gives you the possibility of compiling your code without Grunt, or migrating to another build tool without having to duplicate or change TypeScript preferences.

A minimalist Grunt configuration with the sole purpose of compiling TypeScript into JavaScript may look like the following:

module.exports = function(grunt) {
 grunt.initConfig({
   ts: {
    default : {
     tsconfig: './tsconfig.json'
    }
   }
 });
 grunt.loadNpmTasks("grunt-ts");
 grunt.registerTask("default", ["ts"]);
};

The Grunt configuration creates a default task that executes a custom ts task that links to the tsconfig.json file, which is the default TypeScript configuration file.

The tsconfig.json file can look like the following one, which takes every TypeScript file with the extension .ts and will compile them outputting the result in the build folder:

{
 "compilerOptions": {
   "rootDir": "src",
   "outDir": "build",
 }
}

When using grunt and grunt-ts, you must ensure that that the JSON is valid with no-trailing commas in the tsconfig.json file. Otherwise, you may get the following error:

tsconfig error: "Error parsing "./tsconfig.json".  It may not be valid JSON in UTF-8."

To test the configuration, create a simple index.ts file in an src folder at the root of the project. You can type console.log('test'). After, run grunt in a command line at the root of your project as well. This will create a build folder with an index.js file containing the same line of code. It will also create the js.map file that will let you debug in your browser directly in TypeScript's code.

If, for some reason, you do not want to rely on tsconfig.json, it's possible to specify the source and destination directly into Gruntfile.js file:

module.exports = function (grunt) {
 grunt.initConfig({
  ts: {
   default: {
    src: ["src/**/*.ts"],
     outDir: "build",
     options: {
     rootDir: "src"
    }
   }
  }
 });
 grunt.loadNpmTasks("grunt-ts");
 grunt.registerTask("default", ["ts"]);
};

In the end, grunt-ts wraps the TypeScript command line. It provides options such as the fast compilation, which compile, only what has changed since the last compilation. It is also an interesting option if you are already using Grunt in your project and want to start using TypeScript without modifying your build process.