Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



    Syntagma/Matias Liwski forked original project to extend functionality. If manufacturer accept our new features, we will merge projects. For now, is a separate npm module because we need it for our own products.

    Next, original documentation of manufacturer:

    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, versions automatically sets 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 is known to improperly 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, that's 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.

    API references

    The API references are generated from the source's JSDoc comments:


    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 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.

    <pre>versions.set('auth', 'Sup3rSecr3tP4z5w0rdy0');</pre>
    blacklisted extensions

    Black list extensions that you do not 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.

    <pre>versions.set('blacklisted extensions', ['.conf', '.log', '.gz']);</pre>

    Set custom Access-Control-Allow-Origin headers. The default value is * so all values are allowed. If you only want to allow access from a specific domain set the domain here.

    <pre>versions.set('cors', '*');</pre>

    A directory that is relative to 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 set a root property.

    <pre>versions.set('directory', './public');</pre>
    force extensions

    Only allow files with an extension to be pulled from origin servers. The reason behind this is that you might set your own site as full origin and that would mean that your regular pages would also be proxied by versions and create duplicate content. It's much less common that .html are served. Thats why we force extensions by default.

    <pre>versions.set('force extensions', false);</pre>
    expire internal cache

    How long should we keep items in our internal (memory) cache. It accepts a numeric value as milliseconds or a human readable string like 10 hours or 90 minutes. Defaults to 1 hour.

    <pre>versions.set('expire internal cache', '2 days');</pre>
    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.

    <pre>versions.set('max age', '1 year')</pre>

    As you might imagine, on which port number do you want to run the server. Defaults to 8080.

    <pre>versions.set('port', '8080');</pre>
    origin servers

    An array of of server objects that is used to fetch resources that are not found in the directory property.

    <pre>versions.set('origin servers', { url: "", name: "foo" });</pre>

    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.

    <pre>versions.set('version', '0.0.0');</pre>

    In order to parallelize the downloading of assets in the browser they should be spread across multiple subdomains/domains. You can supply multiple origin servers that the client will use to distribute the assets.

    <pre>versions.set('aliases', '');</pre>
    log level

    As versions is intended to run as a standalone server it comes with a logger that outputs some useful information. You can control the amount of output by changing the log level. The default value is log. Please check the dev/null node.js logger for the supported log levels.

    <pre>versions.set('log level', 'debug');</pre>

    Versions is built on top of the connect framework and is configured to use the minimal amount of plugins to get the job done. The plugins array allows you to specify extra middleware layers that you want to have loaded into versions or custom connect compatible nodejs modules that need to be required.

    <pre>versions.set('plugins', [{ name: 'logger', config: 'short' }, 'logger']);</pre>

    Synchronise configuration between client and server. If you are using multiple servers also set the redis configuration.

    <pre>versions.set('sync', true);</pre>

    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:

        The host name of your redis server.
        The port number of your redis server.
        Optional auth/password to access your redis server.
        The key that should be used to store the configuration and be used as the
        channel name for the pub/sub channel. Defaults to <code>versions</code>


    When you require the versions module it will try to find a versions.json (or versions.js with a module.exports pattern) file in your root folder and use this as default configuration.

      "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,
      "plugins": [
          "name": "custom-nodejs-module",
          "config": {
            "custom": "configuration options that will be feed in to the middleware"

    Configuration API

    In addition to reading your versions.json file for the configuration it is also possible to set the configuration using dedicated API methods or the versions#set method. The versions#set method expects 2 arguments, the first argument is the name of the configuration key that you want to update and the second value is the actual value:

    var versions = require('versions');
    versions.set('auth', 'superSec3rtp4ssw0rd')

    The API is also chainable, so you can do as many versions#set calls if needed. Versions also provides you with some API sugar to make configuring a bit more human readable:

    versions.path('/public').expire('10 hours').set('sync', true);

    The following API methods map directly to configuration (see versions.json configuration above for detailed information about what each configuration key triggers):

    API Configuration key
    path directory
    lifetime max age
    expire expire internal cache

    Server example

    'use strict';
    // require versions, if you have `versions.json` in the same folder as your
    // `package.json` it will load that as default configuration for you
    var versions = require('versions');
    // If you don't have a versions.json or want to override some values:
    versions.set('log level', 'debug')
            .set('auth', 'helloW0nderW0man');
    // Or use some of the nicer API sugar
    versions.path('./public').lifetime('30 days').expire('10 hours');
    // After you have configured everything that you want just start listening on
    // the server.

    But it can be much shorter if you don't have to overide any configuration from your versions.json file:


    Rest API

    GET /flush

    Completely removes the internal cache. This does not flush cache-headers for the HTTP requests.


      flush: 'OK'

    GET /expire?key=

    Removes the matched item(s) from the internal cache. It uses the value of ?key=key to find and match it against request URLS in the cache.


      expire: 'OK',
      expired: 1

    GET /inspect?key=

    Finds the item in the cache and displays some information about it, like the total size of gzip, content-length etc.


      key: 'name of the key',
      data: {
        'Content-Length': 0,
        'Content-Length Gzip': 0,
        'Content-Type': 'text/html',
        'Last-Modified': 'Sun, 31 Mar 2013 13:37:33 GMT'

    Or when a given key is not found:

    { inspect: 'Failed to find the requested key file in cache' }

    GET /keys

    Lists all items that are currently in the cache.


      keys: [

    GET /version

    Get the current version of internal cache.


    { versions: '0.0.0' }

    POST/PUT /version

    Update the server to a new version number, if Redis sync is also the changes will also be synced with other instances.


    { versions: '0.0.0' }

    Or when no body is send:

    { error: 'Invalid body' }

    GET /allowed-versions

    Get the versioning allowed versions.


    { 'allowed versions': ['0.0.1','0.2.0'] }

    POST /version

    Override server allowed versions with the allowed versions sent and the current version, if Redis sync is also the changes will also be synced with other instances.


    { 'allowed versions': ['0.0.1','0.2.0'] }


    { 'allowed versions': ['0.0.1','0.2.0','0.0.0'] }

    Or when no body is send:

    { error: 'Invalid body' }

    PUT /version

    Add sent allowed versions to the current allowed versions, if Redis sync is also the changes will also be synced with other instances.


    { 'allowed versions': ['1.0.1','3.2.1'] }


    { 'allowed versions': ['0.0.1','0.2.0','0.0.0','1.0.1','3.2.1'] }

    Or when no body is send:

    { error: 'Invalid body' }

    DELETE /version (Content-type:text/plain)

    Delete every allowed version except for current version, if Redis sync is also the changes will also be synced with other instances.


    { 'allowed versions': ['0.0.0'] }

    GET /metrics

    Returns a bunch of metrics.






    npm i syntagma-versions

    Downloadsweekly downloads








    last publish


    • avatar