or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

compilation.mdfast-compilation.mdhtml-processing.mdindex.mdtransforms.mdtsconfig.mdvisual-studio.mdwatch-mode.md
tile.json

index.mddocs/

grunt-ts

grunt-ts is a comprehensive Grunt plugin for TypeScript compilation that provides a Grunt-compatible wrapper around the TypeScript compiler (tsc) with extensive additional functionality. It enables seamless TypeScript integration into Grunt build workflows with advanced features like HTML template processing, automatic reference management, fast compilation caching, and code transforms for easier refactoring.

Package Information

  • Package Name: grunt-ts
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install grunt-ts

Core Imports

The package exports a single Grunt plugin function that registers the 'ts' task:

// In your Gruntfile.js
module.exports = function(grunt) {
  grunt.loadNpmTasks("grunt-ts");
  // or
  require("grunt-ts")(grunt);
};

Basic Usage

// Minimalist Gruntfile.js for TypeScript compilation
module.exports = function(grunt) {
  grunt.initConfig({
    ts: {
      default: {
        src: ["**/*.ts", "!node_modules/**"]
      }
    }
  });
  grunt.loadNpmTasks("grunt-ts");
  grunt.registerTask("default", ["ts"]);
};

More advanced configuration:

module.exports = function(grunt) {
  grunt.initConfig({
    ts: {
      dev: {
        src: ["src/**/*.ts"],
        outDir: "built/",
        options: {
          target: "es5",
          module: "commonjs",
          sourceMap: true,
          declaration: true,
          fast: "watch"
        }
      },
      prod: {
        src: ["src/**/*.ts"],
        out: "dist/app.js",
        options: {
          target: "es5",
          removeComments: true,
          sourceMap: false
        }
      }
    }
  });
  grunt.loadNpmTasks("grunt-ts");
};

Architecture

grunt-ts is built around several key systems:

  • Task System: Grunt multi-task registration with target-specific configurations
  • Compilation Engine: Wrapper around TypeScript compiler with result processing and error categorization
  • Fast Compilation: Incremental compilation system with file change detection and caching
  • Transforms System: Code generation for import/export/reference maintenance during refactoring
  • Template Processing: HTML-to-TypeScript conversion for template engines
  • Integration Layer: Support for Visual Studio projects and tsconfig.json files
  • Watch System: File monitoring with automatic recompilation on changes

Capabilities

TypeScript Compilation

Core TypeScript compilation functionality supporting all tsc compiler options and advanced build configurations.

// Task registration (internal)
function registerMultiTask(name: string, description: string, taskFunction: Function): void;

// Main configuration interfaces
interface IGruntTSOptions extends ITaskOptions, ITargetOptions {
  CompilationTasks?: IGruntTSCompilationInfo[];
  warnings: string[];
  errors: string[];
}

interface ITargetOptions {
  reference?: string;
  baseDir?: string;
  html?: string[];
  htmlOutDir?: string;
  htmlOutDirFlatten?: boolean;
  watch?: string;
  amdloader?: string;
  templateCache?: {
    src: string[];
    dest: string;
    baseUrl: string;
  };
  vs?: string | IVisualStudioProjectSupport;
  tsconfig?: boolean | string | ITSConfigSupport;
  options?: ITaskOptions;
}

interface ITaskOptions {
  // Core TypeScript compiler options
  target?: string; // "es3" | "es5" | "es6"
  module?: string; // "amd" | "commonjs" | "umd" | "system" | "es6" | "es2015"
  declaration?: boolean;
  sourceMap?: boolean;
  outDir?: string;
  removeComments?: boolean;
  noImplicitAny?: boolean;
  
  // grunt-ts specific options
  fast?: string; // "never" | "always" | "watch"
  compile?: boolean;
  failOnTypeErrors?: boolean;
  verbose?: boolean;
  emitGruntEvents?: boolean;
  
  // HTML processing options
  htmlModuleTemplate?: string;
  htmlVarTemplate?: string;
  htmlOutputTemplate?: string;
  
  // Advanced TypeScript options (50+ additional options)
  experimentalDecorators?: boolean;
  emitDecoratorMetadata?: boolean;
  jsx?: string;
  moduleResolution?: string;
  allowJs?: boolean;
  // ... (100+ total compiler options)
}

TypeScript Compilation

HTML Template Processing

Convert HTML files to TypeScript variables for template engines and build integration.

interface IHtml2TSOptions {
  moduleFunction: Function;
  varFunction: Function;
  htmlOutputTemplate?: string;
  htmlOutDir?: string;
  flatten?: boolean;
  eol?: string;
}

