Asset Prefixes

The end result of a Gatsby build is a collection of HTML files representing the Gatsby site and assets such as images, videos, JavaScript files, and CSS files. Today, it’s common practice for Gatsby developers to deploy the Gatsby-generated static HTML to a domain root but to leverage a different domain, such as a CDN, for other assets.

Introduced in Gatsby v2.4.0, asset prefixes allow you to enforce this distinction in your Gatsby builds by setting a prefix for assets that need to be hosted elsewhere, whether due to limitations of the infrastructure or corporate hosting policies. As with path prefixes, adding asset prefixes to your Gatsby site is a matter of including them in your gatsby-config.js file, as follows:

// gatsby-config.js
module.exports = {
}

Likewise, to ensure your asset prefixes are taken into account during the build process, whenever you perform a build or a serve of a Gatsby site you must include the --prefix-paths flag:

$ gatsby build --prefix-paths
$ gatsby serve --prefix-paths

Note that if you have path prefixes set in addition to asset prefixes, both of these will be respected upon the execution of the command.

One of the biggest benefits of asset prefixes is the fact that script embeds and references to stylesheets, images, and other assets will come prepopulated with the correctly prefixed paths. For instance, a JavaScript file known as main.js will appear in your generated static HTML like this:

<!-- Gatsby HTML -->

However, asset prefixes also require an additional step: unless you deploy the assets referred to in your static HTML to your CDN of choice or other domain, your Gatsby site will be making references to nonexistent files. Gatsby recommends two approaches as best practices for ensuring your assets are available on a CDN or other domain when the static HTML is presented to an end user: using an onPostBuild API hook in gatsby-node.js or using custom scripts in your package.json file.

To ensure the contents of your public/ folder, which houses all JavaScript files, CSS stylesheets, and other Gatsby-managed assets, are uploaded to the correct location using the onPostBuild API hook, add the following to your gatsby-node.js file:

// gatsby-node.js
const assetsDir = `public`

exports.onPostBuild = async function onPostBuild() {
  // Take the public directory and place its contents somewhere (e.g. a CDN).
}

Another option is to add a script to your package.json file. Many providers and CDN services offer a CLI that can be used to upload the assets in your public/ folder, like in the following example that demonstrates a file sync to an Amazon S3 bucket:

// package.json
{
  "scripts": {
    "build": "gatsby build --prefix-paths",
    "postbuild": "aws s3 sync public s3://myAwsBucket"
  }
}

Path and asset prefixes are powerful tools that enable the deployment of Gatsby sites and their assets to arbitrary locations and are particularly useful in more advanced hosting use cases that require differentiated configuration. In the next section, we direct our attention to individual hosting services and their use.

NOTE

There are some additional considerations when using asset prefixes, such as their interaction with path prefixes and the gatsby-plugin-offline plugin, which are accounted for in the Gatsby documentation.