asseturls

Manage cachebusting asset URLs in node

npm install asseturls
12 downloads in the last week
22 downloads in the last month

node-asseturls

Tiny library for the management of cachebusting asset URLs. MIT License.

Motivation

A way to tell templates what hashed resource URLs should currently be used, without having to mess around with asset-handling middleware. If you like the idea of using hashed resource URLs but prefer to work with a toolchain or a watch daemon for assembling client-side resources, asseturls is for you.

More information on hashed resource URLs and why you would want to use them.

Installation

  $ npm install asseturls

Overview

What this does:

  • You call asset_url("css/example.css") in your templates.
  • Depending on your configuration, this returns either the same URL (but made absolute to some base URL), or a hashed URL.
  • You can update the asset configuration without restarting node using an HTTP API. You can disable this API if you like. Access to the API is secured by IP, by fixed token, or both.

Example Jade template usage:

  link(rel='stylesheet', href=asset_url('css/test.css'))

With the configuration below, this results in:

  <link rel="stylesheet" href="/css/test-11223344.css" />

If you specify an URL not configured in the configuration block, it gets resolved relative to baseUrl and passed through:

  link(rel='stylesheet', href=asset_url('css/other-test.css'))
  <link rel="stylesheet" href="/css/other-test.css" />

Includes Express middleware to implement the API. You don't need the middleware if you don't want the API. In this case, just call asseturls with your configuration to set everything up and set global.asset_url, but don't pass it to app.use.

Example Express usage:

  var asseturls = require('asseturls');
  app.use(asseturls({
    baseUrl: '/', // all URLs below will be interpreted relative to this
    assets: {
      // when you call asset_url('css/test.css'), it gets mapped
      // to '/css/test-11223344.css'. Note baseUrl addition.
      'css/test.css': 'css/test-11223344.css',
    },

    // set to true if you don't want assets to be resolved to their
    // hashed name, but just joined to baseUrl and returned as is.
    dummyMode: false,

    // set to true if you want to be able to update this configuration
    // via a POST request
    enableApi: true,
    // An array of CIDR masks specifying what hosts can update the
    // configuration.
    apiRanges: ['127.0.0.0/8'],
    // A host must present one of these tokens to update the
    // configuration.
    apiTokens: ['password'],

    // If authentication fails the entire middleware falls through
    // silently, so you get a 404.
  }));
  // make the function available to templates
  app.locals.asset_url = global.asset_url;

Command Line Tool

You can use the asseturls-tool to get and set the asseturls configuration to and from a JSON file. Run asseturls-tool with no arguments to set the configuration from assets.json at localhost:3000 with the token specified in assets.json. Run asseturls-tool --help for more information.

Some examples:

  # Set the configuration from assets.json.
  asseturls-tool
  asseturls-tool -s

  # Get the configuration and put it in assets.json.
  asseturls-tool -g

  # Set the configuration in a.json, authenticating with the token in b.json.
  asseturls-tool -s -f a.json -F b.json

  # Get the configuration and put it in x.json, overwriting it if it exists.
  # Authenticate from y.json.
  asseturls-tool -g -f x.json -F y.json -o

  # Manipulate a different server.
  asseturls-tool -a "example.com:81"

Contributing

Contact me if:

  • you have found a bug
  • you have created a patch
  • you have feedback about this package
  • you have discovered something much better that already exists
npm loves you