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