Host a gatsby website

Gatsby’s `public/` folder is the product you upload

Gatsby builds a React-powered site into static files under public/. StaticHost serves that folder’s contents. It will not run gatsby build, GraphQL sourcing, or image CDNs for you. Build elsewhere; publish files. Strict nginx behavior applies: try_files $uri $uri/ =404. Missing client-only routes do not fall back to index.html.

That split—local (or CI) build, remote file serve—is how every serious Gatsby deployment should work even on platforms that offer remote builds. On StaticHost it is explicit: bring public/, nothing else.

Essential config keys

gatsby-config.js:

module.exports = {
  pathPrefix: '/', // avoid '/repo-name' leftovers from GitHub Pages tutorials
  siteMetadata: {
    siteUrl: 'https://example.com',
    title: 'Example',
  },
  plugins: [
    // source and image plugins
  ],
}

For root hosting on StaticHost, do not leave a GitHub Pages pathPrefix: '/repo'. Asset links will request /repo/framework-….js on a host where that prefix does not exist, and the site will look blank.

gatsby-browser.js / gatsby-ssr.js customization still ends as static assets after build—fine. Anything expecting a Node server at request time is not. Set siteMetadata.siteUrl to the canonical HTTPS origin you will use in production so sitemap and SEO plugins emit correct absolute URLs once you know the domain.

Build commands

npm ci
npm run build
# equivalent: npx gatsby build
ls public

Optional:

npx gatsby build --prefix-paths  # only if you truly need pathPrefix

Pack the contents of public/:

cd public && zip -r ../gatsby-site.zip .
unzip -l ../gatsby-site.zip | head

Upload the zip or push public contents to the branch StaticHost deploys. No remote npm on the host—see git deploy a static site. Zip nesting pitfalls: zip a static site without 404.

Worked example: blog starter to HTTPS preview

npm init gatsby
# choose a blog-style starter if prompted, or clone your existing repo
cd my-gatsby-site
npm ci
# set pathPrefix out of GitHub Pages mode in gatsby-config.js
npm run build
cd public && zip -r ../../gatsby-public.zip .

Deploy gatsby-public.zip to a StaticHost site. Open HTTPS preview (TLS without waiting on DNS). Visit /, a post URL from public/, and an image URL under static/. If the post URL 404s, confirm the file exists in the zip listing before blaming the host.

When preview looks right, attach a custom domain. DNS must verify before the certificate issues—same order every time: HTTPS preview → DNS → cert. Broader domain notes: static hosting with a custom domain.

Client-only routes

Gatsby supports client-only routes under matching page shells. On platforms with SPA fallback, hard refreshes on those routes still load the app. On StaticHost they 404 unless you also emit files or use hash-style URLs. Audit createPages and Reach Router / @reach/router usage for client-only paths before launch. General rules: host a single-page application, host a React build online.

If marketing pages are static templates and an app section is client-only, consider putting the app on a hash route or a separate host that offers SPA rewrites. Do not assume StaticHost will rewrite for you—it will not.

Images and storage

gatsby-plugin-image processes at build time into public/static/…. Large photo catalogs inflate storage: Starter 2 GB ($9), Pro 10 GB ($30), Scale 30 GB ($65), Business 100 GB ($130). Trial ~1 day. There is no forever-free tier and no built-in CDN product; compress and size images in the build rather than hoping the edge will save you.

DSG / SSR features

Deferred Static Generation and SSR modes that need the Gatsby Hosting / Node runtime are out of scope here. Use plain static gatsby build output compatible with any file host. If your architecture depends on DSG resolvers at request time, pick a different host or redesign those pages as build-time static pages.

When not to host Gatsby on StaticHost

You require Gatsby SSR or DSG at request time.
Your “site” is mostly client-only app routes with no prerendered HTML files.
You refuse to run Node locally or in CI and expected the host to build for you.
You need WordPress-style editorial UI on the same origin—use a CMS host or a headless CMS feeding your local/CI build, not PHP on StaticHost.

Verification checklist

Deploy public/ contents; open HTTPS preview.
Test homepage, a collection template page, and an image-heavy page.
Hard-refresh any client-only route; note 404s; fix architecture if needed.
Roll back from deploy history on bad plugin upgrades.
Custom domain → DNS verify → certificate.

No cPanel, email, forever-free, built-in CDN product, or PHP runtime.

Failure table (Gatsby on StaticHost)

Symptom	Likely cause	Fix
Blank white page	Leftover `pathPrefix` or nested zip	Set root `pathPrefix`, re-zip `public/` contents, rebuild
`/blog/my-post/` 404	Post not in this build or wrong trailing-slash expectations	Confirm file under `public/blog/…`; match links to emitted paths
Images 404 under `/static/`	Incomplete zip or cleaned `public` mid-pack	Rebuild; zip again from fresh `public/`
Deep app route 404 on refresh	Client-only route without file	Prerender, hash route, or different host
Huge deploy size	Unoptimized image pipeline	Tune `gatsby-plugin-sharp` defaults; audit `public/`

Extra procedure: plugin upgrade without surprising production

Gatsby plugin bumps (especially image and remark ecosystems) can change markup and public/static/ hashes.

Branch; bump plugins in package.json; run npm ci.
npm run build locally; diff a sample of public/ HTML for unexpected churn.
Zip public/ contents; deploy to Pro staging ($30/mo) with staging siteUrl if needed.
Click homepage, one template page, one image-heavy page on HTTPS staging/preview.
Hard-refresh any client-only route; note 404s under try_files $uri $uri/ =404.
Only then deploy the same artifact mindset to production; keep deploy history ready for rollback.
Attach or keep custom domains; certificates already issued stay with verified DNS—new hostnames still wait on verification.

Never upload .cache/ or node_modules/ as a substitute for public/. StaticHost does not run gatsby build. No forever-free after ~1 day trial; Starter $9 / Pro $30 / Scale $65 / Business $130; no email, cPanel, built-in CDN product, or PHP.

FAQ

Is `.cache/` upload required?

No. Only public/. Never upload .cache/ or node_modules/ as a substitute for a build.

Can I use Gatsby Cloud previews with StaticHost production?

You can build anywhere that emits public/. Preview systems are independent of StaticHost’s HTTPS preview of the uploaded tree.

Why is the site blank after deploy?

Often wrong pathPrefix or nested zip. Check Network for /repo/framework-….js 404s.

Does GraphQL run on StaticHost?

No. GraphQL runs at build time during gatsby build on your machine or CI.

How do I host a Gatsby docs theme?

Same as any Gatsby site: build, upload public/. Also see static documentation hosting and JAMstack hosting for beginners.