Assets is an asset manager for node. It isolates assets from environmental changes, gets generates their URLs, retrieves image sizes and base64-encodes them.

Installation

1npm install assets --save

Usage

An instance of Assets should be created:

1var options = { loadPaths: ['fonts', 'images'] };
2var resolver = new Assets(options);

Each of the resolving methods returns a Promise:

1resolver.path('foobar.jpg')
2  .then(function (resolvedPath) {
3    // ....
4  });

To use a node-style callback, pass it as the last argument to the resolving method:

1resolver.path('foobar.jpg', function (err, resolvedPath) {
2  // ...
3});

Resolving methods

.path(path)

Resolve the absolute path for an asset.

1var resolver = new Assets({ loadPaths: ['assets'] });
2resolver.path('patterns/knitwork.gif')
3  .then(function (resolvedPath) {
4    console.log(resolvedPath); // '/var/www/example.com/assets/patterns/knitwork.gif'
5  });

.url(path)

Generates an URL for an asset.

1var resolver = new Assets({ loadPaths: ['assets/images'] });
2resolver.url('page/background.jpg')
3  .then(function (resolvedUrl) {
4    console.log(resolvedUrl); // '/assets/images/page/background.jpg'
5  });

.data(path)

Returns a base64-encoded content of an asset. SVG files would be non-encoded, because then they benefit in size.

1var resolver = new Assets();
2resolver.data('icons/sabre.png')
3  .then(function (resolvedData) {
4    console.log(resolvedData); // 'data:image/png;base64,...'
5  });

.size(path)

Return the size of an asset.

1var resolver = new Assets();
2resolver.size('logo.png')
3  .then(function (resolvedSize) {
4    console.log(resolvedSize); // '{ width: 132, height: 48 }'
5  });

Options

Options are set by passing an options object to the constructor. Available options are:

basePath

The path to the root of the project.

For example: "source/".

Defaults to the current working directory.

baseUrl

URL of the project when running withing the web server.

For example: "/wp-content/themes/twentyfourteen", "http://example.com".

Defaults to "/".

cachebuster

If cache should be busted. If set to true, Assets will bust assets cache, changing urls depending on asset’s modification date:

1var resolver = new Assets({ cachebuster: true, loadPaths: ['assets/images'] });
2resolver.url('page/background.jpg')
3  .then(function (resolvedUrl) {
4    console.log(resolvedUrl); // '/assets/images/page/background.jpg?14a931c501f'
5  });

To define a custom cachebuster pass a function as an option:

1var resolver = new Assets({
2  cachebuster: function (resolvedPath, pathname) {
3    return fs.statSync(resolvedPath).mtime.getTime().toString(16);
4  }
5});

If the returned value is falsy, no cache busting is done for the asset.

If the returned value is an object the values of pathname and/or query are used to generate a cache busted path to the asset.

If the returned value is a string, it is added as a query string.

The returned values for query strings must not include the starting ?.

Busting the cache via path:

1var resolver = new Assets({
2  cachebuster: function (resolvedPath, pathname) {
3    var hash = fs.statSync(resolvedPath).mtime.getTime().toString(16);
4    return {
5      pathname: path.dirname(pathname)
6        + '/' + path.basename(pathname, path.extname(pathname))
7        + hash + path.extname(pathname),
8      query: false // you may omit this one
9    }
10  }
11});

Defaults to false.

loadPaths

Specific directories to look for the files.

For example: ["assets/fonts", "assets/images"].

Defaults to an empty array.

relativeTo

Directory to relate to when resolving URLs. When false, disables relative URLs.

For example: "assets/css".

Defaults to false.

Path resolution

Assets provide a file path resolution algorithm similar to the one used by desktop file systems.

This may come in handy when you have different directories for different types of assets, e.g. images, fonts. You add those to the list of load paths when configuring Assets:

1var resolver = new Assets({
2  loadPaths: ['assets/fonts', 'assets/images']
3});

Now, instead of writing this:

1var url = '/assets/images/icons/create.png';
2var url = '/assets/images/icons/read.png';
3var url = '/assets/images/icons/update.png';
4var url = '/assets/images/icons/delete.png';

You can write this:

1var url = resolver.path('icons/create.png');
2var url = resolver.path('icons/read.png');
3var url = resolver.path('icons/update.png');
4var url = resolver.path('icons/delete.png');

Apart from the fact that these lines are just shorter, it gives you an opportunity to easily change the environment and the way the URLs are being output much quicker.

For instance, if you move all the images from assets/images to client/source/images you wouldn't need to go through all of your stylesheets to replace the URLs, you would just need to edit the corresponding parameter inside your Assets config:

1var resolver = new Assets({
2  loadPaths: ['assets/fonts', 'client/source/images']
3});

When resolving a path, Assets would look for it through every of the following paths in the listed order:

• load paths;
• base path.

Path resolution also gives an opportunity to easily change the URL structure when the directory structure of the project on your computer is not exactly the same as it would be on the server.

For instance, if you have a Wordpress theme project, you may want to append /wp-content/themes/your-theme-name to every URL inside of your stylesheet. This is done by providing a baseUrl parameter to Assets config:

1var resolver = new Assets({
2  baseUrl: '/wp-content/themes/your-theme-name'
3});

Now everything would be resolved relative to that base URL:

1resolver.url('images/create.png')
2  .then(function (resolvedUrl) {
3    console.log(resolvedUrl); // '/wp-content/themes/your-theme-name/images/create.png'
4  });