Astro

Astro is a static site generator with built-in support for React, Vue, Svelte, and other UI frameworks. The pageflare/astro integration hooks into Astro’s build lifecycle and optimizes all output after page generation completes.

Install

npm install -D pageflare

Configuration

Add the integration to your Astro config:

astro.config.mjs

import { defineConfig } from 'astro/config'
import pageflare from 'pageflare/astro'

export default defineConfig({
  integrations: [pageflare()]
})

Every astro build now runs pageflare on the output.

Options

astro.config.mjs

import { defineConfig } from 'astro/config'
import pageflare from 'pageflare/astro'

export default defineConfig({
  integrations: [
    pageflare({
      platform: 'netlify',
      log: 'info',
      args: ['--force'],
    })
  ]
})

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

How It Works

The integration uses Astro’s astro:build:done hook, which fires after all pages have been generated and all assets have been copied to the output directory. This ensures pageflare processes the final, complete output — including static HTML pages, CSS bundles, and processed images.

The output directory is provided by Astro (defaults to dist/).

Why Not the Vite Plugin?

Astro uses Vite internally, so the pageflare/vite plugin would also work. However, the Astro integration is preferred because:

• astro:build:done fires after Astro’s own post-processing (SSG page generation, asset pipeline), while Vite’s closeBundle may fire before Astro finishes.
• The integration receives the output directory directly from Astro, avoiding path resolution issues.

Starlight

If you’re using Starlight (Astro’s documentation theme), the integration works the same way — add it to your astro.config.mjs alongside the Starlight integration:

astro.config.mjs

import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'
import pageflare from 'pageflare/astro'

export default defineConfig({
  integrations: [
    starlight({ title: 'My Docs' }),
    pageflare()
  ]
})

Replacing integrations

pageflare replaces several Astro integrations and Vite plugins. After adding pageflare/astro, you can remove:

Package	pageflare equivalent
astro-compress / @playform/compress	HTML, CSS, JS, SVG, and image minification
astro-imagetools	Image optimization, responsive srcset, lazy loading
@astrojs/sitemap	Sitemap generation via llm.sitemap config
astro-critters / critters	Critical CSS extraction (Pro)
astro-prefetch	Speculation rules and preconnect hints

Tip

pageflare is a single binary — no extra node_modules. If you’re using multiple Astro integrations for compression, image handling, and performance hints, replacing them with one pageflare() integration simplifies your build and shrinks your dependency tree.

Deploying

The integration works with any deployment target. 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

Integration doesn’t run Make sure you’re running astro build, not astro dev. The integration only runs during production builds.

pageflare processes 0 files If the output directory is empty, check that your Astro config has output: 'static' (the default). Server-rendered (output: 'server') or hybrid modes generate server code, not static HTML.

Build takes too long For large sites (1000+ pages), pageflare may add noticeable build time. Use log: 'info' to see the per-phase timing breakdown. Adding --force skips incremental caching and can be faster for CI builds that always start clean.