Vercel Build Output API for Custom SSGs

Vercel is best known for Next.js, and its framework detection makes deploying popular generators almost automatic. The layer underneath the detection is less known and more useful for static sites: the Build Output API, a documented directory format (.vercel/output/) that describes exactly what to deploy — static files, routes, headers, redirects, caching and optional functions. Any build process that writes that format can be deployed with vercel deploy --prebuilt, whether the site is built with Zola, a custom Python script, Hugo with an unusual pipeline, or an Eleventy setup that Vercel's preset gets slightly wrong.

This guide writes a Build Output directory for a static documentation site built with a custom pipeline (Eleventy plus a Python API reference generator), defines headers, redirects and caching precisely, adds one edge function, builds in GitHub Actions and deploys the result. It is part of Netlify vs Vercel Deployment Strategies, and complements Configuring Vercel for Hugo and Eleventy.

Prerequisites

• A static build that produces a directory of files (here _site/).
• The Vercel CLI and a project linked with vercel link, plus a token for CI.
• The site's redirect and header rules in a data file.

The Directory Structure

.vercel/output/
  config.json            # version, routes (headers, redirects, rewrites), overrides
  static/                # every static file, served as-is
    index.html
    guide/install/index.html
    assets/app.3f9a1c2e.js
  functions/             # optional
    api/region.func/
      .vc-config.json
      index.js

Everything in static/ is served from Vercel's edge; config.json decides how requests map to files and functions and what headers they get. There is no vercel.json involved and no framework detection.

Step 1: Write Static Files and Config From the Build

A post-build script copies the site into static/ and generates config.json from the redirect and header data used by every host:

// scripts/vercel-output.mjs
import { cp, mkdir, writeFile, readFile } from 'node:fs/promises';
import yaml from 'yaml';
await mkdir('.vercel/output/static', { recursive: true });
await cp('_site', '.vercel/output/static', { recursive: true });
const redirects = yaml.parse(await readFile('data/redirects.yaml', 'utf8'));
const routes = [
  // 1. redirects first, so old URLs never touch the filesystem
  ...redirects.map((r) => ({ src: toRegex(r.from), status: r.status, headers: { Location: r.to } })),
  // 2. headers for everything, continue matching
  { src: '/assets/(.*)', headers: { 'Cache-Control': 'public, max-age=31536000, immutable' }, continue: true },
  { src: '/(.*)', headers: { 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'strict-origin-when-cross-origin',
      'Strict-Transport-Security': 'max-age=31536000; includeSubDomains' }, continue: true },
  // 3. serve static files
  { handle: 'filesystem' },
  // 4. edge function for one API path
  { src: '/api/region', dest: '/api/region' },
  // 5. anything else: the 404 page with a 404 status
  { src: '/(.*)', status: 404, dest: '/404.html' }
];
await writeFile('.vercel/output/config.json', JSON.stringify({ version: 3, routes, trailingSlash: true }, null, 2));

Route order is explicit: redirects run before the filesystem check, headers apply with continue: true so matching continues, handle: 'filesystem' serves any matching static file, and the final route turns misses into a real 404. That last route fixed a bug from the preset-based deploy, where missing pages returned the 404 page with a 200 status.

Step 2: Cache Control for HTML

Vercel's edge caches static files and serves HTML with a default that revalidates. For documentation, HTML was given a short shared cache with stale-while-revalidate, as in Stale-While-Revalidate for Static HTML:

{ src: '/(.*)/', headers: { 'Cache-Control': 'public, max-age=0, s-maxage=300, stale-while-revalidate=86400' }, continue: true }

Vercel purges its edge cache for a project on every production deploy, so the short s-maxage never serves old HTML after a deploy.

Step 3: One Edge Function

The site needed a tiny endpoint returning the reader's region for a data-residency notice. An edge function in the Build Output format:

// .vercel/output/functions/api/region.func/.vc-config.json
{ "runtime": "edge", "entrypoint": "index.js" }

// .vercel/output/functions/api/region.func/index.js
export default function handler(request) {
  const country = request.headers.get('x-vercel-ip-country') ?? 'unknown';
  return new Response(JSON.stringify({ country }), {
    headers: { 'Content-Type': 'application/json', 'Cache-Control': 'private, no-store' }
  });
}

Only /api/region invokes it, because only that route points at it. Every page remains a static file.

Step 4: Build in CI, Deploy the Output

Building in GitHub Actions gives full control of the build environment and caching, and vercel deploy --prebuilt uploads the finished output:

