node-static-asset is a static asset manager for Node.JS, designed for Express. This project aims to solve the problem of caching static assets (including assets like *.js files that might change from time to time).
Google has a nice article about "strong" and "weak" caching. It's worth a quick read if you don't know what that means.
npm install static-asset
node-static-asset allows you to generate URL fingerprints for static assets.
- Add the static-asset middleware to your Express stack
var staticAsset = ;app;
- Get URL fingerprints of your static resources using
assetFingerprintview helper function.
Now that you have obtained the asset fingerprint for
if you send a request for that asset to the URL
static-asset will automatically add appropriate caching headers (i.e.
Last-Modified, ETag, and Expires).
static-asset exposes a function
req.assetFingerprint, which allows one to generate
and register URL fingerprints for static assets.
Once a URL fingerprint is registered with static-asset, any HTTP request for that
static asset (i.e. when
req.url matches the registered URL fingerprint) will
trigger static-asset to set certain HTTP headers (i.e. Last-Modified, ETag, or
Adding the middleware function
require('static-asset')(path[, cache]) - Returns an Express middleware
function that exposes a
req.assetFingerprint function and adds
assetFingerprint view helper function to
res.locals. If any request's URL
matches a previously generated URL fingerprint, static-asset will attempt to add
weak and strong caching headers to the HTTP response.
path- the path from which static files are served
cache- a "cache strategy" Object, which must implement all "cache strategy" methods, as described below. If
cacheis omitted, the default "cache stategy" is used.
A "Cache Strategy" Object
A "cache strategy" object should implement one or more of the following methods:
lastModified(filename)- a function that accepts a filename and returns its last modified date. If a last modified date could not be determined, the function should return
null; otherwise, static-asset may use this Date to set the
Last-ModifiedHTTP response header when the resource is requested.
etag(filename, cb)- Same as lastModified (above), except that it must return an ETag (or hash value). If the returned ETag is not
null, static-asset may use this value to set the
ETagHTTP header when the named resource is requested.
expires(filename)- Same as lastModified (above), except that it must return a Date Object indicating when the resource shall expire. The Date may be no more than one year in the future. If
expiresis implemented, static-asset may use the date to set an
Cache-Control: max-ageHTTP headers; otherwise, static-asset will use a Date approximately one year into the future.
fileFingerprint(filename, fullPath)- Returns the URL fingerprint of the resource
filename, stored at the location
fullPathis provided for convenience, since the caching strategy does not know what root path was passed into the static-asset middleware.
Registering URL fingerprints
req.assetFingerprint(label_or_filename) - Return a URL fingerprint for the labelled resource, or if no such label is registered, use the "cache strategy" to determine the file's ETag or last modified date. If you're confused by this description, read on...
If you call
req.assetFingerprint(filename) and pass a filename relative to the
path from which static files are served, static-asset will use the cache strategy
you specified to generate and return a unique URL fingerprint for the asset.
If that file is requested later by the URL fingerprint, static-asset will respond
by setting the appropriate HTTP headers like Last-Modified, ETag, and Expires,
according to the cache strategy.
If an ETag is provided by the cache strategy, it will be used to generate the fingerprint; otherwise, the last modified date will be used.
If you call
req.assetFingerprint() with no arguments, a fingerprint will be
registered and generated using the cache strategy on the current URL (i.e.
req.url). This is equivalent to
You can call
req.assetFingerprint(label, fingerprint, cacheInfo) to manually
fingerprint for the specified
label. In addition, the HTTP headers
returned to the client when this URL fingerprint is requested are specified by
req.assetFingerprint(label, urlFingerprint, cacheInfo) - Registers a URL fingerprint for a labelled resource.
label- a label identifying the resource
urlFingerprint- the URL fingerprint for the resource. If a request for this resource is made, static-asset may add caching headers to the response.
cacheInfo- an Object containing one or more of these properties:
lastModified- the last modified date of the resource
etag- the ETag of the resource
expires- the expiration date of the resource
Other middleware on the stack can generate their own URL fingerprints for
static resources and expose them through
req.assetFingerprint. Like this:
//Suppose we are in a middleware function, designed to uglify JS files...//stat will refer to the stat Object generated by `fs.stat`req;
If you call
req.assetFingerprint(label) and pass a label, static-asset will return
the fingerprint for the resource, as specified by the last corresponding
req.assetFingerprint(label, fingerprint, cacheInfo) call. If that file is requested,
static-asset will respond by setting the appropriate HTTP headers, according to the
cacheInfo Object passed to the last
req.assetFingerprint(label, fingerprint, cacheInfo) call.
Default Caching Strategy
static-asset can be fully customized, but it has some basic, reasonably sane default behavior. By default, static-asset does the following:
- The URL fingerprint of the resource is based on the ETag
- The ETag is generated based upon the file size and the file's CRC-32 hash.
- The last modified date is pulled from
- The expires date is set to one year in the future
- The default strategy relies on
connect.staticto load the resource from the filesystem.
- In development environments (based on
process.env.NODE_ENV), the URL fingerprint will be updated whenever the file changes
- In production environments, the URL fingerprints are cached and cannot change until the server is restarted.
Usually, this should be good enough to get started.
var express = ;var app = ;var staticAsset = ;app;app;//... application code follows (routes, etc.)
This will render to something like this:
Notice that static-asset added a URL fingerprint (the UNIX timestamp 1318365481) to the filename.
More Advanced Usage
You can override the "cache strategy" with your own implementation that might allow you to:
- Upload the asset to Amazon S3 and generate a URL fingerprint that points to S3
- Fly in a spaceship to the moon
- Do something really crazy like generate URL fingerprints that are Base64-encoded MD5-hashes of the names of random lunar craters.