Vercel

Vercel runs your build command in a managed environment and then deploys the output to its edge network. Pageflare slots in as a post-build step via a build command override in vercel.json.

How It Works

Vercel exposes a buildCommand field in vercel.json that overrides whatever build script is in your package.json. Set it to run your normal build followed by pageflare:

vercel.json

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

When pageflare detects a vercel.json file in the project root it automatically activates the platform_images feature, which routes image references through Vercel’s own image optimization pipeline instead of processing them locally. This gives you the best of both worlds: pageflare handles HTML, CSS, JS, and font optimizations, while Vercel handles image delivery and resizing.

Step 1 — Add Your License as a Secret

1. Go to your project in the Vercel dashboard.
2. Navigate to Settings > Environment Variables.
3. Add a variable named PAGEFLARE_LICENSE with your license key.
4. Set the Environment to Production (and optionally Preview).
5. Save.

Tip

Vercel automatically encrypts environment variables — you do not need to take any extra steps to protect the value.

Step 2 — Install pageflare in the Build

Add pageflare as a dev dependency so Vercel installs it automatically:

npm install --save-dev @pageflare/cli

Or install it globally in the build command:

vercel.json

{
  "buildCommand": "npm install -g @pageflare/cli && npm run build && pageflare .vercel/output/static --in-place --no-progress"
}

Step 3 — Configure vercel.json

A minimal vercel.json that enables pageflare:

vercel.json

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

With framework preset

If your project uses a Vercel framework preset (e.g., Astro, Next.js static export), the output directory differs:

Framework	Output directory
Astro	.vercel/output/static
Next.js static export	out/ (before Vercel restructures it)
Hugo	public/
Eleventy	_site/

For most Vercel-native deployments, .vercel/output/static is correct. Check your framework’s Vercel adapter documentation if unsure.

Full vercel.json example

vercel.json

{
  "buildCommand": "npm run build && pageflare .vercel/output/static --in-place --no-progress",
  "framework": "astro",
  "regions": ["iad1"]
}

Step 4 — Platform Images Feature

When pageflare detects vercel.json in the project root, it automatically enables platform_images. This means:

• Local <img> src attributes pointing to static assets are rewritten to use Vercel’s Image Optimization API (/_vercel/image?url=...&w=...&q=...).
• Pageflare still infers missing width and height attributes from the source images to prevent layout shift.
• Vercel handles format conversion (WebP/AVIF), resizing, and CDN caching — you do not need to configure anything extra.

Note

platform_images only applies when vercel.json exists at the project root. You can also force it explicitly in pageflare.jsonc:

pageflare.jsonc

{
  "platform_images": true
}

Step 5 — Verify the Deployment

After deploying, open the Vercel Deployment view and expand the Build Logs. Look for the pageflare summary near the end:

  Done  145.2 KB saved (38.1%)  1.2s
  Files  42 total, 38 optimized, 4 unchanged, 0 errors

Verify image optimization is active by inspecting an image URL in the deployed site — URLs should include /_vercel/image?url= when platform_images is working.

Environment Variable Reference

Variable	Description
PAGEFLARE_LICENSE	Pro license key. Set in Vercel project settings.

pageflare.jsonc for Vercel Projects

pageflare.jsonc

{
  "minify_html": true,
  "minify_css": true,
  "minify_js": true,
  "js_defer": true,
  "lazy_images": true,
  "img_dimensions": true,
  "font_swap": true
  // platform_images is auto-detected from vercel.json
}

Troubleshooting

pageflare processes 0 files The output path in the build command does not match where your framework writes its output. For Vercel’s file system output API, files land in .vercel/output/static/. If you are running pageflare before the framework adapter moves files, try pointing at the framework’s native output directory instead (e.g., dist/).

Images are not rewritten to Vercel URLs Confirm vercel.json exists in the repository root (not a subdirectory). If using a monorepo, ensure the Vercel project root is set to the directory containing vercel.json.

Build time out If your site has thousands of images, platform_images rewriting can slow the build. Disable it and manage Vercel image URLs manually, or increase your Vercel plan’s build timeout.