Build with Gatsby
Create a Gatsby site from an Azion template or with the Azion CLI, and deploy it to an Azion domain.
You can deploy a Gatsby site on Azion from a template in Azion Console or from a project you create with the Azion CLI. Both routes finish with the site served on Azion from an Azion domain.
A Gatsby site runs on Azion as a static application. The Gatsby build writes the pages to ./public, and the deploy uploads that folder to a storage bucket that an application serves. To check which other frameworks Azion builds, refer to Frameworks compatibility.
Choose a route. The prerequisites and the deploy procedure below change with your choice.
Prerequisites
- An Azion account. To create one, refer to Create an account.
- Access to Azion Console. To sign in, refer to How to access Azion Console.
- A GitHub account, which the template form connects when it asks for one.
Gatsby templates
A Gatsby template is a complete Gatsby project that Azion deploys on your behalf. The Console route deploys one of these templates:
| Template | Use |
|---|---|
| Gatsby Blog Starter Kit | Blog |
| Gatsby Boilerplate | Single-page application |
| Gatsby Ecommerce Theme | E-commerce |
| Gatsby with ButterCMS Starter Project | CMS integration |
Three of the templates have their own guide, linked in the table. For more information on the fourth, refer to Azion Marketplace. In the CLI route, the template picker of azion init offers the same four Gatsby templates.
Deploy the site
Every route builds the Gatsby project and creates the Azion resources that serve it. Use the panel of the route you chose:
To create a Gatsby project, run azion init with a project name. Select Gatsby in the preset picker, and then select a template:
With -y, the command installs the project dependencies. With --auto, it does not ask whether to start a local development server or to deploy. Without both options, the command asks the questions listed in Azion CLI init. With the Gatsby Blog Starter Kit template, the output is:
The npm install of the template prints npm warn lines about peer dependencies, and the project still initializes. The project goes in a my-site folder. Its azion.config.cjs file sets the gatsby preset and uploads ./public to a storage bucket with read-only access for workloads. For every setting in that file, refer to azion.config.js.
To build the site, go to the project folder and run azion build:
Azion Bundler runs the Gatsby build with the gatsby preset and writes the site to public. The output is:
To deploy the site, run azion deploy from the project folder:
The deploy uploads the project and opens the Console page that tracks the deploy. It also prints the URL of that page in case the browser does not open. At the end, the command prints the URL of the site’s domain. For the full output and the flags that change a deploy, refer to Azion CLI deploy.
To test the site on your machine before the deploy, refer to Azion CLI dev. For a Gatsby project that exists already, run azion link in the project folder and select the Gatsby preset, as described in Azion CLI link.
Check the site
Each route gives you the URL of the site’s Azion domain, in the format https://xxxxxxxxxx.map.azionedge.net. In Azion Console, the URL is on the deploy page. In the CLI, azion deploy prints it at the end. Open the URL in a browser to load the Gatsby site.
The first deploy can take several minutes to answer from every location; later deploys take about two minutes. A location that does not have the site yet returns a 404 page with the text There's nothing here yet. If you get that page, wait and load the URL again.