Requires no build manifest. All information about your project is
gathered from the HTML/CSS/JavaScript itself. Just tell it where to
find your HTML file(s), and it will find the referenced JavaScript,
CSS, etc.

Reads your web application from one directory, manipulates and
optimizes it, then writes the resulting build to a separate
directory with everything included.

Supports require.js define and require statements, rolls up the
dependency graph like the require.js
optimizer does (still missing some features though). Understands
the require.js config options baseUrl and paths.

Renames JavaScript, CSS, images etc. to a 10-char MD5 prefix + the
original extension so they can be served with a far-future expiry time.

Supports a special syntax for getting the url of static assets from
JavaScript code (GETSTATICURL). These are also modelled as
relations so the target files will be included in the build and thus
renamed so they can be served with a far-future expiry time.

Helps getting your static assets on a CDN by rewriting the
references to them (controlled by the --cdnroot and
--cdnoutroot switches).

Supports internationalization of HTML, JavaScript, SVG, and Knockout.js
templates (support for more template formats will be added on demand).

Very customizable, the entire build script is only around 100 lines
of code due to the reliance on high level AssetGraph
transforms.

Optional first step: To take full advantage of the image processing
and optimization features, you need several libraries and command line
utilities installed. On Ubuntu you can grab them all by running:

Assetgraph needs a web root to resolve URLs correctly. If you pass in the --root option assetgraph will use it, otherwise it will take a best guess based on your startingAssets.

The --outroot option tells assetgraph-builder where to write the built files to. If the directory does not exist it will be created for you.

Your startingAssets can be one or more file paths or minimatch patterns, which will be used as the starting point of assetgraphs automatic discovery process. The default is index.html, but you might also want to add any file here that is not linked to by your website, but still has to be a part of the build, for example robots.txt, .htaccess or 404.html. If one or more files are missing from your build, check that you are actually linking to them. If you are not, and it is by design, then you should add these files as input paths in startingAssets.

There are many more options to assetgraph-builder. We suggest you consult the help with buildProduction -h.

This will produce a build that assumes that the contents of path/to/production/static/cdn
are available at http://xxxxxx.cloudfront.net/static/cdn. We recommend putting the entire
contents of path/to/production online and pointing your CloudFront (or other CDN provider)
distribution at the root of your origin server. As long as you serve /static and everything
below it with a far-future expires, you won't need to touch your CDN config or manually
upload anything to your CDN provider.

Assetgraph will compile your sass assets to CSS, but only if you link in your .scss-files like this:

<linkrel="stylesheet"type="text/css"href="path/to/stylesheet.scss">

Or using a requirejs css plugin:

// RequireJS AMD syntax

define(['css!path/to/stylesheet.scss'],function(){

// Your code here

})

// RequireJS CommonJS compatible syntax

define(function(require){

require('css!path/to/stylesheet.scss');

// Your code here

})

In order to make this work for you in development you can use livestyle as a static webserver.
It will automatically convert the sass files in the HTTP stream, making your page work out of the box with no configuration.

Sometimes you need to load a template or a JSON file from your
JavaScript, and you want the file to be included in the build so it's
renamed to <md5Prefix>.<extension> etc. Simply putting something
like var url = 'foo.json'; $.ajax(url, ...) in your code won't make
buildProduction aware that foo.json is a url -- it's
indistinguishable from a regular string.

However, if you wrap GETSTATICURL(...) around your url, it will be
modelled as a relation, and the target asset will be included in the
build. Note that relative urls will be resolved from the url of the
containing HTML asset, not the JavaScript asset (otherwise it wouldn't
work without buildProduction as there's no way to get retrieve
the url of the JavaScript being executed in a browser).

Example:

var url = GETSTATICURL('foo.json');

$.ajax(url,...);

... which will produce something like this after being run through
buildProduction:

var url ='static/96b1d5a6ba.json';

$.ajax(url,...);

GETSTATICURL includes support for wildcards for cases where you need
to pull in multiple static files in one go:

var url = GETSTATICURL('myData/*.json', name);

