Helpers for working with static files in express projects.


Utilities for working with assets, especially assets' URIs (right now, this is all it does, heh).

If you want an easier way to set your assets' URIs, being able to change them in a single place, assetly may come in handy. It helps creating builder functions for generating URIs. Like this:

var assets;
assets = assetly('//')
assets.img.provides('brand', 'b');;

Then in your jade templates you could use:

    title= Example
    link(type='text/css', rel='stylesheet', href=assets.css('base.css'))
    img(src=assets.img.brand('logo-md.png'), alt='Example')

Giving you...

    <script src="//"></script> 
    <link type="text/css" rel="stylesheet" href="//" />
    <img src="//" alt="Example" />

Should you ever need to change your assets folders, all you have to do is change your assetly setup.

From NPM.

npm install assetly

Require it.

var assetly = require('assetly');

Creating a builder is very straightforward. A simple builder would look like this:

var assets = assetly('//');
assets('main.js'); // '//' 
assets('css/base.css'); // '//' 

You can see more complex examples in under "Sub-builders", read on.

Usually you'll want to organize your assets in sub-directories or some file structure. To help you handle this, assetly supports sub-builders. They append to their parent's path, going deeper into your folder structure.

But it is NOT required that a sub-builder advances to a deeper folder in your file structure. If you pass null as your sub-builder base path, it will stay in the same folder as its parent.

Note that there's a difference between setting null and undefined as your sub-buider's base path: the former will make it use the same path as its parent, while the later makes the new builder use a folder with the same name as the builder.

var assets = assetly('//');
  .provides('scripts', null)     // stays in the same folder 
  .provides('styles', 'css')     // advances to the 'css' folder 
  .provides('images');           // advances to the 'images' folder 
assets.scripts('main.min.js'); // '//' 
assets.styles('base.min.css'); // '//' 
assets.images('foo.jpg'); // '//' 

You can use sub-builders to set a multi-root structure by starting with a call to assetly() with no args.

assets = assetly();
  .provides('scripts', '//')
  .provides('images', '//');
assets.scripts('base.js'); // '//' 
assets.images('logo.png'); // '//' 

Builders can be nested as needed:

var assets = assetly('//');
assets.sub.subsub('subsubsub.txt'); // '//' 

assetly allows you to set query string data in your builders. This way you don't need to set it to every URI and, when a query param changes, you can update your code very quickly.

var assets = assetly('//', {: 1, s : 'm'});
assets('foo.jpg'); // '//' 
// Query data can be updated on a case by case basis. 
assets('bar.jpg', {: 2}); // '//' 
// If you need to unset a previously defined query param, set it to 
// undefined. 
assets('baz.jpg', {: undefined}); // '//' 

Note that query string data defined in the root builder, will be inheritted by all sub-builders.

var assets = assetly('//', {: 1});
// Inherits {v : 1} from assets. 
assets.js('main.js'); // '//' 
// Inherits 'v' from parent and sets new data 
assets.provides('css', {min : true});
assets.css('base.css'); // '//' 
// Updates 'v' 
assets.provides('img', {: 3});
assets(img('logo.png')); // '//' 

If you are working with express, there's a helper method for making your root builder available to your application and in your templates.

var assets = assetly('//');;
app.assets === assets; // true 
app.locals.assets === assets; // true 

Now your builder is available in your templates thanks to the locals object:


If you think 'assets' is not a good property, you can change it with the propertyName option of #express():

var assets = assetly('//');, {propertyName : 'static'});
app.static === assets; // true 
app.locals.static === assets; // true 

And in your templates:


Testing should be as simple as running:

npm test

All contributions are welcome. If you find any bugs or grammar mistakes, please, open an issue. Any kind of help to improve this code or documentation is greatly appreciated.

Feel free to submit pull requests too, for both code and grammar. I promess I'll check it as quick as possible (usually in a few days). When submitting a patch, please, add your name + contact to the authors section below.

Created by Mathias Kretschek (mkretschek).