http2-push-manifest

A utility script for doing http2 push and/or preload.

Generates a list of local static resources used in your web app by outputting a json file. This file can be read by your web server to more easily construct the appropriate Link: <URL>; rel=preload; as=<TYPE> headers(s) for http2 push/preload.

Install

npm install --save-dev http2-push-manifest

Run tests

npm run test

What's a push manifest?

A manifest is not required by the HTTP2 protocol. We need it up! We found that it is useful for telling your server what critical resources to push for the requesting page.

http2-push-manifest is a Node script for generating a JSON file listing all of the static resources used on a page. It tries to discover the resources in an .html file you specify. This file can be read by your web server to more easily construct the appropriate Link: <URL>; rel=preload headers(s) used in HTTP2 push. Since all the resources are discovered, you'll almost certainly want to prune the list of files that get pushed. Pushing too much can actually hurt page load performance.

By default, the script generates push_manifest.json in the top level directory of your app with a mapping of <URL>: <PUSH_PROPERTIES>. Feel free to add/remove URLs from this list as necessary for your app or change the priority level.

Example of generated push_manifest.json with discovered local resources:

{
  "/css/app.css": {
    "type": "style",
    "weight": 1
  },
  "/js/app.js": {
    "type": "script",
    "weight": 1
  },
  "/bower_components/webcomponentsjs/webcomponents-lite.js": {
    "type": "script",
    "weight": 1
  },
  "/bower_components/iron-selector/iron-selection.html": {
    "type": "document",
    "weight": 1
  },
  ...
  "/elements.html": {
    "type": "document",
    "weight": 1
  },
  "/elements.vulcanize.html": {
    "type": "document",
    "weight": 1
  }
}

Note: as of now, no browser implements control over the priority/weight level.

Examples

Example - list all the static resources of app/index.html (including sub-HTML Imports):

http2-push-manifest -f app/index.html

A single file produces the "single-file manifest format":

{
  "/css/app.css": {
    "type": "style",
    "weight": 1
  },
  "/js/app.js": {
    "type": "script",
    "weight": 1
  },
  ...
}

Example - list all the resources in static/elements/elements.html:

http2-push-manifest -f static/elements/elements.html

Example - list all the resources app/index.html and page.html, and combine into a singe manifest:

http2-push-manifest -f app/index.html -f page.html

Using multiple files produces the "multi-file manifest format". Each key is the file and it's sub-objects are the found resources. It would be up to your server to decide how the mappings of key -> actual URL work.

{
  "index.html": {
    "/css/app.css": {
      "type": "style",
      "weight": 1
    },
    ...
  },
  "page.html": {
    "/css/page.css": {
      "type": "style",
      "weight": 1
    },
    ...
  }
}

Example - using a custom manifest filename:

http2-push-manifest -f path/to/site/index.html -m push.json
http2-push-manifest -f path/to/site/index.html --manifest push.json

Usage on App Engine

If you're using App Engine for your server, check out http2push-gae. It leverages this manifest file format and automagically reads push_mainfest.json, setting the Link: rel="preload" header for you.

Simply decorate your request handler like so:

class Handler(http2.PushHandler):

  @http2push.push('push_manifest.json')
  def get(self):
    # Resources in push_manifest.json will be server-pushed with this handler.

License

Apache 2.0 © 2015 Google Inc.