ark

Ark

Ark allows you package up your browser Javascript using the Node module system. You can use require just like in Node. Put another way, you can reuse server-side code in the browser and still use require and NPM.

Hat Tip

To browserify, which was the original inspiration for Ark, and from which I took some code, such as the HTTP implementation.

Speaking Of Which ...

The obvious question is: how is Ark different than browserify?

• Ark is more CoffeeScript-friendly. You don't need to add a transform or plugin to bundle CoffeeScript into your Ark. Also, most of Ark is actually implemented in CoffeeScript in case you want to fork or submit patches.

• Ark uses a CSON manifest file with glob expansion to decide what to package up. You can easily see what's include with the list command (or, programmatically, with the list method).

• Ark does not use the package.json browser field, or any other specification for generating your bundled JavaScript. Everything you need to know is in the manifest.

• Ark allows you to include any arbitrary files into your ark. You can then use the node fs API to read them. For example, we often bundle a configuration file that tells us where to find various backend resources.

• Ark is just simpler, both in terms of usage and implementation.

Installation

npm install -g ark

Usage

1. Create an ark directory in your source tree. Put stuff in that directory that you want to ship to the browser. In Ark parlance, that stuff is called "the ark."

2. Add in a package.json file to set the entry point for your ark (using the main property).

3. Create a ark.cson file with the list of files and emulated Node APIs you want to bundled in your ark.

4. Package up your ark: ark package -p <ark-directory> -o <path-to-javascript>

The Manifest

The manifest file might look like this:

include: [
  "**/*.coffee"
  "package.json"
]
apis: [ "assert", "child_process", "crypto", "events", "fs", "http",  
        "https", "module", "path", "querystring", "stream", "sys", "tty", 
        "url", "util" ]

That's it. There's never any question about which files or APIs are included, because you control it via the manifest.

Excluding Files

You can also exclude files. For example, if you want to make sure that no files within test directories are committed, you might do something like this:

include: [
  "**/*.coffee"
  "package.json"
]
exclude: [
  "**/test/**"
  "**/spec/**"
]
apis: [ "assert", "child_process", "crypto", "events", "fs", "http",  
        "https", "module", "path", "querystring", "stream", "sys", "tty", 
        "url", "util" ]

Checking The Manifest

If you use glob expansion, you might want to see exactly what the result of the expansion is -- you can do this by using the list command:

ark ls -p <manifest>

More Details

See the man page for more, or just type ark help.

API

You can also use Ark programmatically. It's pretty simple:

Ark = require "ark"

ark = new Ark
  path: "."
  manifest:
    include: [ "**/*.coffee", "package.json" ]
    exclude: [ "**/test/**", "**/spec/**" ]
    apis: [ "assert", "child_process", "crypto", "events", "fs", "http",  
      "https", "module", "path", "querystring", "stream", "sys", "tty", 
      "url", "util" ]
ark.package()      

Other options include:

• compilers. This is just an object with file extensions as keys and functions that take a string and transform it somehow. The default compilers include one for CoffeeScript, but using this mechanism, you can include others.

Example Suppose you want to compile Jade templates when you bundle your JavaScript so that they can simply be required. You might write an Ark compiler like this:

compileJade = do ->
  jade = require "jade"
  options = 
    client: true
    compileDebug: false
  (template) -> jade.compile template, options
  
ark = new Ark
  path: "."
  compilers: jade: compileJade
  manifest:
    include: [ "**/*.coffee", "package.json" ]
    exclude: [ "**/test/**", "**/spec/**" ]
    apis: [ "assert", "child_process", "crypto", "events", "fs", "http",  
      "https", "module", "path", "querystring", "stream", "sys", "tty", 
      "url", "util" ]
  

The list Function

You can also generate the full manifest, after glob expansion, with list, which returns an array of relative paths.

Ark Middleware

New in 0.5.0 is the ability to use Ark as connect/express-style middleware so that you don't need a build step while developing. You can run it like this:

Ark = require "ark"
connect = require "connect"
app = connect()
app.use connect.static("public")
app.use Ark.middleware("my-ark-directory")

The Ark middleware keeps a "live" copy of the Ark in memory and only updates files that have changed.

Roadmap

We've temporarily removed support for minification and beautification, as well as mtime checks for the command-line tool. We expect to add these back soon.

We also plan to add auto-generation of source maps and more sophistication to the middleware (for example, keeping the generated JavaScript cached so that it can just be returned directly if nothing has changed).

Status

Ark is under active development and is still alpha-status. Please use with caution.