README

`cdnup`

CDNup is a simple wrapper around pkgcloud which allows for a simple uploading interface as well as the ability to define a CDN URL that fronts whereever you are uploading your assets to.

Installation

npm install --save cdnup

Usage

You can refer to BFFS to see cdnup in action. In all examples below we assume that you've already required and initialized the module as followed:

'use strict';

const CDNUp = require('cdnup');
const cdnup = new CDNUp('bucket-name', {
  //
  // It is still assumed that the `bucket-name` prefix is appended to the
  // following url
  //
  url: 'https://myCdnEndpoint.com',
  pkgcloud: { /* Pkgcloud config options */ }
});

As you can see in the example above we allow 2 arguments in the constructor:

bucket: The relative path to the files on the CDN server.
options: Optional configuration object. The following keys are supported:

sharding: Randomly select one of the supplied urls of the CDN so assets can be sharded between different DNS/subdomains.
url/urls: A url string or urls array for what you will use to publicly fetch assets from the CDN.
subdomain: Boolean indicating the bucket should be used as subdomain.
pkgcloud: Options passed to pkgcloud constructor.
mime: Object containing custom mime types per file type.
check: Used to validate asset URL if the CDN assets are behind a firewall.

Authorization

We use pkgcloud in order to upload CDN assets. It supports most if not all cloud providers depending on what you use and who you want to trust with your assets. Check out the documentation and our sample config to see how you may set this up for you.

const cdnup = new CDNUp('ux/core', {
  pkgcloud: {
    provider: 'amazon',   // Use AWS s3
    forcePathBucket:      // Inform AWS to use `s3ForcePathStyle`
    //...
  }
});

Note: more information about forcePathBucket is available in AWS documentation.

API

The following API methods are available.

upload

This is the method that you will be using the most, upload. When you first call the method it might take a second to work because it will first create the bucket if that has not already been done

Once initialized, it will write the files to the cloud provider and call your supplied callback. It requires 3 arguments:

A buffer, stream or path to the file that needs to be stored.
Filename of the thing that we're about to store. It will be path.join'ed with the root argument of the constructor.
Completion callback that follows the error first callback pattern.

cdnup.upload('/path/to/file.js', 'file.js', function (err) {
  if (err) return console.error('Shits on fire yo.');

  console.log('all good');
});

init

Initialize the cloud provider with the given bucket-name passed to the constructor.

cdnup.init(function (err) {
  if (err) console.error('failed to mount cdn');
});

url

Return the URL and path of the CDN.

const fullCDNPath = cdnup.url();

checkUrl

Return the URL of the file specified against the configured check.

const cdn = new CDNUp('my-bucket', {
  check: 'https://my-bucket.s3.amazonaws.com/',
  url: 'https://whatever.com/world'
});

// Will be rewritten against the specific `check`.
const fileURL = cdn.checkUrl('https://whatever.com/world/hello-fixture.js');

Test

Run AWS local, pull latest localstack. This requires docker [to be setup][docker].

docker pull localstack/localstack:latest
npm run localstack

Finally, run the unit test.

npm test

Usage no npm install needed!