function compileHTML(filename: string, options: IHtml2TSOptions): string;

HTML Processing

Code Transforms

Automatic import/export/reference path maintenance for easier refactoring when file locations change.

// Transform syntax (used in TypeScript comments)
// ///ts:import=<fileOrDirectoryName>[,<variableName>]
// ///ts:export=<fileOrDirectoryName>[,<variableName>]  
// ///ts:ref=<fileName>

function transformFiles(
  changedFiles: string[], 
  targetFiles: string[], 
  options: IGruntTSOptions
): void;

Code Transforms

Visual Studio Integration

Support for TypeScript compilation settings from Visual Studio project files.

interface IVisualStudioProjectSupport {
  project: string;
  config?: string;
  ignoreFiles?: boolean;
  ignoreSettings?: boolean;
}

Visual Studio Integration

TypeScript Configuration Support

Integration with tsconfig.json files with flexible override options.

interface ITSConfigSupport {
  tsconfig?: string;
  ignoreSettings?: boolean;
  overwriteFilesGlob?: boolean;
  updateFiles?: boolean;
  passThrough?: boolean;
}

interface ITSConfigFile {
  compilerOptions?: ICompilerOptions;
  files?: string[];
  exclude?: string[];
  filesGlob?: string[];
}

TSConfig Integration

Watch Mode

File monitoring with automatic recompilation and fast incremental builds.

// Watch configuration (part of ITargetOptions)
interface WatchOptions {
  watch: string; // Directory to watch
  fast: "watch" | "always" | "never"; // Fast compilation mode
}

Watch Mode

Template Cache

Generate AngularJS template cache files from HTML templates for RequireJS/AMD loading.

interface TemplateCache {
  src: string[];    // HTML template files to process
  dest: string;     // Output JavaScript/TypeScript file
  baseUrl: string;  // Base URL for template paths
}

function generateTemplateCache(
  templateCacheSrc: string[], 
  templateCacheDest: string, 
  templateCacheBasePath: string, 
  eol: string
): void;

AMD Loader

Generate AMD loader files for RequireJS integration with proper dependency ordering.

interface IReferences {
  all: string[];
  before: string[];
  generated: string[];
  unordered: string[];
  after: string[];
}

function updateAmdLoader(
  referenceFile: string, 
  referenceOrder: IReferences, 
  amdloaderFile: string, 
  amdloaderPath: string, 
  outDir: string
): void;

function getReferencesInOrder(
  referenceFile: string, 
  referencePath: string, 
  generatedFiles: string[]
): IReferences;

Fast Compilation

Incremental compilation system with intelligent caching for improved build performance.

interface ICompileResult {
  code: number;
  output: string;
  fileCount?: number;
}

function compileAllFiles(
  options: IGruntTSOptions, 
  compilationInfo: IGruntTSCompilationInfo
): Promise<ICompileResult>;

function compileResultMeansFastCacheShouldBeRefreshed(
  options: IGruntTSOptions, 
  result: ICompileResult
): boolean;

Fast Compilation

Events

grunt-ts can emit Grunt events for build pipeline integration:

// Event emitted on compilation failure (when emitGruntEvents: true)
grunt.event.on('grunt-ts.failure', function() {
  // Handle compilation failure
});

Types

interface IGruntTSCompilationInfo extends grunt.file.IFilesConfig {
  outDir?: string;
  out?: string;
  src?: string[];
  glob?: string[];
}

interface ICompilerOptions {
  allowNonTsExtensions?: boolean;
  charset?: string;
  codepage?: number;
  declaration?: boolean;
  diagnostics?: boolean;
  emitBOM?: boolean;
  experimentalAsyncFunctions?: boolean;
  experimentalDecorators?: boolean;
  emitDecoratorMetadata?: boolean;
  help?: boolean;
  isolatedModules?: boolean;
  inlineSourceMap?: boolean;
  inlineSources?: boolean;
  jsx?: string;
  locale?: string;
  mapRoot?: string;
  module?: string;
  moduleResolution?: string;
  newLine?: string;
  noEmit?: boolean;
  noEmitHelpers?: boolean;
  noEmitOnError?: boolean;
  noErrorTruncation?: boolean;
  noImplicitAny?: boolean;
  noLib?: boolean;
  noLibCheck?: boolean;
  noResolve?: boolean;
  out?: string;
  outFile?: string;
  outDir?: string;
  preserveConstEnums?: boolean;
  removeComments?: boolean;
  rootDir?: string;
  sourceMap?: boolean;
  sourceRoot?: string;
  suppressImplicitAnyIndexErrors?: boolean;
  target?: string;
  version?: boolean;
  watch?: boolean;
}