Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Deployment and Migration

Deploying Gatsby Sites: Hosts, Env Vars and Path Prefixes

Build and deploy a Gatsby site to Netlify, Vercel, Cloudflare Pages or GitHub Pages, manage environment variables safely and set a path prefix correctly.

gatsby build produces a public folder. For a purely static site (SSG only), that folder is the whole product: upload it to any web server and you are done. This lesson shows the common hosting options, the settings each needs, how environment variables work, and the one setting that breaks GitHub Pages deployments: the path prefix.

Static hosting basics

Terminal
# real commands, read-only
npm run build        # runs "gatsby build" and writes public/
npm run serve        # runs "gatsby serve": preview the production build on port 9000

Always preview with gatsby serve before deploying. It serves public the way a host would, and reveals problems that gatsby develop hides (missing images, broken links, build-only errors).

Host Build command Publish directory Notes
Netlify gatsby build public Best support for DSG/SSR/Functions through its Gatsby adapter.
Vercel gatsby build public Detects Gatsby; Functions and SSR through the Gatsby support layer.
Cloudflare Pages npm run build public Static sites work well; functions need a Workers setup.
GitHub Pages gatsby build --prefix-paths public Static only; needs a path prefix for project sites.
Any Nginx or S3 + CDN gatsby build public Static only. Configure caching headers yourself.

Choose a host that matches your rendering modes: SSG only runs anywhere, while DSG, SSR and Gatsby Functions need a host with server-side support. Since Gatsby 5.12, adapters (for example gatsby-adapter-netlify) can be listed in gatsby-config.js so Gatsby knows how to package routes and functions for the target platform.

JavaScript
// gatsby-config.js (real Gatsby, read-only)
const adapter = require("gatsby-adapter-netlify")
module.exports = {
  adapter: adapter(),
  siteMetadata: { siteUrl: "https://example.com" },
}

Deploying with Git

The most common flow: push the project to GitHub, connect the repository in the host dashboard, set the build command and publish directory, and every push to main builds and deploys. Pull requests get preview URLs. Set the Node version to match your local one with an .nvmrc file or the host's setting, and keep package-lock.json committed so installs are reproducible.

Environment variables

Gatsby reads .env files only if you load them. In gatsby-config.js:

JavaScript
// gatsby-config.js (real Gatsby, read-only)
require("dotenv").config({ path: `.env.${process.env.NODE_ENV}` })

Then create .env.development and .env.production. Two rules matter:

  1. GATSBY_ prefix: variables starting with GATSBY_ are embedded into the browser bundle at build time. Everyone can read them. Use them for public values such as an analytics ID or a public API URL.
  2. No prefix: available only in Node (gatsby-config.js, gatsby-node.js, Functions). Use these for secrets, such as a CMS token used during the build.

Never put a secret in a GATSBY_ variable. Never commit .env files with real keys: add .env* to .gitignore, and set the values in your host's dashboard. A variable changes the output only when you rebuild; changing it on the host does nothing to an already-built site.

JS Stand-in: which variables reach the browser?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Path prefix

If the site does not live at the domain root (for example GitHub Pages project sites, https://user.github.io/my-site/), links and assets must start with /my-site. Set pathPrefix and build with the flag:

JavaScript
// gatsby-config.js (real Gatsby, read-only)
module.exports = { pathPrefix: "/my-site" }
Terminal
gatsby build --prefix-paths

Gatsby's Link and image components add the prefix automatically. Plain <a href="/about"> and hard-coded asset paths do not; wrap them with withPrefix from gatsby:

JSX
// real Gatsby, read-only
import { withPrefix } from "gatsby"
<img src={withPrefix("/logo.png")} alt="Logo" />

Related: assetPrefix serves JavaScript and static assets from a CDN domain while pages stay on the main domain.

JS Stand-in: withPrefix

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Checklist before launch

  • siteMetadata.siteUrl is the final HTTPS address.
  • Preview the production build with gatsby serve and click through important pages.
  • Custom 404 page exists: src/pages/404.js; hosts serve it for unknown URLs.
  • Caching: files in static and hashed assets can be cached long; HTML should revalidate. Most hosts configure this for Gatsby automatically.
  • robots.txt, sitemap and canonical URLs (see SEO).
  • Environment variables set in the host, with secrets unprefixed.
  • Run Lighthouse on the live URL, not just locally.

Common mistakes

  • Deploying gatsby develop output or the wrong folder (.cache instead of public).
  • Missing --prefix-paths, so a project site loads with a blank page and 404 assets.
  • A secret in a GATSBY_ variable.
  • A Node version mismatch between local and host.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which folder is uploaded to a static host?

    gatsby build writes the finished site into public.
  2. 2. Which environment variables are embedded into the browser bundle?

    Only GATSBY_ prefixed variables are available in browser code.
  3. 3. When is pathPrefix needed?

    A sub-path deployment needs prefixed links and assets, enabled with --prefix-paths.
  4. 4. Can a static-only host run DSG pages and Functions?

    DSG, SSR and Functions run code on request.

Summary

  • Build with gatsby build, preview with gatsby serve, upload public.
  • Netlify and Vercel support server features; static hosts only serve SSG output.
  • Use GATSBY_ for public values, unprefixed variables for secrets, and rebuild to apply changes.
  • Use pathPrefix with --prefix-paths for sub-path hosting, and withPrefix for manual URLs.

Next: Redirects, headers and adapters