- run: npm ci && npm run build && python3 tools/api_ref.py && node scripts/vercel-output.mjs
- run: npx vercel pull --yes --environment=${{ github.ref == 'refs/heads/main' && 'production' || 'preview' }} --token=$VERCEL_TOKEN
- run: npx vercel deploy --prebuilt ${{ github.ref == 'refs/heads/main' && '--prod' || '' }} --token=$VERCEL_TOKEN > url.txt
  env: { VERCEL_TOKEN: '${{ secrets.VERCEL_TOKEN }}', VERCEL_ORG_ID: '${{ secrets.VERCEL_ORG_ID }}', VERCEL_PROJECT_ID: '${{ secrets.VERCEL_PROJECT_ID }}' }

Pull requests get preview deployments with their own URLs, exactly as with Vercel's Git integration; the URL in url.txt is commented on the pull request. The Python API reference generator, which Vercel's build image did not support at the needed version, now runs in the Actions environment.

Testing the Output Before Deploy

Because the whole deployment is described by files, it can be tested before upload. vercel dev does not use .vercel/output directly, so the team tests two ways. A unit test loads config.json and checks invariants: every redirect source is unique, no redirect target is itself a redirect source (no chains), every dest in a route exists in static/ or functions/, and the final route is the 404 fallback. And the header and redirect table from Testing Redirects and Headers Before Deploy runs against each preview deployment URL. The unit test caught a redirect loop introduced by a data-file edit before it was ever deployed.

Portability Across Hosts

Generating host configuration from shared data pays off beyond Vercel. The same redirects.yaml and header definitions also produce a _redirects and _headers pair for a Netlify mirror and a Caddy import file for the self-hosted internal copy of the docs, each from a small writer function. When the team evaluated moving the site between hosts, the build already emitted every format; switching was a change to the deploy step, not a rewrite of routing rules. It also made differences between hosts visible: Vercel's route patterns are regular expressions while Netlify's use splats and placeholders, and the writer functions are where those differences are handled — once, with tests — rather than in hand-edited files that drift apart.

The Build Output API also makes it easy to inspect exactly what will be deployed. Before each production deploy, the workflow prints a summary of the output — number of static files, total size, route count, functions — into the job summary, which is where an unexpected change (a doubled file count, a missing redirect block) shows up before it goes live.

Measured Impact

Pitfalls & Rollback

• Route order mistakes. Headers without continue: true stop matching; redirects after filesystem never run for existing paths.
• Forgetting the 404 status. A catch-all rewrite to 404.html without status: 404 creates soft 404s.
• Mixing vercel.json and prebuilt output. With --prebuilt, the output's config.json is authoritative; keep one source.
• Missing vercel pull. Prebuilt deploys need the project settings pulled first.
• Rollback: Vercel keeps previous deployments; vercel rollback or promoting an older deployment restores the previous version instantly.

Conclusion

The Build Output API turns Vercel into a precise static host for any generator: write the files to static/, describe routing, headers and caching in config.json, add a function only where needed, and deploy the prebuilt directory from your own CI. For this site it replaced implicit preset behaviour with a generated, tested configuration, fixed soft 404s and let the build use tools Vercel's image did not provide.

FAQ

What is the Vercel Build Output API?

A documented directory structure, .vercel/output, that describes a deployment: static files, routing configuration, and optional serverless or edge functions. Anything that writes this structure can be deployed to Vercel with vercel deploy --prebuilt, without Vercel knowing the generator.

When do I need it instead of Vercel's framework presets?

When the generator has no preset, such as a custom build script, Zola or a less common SSG, or when you want exact control over routes, headers and caching that presets configure implicitly. It is also useful for building in your own CI and uploading only the result.

How are headers and redirects defined?

In the routes array of .vercel/output/config.json, with src patterns, headers, status codes and destinations, processed in order. There are also handle phases such as filesystem to control whether routes run before or after static files are matched.

Can I add an edge function without a framework?

Yes. Create a directory under .vercel/output/functions with a .vc-config.json declaring the edge runtime and an entrypoint file, and route requests to it from config.json. The function receives standard Request objects and returns Responses.

Related

• Parent: Netlify vs Vercel Deployment Strategies — the two platforms compared.
• Vercel ISR vs Static Generation for SSGs — when static is the right choice.
• Netlify Edge Functions for Static Sites — the Netlify equivalent of edge logic.
• Build Caching on Netlify and Vercel — caching when building on the platform.
• Keeping Redirects Working After an SSG Migration — the redirect data file.