CLI Guide

Deploy Gatsby with Bantam CLI

Deploy React-based static sites with GraphQL data layer

Install Bantam CLI:

npm install -g @bantamhq/cli

View on NPM: @bantamhq/cli

Quick start:

# Build your Gatsby app
gatsby build

# Deploy it
bantam deploy ./public

Quick Start

Clean cache and build

Clear cache and create production build

gatsby clean && gatsby build

Gatsby generates files in ./public directory

Test locally (optional)

Preview your production build at localhost:9000

gatsby serve

Deploy with Bantam

Your Gatsby site is live!

bantam deploy ./public

Add --permanent for a permanent URL

Framework Details

Build Configuration

Essential Gatsby configuration for production builds:

gatsby-config.js - Basic setup:

module.exports = {
  siteMetadata: {
    title: 'My Gatsby Site',
    siteUrl: 'https://mysite.bantam.site',
  },
  pathPrefix: '/my-site', // If deploying to subdirectory
  plugins: [
    'gatsby-plugin-react-helmet',
    'gatsby-plugin-sitemap',
    {
      resolve: 'gatsby-plugin-manifest',
      options: {
        name: 'My Gatsby Site',
        short_name: 'MySite',
        start_url: '/',
        icon: 'src/images/icon.png',
      },
    },
  ],
}

Set siteUrl for proper sitemap generation and canonical URLs.

Path Prefix for Subdirectories

Deploy to a subdirectory with path prefix:

Configure and build with prefix:

// gatsby-config.js
module.exports = {
  pathPrefix: '/blog',
  // ... other config
}

# Build with prefix
gatsby build --prefix-paths

# Deploy
bantam deploy ./public

Always use --prefix-paths flag when building if you've set a pathPrefix.

Environment Variables

Gatsby uses different prefixes for build-time and client-side variables:

.env.production:

# Available at build time only
CONTENTFUL_SPACE_ID=abc123
CONTENTFUL_ACCESS_TOKEN=xyz789

# Available in browser (GATSBY_ prefix)
GATSBY_API_URL=https://api.example.com
GATSBY_GA_TRACKING_ID=UA-123456789

Access in your code:

// Build time (Node.js)
exports.sourceNodes = async ({ actions }) => {
  const data = await fetch(process.env.CONTENTFUL_SPACE_ID)
}

// Client side (browser)
const apiUrl = process.env.GATSBY_API_URL

Image Optimization

Gatsby's image plugin creates optimized images at build time:

Using gatsby-plugin-image:

import { StaticImage, GatsbyImage } from "gatsby-plugin-image"

// For static images
<StaticImage
  src="../images/hero.jpg"
  alt="Hero"
  placeholder="blurred"
  layout="fixed"
  width={1200}
  height={600}
/>

// For dynamic images from GraphQL
export const query = graphql`
  query {
    file(name: { eq: "hero" }) {
      childImageSharp {
        gatsbyImageData(
          width: 1200
          placeholder: BLURRED
          formats: [AUTO, WEBP, AVIF]
        )
      }
    }
  }
`

Advanced Usage

Custom Domain

Deploy directly to your own domain

bantam deploy ./dist --domain myapp.com

Permanent Deployment

Keep your site online forever (requires login)

bantam deploy ./dist --permanent

Custom Expiry

Set how long your deployment stays online

bantam deploy ./dist --expiry-days 7

Custom Subdomain

Choose your own subdomain on bantam.site

bantam deploy ./dist --subdomain my-project

CI/CD Integration

Add Bantam to your continuous deployment pipeline:

# GitHub Actions example
- name: Deploy to Bantam
  run: |
    npm install -g @bantamhq/cli
    bantam login --token ${{ secrets.BANTAM_TOKEN }}
    bantam deploy ./dist --domain myapp.com --permanent

Troubleshooting

Common Issues & Solutions

Quick fixes for deployment challenges

01.Build fails with 'out of memory' error

Large Gatsby sites may need more memory:

# Increase Node memory limit
NODE_OPTIONS="--max-old-space-size=8192" gatsby build

# Or add to package.json
"scripts": {
  "build": "NODE_OPTIONS='--max-old-space-size=8192' gatsby build"
}

Also try gatsby clean before building to clear cache.

02.404 page not working in production

Create a custom 404 page at src/pages/404.js:

// src/pages/404.js
import React from "react"
import Layout from "../components/layout"

const NotFoundPage = () => (
  <Layout>
    <h1>404: Not Found</h1>
    <p>This page doesn't exist.</p>
  </Layout>
)

export default NotFoundPage

Gatsby automatically uses this for unmatched routes.

03.Client-side routes not working

For client-side only routes, use gatsby-plugin-create-client-paths:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-create-client-paths',
      options: { prefixes: ['/app/*'] },
    },
  ],
}

// Or use @reach/router for client routes
import { Router } from "@reach/router"

const App = () => (
  <Router basepath="/app">
    <Dashboard path="/dashboard" />
    <Settings path="/settings" />
  </Router>
)

04.GraphQL queries failing in production

Common causes and solutions:

Environment variables missing - check .env.production
API endpoints changed - update source plugins
Cache issues - run gatsby clean

# Debug build issues
gatsby build --verbose

# Clear all caches
rm -rf .cache public
gatsby build

05.How to optimize Gatsby build times?

Speed up builds with these techniques:

// gatsby-config.js
module.exports = {
  flags: {
    PARALLEL_SOURCING: true,
    FAST_DEV: true,
  },
  plugins: [
    {
      resolve: 'gatsby-plugin-sharp',
      options: {
        defaults: {
          formats: ['auto', 'webp'],
          placeholder: 'blurred',
          quality: 80,
        },
        failOnError: false,
      },
    },
  ],
}

Consider using Gatsby Cloud for incremental builds in CI/CD.