A simple yet sophisticated tool for building, compiling & minifying projects.

Rocket is a node.js based universal compiler, builder & minifier offering functionality similar to CodeKit and Springboard. The sugar that separates Rocket from the rest lies at the core of its flexibility. Read on for guaranteed gasps…

Firstly, you will need node.js version 0.8.2 or higher. Once installed, run the following command:

sudo git clone -b "deploy" https://github.com/carlcalderon/Rocket.git /usr/local/lib/rocket; sudo ln -s /usr/local/lib/rocket/rocket /usr/local/bin/rocket

This will install Rocket to your user directory and make it available everywhere.

To update Rocket, open up the terminal and run:

rocket --update

To use Rocket, simply open up the terminal and run:

rocket [ options... ] <path_to_config>

Rocket's only requirement is a single JSON configuration file. It really is that simple!

{
    "input_dir": "source",
    "output_dir": "deploy",
    "buildOrders": [
        {
            "id": "build-my-site",
            "items": [

                // My index file
                "index.html",

                // Copy my images
                "images",

                // Compile my CoffeeScript
                {
                    "input": "coffee/scripts.coffee",
                    "output": "js/scripts.js",
                    "minify": true
                },

                // Compile my LESS files
                {
                    "input": [
                        "less/mixins.less",
                        "less/styles.less"
                    ],
                    "output": "css/styles.css"
                }
            ]
        }
    ]
}

...will output...

• deploy/index.html
• deploy/images/
• deploy/js/scripts.js
• deploy/css/styles.css

...where scripts.js is compiled and minified into scripts.js and mixins.less is compiled together with styles.less into styles.css.

Tip: If no configuration file is specified, Rocket automatically tries to load rocket-config.json in the current working directory.

The root JSON object may specify the following fields:

The buildOrders field specified in a configuration file should contain a list of Build Orders. A Build Order consists of a single Object which contain an idfield and an items field. The id is used to reference the build order and the items field may contain Build Objects (See Build Objects). Build Orders are similar to <target> nodes in ANT.

Tip: You may list available Build Orders in a Rocket configuration file by adding the -l or --list flag.

Tip: You may select a specific Build Order to execute by setting the -b or --build flag (i.e. $ rocket --build "push-to-git" rocket-config.json).

{
    "input_dir": "source",
    "output_dir": "deploy",
    "buildOrders": [
        
        // A Build Order copying JavaScript
        {
            "id": "scripts",
            "items": [
				"js/my-script.js",
				"js/lib/jquery.js"
            ]
        },
        
        // Another Build Order that concatenates 3 folders
        // of pictures into a single "my-pets" folder and
        // copy the favicon.ico from the source to the deploy.
        {
        	"id": "images",
        	"items": [
        		{
        			"input": [
        				"my-dog",
        				"my-cat",
        				"my-parrot",
        			],
        			"output": "my-pets"
        		},
        		"favicon.ico"
        	]
        }
        
    ]
}

Build Objects may be as simple as a path to a file or folder. There are several different types of Build Objects each performing a different task.

Files & folders may hold the following fields:

The following Build Object specifies 3 folders containing pictures of pets as input directories and concatenate them to a single my-pets folder.

{
	"input": [
		"my-dog",
		"my-cat",
		"my-parrot",
	],
	"output": "my-pets"
}

The following Build Object concatenates, compiles and minifies two coffee scripts into a single scripts.js file.

{
	"input": [
		"coffee/bootstrap.coffee",
		"coffee/menu.coffee"
	],
	"minify": true,
	"output": "js/scripts.min.js"
}

Each line below are valid Build Objects and are parsed and compiled if needed too.

[...]
"scripts/bootstrap.coffee", // will result in scripts/bootstrap.js
"images", // will be copied recursively
"index.html" // will be parsed for notation blocks (See Notation) and copied
[...]

Tip: If a string; Rocket will automatically derive whether it is a file or a folder and perform the appropriate tasks pending on the type. Folders will be copied recursively and files will be parsed for notation blocks before being copied directly to a mirrored path in the outputDir.

Build Objects may also execute command line tasks such as git or curl. The output from these executions may be stored into files as well making Rocket extremely powerful.

// Get a fresh copy of jQuery
{
	"exec": "curl http://code.jquery.com/jquery-1.8.2.min.js",
	"output": "js/jquery.min.js"
},

// Pull the latest from your GIT repo
{
	"exec": "git pull"
}

