grunt-coffee-build v1.2.1

grunt-coffee-build

Compiles hybrid coffeescript/javscript commonjs projects to run anywhere transparently(amd, commonjs or plain browser load)

Getting Started

npm install grunt-coffee-build --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

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

Overview

This task will take care of compiling, merging and generating source maps for your .coffee/.js files. If merging, the resulting source map will contain information about each individual file so they can be debugged separately.

While the name is 'coffee-build', this task may be used in javascript-only commonjs projects just for the automatic dependency resolution and merged source map generation.

Unlike other solutions that normalize commonjs projects to work in web browsers, this one won't bundle a small commonjs runtime. Instead, it will parse all require calls for relative paths, concatenate files in dependency order while wrapping each file into a commonjs-like module. All require calls are replaced by a module identifier generated from the file path (This is how google-traceur compiler handles imports when merging files)

When compiling the project to a single file, the task will wrap everything into umd, and the result runs anywhere a umd module would run. This mode of operation also integrates nicely with grunt-contrib-watch, as it will keep an in-memory cache of the compiled files and their modification date, so only modified files will be reprocessed.

When compiling to a directory(normal commonjs target) each file modification timestamp will be saved, so only modified files are recompiled(even across grunt restarts).

Example usage

This example shows a real project(vm.js) that runs on browser or node.js. It depends on the 'esprima' parser, so third party library handling is also illustrated:

# Gruntfile.coffee
  coffee_build:
      options: # options shared across all targets:
        moduleId: 'Vm'
        # it is necessary to specify a main file which exports the
        # module public API, just like one normally does in a package.json
        # file 
        main: 'src/index.coffee'
        src: 'src/**/*.coffee'
      browser:
        # this target will build everything to a single umd module.
        # it is meant for javascript environments without a module loader
        # like web browsers, but it should work anywhere.
        options:
          # if you depend on a third party library of a specific version
          # and are targeting web browsers without a module loader,
          # bundle the library in the 'includedDeps' options and it will be
          # run in a fake global object/context so it can coexists with
          # other versions of the library already loaded.
          # As an altenative you can just load the third party library
          # separately.
          # 
          # In this particular case everything works because esprima uses the
          # same name for the node.js module and the browser global object(it
          # is also wrapped in umd). 
          # 
          # In most cases this should work as long as the library is consistent
          # regarding its global object alias and commonjs module name
          includedDeps: 'node_modules/esprima/esprima.js'
          dest: 'build/browser/vm.js'
      browser_test:
        # this target will build a bundle containing the code plus
        # automated tests. no need to add the files in the 'src' directory
        # since the tests will require the source files
        options:
          src: 'test/**/*.coffee'
          dest: 'build/browser/test.js'
      nodejs_test:
        # while the above target could also be reused, this is preferred
        # when you dont need to re-run browser tests everytime,
        # as only modified files will ever need to be recompiled since
        # files are being compiled individually. (when merging compilation
        # will only be cached in memory, so it works better with
        # grunt-contrib-watch and nospawn: true)
        options:
          src: ['src/**/*.coffee', 'test/**/*.coffee']
          # if the destination doesnt end with '.js' it will be considered
          # a directory build
          dest: 'build/nodejs'

Comments

The main reason I wrote this task is because I couldn't get any existing grunt task to do what I wanted: Provide me with a single javascript file/source map that maps(correctly) to the original source files and that lets me easily integrate javascript/coffeescript with automatic dependency resolution, while letting me handle platform-specific particularities without runtime hacks.

The source maps generated by this task work flawless(at least in my tests). Debugging with node-inspector(0.3.2) or google chrome should just work.

This intends to provide a one-stop solution for building commonjs projects for web browsers or node.js using coffeescript and/or javascript. Enjoy!