Docusaurus

Docusaurus is a React-based documentation framework by Meta. It outputs a fully static site to build/ by default. pageflare integrates as a post-build step via npm scripts.

Install

npm install -D @pageflare/cli

Usage

Chain pageflare after docusaurus build in your npm scripts:

package.json

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

Every npm run build now optimizes the output automatically.

Configuration

Create a pageflare.jsonc in your project root:

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
}

If you use a custom output dir (docusaurus build --out-dir dist), pass the same path:

docusaurus build --out-dir dist && pageflare dist/ --in-place

What pageflare Adds

Docusaurus bundles and minifies JS/CSS via webpack, but does not optimize the final HTML output. pageflare adds:

• HTML minification
• 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)

CI/CD Integration

GitHub Actions

.github/workflows/build.yml

- name: Build Docusaurus
  run: npm run build

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

Netlify

netlify.toml

[build]
  command = "npm run build && pageflare build/ --in-place --no-progress"
  publish = "build"

Vercel

vercel.json

{
  "buildCommand": "npm run build && pageflare build/ --in-place --no-progress"
}

Replacing plugins

Docusaurus includes some optimizations by default (webpack minification, image handling). After adding pageflare, you can remove or disable:

Feature / Plugin	pageflare equivalent
@docusaurus/plugin-sitemap	Sitemap generation via llm.sitemap config
Third-party image optimization plugins	Image optimization, lazy loading, responsive srcset
@docusaurus/plugin-ideal-image	Image optimization and responsive loading

Tip

Docusaurus’s built-in webpack minification handles JS and CSS well. pageflare adds HTML minification, font optimization, lazy loading, resource hints, and critical CSS on top — the two complement each other.

Pro License

Set the PAGEFLARE_LICENSE environment variable to unlock Pro optimizations:

PAGEFLARE_LICENSE=your-key npm run build

Deploying

Docusaurus 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 Verify the output directory — Docusaurus defaults to build/ but this changes with --out-dir. Use && to ensure Docusaurus finishes before pageflare runs.

JS defer breaks client-side navigation Docusaurus uses client-side routing. If deferred scripts interfere, disable JS deferral in pageflare.jsonc:

{ "js_defer": false }

Duplicate minification Docusaurus already minifies JS and CSS via webpack. pageflare’s CSS/JS minification may produce marginal additional savings. You can disable them if you prefer Docusaurus to handle it:

{ "minify_css": false, "minify_js": false }