Next.js

Next.js is a React framework with support for static export, server rendering, and hybrid modes. The pageflare/next integration supports static export mode only (output: 'export'), where Next.js generates a fully static site to the out/ directory.

Note

pageflare optimizes static files on disk. Next.js server-rendered pages (the default mode) are generated at request time and cannot be optimized at build time. If you’re using server rendering, consider the CLI with a custom build script instead.

Install

npm install -D pageflare

Usage (Recommended — npm script)

The simplest approach is to chain pageflare after next build in your npm scripts:

package.json

{
  "scripts": {
    "build": "next build && pageflare out/"
  }
}

This requires @pageflare/cli to be available on PATH (it’s installed automatically as a dependency of pageflare).

Usage (Programmatic API)

For more control, use the optimizeNextExport function in a custom build script:

scripts/optimize.mjs

import { optimizeNextExport } from 'pageflare/next'

await optimizeNextExport({
  platform: 'vercel',
  log: 'info',
})

package.json

{
  "scripts": {
    "build": "next build && node scripts/optimize.mjs"
  }
}

Options

Option	Type	Default	Description
platform	string	'auto'	Deployment platform: auto, vercel, netlify, cloudflare-pages, none
log	string	'warn'	Log level: off, error, warn, info, debug
args	string[]	[]	Extra CLI flags passed to pageflare optimize
outputDir	string	'out'	Path to the static export directory

Config Wrapper (Optional)

The package also exports a withpageflare config wrapper that validates your Next.js config is in export mode:

next.config.mjs

import withpageflare from 'pageflare/next'

export default withpageflare()({
  output: 'export',
  // ... rest of your Next.js config
})

This doesn’t hook into the build — it only warns if output: 'export' is not set. Optimization still happens via the npm script or programmatic API.

Next.js Config Requirements

Your next.config.mjs must have output: 'export':

next.config.mjs

export default {
  output: 'export',
}

Caution

Without output: 'export', Next.js produces server bundles in .next/ instead of static HTML in out/. pageflare cannot optimize server bundles.

Replacing plugins

pageflare is a single binary that replaces several Next.js packages. After adding pageflare, you can remove:

Package	pageflare equivalent
next-optimized-images	Image optimization, responsive srcset, lazy loading
next-pwa / @ducanh2912/next-pwa	Not replaced — keep if you need PWA
next-sitemap	Sitemap generation via llm.sitemap config
next-seo	Not replaced — keep for meta tags; pageflare handles performance, not SEO tags
@next/bundle-analyzer	Not replaced — different purpose (bundle analysis vs output optimization)

Tip

pageflare handles HTML/CSS/JS minification, image optimization, lazy loading, font optimization, and resource hints. If you have plugins that do any of these individually, remove them — pageflare covers all of it with zero config.

Deploying

Static exports work with any hosting provider. For platform-specific image optimization:

• Vercel — automatic Vercel Image Optimization
• Netlify — automatic Netlify Image CDN
• Cloudflare Pages — Cloudflare Image Resizing

Pro License

Set the PAGEFLARE_LICENSE environment variable to unlock Pro optimizations:

PAGEFLARE_LICENSE=your-key npm run build

Troubleshooting

“Next.js integration only supports output: 'export' mode” Add output: 'export' to your next.config.mjs. Without it, Next.js generates server bundles that pageflare cannot optimize.

out/ directory is empty Make sure next build completes before pageflare runs. If using the npm script approach (next build && pageflare out/), the && ensures correct ordering.

Images not optimized Next.js’s built-in <Image> component uses server-side optimization by default, which is disabled in static export mode. pageflare’s image optimization (lazy loading, dimensions, responsive srcset) works on standard <img> tags in the exported HTML.