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.)

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 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 number or 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 number 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 number.

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.

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

The other option is to set a version number on the CDN settings page and then if the CDN is enabled the version number 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 number 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 number.
  3. Set the version number (note that his value can contain letters and/or numbers).
  4. Save.

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

If you need to make an update to a file that has a version number 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 number 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 number 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}) }}