Gatsby Deployment — Deploying to Production Hosting

Learn how to deploy Gatsby sites to Netlify, Vercel, Cloudflare Pages, and Gatsby Cloud with build optimization and CI/CD pipeline setup.

In this lesson, you'll understand how to build Gatsby for production, configure hosting platforms, and set up continuous deployment.

What You'll Learn

How to run production builds, deploy to popular hosting platforms, configure build settings, and set up automated deployments from GitHub.

Why It Matters

Deployment is the final step in getting your site to users. Proper deployment configuration ensures fast builds, correct redirects, and optimal caching.

flowchart LR
    A[Git Push] --> B[CI/CD Trigger]
    B --> C[gatsby build]
    C --> D[Deploy to Host]
    D --> E[CDN Cache]
    E --> F[Live Site]
    style C fill:#639,color:#fff

Production Build

gatsby build

Output: Static HTML, CSS, JS files in the public/ directory. Optimized with code splitting, image processing, and asset hashing.

# Serve the build locally to verify
gatsby serve

Output: The production build runs at http://localhost:9000. Test all features before deploying.

Netlify Deployment

# netlify.toml
[build]
  command = "gatsby build"
  publish = "public/"

[build.environment]
  NODE_VERSION = "18"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Connect your GitHub repo to Netlify. Netlify auto-detects Gatsby and runs gatsby build on every push.

Vercel Deployment

// vercel.json
{
  "buildCommand": "gatsby build",
  "outputDirectory": "public",
  "framework": "gatsby",
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

Connect to Vercel from GitHub. Vercel auto-detects Gatsby and sets up optimal build configuration.

Cloudflare Pages

# wrangler.toml
name = "my-gatsby-site"
compatibility_date = "2024-01-01"

[build]
  command = "gatsby build"
  publish = "public/"

Connect Cloudflare Pages to your GitHub Repository. Set NODE_VERSION=18 in environment variables.

Gatsby Cloud

Gatsby Cloud is purpose-built for Gatsby sites with incremental builds:

# Connect gatsby-config.js to Gatsby Cloud
# Builds automatically on git push
# Supports CMS previews and content webhooks

Gatsby Cloud provides: instant preview deployments, incremental builds (only rebuild changed pages), CMS previews, and performance monitoring.

Build Optimization

// gatsby-config.js
module.exports = {
  flags: {
    DEV_SSR: false,
    FAST_DEV: true,
    PARALLEL_SOURCING: true
  }
};

CI/CD configuration for faster builds:

# .github/workflows/deploy.yml
name: Deploy to Netlify
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 18 }
      - run: npm ci
      - run: npm run build
        env:
          CONTENTFUL_SPACE_ID: ${{ secrets.CONTENTFUL_SPACE_ID }}
          CONTENTFUL_ACCESS_TOKEN: ${{ secrets.CONTENTFUL_ACCESS_TOKEN }}
      - run: npx netlify-cli deploy --prod --dir=public

Common Mistakes

1. Not testing the production build locally: Always run gatsby build && gatsby serve before deploying. Development mode hides build errors.
2. Missing siteUrl in siteMetadata: Sitemap, RSS, and OG tags use absolute URLs. Without siteUrl, they use relative paths.
3. Not configuring redirect rules: Client-only routes need redirects for direct URL access. Configure /* -> /index.html for SPAs.
4. Hardcoding environment variables in CI: Use repository secrets or CI/CD environment variables to inject API keys and tokens.
5. Deploying without checking Lighthouse: Run Lighthouse on the production URL after first deploy. Fix performance and SEO issues.

Practice Questions

1. What command builds Gatsby for production? Answer: gatsby build. It outputs optimized files to public/.

2. How do you test the production build locally? Answer: Run gatsby serve after gatsby build. It serves the public/ directory at http://localhost:9000.

3. What is the purpose of the /* -> /index.html redirect rule? Answer: It enables client-side routing by serving index.html for all paths, letting the JavaScript router handle the URL.

4. Which hosting platform offers incremental builds for Gatsby? Answer: Gatsby Cloud offers incremental builds — only changed pages are rebuilt, reducing deployment time.

Challenge

Set up a complete CI/CD pipeline with: GitHub Actions that builds on push, deploys to Netlify, runs Lighthouse CI for performance checks, and posts the report as a PR comment.

Mini Project

Deploy the Gatsby blog you built in previous lessons to production. Configure: custom domain, HTTPS, redirect rules for client-only routes, environment variables for CMS credentials, and a deploy status badge in the README.

FAQ

What's Next

Build a complete Gatsby application in the Gatsby Mini Project lesson, combining all concepts into a real-world site.