Static Asset Service

This repository provides tools to generate and upload to S3 the asset files used by a static asset service. Such a service can be used by client applications to share Javascript assets in an organized, declarative way, and thus reduce the overall page size and number of requests when multiple applications coexist on the same page.

Overview

This repository provides the tools for generating combined and compiled asset files from base assets, and then deploying the files to S3 so that they can be consumed by applications using the static asset loader client.

The example Assets illustrate the form required for assets that the service provides.

The static asset client used to require and define assets in a Javascript client application is not included in this repository, but is rather a part of bv-ui-core.

Generating Static Asset Files

To generate the asset files:

var staticAssetService = require('static-asset-service');

staticAssetService.generate({
  // The namespace that apps consuming these generated assets will use.
  namespaceName: 'BV',

  // The directory where the generator can expect to find the asset files.
  sourceDir: '/path/to/assets',

  // The destination where the assets will be created.
  targetDir: '/path/to/dist',

  // If true, minify the generated outputs using uglify.
  uglify: true,

  // If true, log progress to the console.
  log: true,

  // List the asset bundles that need to be supported for each application using
  // this service. The generator will only generate combination files for these
  // listed assets.
  //
  // We constrain the asset generation in this way for combinatorial reasons -
  // creating static combinations gets large rapidly. Ten assets combine to
  // more than 1000 files even with alphanumeric ordering of names enforced, but
  // four or less is managable.
  //
  // Each asset must have a corresponding file in the assets directory. For
  // example, for the asset jquery-example@1.11.1, there must be a file
  // assets/jquery-example/1.11.1.js.
  //
  // IMPORTANT: assets MUST be listed in dependency order, i.e. the order in
  // which they must load to satisfy one another.
  assetBundles: {
    firebird: [
      'jquery-example@1.11.1',
      'lodash-example@1.2.0',
      'backbone-example@1.0.0'
    ],
    curations: [
      'jquery-example@1.11.1',
      'underscore@1.5.2'
    ],
    spotlights: [
      'lodash@2.4.1',
      'backbone-example@1.2.0'
    ]
  }
}, function (error) {
  if (error) {
    console.error('Generation failed.', error);
  }
  else {
    console.info('Generation complete.');
  }
});

About the Namespace

The static asset service requires a global namespace - that is, a property on window - that it can use to communicate back to the apps that request assets. When generating files, this namespace needs to be known in order to properly provide the individual assets to the requesting application.

In browser applications, the namespace is generated by the bv-ui-core namespacer module.

Uploading Generated Files to S3

To upload the generated asset files to an S3 bucket:

var staticAssetService = require('static-asset-service');

staticAssetService.deployToS3({
  // Upload assets to this S3 bucket.
  bucket: 'example',

  // The prefix put in place for the keys of the uploaded files.
  keyPrefix: 'example/assets/'

  // If true, log progress to the console.
  log: true,

  // Optionally, specify configuration for the aws-sdk client instance. This is
  // not recommended. For preference configure S3 access using the other options
  // that do not require configuration changes in code: environment variables,
  // EC2 instance roles, etc.
  // s3ClientConfig: {
  //   accessKeyId: 'akid',
  //   secretAccessKey: 'secret',
  //   region: 'us-east-1'
  // },

  // The absolute path to the generated asset files.
  sourceDir: '/path/to/dist',

  // A semver version for your assets. Assets will be uploaded to multiple
  // locations in the bucket determined by the version and keyPrefix:
  //
  // example/assets/1
  // example/assets/1.0
  // example/assets/1.0.0
  version: '1.0.0'
}, function (error) {
  if (error) {
    console.error('Deployment failed.', error);
  }
  else {
    console.info('Deployment complete.');
  }
});

Creating Asset Files

Example Assets

The example-assets directory contains a selection of example assets that could be provided by a static asset service. The file names and contents have a few restrictions, outlined here.

File Names

Asset files must have names in the format: <resource>@<version>.js.

File Contents

Asset files should contain valid JavaScript, structured as follows so that the define function is invoked as define(assetName, asset). The asset code is wrapped in a closure to ensure that different versions can be loaded and used if necessary.

define('<resource>@<version>', (function () {

  // ...

  return resource;
})());

Development

Getting Started

Developers should run npm install before doing any work on this repository. This will install the project dependencies, as well as a pre-push hook.

Running the Tests

grunt test will run the browser tests using PhantomJS, as well as ESLint and the tests of the generator code.

grunt serve will open a browser to show the browser tests.