assetflow

assetflow

Assetflow is an asset deployment tool for node. It enables you to create powerfull asset flows easily and fast.

Assetflow is a Grunt task and works with S3 out of the box. It will take care of versioning and apply solid cache-busting techniques transparently.

If you are not familiar with Grunt check out the Grunt's Getting Started guide.

Overview

A typical deployment flow using assetflow:

• Scan assets and generate MD5 hashes.
• Create the manifest.json file.
• Copy all assets and rename them with their md5 hash to a temporary location.
• Perform HEAD operations with S3 and compare hashes using S3's ETAG.
• Upload all assets that did not have a matching ETAG.

Optionally there are two more tasks you can perform:

• Search & replace any set of assets based on a custom keyword, i.e. __ASSET(img/logo.jpg).
• Create the clientManifest.js file, a client optimized subset of the manifest.

Quick Start

npm install assetflow --save-dev

Open your Gruntfile and add the following config:

  assets: {
      options: {
        manifest: 'temp/manifest.json',
      },
      all: {
        src: ['assets/**'],
        dest: 'temp/assets'
      },
    },
    assetsS3: {
      options: {
        checkS3Head: true,
        manifest: 'temp/manifest.json',
        key: config.aws_key,
        secret: config.aws_secret,
        bucket: config.aws_static_bucket,
        access: 'public-read',
      },
      target: {
        upload: {
          src: 'temp/assets/**',
          dest:  'assets/'
        }
      }
    }

Grunt Task assets

The assets task performs these operations:

• Scans all the defined assets.
• Generates md5 hashes for each asset.
• Create the manifest.json file.
  • If a manifest file exists, it will compare the hashes.
• Copy all new or updated assets and rename them with their md5 hash to a temporary location.

When this task finishes all your assets have been copied to a new temporary folder that you defined. This folder will contain your assets renamed with their own hash, like so:

app.js --> app-h522md41d.js

The manifest.json file generated by this task keeps a reference to all your assets so their names can be properly resolved in all environments.

Options

manifest

Type: string Default: manifest.json

Define the location of the manifest file.

cdnurl

Type: string Default: none

Add the url of your CDN to prepend it to all assets.

rel

Type: string Default: none

The rel option will perform directory substraction on the source to calculate the relative path to the asset. Consider this case:

Your folder of static assets is under assets/, so the path to your logo would be assets/img/logo.png which would be accessed by the browser as /img/logo.png.

Declaring the assets folder as a rel path will make sure that all assets have the proper url.

Example

assets: {
  options: {
    rel: 'assets/'
  },
  all: {
    src: 'assets/**',
    dest: 'temp/assets'
  }
}

truncateHash

Type: number Default: none

The md5 hash is 32 bytes long, you don't need all of it, use this option to truncate the hash down to n chars.

prepend

Type: string Default: none

This option will prepend a value to the asset's key. It is mostly used to prepend a slash and make the asset key absolute, for example:

By default, the assets task will create records in the manifest.json file as relative web paths: img/logo.png. If you need the key to be an absolute path then you have to use prepend.

options: {
  prepend: '/'
}

maxOperations

Type: number Default: 100

The maximum number of concurent operations, in this case the operations are file copying.

progress

Type: boolean Default: false

A fancy progress bar.

debug

Type: boolean Default: false

Print extra debugging information.

Grunt Task assetsReplace

The assetsReplace task will search and replace the contents of your assets. It is usefull for cases where you don't have the ability of a 'helper' to resolve your assets.

LESS files are a typical example, use a custom keyword to include your assets and run the assetsReplace task to populate the asset urls in your .less files. For example if the custom keyword is __ASSET():

@bg-dot-light: url(__ASSET(img/pdf-icon-cv.png)) repeat 0 0 #2a2a2a;

After the assetsReplace task is executed the same line will look like this:

@bg-dot-light: url(http://d3s3z9buwru1xx.cloudfront.net/assets/img/pdf-icon-cv-fk44j2s.png) repeat 0 0 #2a2a2a;

The assetsReplace task is based on grunt-string-replace by @erickrdch

Release History

• v0.1.0, Mid March 2013
  • Big Bang