Deploying a Gatsby site can feel like a daunting task, especially with the array of potential hosting platforms. Among them, Netlify is a strong contender due to its seamless integration and deployment process. This post will show how to get your Gatsby site live on Netlify.
As your Gatsby site matures you’ll naturally start to think about where and how it will be deployed. There are a lot of options including
- GitHub Pages
- GitLab Pages
- Heroku (⛔ but no free tier!) and
In this post we’ll focus on Netlify.
gatsby-adapter-netlify package to
packages.json. This package enables a zero-configuration deployment, which certainly sounds like a labour-saving feature.
Update the site packages with
gatsby-adapter-netlify package should be used for all new Gatsby sites. If you have a site which uses an older version of Gatsby then you might have to use
gatsby-adapter-netlify to the list of plugins in
Deploying on Netlify
Over on Netlify you kick off the deployment process.
- Click on the button.
- Select the “Import an existing project” option.
- Choose where you’ll be deploying from. The options are:
- Bitbucket and
- Azure DevOps.
- Choose the appropriate project and branch.
- Scroll down and press the button.
All being well the deploy process will churn for a short while before your site becomes available.
Netlify will assign a randomised URL to your site. You can change the site name via the site configuration.
You can simulate the Netlify build process locally with the Netlify CLI.
First login to Netlify (this will open a browser tab).
# Login. netlify login # Switch from one Netlify account to another. netlify switch
Now link your local project to the site that you’ve just deployed on Netlify.
There are a few options for how this link can be created. These are the ones that I find most useful:
- search by full or partial site name;
- choose from a list of your recently updated sites; or
- enter a site ID. 👈 Get the site ID from the site configuration on Netlify.
That will create a
.netlify directory containing a file,
state.json, that stores the site ID.
And finally build the site.
You can also use a Docker image. You’ll need to first generate a personal access token. Pass this to Docker as the
NETLIFY_AUTH_TOKEN environment variable.
docker run -it -v $PWD:/site \ -e NETLIFY_AUTH_TOKEN=3xhsAv6QovEGu0LCDFXOLkFercZ9wQieiLK0bpGB8CX \ datawookie/netlify-cli:latest build
Your Netlify deploy is likely to go very smoothly. Here are some notes from a few of the minor wrinkles I’ve encountered.
Running out of Heap Space
I addressed this issue in another post. If you’re watching the build progress on Netlify then you might think that it’s been successful… until it fails at the last instant. You can set an environment variable to increase the available heap space. You can set environment variables under site configuration, where you’ll find an environment variables section.
Try setting the
NODE_OPTIONS environment variable to
--max_old_space_size=4096. If that doesn’t solve the problem then try a larger value like 8192 or 16384.
Another symptom of this problem is an error about not being able to find a temporary query result or not being able to write page-data.
You might find that your build is being killed with an exit code of 137 (more infomation on that here). This might be because the build is taking more than 15 minutes, which is the maximum for a free deploy. Check the timestamps on the build log. If the build has taken around 15 minutes then this is likely to be the problem. Add a credit card on your account to get extra minutes of build time. Or take advantage of the free trial of a Pro membership (credit card still required).
Other things to try:
- Change the build command to
npm run build. 👈 Not sure why this seems to be preferable to
yarn run build. Could be due to different dependency resolutions?
- Set environment variable
CI=falseto disable Continuous Integration mode.
- Set environment variable
- Try changing the Node version. This can be set via the
.nvmrc(check the build logs).