Skip to content
Versions, A small module for creating a flexible CDN application
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Versions is a simple but powerful node.js module that allows you to create a flexible static server or content delivery network. Serving static assets is a pain in Node, it's not something it focuses on and everybody advises you to setup a static server using NGINX or implement a cache proxying using Varnish or Squid. The biggest advantage that these servers have is that they support sendfile for sending static assets and is generally agreed upon that this is "The Best" method for sending static data. But Node doesn't have this advantage, it's removed from the core "due to reasons" and the only way to get decent file serving performance is to do aggressive caching of the assets in memory to reduce I/O operations as well as optimize for cache hits inside the browser or using conditional requests. And that is the goal of this project, cache all the things!

Build status

Please note that the build status only displays the status of the GitHub master branch. New stable versions are only released once the master passes all tests.

Build Status


Versions comes with tons of features to make it easier for you to set up a simple static server. We try to support as many features as a normal paid CDN would provide for you.

Origin Pull

In addition to serving files from disk you can also configure versions to pull static content from an origin server. This way you don't have to upload you static assets to a separate server in order to get them cached.

Set caching headers for files

In order to reduce the amount of HTTP requests that a browser would do for your files it's automatically setting the appropriate caching headers. This way you assets will be served from the browser cache instead of the server.

Advanced gzipping

Gzip is enabled on every compatible file format. Even if the origin server doesn't support gzip. In addition to that, we have disabled gzip for IE 5 and IE6 without service pack 2 as it's known to impropperly cache it. We also have detection for obfuscated gzip headers as researched by the Yahoo performance team.

REST API for managing your server

You can communicate with the server using a REST API. You can inspect items from the cache, see what keys are cached or flush the server. The possibilities are endless.


Everybody loves stats, thats why we are gathering metrics about the requests and the state of the server. These metrics can be accessed through the REST API.

Client API

Versions comes with a dedicated client that can communicate with it's REST API's or through Pub/Sub.


Synchronises configuration and versions number between different connected consumers to ensure that they are all hitting the same cached version.


It's crafted and engineered with love, what else do you need?


Installation is done through the node package manager (npm)

npm install versions --save

The --save tells npm to automatically add this file to the dependencies object of your package.json file.


The server can be configured in 2 different ways or a hybrid of both. It has a dedicated configuration file called versions.json that lives in the root of your application folder (the application folder is the folder that contains your node_modules folder). But you can also configure the module through a chainable API. And the last would be a hybrid of those. Using a configuration file and using the API to override some of the configuration values.


The versions file can configure different aspects of the module. The following properties can be configured:

The auth property is a simple security token that you can use to secure your versions REST API. After setting this property it requires an ?auth= parameter to be used to access the API.
blacklisted extensions
Black list extensions that you do want to have pulled from your origin server. You can for example black list .conf files or maybe some other random files. Please note that people can still fetch these files directly from the origin server.
Set custom Access-Control-Allow-Origin headers. The default value is * so all values are allowed. If you only want allow access from a specific domain set the domain here.
A directory that is relative the module that required versions that is used to serve static content. If you want this directory to be relative to a different path. You can see a root property.
expire internal cache
How long should we keep items in our internal (memory) cache. It accepts a numeric value as miliseconds or a human readable string like 10 hours or 90 minutes. Defaults to 1 hour.
max age
How long should the browser cache the files? It accepts a numeric value as miliseconds or a human readable string like 10 hours or 90 days. Defaults to 30 days. Please note that this value should not be longer then a year.
As you might imagine, on which port number do you want to run the server. Defaults to 8080.
origin servers
An array of of servers objects that is used to fetch resources from that is not found in the directory property. { url: "", name: "foo" }
The version number of the cache that can be automatically increased and synced between clients so cache can be expired on demand and still have the same version number/cache hits between different clients.
In order to parallize the downloading of assets in the browser it's should be spread accross multiple subdomains/domains. You can supply origins multiple origin servers that the client will use to distribute the assets.
Syncronise configuration between client and server.
In order to enable a truely distributed cache cloud you can opt in to use a Redis back-end for syncing purposes. This object accepts the following properties:
  • host The host name of your redis server.
  • port The port number of your redis server.
  • auth Optional auth/password to access your redis server.
  • namespace The key that should be used to store the configuration and be used as channel name for the pub/sub channel. Defaults to versions

Full example of a versions.json:

  "auth": "my-secret-auth-key",
  "blacklisted extensions": [".foo", ".conf"],
  "cors": "*",
  "directory": "./public",
  "expire internal cache": "1 hour",
  "max age": "30 days",
  "origin servers": [
    { "url": "", "id": "home" },
    { "url": "", "id": "webops" }
  "port": 8080
Something went wrong with that request. Please try again.