--- name: azion-build-with-gatsby description: >- Create a Gatsby site from an Azion template or with the Azion CLI, and deploy it to an Azion domain. --- # Build with Gatsby You can deploy a Gatsby site on Azion from a template in Azion Console or from a project you create with the [Azion CLI](/en/documentation/devtools/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](/en/documentation/platform/applications/) serves. To check which other frameworks Azion builds, refer to [Frameworks compatibility](/en/documentation/devtools/runtime/frameworks/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](/en/documentation/fundamentals/creating-account/). **Console** - Access to Azion Console. To sign in, refer to [How to access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - A GitHub account, which the template form connects when it asks for one. **CLI** - The Azion CLI, installed and logged in. To set it up, refer to [Azion CLI quickstart](/en/documentation/devtools/cli/quickstart/). - Node.js 18 or later, with npm. - A terminal and a code editor. --- ## 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](/en/documentation/guides/application-development/frameworks/gatsby-blog-starter-kit/) | Blog | | [Gatsby Boilerplate](/en/documentation/guides/application-development/frameworks/gatsby-boilerplate/) | Single-page application | | [Gatsby Ecommerce Theme](/en/documentation/guides/application-development/frameworks/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](/en/documentation/platform/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: **Console** To deploy a Gatsby template from Azion Console: 1. **Open the templates** Access [Azion Console](https://console.azion.com/) > **Create** > **Templates**. 2. **Search for Gatsby** In **Search by name, framework, or keyword**, enter `Gatsby`. 3. **Select a Gatsby template** 4. **Connect your GitHub account** When the form shows **GitHub Connection**, select **Connect with GitHub** and install the [Azion GitHub App](/en/documentation/guides/application-development/automation/azion-github-app/). 5. **Select a Git Scope** In **Git Scope**, select the scope where the template repository goes. 6. **Fill in the settings the template asks for** 7. **Select Deploy** The deploy page opens and shows the **Deploy Log** during the build. After a successful deploy, the page shows **Successfully created!**, the domain URL, and a **Manage** button that opens the application. **CLI** To create a Gatsby project, run `azion init` with a project name. Select *Gatsby* in the preset picker, and then select a template: ```bash azion init --name my-site --auto -y ``` 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](/en/documentation/devtools/cli/init/). With the *Gatsby Blog Starter Kit* template, the output is: ```text ? Choose a preset: [Use arrows to move, type to filter] AI Studio Angular Astro Docusaurus Eleventy Emscripten > Gatsby Hexo Hono Hugo Javascript Jekyll Next Nuxt OpenNextJS Preact Qwik React Rustwasm Stencil Svelte Typescript Vitepress Vue Vuepress ? Choose a preset: Gatsby ? Choose a template: [Use arrows to move, type to filter] > Gatsby Blog Starter Kit Gatsby Boilerplate Gatsby Ecommerce Theme Gatsby with ButterCMS Starter Project ? Choose a template: Gatsby Blog Starter Kit Fetching selected template... Template successfully fetched Template successfully configured Installing application dependencies … ... (41 more lines) … [Azion] [Build] › ℹ info Using preset: gatsby [Azion] [Build] › ✔ success Build completed successfully with only azion.config [Azion] [IaC] › ✔ success Manifest generated successfully at /my-site/.edge/manifest.json If you want to start a local development server later, run 'azion dev' Make sure to change to the new working directory before running building or deploying your project If you want to deploy your application later, run 'azion deploy' Make sure to change to the new working directory before running building or deploying your project Your application my-site was initialized successfully ``` 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](/en/documentation/devtools/cli/azion-config-js/). To build the site, go to the project folder and run `azion build`: ```bash cd my-site azion build ``` Azion Bundler runs the Gatsby build with the `gatsby` preset and writes the site to `public`. The output is: ```text Building your Application. This process may take a few minutes Running build step command: $ npx --yes @aziontech/bundler@1.1.4 build --preset gatsby … [Azion] [Build] › ℹ info Using preset: gatsby [Azion] [Pre-Build] › ℹ info Starting pre-build... … [Gatsby] › ℹ info > gatsby-starter-blog@0.1.0 build > gatsby build [Gatsby] › ℹ info success compile gatsby files - 1.000s [Gatsby] › ℹ info success load gatsby config - 0.017s [Gatsby] › ℹ info [Gatsby] › ℹ info success load plugins - 0.967s ... (112 more lines) └ /using-typescript/ ╭────────────────────────────────────────────────────────────────╮ │ │ │ (SSG) Generated at build time │ │ D (DSG) Deferred static generation - page generated at runtime │ │ ∞ (SSR) Server-side renders at runtime (uses getServerData) │ │ λ (Function) Gatsby function │ │ │ ╰────────────────────────────────────────────────────────────────╯ [Azion] [Pre-Build] › ℹ info Pre-build completed successfully [Azion] [Build] › ℹ info Using built-in handler from "gatsby" preset. [Azion] [Build] › ℹ info Starting build... [Azion] [Build] › ✔ success Build completed successfully [Azion] [Post-Build] › ℹ info Starting post-build... [Azion] [Post-Build] › ✔ success Post-build completed successfully [Azion] [Storage] › ℹ info Using provided prefix for storage '$BUCKET_NAME': $BUCKET_PREFIX [Azion] [IaC] › ✔ success Manifest generated successfully at /my-site/.edge/manifest.json Your Application was built successfully ``` To deploy the site, run `azion deploy` from the project folder: ```bash azion deploy ``` 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](/en/documentation/devtools/cli/deploy/). To test the site on your machine before the deploy, refer to [Azion CLI dev](/en/documentation/devtools/cli/dev-command/). 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](/en/documentation/devtools/cli/link-command/). --- ## 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. --- ## Next steps - [Frameworks compatibility](/en/documentation/devtools/runtime/frameworks/frameworks-compatibility.md): See the other frameworks and presets that Azion builds. - [Azion CLI deploy](/en/documentation/devtools/cli/deploy.md): Read the full deploy output and the flags that change a deploy. - [Azion CLI dev](/en/documentation/devtools/cli/dev-command.md): Run the Gatsby site on your machine before you deploy it. - [azion.config.js](/en/documentation/devtools/cli/azion-config-js.md): Change the bucket, cache, and rules that the Gatsby preset generates.