gd-assets

CSS & JS combiner, compressor, and server

gd-assets

JS/CSS combining, compression, and serving.

Usage

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);
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);
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


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.

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].

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 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"
  ]
}

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 
      ]
    }
  }
}

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

NameDefaultDescription
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:noneIf set, this prefix will prepended to template names in the compiled output, so you will ask handlebars to render {tplPrefix}{templateName}
handlebarVar:HandlebarsClient-side variable name where Handlebars can be found. Will be included in the compiled output.
templateVar:Handlebars.templatesClient-side variable name where compiled templates will be put.
templatePrefix:nonePrefix to put on template names when defining them in the compiled output.
emberViews:falseIf true, use Ember's Handlebars to produce compiled views that will work in Ember instead of the standard Handlebars.
emberPath:noneIf emberViews: is true, the path to ember.js to use when compiling
handlebarsPath:noneIf 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)