Another handy trick Rocket provides is linkage to other Build Orders. Much like the depends attribute in ANT but with the advantage of being able to decide when it's executed.

// Single
"buildOrder": "get-latest-from-git",

// Multiple
"buildOrder": ["get-latest-from-git", "build-all", "deploy-to-server"]

Rocket comes with a collection of commonly used compilers for your convenience. Furthermore, these compilers are automatically selected and employed by the following schema:

An awesome feature of Rocket is custom compiler configuration.

If you have some CoffeeScript that needs to be compiled with the bare flag (-b), you can specify a custom compiler like so:

{
    "inputDir": "source",
    "outputDir": "deploy",
    "compilers": {
        "coffeescript-bare": {
            "executable": "coffee",
            "arguments": "-cb -o {output} {input}"
        }
    },
    "buildOrders": [
        {
            "id": "compile",
            "items": [
                {
                    "input": "coffee/scripts.coffee",
                    "output": "js/scripts.js",
                    "compiler": "coffeescript-bare"
                }
            ]
        }
    ]
}

The above example declares a custom compiler with an ID of coffeescript-bare and specifies the executable and bespoke arguments. The custom coffeescript-bare compiler is then referenced in a build object to be used to compile scripts.coffee into scripts.js.

The custom compiler can contain any number of custom fields which are shared between the arguments string and the build object it self (NOTE: {input} and {output} are reserved). This allows for shared compiler setups but file-to-file specific arguments.

The following example shows how a single custom compiler can produce different results by using a custom message field:

{
    "inputDir": "source",
    "outputDir": "deploy",
    "compilers": {
        "coffeescript-custom": {
            "executable": "coffee",
            "returnsOutput": true,
            "arguments": "-pe {message}"
        }
    },
    "buildOrders": [
        {
            "id": "compile",
            "items": [
                {
                    "compiler": "coffeescript-custom", // Link to custom compiler
                    "message": "### Hello! ###",  // Custom message
                    "output": "js/hello.js"
                },
                {
                    "compiler": "coffeescript-custom", // Link to custom compiler
                    "message": "### World! ###", // Custom message
                    "output": "js/world.js"
                }
            ]
        }
    ]
}

Rocket (as well as Springboard) provides basic html comment notations to specify inline build actions within files. Rocket recognises both Rocket & Springboard (limited) notation blocks.

<!-- <rocket|sb>: <action> <target|notes> -->
<content>
<!-- end -->

<!-- rocket: replace js/scripts.js -->
<script type="text/coffeescript" src="coffee/scripts.coffee"></script>
<!-- end -->

<!-- rocket: minify css/styles.css -->
<link rel="stylesheet" type="text/css" href="less/styles.less">
<!-- end -->

<!-- rocket: remove Debug mode -->
<script type="text/javascript">

    var DEBUG_MODE = true;

</script>
<!-- end -->

<!-- rocket: insert -->
header.html
body.html
footer.html
<!-- end -->

Unless running in watch mode, all builds are made in order of input. This provides a unique way of nesting build objects.

The following example shows how the output of one build item can be used as the input of the next.

{
    "input_dir": "source",
    "output_dir": "deploy",
    "build": [
        {
            "input": "coffee/library.coffee",
            "output": "js/library.js"
        },
        {
            "input": "../deploy/js/library.js",
            "output": "js/library.min.js",
            "minify": true
        }
    ]
}

Pretty awesome right? Now imagine the following scenario:

1. Rocket performs a build which constructs a new configuration file.
2. In the same build, a new Rocket instance is run as a custom compiler with the -a flag targeting the generated configuration file.
3. The new Rocket instance could then perform step 1 and so on and so on...

Combine custom compilers with the order of compilation and it is easy to see that Rocket can perform the most amazing things. With minimal effort, you can setup a complete build order including LESS, CoffeeScript, compression and even deployment.

Rocket will always be in favour of developers and evolve along side the community. So please get involved, post a suggestion, or send a pull request!

SEP 28, 2012

• Image compression (optipng and jpegoptim)
• Output JSON through -j or --json
• Output tokens through -t or --tokens

SEP 24, 2012

• Multiple Build Orders
• Build Order linkage (multiple execution)
• Quiet -q mode
• Less aggressive error reports
• Even more clever watch-mode
• Completely rewritten source
• Modular configuration
• Better output type pattern
• Elaborated schematic output

Carl Calderon: @carlcalderon

Matthew Wagerfield: @mwagerfield

Licensed under the Apache License, Version 2.0