Referencing assets in templates

Now, the interesting part - wiring it all up.

Manually Wiring it Up

To manually include an asset in your project, you need to ensure there are sufficient configuration variables (that will change on an environment by environment basis) in your configuration (assume the service is called app-resource):

{
  "cdnUrl":"http://localhost:7334/app-resource/",
  "bundleVersion":"local"
}

You should then be able to create a url using the following helper:

function getAssetUrl(config, type, bundle) {
  var assetUrl = config.cdnUrl + config.bundleVersion + '/' + type + '/' + bundle + '.' + type;
}

If you run locally:

bosco cdn minify

The above helper will resolve (for type = 'js' and bundle = 'main') to:

http://localhost:7334/app-resource/local/js/main.js

This manual mode of operation does not allow you to use bosco cdn in an 'un-minified' mode. If you do want to use it in unminified mode you need to reference the generated html files instead (as Compoxure does), which can be found via similar URL construction:

function getAssetHtmlUrl(config, type, bundle) {
  var assetUrl = config.cdnUrl + config.bundleVersion + '/html/' + bundle + '.' + type + '.html';
}

The difference is explained in more detail here: Running a local 'CDN'.

Using Bundle Version

Bundle Version provides some middleware for Express, and a Hapi plugin, that makes it easier to generate the URL for a static asset using the convention within Bosco. It assumes that it has been installed within a service or application that has a bosco-service.json file.

You can add it to your project very simply:

var buildNumber = config.get('build'); // Or whatever appropriate in your environment
var buildVersion = require('bundle-version')(buildNumber, cdnUrl);
app.use(buildVersion.middleware);

It takes a few key facts:

InputDescriptionExample Value
buildNumberCurrent build number - typically written into the application config by the build server. Default to 'local'.local, 105
cdnUrlYou can manually provide it, or it defaults to checking the header 'x-cdn-url' that is provided by an upstream proxy (e.g. Compoxure).http://localhost:7334/ or a cloudfront URL.
bosco-service.json : service.nameName of the service.app-resource

When a request comes in, it uses this information to construct a base CDN url that is applicable to this version of the service, and then re-sets this full URL on the request.

This means that if you expose the property to your template layer:

var cdnUrl = req.headers['x-cdn-url'];

To your template layer, you can then append a specific bundle or image name to this to generate an actual endpoint that works in both Bosco local cdn as well as on an actual CDN when it is later deployed. e.g.

<img src='{{cdnUrl}}img/image.jpg'/>

Using Compoxure and Bundle Version

The final option is to combine Compoxure and Bundle Version together. In this mode, Bundle Version, and the actual service works in exactly the same way, but you are now able to include the assets in a page processed by Compoxure in a simpler declarative way:

<div cx-bundles="app-resource/main.css,resource-reviews/main.css,app-resource/main.js" cx-replace-outer="true" cx-ignore-error="true"></div>

This directive is a shortcut to generating a lot of URLs by hand, the end result will be:

This 'magic' works by one simple trick - when you include Bundle Version in a service, it also attaches a header to the response, that tells Compoxure which version of the service is currently running.