grunt-contrib-coffee

grunt-contrib-coffee is a Grunt plugin that compiles CoffeeScript files to JavaScript. It provides comprehensive CoffeeScript compilation capabilities with advanced features including source map generation, file concatenation, literate CoffeeScript support, and configurable compilation options for various development and production scenarios.

Package Information

• Package Name: grunt-contrib-coffee
• Package Type: npm
• Language: JavaScript
• Installation: npm install grunt-contrib-coffee --save-dev
• Peer Dependency: Requires Grunt >= 0.4.5

Core Imports

After installation, load the plugin in your Gruntfile:

grunt.loadNpmTasks('grunt-contrib-coffee');

The plugin automatically registers the coffee multi-task with Grunt. This task can then be configured and run like any other Grunt task.

Basic Usage

Configure the coffee task in your Gruntfile.js:

grunt.initConfig({
  coffee: {
    compile: {
      files: {
        'path/to/result.js': 'path/to/source.coffee',
        'path/to/another.js': ['path/to/sources/*.coffee', 'path/to/more/*.coffee']
      }
    }
  }
});

Run the task:

grunt coffee

Capabilities

CoffeeScript Compilation

The main coffee multi-task compiles CoffeeScript files to JavaScript with configurable options.

// Task configuration object
interface CoffeeTaskConfig {
  options?: CoffeeOptions;
  files: FilesConfig;
}

interface CoffeeOptions {
  /** Compile JavaScript without the top-level function safety wrapper */
  bare?: boolean;
  /** When compiling multiple files into single file, concatenate source first */
  join?: boolean;
  /** Generate source map files (.js.map) */
  sourceMap?: boolean;
  /** Directory where source map files will be created */
  sourceMapDir?: string;
  /** Extension for joined source files when using join option */
  joinExt?: string;
  /** String used to concatenate files */
  separator?: string;
}

interface FilesConfig {
  [destination: string]: string | string[];
}

Usage Examples:

Single file compilation:

coffee: {
  compile: {
    files: {
      'js/app.js': 'coffee/app.coffee'
    }
  }
}

Multiple file compilation and concatenation:

coffee: {
  compile: {
    files: {
      'js/bundle.js': ['coffee/*.coffee', 'coffee/modules/*.coffee']
    }
  }
}

Bare Compilation

Compile CoffeeScript without the top-level function wrapper.

interface BareCompilationOptions extends CoffeeOptions {
  bare: true;
}

Usage Example:

coffee: {
  compileBare: {
    options: {
      bare: true
    },
    files: {
      'js/library.js': 'coffee/library.coffee'
    }
  }
}

Joined Compilation

Concatenate multiple CoffeeScript files before compilation for better source maps and single output.

interface JoinedCompilationOptions extends CoffeeOptions {
  join: true;
  joinExt?: string; // Default: '.src.coffee'
}

Usage Example:

coffee: {
  compileJoined: {
    options: {
      join: true,
      joinExt: '.joined.coffee'
    },
    files: {
      'js/combined.js': ['coffee/module1.coffee', 'coffee/module2.coffee']
    }
  }
}

Source Map Generation

Generate source map files for debugging compiled JavaScript.

interface SourceMapOptions extends CoffeeOptions {
  sourceMap: true;
  sourceMapDir?: string; // Default: same directory as compiled JS
}

Usage Example:

coffee: {
  compileWithMaps: {
    options: {
      sourceMap: true,
      sourceMapDir: 'maps/'
    },
    files: {
      'js/app.js': 'coffee/app.coffee'
    }
  }
}

Dynamic File Configuration

Use Grunt's dynamic file expansion for processing multiple files.

interface DynamicFilesConfig {
  expand: boolean;
  cwd?: string;
  src: string | string[];
  dest: string;
  ext?: string;
  flatten?: boolean;
}

Usage Example:

coffee: {
  glob_to_multiple: {
    expand: true,
    flatten: true,
    cwd: 'src/coffee/',
    src: ['*.coffee'],
    dest: 'js/',
    ext: '.js'
  }
}

Literate CoffeeScript Support

