Deploying to S3/CloudFront
This guide walks through how to host and publish your next Gatsby site to AWS using S3. Optionally - but very recommended - you can add CloudFront, a global CDN to make your site even faster.
- A Gatsby project set up. (Need help creating one? Follow the Quick Start)
- An AWS account, and a access key ID and secret access key. Follow the Prerequisites to use the AWS CLI version 2 guide
- The AWS CLI installed, follow the install instructions
Setting up S3
Now that your Gatsby site is up and running and AWS access is sorted out, you’ll need to add hosting and make the site live on AWS.
First, install the Gatsby S3 plugin:
Add it to your
gatsby-config.js. Don’t forget to change the bucket name:
And finally, add the deployment script to your
That’s it! Run
npm run build && npm run deploy to do a build and have it immediately deployed to S3!
Deploying with environment variables
Some deployments require passing environment variables. To deploy with environment variables, update the deployment script to your
This command requires
dotenv first, runs build next, and finally deploys to S3.
dotenv, a dependency of Gatsby that doesn’t need to be installed directly, loads environment variables and makes them available globally.
If you have multiple AWS profiles in your machine, you can deploy by declaring your
AWS_PROFILE before the deploy script:
Setting up CloudFront
There are a couple of things that you need to consider when using
gatsby-plugin-s3 to deploy a site which uses CloudFront.
gatsby-plugin-meta-redirect can compensate for the former. But just because you can’t see these issues, doesn’t mean they won’t affect search engines.
In order for all the features of your site to work correctly, you must instead use your S3 bucket’s Static Website Hosting Endpoint as the CloudFront origin. This does (sadly) mean that your bucket will have to be configured for public-read, because when CloudFront is using an S3 Static Website Hosting Endpoint address as the Origin, it’s incapable of authenticating via IAM.
In the gatsby-plugin-s3 configuration file, there are a couple of optional parameters that you can usually leave blank,
hostname. But when you’re using CloudFront, these parameters are vital for ensuring redirects work correctly. If you omit these parameters, redirects will be performed relative to your S3 Static Website Hosting Endpoint. This means if a user visits your site via the CloudFront URL and hits a redirect, they will be redirected to your S3 Static Website Hosting Endpoint instead. This will disable HTTPS and (more importantly) will display an ugly and unprofessional URL in the user’s address bar.
By specifying the
hostname parameters, you can cause redirects to be applied relative to a domain of your choosing.
If you use your site’s URL elsewhere in gatsby-config.js, you can define the URL once at the top of the config:
And then in the Gatsby config you can reference it like so:
If you need the full address elsewhere in your config, you can access it via
For automatic setup of builds that are deployed straight to S3:Start building today on Gatsby Cloud!