BranchCMS File CDN

Files such as images, PDFs, and CSS files can be served through a CDN powered by AWS CloudFront. 

To enable the CDN go to Settings -> CDN.

Once the CDN is enabled, any URLs for files will be updated automatically to use the CDN URL. (The only exception to this are files whose paths are relative or absolute URLs within the site's domain name. Typically only websites that were set up before the CDN was available will have URLs like this.)

Turn off the CDN during development

If you are actively making changes to files (like CSS or Javascript files) it's best to simply turn off the CDN during development. To do that go to Settings -> CDN and toggle off the CDN.

Turn it back on after development and use one of the cache busting techniques described below. The Automatic Cache busting technique B is the best choice.

Cache busting

If the CDN is enabled and you update a file then you won't see the changes to the file. This is because the file is still cached in the CDN. You have to update the file name in order to get the changes.

However, instead of changing the actual name of the file there are a few cache-busting techniques to tell the CDN to get the latest version of the file even though you haven't technically changed the file name.

The Automatic Cache busting technique is the best choice.

The way this works is that the CDN looks for these special cache busting values. If it detects one then on the first request for the file with this particular cache busting value it will strip the cache busting value to get the original file name. It will then retrieve the updated file, save that in the CDN and return that file. Future requests for the file with the same cache busting value will then be simply returned from the CDN.

Essentially what each technique does is to enable you to see a version value on the file.

Technique 1 - cache buster value

The first technique is to add a number or string between the file name and the extension. You would do this in your templates that reference the file. You do not change the actual file name of the file.

For example, if your file name is main.css then you can update the name in your templates to main.2.css to force the cache to get the latest version. The value can be any alphanumeric string.

 <link type="text/css" rel="stylesheet" href="/theme/custom/css/main.2.css">

Note: the name of the actual file is still main.css. You're just adding the version value in the file name in your template.

Technique 2 - URL parameter

The other technique is to add a URL parameter to set the "version" for the file. The only URL parameter that will work is "v". If you use a different URL parameter then it will simply get ignored. Likewise, if you do use the "v" parameter and you have additional URL parameters then any other URL besides the "v" parameter will be ignored.

URL parameters besides the "v" parameter are completely ignored when saving the file in the CDN and when retrieving the file from the CDN.

The value of the URL parameter can be any alphanumeric string.

For example, if your file is main.css then you can add ?v=SOMETHING to the URL in your templates to tell the CDN to get the latest version of the file.

 <link type="text/css" rel="stylesheet" href="/theme/custom/css/main.css?v=4">

With each change to the file, you will need to update the cache buster or URL parameter value. Or, see below for other options to help streamline the process of updating the version value.

Automatic cache busting

Manually using one of the techniques above can be challenging if you need to make updates to the files. You would need to turn the CDN off to see any changes to your files while you are making updates. However, you'd have to first remove the cache-busting version value from the files if you turn the CDN off. If you don't do that then the correct file won't load after the CDN is turned off.

There are two ways to more easily set a version value on files. Both options depend on the file_url filter or the  theme_url filter being used on file paths in your templates. You can also apply the cache version value to other files that don't use the file_url filter or the  theme_url filters.

The filters will only add the version to the file if the CDN is turned on.

Technique A

The first option is to set the version manually with the file_url or theme_url filter tags.

Below is an example with the file_url filter. The technique is the same for the theme_url filter.

{{ '/path/to/file.css'|file_url({version: 2}) }}

If you prefer to have the version appended to the URL ( ?v=2 ) then you could do the following.

{{ '/path/to/file.css'|file_url({version: 2, append: true}) }}

Technique B - recommended approach

The other option is to set a version value on the CDN settings page and then if the CDN is enabled the version value will be automatically set on any file that also has the file_url or theme_url filters.

This option makes it easier to turn off the cache if you need to make some updates to a file. For example, say you needed to update a CSS file. You can simply turn off the CDN and then make your changes to the file. When you're done you can update the version value to be different and turn back on the CDN.

Follow these steps:

  1. Go to Settings -> CDN in the administration of your website.
  2. Turn on the option to automatically set the version value.
  3. Set the version value (note that his value can contain letters and/or numbers).
  4. Save.

Make sure that you have first removed any manual cache-busting version values that you may already have on your files.

If you need to make an update to a file that has a version value on it follow these steps:

  1. Go to Settings -> CDN in the administration of your website.
  2. Turn off the CDN and save.
  3. Make the changes to your file(s) and test.
  4. When complete go back to the CDN settings page.
  5. Turn on the CDN (note - it's not actually turned on until you click the Save button).
  6. Update the version value to be different from before (typically just increment it by 1).
  7. Save.

When the CDN settings are updated the cache for the website is also cleared to ensure that the latest versions of the files are used.

If you prefer to have the version appended to the URL ( ?v=2 ) then you could do the following.

{{ '/path/to/file.css'|file_url({append: true}) }}

Exclude certain files

If you need to exclude certain files from automatically having a version value added to them if the CDN is enabled then you can set the version option to false.

{{ '/path/to/file.css'|file_url({version: false}) }}

Apply cache busting to most images and file links

By default, only files that have the file_url or theme_url filters applied to them will have the automatic CDN version value applied to them. You can, however, choose to have the version value applied to most images and links to files on a page that are in the CDN. 

For example, you may want all images and file links updated in the CDN when a the CDN version value is changed. An example scenario could be that you have recently uploaded some new files that should overwrite some existing ones.

To enable this feature you have to first enable the automatic versioning. Then, set the "Apply the version value to most images and links on a page" field to "Yes".

The only files that will be affected are images within a <img> tag and links to files within a <a> link tag. Only files that are in the CDN get the version value applied to it. Third-party image and file URLs are unaffected.