Automatically handles literate CoffeeScript files with .litcoffee and .coffee.md extensions.

Supported File Types:

• .coffee - Standard CoffeeScript files
• .litcoffee - Literate CoffeeScript files
• .coffee.md - Markdown-formatted literate CoffeeScript files

Usage Example:

coffee: {
  compileLiterate: {
    files: {
      'js/documentation.js': 'docs/api.litcoffee',
      'js/tutorial.js': 'docs/tutorial.coffee.md'
    }
  }
}

Error Handling

The plugin provides comprehensive error reporting for CoffeeScript compilation failures:

• Line and column information for syntax errors with precise location details
• Visual error indication with highlighted offending characters using red arrows
• File path context for debugging multi-file projects
• Proper Grunt task failure to halt build processes when compilation fails
• Detailed error context showing the problematic code line with character highlighting

Types of Errors Handled:

1. Syntax Errors: Invalid CoffeeScript syntax with line/column positioning
2. File Not Found: Missing source files with clear warning messages
3. Extension Mismatch: When using join/sourceMap with mixed file extensions
4. Empty Output: Warnings when compilation results in empty files
5. Unexpected Compiler Exceptions: Fallback handling for CoffeeScript compiler issues

Example error output:

Error: unexpected INDENT
In file: coffee/app.coffee
On line: 15
>> function badIndent()
>>        ^

Warning Messages:

• Source file not found: Source file "file.coffee" not found.
• No output: Destination "path/file.js" not written because compiled files were empty.
• No matches: Destination not written because no source files were found.

Task Execution Patterns

Single Target Execution

Run a specific task target:

grunt coffee:compile
grunt coffee:compileWithMaps

All Targets Execution

Run all coffee task targets:

grunt coffee

Integrated Build Process

Combine with other Grunt tasks:

grunt.registerTask('build', ['clean', 'coffee', 'uglify']);
grunt.registerTask('dev', ['coffee:compile', 'watch']);

Configuration Options Reference

interface CompleteCoffeeOptions {
  /** Compile without function wrapper (default: false) */
  bare?: boolean;
  /** Concatenate before compilation (default: false) */
  join?: boolean;
  /** Generate source maps (default: false) */
  sourceMap?: boolean;
  /** Source map output directory (default: same as JS files) */
  sourceMapDir?: string;
  /** Extension for temporary joined files (default: '.src.coffee') */
  joinExt?: string;
  /** File concatenation separator (default: grunt.util.linefeed) */
  separator?: string;
}

// Additional CoffeeScript compiler options that may be passed through:
interface CoffeeScriptCompilerOptions {
  /** Filename for error reporting and source maps */
  filename?: string;
  /** Treat file as literate CoffeeScript (auto-detected from extension) */
  literate?: boolean;
  /** Generate inline source map */
  inline?: boolean;
  /** Source files referenced in source map */
  sourceFiles?: string[];
  /** Source root path for source map */
  sourceRoot?: string;
  /** Generated file name for source map */
  generatedFile?: string;
}

Requirements

• Node.js: >= 8
• Grunt: >= 0.4.5
• CoffeeScript: 2.3.2 (automatically installed as dependency)

Dependencies

The plugin automatically installs and uses:

• coffeescript@^2.3.2 - The CoffeeScript compiler
• chalk@^2.4.2 - Terminal styling for error messages
• lodash@^4.17.11 - Utility functions
• uri-path@^1.0.0 - URI path handling for source maps

File Processing Details

File Extension Support:

• .coffee - Standard CoffeeScript files
• .litcoffee - Literate CoffeeScript files
• .coffee.md - Markdown-formatted literate CoffeeScript files (alias for .litcoffee)

Processing Behavior:

• Files are validated for existence before compilation
• Literate mode is automatically detected from file extensions
• Source map URLs are calculated relative to output JavaScript files
• Temporary joined files are created when using join with sourceMap options
• File concatenation preserves the order specified in the files array
• Empty compilation results trigger warnings without creating output files

Output File Naming:

• Source map files use .js.map extension
• Joined source files use the joinExt option (default: .src.coffee)
• Source map directory can be different from JavaScript output directory