README.md

cdnpm

Note: This is obviously not remotely complete.

Rationale

Systems like browserify and webpack allow us to use reasonable dependency management in our front-end projects, with all the related benefits like easily staying up-to-date. However, CDN-hosted libraries offer speed, free bandwidth, and may already be primed in a user's browser cache, but with the caveat that one must manually manage versions and script tags. The goal of cdnpm is to allow us to manage our CDN references in the same fashion that we manage our npm dependencies, and providing us the benefits of both approaches.

In prod, we will have certain large deps pulled in via CDN with versions that exactly match what we pulled in via npm locally (or in dev).

Usage

While not required, you will probably be using browserify or webpack to create a js bundle for your app. To extract CDN-able deps from your project you will:

1. Run cdnpm stats to see which deps you can extract
2. Use the API to add these deps to your index.html
3. Add these deps to
   • localify plugin config for browserify (see https://github.com/pluma/literalify)
   • external property in your webpack config (see http://webpack.github.io/docs/library-and-externals.html)
4. Serve your project with deps pulled in via CDN up-to-date (as much as your node_modules anyhow ;-)

Node API

Usage

var cdnpm = require('cdnpm')(/*config*/);

Note: config is currently unused (future use)

getScriptTags

var cdnpm = require('cdnpm')(/*config*/);
var getScriptTags = cdnpm.getScriptTags;
...
getScriptTags().then(function(depScriptTags) {
    templateEngine.template(stringVar, {
        depScriptTags: depScriptTags
    });
});

getScriptTags returns a promise for the html markup for relevant script tags. You will want to template this into your index.html wherever you deem appropriate for these libraries.

getWebpackExternals

var cdnpm = require('cdnpm')(/*config*/);
var getWebpackExternals = cdnpm.getWebpackExternals;
...
getWebpackExternals().then(function(webpackExternalsConfig) {
    /*
    Code to merge webpackExternalsConfig into `externals` property of your webpack config
    */
});

getWebpackExternals returns a promise for an object that can be used as your webpack config's externals property.

CLI Commands

cdnpm stats

This command looks in your package.json for packages that are also hosted on CDN. It then reports the versions and (minified) sizes of those packages on the CDN. This gives an idea of how much one could reduce their bundle size by using the CDN version.

cdnpm dry-tags

Dry run to see what script tags get returned by the API. Useful to ensure that these are indeed the scripts you are looking for.

cdnpm dry-webpack

Dry run to see what webpack externals config gets returned by the API.