Grunt Asset Manifest

A Grunt task to promote and register generated assets in manifests.

This task was created to integrate the results of a multi-step asset pipeline with a Django instance formerly running compressor. In particular, in order to employ the Bless preprocessor, support was needed for a single file to expand to many.

How it works

This task moves compiled assets (for example CSS files) from a temp directory to another location on disk, generally a publicly available static asset store. If configured, a cache-busting suffix can be added to filenames as they are moved. In addition, this task updates a JSON-based manifest file which declares which files should be served by a dynamic web server in particular contexts. As the task is re-run, temp files in the source directory, prior outputs in the static asset store, as well as references stored in the manifest are kept clean.

Use

As a Grunt task, you must declare a configuration block and load the NPM module.

example configuration:

grunt.initConfig({
    manifest: {
        css: {
            home: "tmp",
            phase_directories: ['less', 'bless'],
            patterns: [
                {
                    regexp: /^([a-zA-Z_]*)-?([a-z0-9]*)?\.css$/,
                    lookup: ['name', 'fragment']
                },
                {
                    regexp: /^([a-zA-Z_]*)\.css.map$/,
                    lookup: ['name'],
                    skip_manifest: true,
                    skip_cache_buster: true
                }
            ],
            sort: 'reverse',
            asset_home: 'src/rue-storefront/rue/static',
            asset_subdir: 'CACHE/css',
            manifest_path: 'src/rue-storefront/rue/static/manifest.json',
            include_cache_buster: true
        }
    }
});

grunt.loadNpmTasks('grunt-contrib-asset-manifest');

Configuration Reference

home

Source directory to look for input files.

It is assumed that this is a temp directory created by the output of some other preprocessor step.

phase_directories

An array of strings representing subfolders within home

These directories will be scanned for input files. These are listed in order of their execution in prior steps. Files found in later steps will be favored over earlier steps. This was done to support environment-specific variations in pipeline steps.

patterns

a series of regular expressions mapping filenames to top-level names.

As phase_directories are scanned for files, those filenames will be matched against these regular expressions. Upon finding a match, the lookup list will be used to assign labels to parenthetical groups.

patterns.lookups

Labels for parenthetical groups w/in the regular expressions.

The name label is required. This utility assumes that the source filename will remain part of the output filename throughout the pipeline steps. For example, the Bless utility may split one file library.css into several files named library-blessed2.css, library-blessed1.css, library.css. A regular expression could be used to extract the library portion of each filename to create the correct association.

patterns.skip_manifest

Flag indicating that files matching this pattern should be copied, but not referenced in the manifest.

patterns.skip_cache_buster** Flag indicating that files matching

this pattern should not receive a cache-busting suffix.

Taken together, the two skip options can be used to pass a Less-generated sourcemap through to the Django instance for development environments.

sort

Indicates that entries within a top-level name should be sorted alphabetically.

A truthy value besides reverse will sort alphabetically forwards, while reverse sorts them in reverse.

asset_home

The root path on disk to move assets to.

asset_subdir

An optional subpath within asset_home for assets.

This subdir will appear in each entry in the manifest. This assumes that the webserver is simply mapping assets_home to a route, allowing the webserver to resolve paths to specific assets. In conjunction with the above example, a URL pattern of ^static\/(?P<path>.*)$ is declared on the server. By placing library.css in /CACHE/css, it is made available at the following url: http://ruelala.com/static/CACHE/css/library.css.

manifest_path

The path on disk to the asset manifest.

This path should be available to the server for reading, but not served to the public.

include_cache_buster

A flag to indicate that a cache-busting suffix should be added to filenames.

Default is false.

Hacking

This is a standard, event-driven Node application. package.json declares all dependencies and provides basic build management scripts.

Getting started

After checking out this repo, run npm init to load all dependencies.

Build scripts

npm test

Run all unit and integration tests.

npm run-script coverage

Runs the tests using istanbul, a code coverage utility. View coverage/lcov-report/index.html in a browser to see the report after running this coverage script.

npm run-script lint

Run JSHint on the source files. Blank output means zero errors.