Gatsby

Gatsby is a React-based static site generator. It outputs a fully static site to public/ by default. pageflare integrates as a post-build step via npm scripts.

Gatsby has a plugin system with an onPostBuild hook, but the simplest approach is chaining pageflare in your build command.

Install

npm install -D @pageflare/cli

Usage

Chain pageflare after gatsby build in your npm scripts:

{
  "scripts": {
    "build": "gatsby build && pageflare public/ --in-place"
  }
}

Configuration

Create a pageflare.jsonc in your project root:

{
  "minify_html": true,
  "minify_css": true,
  "minify_js": true,
  "js_defer": true,
  "lazy_images": true,
  "img_dimensions": true,
  "font_swap": true,
  "preconnect_hints": true
}

What pageflare Adds

Gatsby handles image optimization via gatsby-plugin-image and minifies JS/CSS via webpack, but does not optimize the final HTML output. pageflare adds:

HTML minification
Lazy loading for images not using gatsby-plugin-image
JavaScript defer and loader injection
Font display swap and self-hosting
Preconnect hints for third-party origins
Critical CSS extraction (Pro)
Responsive image srcset generation (Pro)

Replacing plugins

pageflare replaces several Gatsby plugins. After adding pageflare to your build, you can remove:

Package	pageflare equivalent
`gatsby-plugin-minify` / `gatsby-plugin-minify-html`	HTML minification
`gatsby-plugin-preload-fonts`	Font preloading and self-hosting
`gatsby-plugin-preconnect`	Preconnect hints
`gatsby-plugin-sitemap`	Sitemap generation via `llm.sitemap` config
`gatsby-plugin-image`	Keep — Gatsby’s image pipeline is tightly integrated; pageflare handles images that bypass it

CI/CD Integration

GitHub Actions

- name: Build Gatsby
  run: gatsby build

- name: Optimize with pageflare
  uses: getappz/pageflare-cli@v1
  with:
    args: "public/ --in-place"

Netlify

[build]
  command = "gatsby build && pageflare public/ --in-place --no-progress"
  publish = "public"

Vercel

{
  "buildCommand": "gatsby build && pageflare public/ --in-place --no-progress"
}

Pro License

Set the PAGEFLARE_LICENSE environment variable to unlock Pro optimizations:

PAGEFLARE_LICENSE=your-key npm run build

Deploying

Gatsby static output works with any hosting provider:

Vercel — automatic Vercel Image Optimization
Netlify — automatic Netlify Image CDN
Cloudflare Pages — Cloudflare Image Resizing
Self-hosted — any static file server

Troubleshooting

JS defer breaks client-side navigation Gatsby uses client-side routing via @reach/router. If deferred scripts interfere with page transitions, disable JS deferral:

{ "js_defer": false }

Duplicate image optimization If you use gatsby-plugin-image, Gatsby already handles responsive images and lazy loading for those images. pageflare will skip images that already have loading="lazy" and srcset attributes. The two work safely together.

pageflare processes 0 files Verify Gatsby finished building — gatsby build can fail silently on GraphQL errors. Check that public/ contains HTML files before running pageflare.