grunt-coffee-build v0.0.5

grunt-coffee-build

Compiles Coffeescript files, optionally merging and generating source maps.

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. It also supports merging javascript files, and the resulting source map will contain information about each individual file.

While the name is 'coffee-build', this task may be used with javascript-only 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 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 closure. All require calls are replaced by a module identifier generated from the file path(An idea taken from the google-traceur compiler).

The task 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 recompiled.

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

Example usage

This example shows how you can configure a project that includes third party libraries and needs to have platform-specific builds (browser/node.js):

# Gruntfile.coffee
grunt.initConfig
  # This project should work seamless in browser and node.js. Each platform
  # will have a single .js file containing all the code, and a single .map
  # file that can be used to easily debug using node-inspector or any browser
  # that supports source map debugging.
 
  coffee_build:
    options:
      # default options
      wrap: true # wrap the result into an anonymous function
      sourceMap: true # generate source maps
    browser_build:
      options:
        # Merge the third party library into the browser dist, but disable source
        # map generation and module wrapping for it. The browser_export.js file
        # will export the public API to the window object(it needs to be included last).
        disableModuleWrap: ['third_party/lib.js', 'platform/browser_export.js']
        disableSourceMap: ['third_party/lib.js']
      files: [
      # src files
      {src: ['third_party/lib.js', 'src/**/*.coffee'], dest: './dist/browser_src.js'}
      # Test files. Since sources are likely to be required by the test files,
      # 'browser_test' is the only file that needs to be included in the
      # index.html that bootstraps the tests
      {src: ['third_party/lib.js', 'src/**/*.coffee', 'platform/browser_export.js' ], dest: './dist/browser_test.js'}
      ]
    nodejs_build:
      options:
        # The node.js version dont need to merge the library, but cannot include
        # it using require in the sources shared with the browser(require calls to
        # relative paths are preprocessed), so we use a special node-only file that is
        # concatenated first and will require the library into the package namespace.
        # Besides dependency initialization, this file might contain nodejs-specific code,
        # so we dont include it in 'disableSourceMap' for debugging. We also need to
        # export the package API, so the 'index.js' file is not wrapped into a module so
        # the 'module/exports' names are bound to the nodejs module object.
        disableModuleWrap: ['platform/nodejs_init.js', 'platform/nodejs_export.js']
      files: [
      # src files
      {src: ['platform/nodejs_init.js', 'src/**/*.coffee', 'platform/nodejs_export.js'], dest: './dist/nodejs_src.js'}
      # test files
      {src: ['platform/nodejs_init.js', 'test/**/*.coffee', 'platform/nodejs_export.js'], dest: './dist/nodejs_test.js'}
      ]

As the above example shows, when a filename is passed to 'dest', the task will concatenate all files, generating a source map that maps to the original files.

By default each merged file is wrapped into a module function that simulates a commonjs environment, excluding files passed to the 'disableModuleWrap' option(useful if you want a piece of code that isn't bound to a scope that has module/exports defined).

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.