Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bazaarvoice/static-asset-service

An optimization service for web application static assets.
https://github.com/bazaarvoice/static-asset-service

Last synced: 3 months ago
JSON representation

An optimization service for web application static assets.

Awesome Lists containing this project

README 

        
# 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][1].



The [example Assets](./example-assets) illustrate the form required for assets

that the service provides.



The [static asset client][1] 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][2].



## Generating Static Asset Files



To generate the asset files:



```js

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 [email protected], 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: [

      '[email protected]',

      '[email protected]',

      '[email protected]'

    ],

    curations: [

      '[email protected]',

      '[email protected]'

    ],

    spotlights: [

      '[email protected]',

      '[email protected]'

    ]

  }

}, 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][3] module.



## Uploading Generated Files to S3



To upload the generated asset files to an S3 bucket:



```js

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: `@.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.



```js

define('@', (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.



[1]: https://github.com/bazaarvoice/bv-ui-core/tree/master/lib/staticAssetLoader

[2]: https://github.com/bazaarvoice/bv-ui-core

[3]: https://github.com/bazaarvoice/bv-ui-core/tree/master/lib/namespacer