statics

Mission

Package static assets in npm.

Goals

Let component authors include static assets and resolve them to public URLs at runtime. And support future advanced optimization strategies, including static analysis. It should work transparently on the client and server and not require a specific JS packaging solution. Should not need to download the whole static map. Should be able to opt out of optimizing some files.

Non-goals

Actually implementing optimizations, or actually inserting anything into the DOM or HTML.

For the package author

Basic usage

• Add a static key to your package.json:

{
  "name": "MyPackage",
  "statics": {
    MyResourceID: "./statics/image.png"
  }
}

If you called it rawStatics they wouldn't be optimized.

• Get information about the asset at runtime:

require('statics').resolveStatic('MyPackage/MyResourceID')

This will return a JS object describing the asset called an asset description. NOTE: resolveStatic() must be invoked with the name resolveStatic and must be passed a literal string to allow for static analysis.

The string literal is the name of the package specified in package.json followed by a / and then the ID of the static resource.

Asset descriptions

Images

The reason these have a custom descriptor is to support optimizers that may use spriting.

{
  "href": "//mycdn.com/image.jpg",
  "left": 0,
  "top": 0,
  "width": 240,
  "height": 240
}

Stylesheets

These should be valid CSS. If an optimizer performs spriting of images it's repsonsible for changing url() in the stylesheet and adding the appropriate CSS properties to reflect the new path and sprite location.

Stylesheets may be concatenated.

{
  "href": "//mycdn.com/stylesheet.css"
}

All other files

{
  "href": "//mycdn.com/whatever.bin"
}

For the package consumer

Just npm install the package and require() what you need.

Command-line tool

Then run statics --output=./statics/ --map=staticmap.js --url=//mycdn.com/statics/ ./

This takes all the static resources that a given package (./) depends on (by traversing its CommonJS dependencies and looking at the statics field in package.json) and copies them to known locations inside of the output dir (./statics/). The user then uploads this dir to the URL provided (//mycdn.com/statics/). Their app needs to require('./staticmap') to tell the runtime the information about the statics.

Relative paths between the files in a given package need to remain intact or be rewritten by the statics tool.

staticmap.js will look something like this:

require('statics').configure({
  "MyPackage/MyResourceID": {
    "href": "//mycdn.com/statics/MyPackage/statics/myimage.png",
    "left": 0,
    "top": 0,
    "width": 240,
    "height": 240
  }
});

Development server

We could provide an express middleware that does everything the statics tool does but at runtime.

Optimizers

People should be able to write their own statics tool which does stuff like image spriting, CSS concat, and running stuff like SASS.