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.