gd-assets

JS/CSS combining, compression, and serving.

Usage

Compiling to files

var Assets    = require('gd-assets');
var config    = Assets.Config.load('/path/to/your/assets.json');
var pkg       = require('/path/to/your/package.json');
var outputDir = '/path/to/compiled'

var opt = {
  // See options
};

Assets.Compile(config, pkg, outputDir, opt);

As a middleware

var app = express(); // Or connect

var Assets = require('gd-assets');
var config = Assets.Config.load('/path/to/your/assets.json');
var opt = {
  // See options
};

Assets.Middleware(app, config, opt);

As a standalone server

var Assets = require('gd-assets');
var config = Assets.Config.load('/path/to/assets.json');
var pkg    = require('/path/to/package.json');
var port   = 3000;

Assets.Server(config, pkg, port);

Assets.json file

CSS and JavaScript files

The assets.json file describes which files should be processed, and how they should be grouped together. The file can be called whatever you like, but it must contain a JSON dictionary. It is easiest to describe with an example:

{
  "groups": {
    "main": {
      "js":   ["init","util","main"],
      "view": ["layout","index","login"],
      "css":  ["bootstrap","app"]
    }
  }
}

This will combine:

  js/init.js
  js/util.js
  js/main.js
  The pre-compiled representation of view/layout.hbs
  The pre-compiled representation of view/index.hbs
  The pre-compiled representation of view/login.hbs

into one file and make it available as main.js (in compiling files mode), {prefix}/main.js (in middleware mode), or http://localhost/main.js (in standalone server mode).

It will also combine

  css/bootstrap.css
  css/app.js

into one main.css in the same places.

A minified version of each is also produced, main.min.js and main.min.css.

Groups

All files are included in the output in the order they appear in the input arrays. Groups can include other groups (and so on). Includes will be included before the other files of that group.

{
  "groups": {
    "framework": {
      "saveOutput": false,
      "view": ["layout","index"],
      "css":  ["bootstrap"],
      "js": ["init","util"]
    },

    "main": {
      "include": ["framework"],
      "view": ["login"],
      "css":  ["app"],
      "js": ["main"]
    }
  }
}

Groups that contain "saveOutput": false can be used as includes in other groups for logical organization, but will not produce any output file/URL themselves. In the example above, only main[.min].[js|css] would be produced, not framework[.min].[js|css].

Images and other static files

Directories of additional 'static' assets that do not need to be compiled may also be included using the "staticFileDirs": property. Paths are relative to the location of the config file.

{
  "staticFileDirs": {
    "image": "public/my-images",
    "font":  "/path/to/some/fonts"
  }
}

The above example will make the contents of public/my-images available at {prefix}/image/ and /path/to/some/fonts at {prefix}/font.

Root files

Root files are similar to staticFileDirs, but are intended to be served from the absolute root of your URL (http://app.com/). This is useful for things like favicon.ico and robots.txt that are expected to be at the root of the site even if the rest of the assets aren't. Paths are relative to the location of the config file.

{
  "rootFileDirs": [
    "root",
    "/path/to/more/root/stuff"
  ]
}

Path resolution

Group entries

Group entry paths are relative to {the directory the assets.json file is in}/public/{js,css,view}/ by default. All examples below assume the assets.json file is located at /app/assets.json.

{
  "groups": {
    "main": {
      "js": ["things"] // -> /app/public/js/things.js
  }
}

Relative paths may include ../:

{
  "groups": {
    "main": {
      "js": ["../vendor/blah/things"]  // -> /app/public/js/../vendor/things.js -> /app/public/vendor/things.js
  }
}

Or you can specify an absolute path:

{
  "groups": {
    "main": {
      "js": ["/path/to/some/things"] // -> /path/to/some/things.js
    }
  }
}

Individual groups may specify an alternate base directory for the paths to be relative to.

• If specified, public/{js,css,view} will not be added automatically for you.

{
  "groups": {
    "main": {
      "baseDir": "vendor", // <-- Relative to the directory the assets.json file is in, or absolute.  See below.
      "js": [
        "jquery" // <-- /app/vendor/jquery.js
      ],
      "css": [
        "jquery" // <-- /app/vendor/jquery.css
      ]
    }
  }
}

Static paths and base directories

rootFileDirs, staticFileDirs, and baseDir paths are relative to directory the assets.json file is in. Relative paths, including ../ and absolute paths may be used.

Options

Name | Default | Description -----|---------|------------- prefix: | / | For middleware mode, the base path to listen for requests on. e.g. '/assets' will make things available at http://host:port/assets/something.js rootPrefix: | / | For middleware mode, if root files are specified, the base path to listen for root requests on. Since the point of root files is to be at the root, you probably don't want to change this. tplPrefix: | none | If set, this prefix will prepended to template names in the compiled output, so you will ask handlebars to render {tplPrefix}{templateName} handlebarVar: | Handlebars | Client-side variable name where Handlebars can be found. Will be included in the compiled output. templateVar: | Handlebars.templates | Client-side variable name where compiled templates will be put. templatePrefix: | none | Prefix to put on template names when defining them in the compiled output. emberViews: | false | If true, use Ember's Handlebars to produce compiled views that will work in Ember instead of the standard Handlebars. emberPath: | none | If emberViews: is true, the path to ember.js to use when compiling handlebarsPath: | none | If emberViews: is true, the path to handlebars.js to use when compiling jsmin: | {warnings: false, hoist_funs: false} | Options to pass to UglifyJS (see documentation)