grunt-cjsc

A grunt task for running CommonJS modules compiler (https://github.com/dsheiko/cjsc)

CJSC is a command-line tool that makes your Common JS modules suitable for in-browser use.

Modular programming separates the functionality of a program into independent modules, so that each module encapsulates everything required to implement a single aspect of the desired functionality. That makes the entire system easier to debug, update and modify. Prior to Ecma-262 Edition 6, which is still a working draft, JavaScript had no build-in facilities to define a module. Nonetheless the module pattern can be achieved in JavaScript by leveraging closure scopes. There are also standardized approaches: CommonJS Modules/1.1 and AMD (Asynchronous module definition). The fist one was initially designed for server-side (desktop app) JavaScript while the second is widely used in browser-oriented web applications. CommonJS Compiler tool converts CommonJS modules into a single JavaScript file that run natively in browser.

See also the slides http://www.slideshare.net/dsheiko/modular-javascript-with-commonjs-compiler

Note: This used to be called 'grunt-contrib-cjsc' in the npm registry, but as of version 1.0.0 it has taken over the 'grunt-cjsc' name.

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-cjsc --save-dev

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

grunt.loadNpmTasks( "grunt-cjsc" );

The "cjsc" task

Overview

In your project's Gruntfile, add a section named cjsc to the data object passed into grunt.initConfig().

grunt.initConfig({
  cjsc: {
    your_target: {
			options: {
				sourceMap: "<string>",
				sourceMapUrl: "<string>",
				minify: false,
				banner: "/*! <string> %> */",
                transform: [{
                  target: "babelify",
                  options: {
                    presets: [ "es2015" ]
                  }
                }],
				config: {
					"<dependency-name>": {
						"path": "<dependency-path>",
						"require": "<dependency-name>",
						"exports": "<object>"
					}
				}
			},
      files: {
        "destination file" : "source file",
        "destination file" : "source file"
      }
    }
  }
})

Usage Examples

Compile main.js to build.js

grunt.initConfig({
  cjsc: {
    development: {
        files: {
          "./fixture/build.js" : "./fixture/main.js"
        }
      }
  }
});

Compile main.js to build.js and generate source map

grunt.initConfig({
  cjsc: {
    development: {
			options: {
				sourceMap: "fixture/*.map",
				sourceMapUrl: "http://localhost/",
			},
			files: {
				"./fixture/build.js" : "./fixture/main.js"
			}
		}
  }
});

Compile with compression and prepend destination code with a banner

grunt.initConfig({
	pkg: grunt.file.readJSON( "package.json" ),
  cjsc: {
		options: {
			minify: true,
			banner: "/*! <%= pkg.name %> - v<%= pkg.version %> - " +
				"<%= grunt.template.today(\"yyyy-mm-dd\") %> */"
		},
    development: {
			files: {
				"./fixture/build.js" : "./fixture/main.js"
			}
		}
  }
});

Compile main.js to build.js by using dependency configuration

grunt.initConfig({
  cjsc: {
		options: {
			config: {
				"jQuery": {
					"path": "./jquery-stub.js"
				},
				"plugin": {
					"path": "./jquery-plugin-stub.js",
					"require": "jQuery",
					"exports": "jQuery"
				}
			}
		},
    development: {
			files: {
				"./fixture/build.js" : "./fixture/main.js"
			}
		}
  }
});

Usage Examples

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.