Squash

Why?

Squash was built to simplify building browser-compatible scripts from libraries written and tested with NodeJS.

How?

Squash locates your initial requires (the ones you want to execute in the browser) using the require.resolve algorithm used by Node. The code in that file is then searched for further dependencies and so on until all dependencies have been found. The code is then combined into a single script which will work as expected on the browser or even in Node.

Installation

npm install squash

Usage

Command Line

squash [options] <require[=alias]...>

Options

--coffee           Register the '.coffee' extension to support CoffeeScript
                   files (requires the 'coffeescript' module)
--compress     -c  Compress result with uglify-js (otherwise result is
                   beautified)
--help         -h  Print this notice
--file <file>  -f  A file to write the result to
--obfuscate    -o  Replaces all non-essential paths with dummy values
--relax        -r  Continues when modules cannot be found.  Useful if a
                   core module is required conditionally.
--watch        -w  Watch all found requires and rebuild on changes (for best
                   results an output file should be specified)

Example

To bundle src/index.coffee and all its dependencies to lib/project.js every time a dependency changes, and make it available as window.project (without the alias, it would be as window['./src']):

squash --coffee -f lib/project.js -w ./src=project

API

// build.js
var fs     = require('fs'),
    Squash = require('squash').Squash,
    squash = new Squash({ requires: {'./src': 'project'} });
fs.writeFileSync('lib/project.js', squash.squash(), 'utf8');

Browser

Having built your lib/project.js as above, you can run your project in the browser with:

<script src='lib/project.js'></script>
<script>
  project.do_awesome_things();
</script>

Node

You can also load packages with Node should you wish:

var project = require('./lib/project').project;
project.do_awesome_things();

Limitations

• The 'compatibility layer' is currently very lightweight. Scripts are given global, module (= { exports: {} }), exports and require variables (also this === exports === modules.exports). Additional properties may be added to module to improve compatibility in future versions.

• For the above reason, libraries such as jQuery that have vastly different dependencies on Node (jsdom etc.) than in the browser (DOM) do not work terribly well 'cross-platform' in this way. The easiest option here is to use the global variable to access the browser's window object, allowing you to include the library normally in the browser or attach it to global in Node.

• There is no support for core Node modules such as path, fs, etc.

Bugs etc.

If you find a bug or think something could be done better don't hesitate to submit an issue and/or pull request.