Hugo

Hugo is a fast static site generator written in Go. It outputs a fully static site to public/ by default. Since Hugo has no build plugin system, pageflare integrates as a post-build step — chain it after hugo in your build command or CI pipeline.

pageflare auto-detects Hugo projects when it finds hugo.toml, hugo.yaml, or config.toml in the project root.

Install

npm install -D @pageflare/cli

Or install globally:

# Shell (Linux/macOS)
curl -fsSL https://get.appz.dev/pageflare/install.sh | sh

# Homebrew
brew tap getappz/tap && brew install pageflare

Usage

Run pageflare after Hugo builds:

hugo && pageflare public/ --in-place

Or add it to your npm scripts if you use a package.json:

package.json

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

Configuration

Create a pageflare.jsonc in your project root to customize behavior:

pageflare.jsonc

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

pageflare respects Hugo’s output directory automatically. If you use a custom output dir (hugo -d build/), pass the same path to pageflare:

hugo -d build && pageflare build/ --in-place

CI/CD Integration

GitHub Actions

.github/workflows/build.yml

- name: Build Hugo
  run: hugo --minify

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

Netlify

netlify.toml

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

Or use the Netlify build plugin for automatic optimization.

Vercel

vercel.json

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

See the Vercel platform guide for image CDN integration.

Hugo’s Built-in Minification

Hugo has its own --minify flag. You can use both — Hugo’s minifier runs first, then pageflare applies additional optimizations that Hugo doesn’t cover:

• Lazy loading and image dimension inference
• 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)

hugo --minify && pageflare public/ --in-place

Replacing Hugo features

Hugo has built-in minification (--minify), but pageflare goes further. If you’re using Hugo Pipes for asset processing, note the overlap:

Hugo feature	pageflare equivalent
--minify	HTML, CSS, JS minification (more aggressive)
resources.Fingerprint	Content-hashed filenames
resources.PostCSS	Keep — pageflare doesn’t run PostCSS, it optimizes the output
Hugo image processing (Resize, Fit)	Keep for content images; pageflare adds lazy loading, dimensions, and responsive srcset

Tip

You can safely drop --minify from your Hugo build command — pageflare’s minification is more thorough. Keep Hugo’s image processing if you use it in templates, since pageflare operates on the final output.

Pro License

Set the PAGEFLARE_LICENSE environment variable to unlock Pro optimizations:

PAGEFLARE_LICENSE=your-key hugo && pageflare public/ --in-place

Deploying

Hugo 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

pageflare processes 0 files Make sure Hugo has finished building before pageflare runs. Use && (not &) to chain commands sequentially. Verify the output directory matches — Hugo defaults to public/ but this can be changed in hugo.toml.

HTML looks different after optimization If Hugo’s --minify and pageflare’s HTML minification conflict, disable one. You can turn off pageflare’s HTML minification in pageflare.jsonc:

{ "minify_html": false }

Slow builds on large sites Hugo builds are fast, but pageflare’s image processing can add time for sites with thousands of images. Use --force to skip incremental caching in CI, or run with log: 'info' to identify which phase takes the most time.