This will glob for myData/*.json and include all the found files in
the build. The additional parameters passed to GETSTATICURL will be
used as the wildcard values and can be any JavaScript expression. If
myData contains a.json and b.json, the output of
buildProduction would look something like this:

The wildcards are expanded using node-glob, so all
constructs supported by minimatch are
supported, except ?, because it's interpreted as a GET parameter
delimiter.

For GETSTATICURL to work in development mode the function needs to
be declared. The buildDevelopment script adds a bootstrapper script
that includes GETSTATICURL, but you can also put this into your main
HTML before all your other scripts:

The buildProduction switch --optimizeimages turns on automatic lossless
optimization of all images of the relevant type in the graph.

Additionally, you can specify individual processing instructions for
each image using custom GET parameters. For example you might want to
reduce the palette of an image to a specific number of colors or apply
a specific compression level:

<imgsrc="myImage.png?pngquant=37">

<imgsrc="myOtherImage.png?optipng=-o7&amp;pngcrush=-rem+tEXT">

The image processing is supported everywhere you can refer to an
image, including background-image properties in CSS, shortcut icon
links etc.

Additionally, all GraphicsMagick operations (as exposed by the gm module) are supported:

body{

background-image:url(foo.png?resize=500+300&flip&magnify&pngcrush);

}

These are especially useful for responsive images:

<imgsrcset="bar.jpg 1024w,

bar.jpg?resize=600 600w,

bar.jpg?resize=500&amp;gravity=Center&amp;crop=300+300 300w"

sizes="(min-width: 768px) 50vw, 100vw">

They work in JavaScript too:

var img =document.querySelector('.responsive-image');

img.setAttribute('srcset',

GETSTATICURL('baz.gif')+' 500w, '+

GETSTATICURL('baz.gif?resize=300')+' 300w');

picturefill({ elements:[img]});// reload if you're using Picturefill

This allows you to only check your original images into version
control and have your build system create the scaled/processed/derived
ones dynamically.

The processing instructions are executed using the same engine that
powers express-processimage
and livestyle with the
--processimage switch. You can use one of those to have the image
processing instructions applied on your development setup.

AssetGraph-builder supports internationalization of strings in your
HTML and JavaScript code via a custom syntax. The approach is to do as
much as possible at "compile time". For each language you want to
support, buildProduction outputs a separate html file,
eg. index.en_us.html, index.da.html, and so on. If you're using
the TR/TRPAT syntax for getting language-specific
strings within JavaScript, buildProduction will also output multiple
versions of your JavaScript, one per language, and it will be wired up
so that eg. index.da.html will refer to the Danish JavaScript file.

The i18n feature is optional. Enable it by specifying the --locales
switch with a comma-separated list of locale ids to compile, for
example --locales en_us,da,fr,de.

In JavaScript code you can use the TR function for getting a
locale string and TRPAT for getting a function that accepts
the placeholder values and returns a locale string.

For these functions to work in development, you currently have to use
buildDevelopment tool (still to be documented) to inject some
bootstrapper code that implements them. The bootstrapper will be
removed by buildProduction.

The second argument for TR and TRPAT is optional. It
will be used as the default translated value if the key isn't found in an .i18n
file. This is very useful when you haven't yet translated your
project. That way you don't need to create the .i18n files before you
actually have something to put in them.

JavaScript example:

INCLUDE('foo.i18n');

// This alerts "The value in English" or "Værdien på dansk" depending on which build you're running:

As the translation files consist of plain JSON, translated values do
not have to be strings. This enables more advanced features, that you
would otherwise have to implement with string concatenation. The
feature is best explained with an example. Let's say we would like to
translate certain e-mail folder names, but otherwise default to their
real name. That could be achieved the following way.

The translation file:

{

"FolderName":{

"en":{

"Inbox":"Inbox",

"Draft":"Draft",

"Sent":"Sent Mail"

},

"da":{

"Inbox":"Indbakke",

"Draft":"Kladder",

"Trash":"Sendte e-mails"

}

}

}

The code translating the e-mail folder names:

var folderTranslations = TR("FolderName",{

"Inbox":"Inbox",

"Draft":"Draft",

"Sent":"Sent Mail"

});

return folderTranslations[folderName]|| folderName;

The TR function call extracts the internationalized FolderName
structure or uses the provided default. Then we look for the folder
name in the translation structure, if it is found we return it;
otherwise we just return the folder name.