Adding an Asset Prefix
assetPrefix functionality is available starting in firstname.lastname@example.org, so that you can seamlessly use Gatsby with assets hosted from a separate domain. To use this functionality, ensure that your version of
gatsby specified in
package.json is at least
One more step - when you build out this application, you need to add a flag so that Gatsby picks up this option.
When building with an
assetPrefix, you require a
--prefix-paths flag. If this flag is not specified, the build will ignore this option, and build out content as if it was hosted on the same domain. To ensure you build out successfully, use the following command:
That’s it! You have an application that is ready to have its assets deployed from a CDN and its core files (e.g. HTML files) can be hosted on a separate domain.
app-common-1234.js, the script tag will look something like:
However - if you were to deploy your application as-is, those assets would not be available! You can do this in a few ways, but the general approach will be to deploy the contents of the
public folder to both your core domain, and the CDN/asset prefix location.
You expose an
onPostBuild API hook. This can be used to deploy your content to the CDN, like so:
Additionally, you can use an npm script, which will let you use some command line interfaces/executables to perform some action, in this case, deploying your assets directory!
In this example, the
s3 is used to sync the
public folder (containing all the assets) to the
Now whenever the
build script is invoked, e.g.
npm run build, the
postbuild script will be invoked after the build completes, therefore making your assets available on a separate domain after you have finished building out your application with prefixed assets.
pathPrefix feature can be thought of as semi-related to this feature. That feature allows all your website content to be prefixed with some constant prefix, for example you may want your blog to be hosted from
/blog rather than the project root.
This feature works seamlessly with
pathPrefix. Build out your application with the
--prefix-paths flag and you’ll be well on your way to hosting an application with its assets hosted on a CDN, and its core functionality available behind a path prefix.
When using a custom asset prefix with
gatsby-plugin-offline, your assets can still be cached offline. However, to ensure the plugin works correctly, there are a few things you need to do.
Your asset server needs to have the
Access-Control-Allow-Originheader set either to
*or your site’s origin.
Certain essential resources need to be available on your content server (i.e. the one used to serve pages). This includes
sw.js, as well as resources to precache: the Webpack bundle, the app bundle, the manifest (and any icons referenced), and the resources for the offline plugin app shell.
You can find most of these by looking for the
self.__precacheManifestvariable in your generated
sw.js. Remember to also include
sw.jsitself, and any icons referenced in your
manifest.webmanifestif you have one. To check your service worker is functioning as expected, look in Application → Service Workers in your browser dev tools, and check for any failed resources in the Console/Network tabs.
Edit this page on GitHub