TemperStack
Find Tools
Intermediate8 min readUpdated Mar 18, 2026

How to use build output api on Vercel

Quick Answer

The Vercel Build Output API allows you to define custom build outputs through a standardized directory structure and configuration files. You create a .vercel/output directory with static files, serverless functions, and configuration to control how Vercel serves your application.

Prerequisites

  1. Basic knowledge of Node.js and deployment concepts
  2. Vercel account and CLI installed
  3. Understanding of build processes and static file generation
  4. Familiarity with JSON configuration files
1

Create the Build Output Directory Structure

Create a .vercel/output directory in your project root. Inside this directory, create three subdirectories: static for static assets, functions for serverless functions, and config.json for routing configuration.

mkdir -p .vercel/output/static
mkdir -p .vercel/output/functions
touch .vercel/output/config.json
Tip
The .vercel/output directory structure must follow Vercel's exact specification for proper deployment.
2

Configure the Routes in config.json

Create your config.json file to define routing rules. Specify version as 3, and define routes array with patterns and destinations:

{
  "version": 3,
  "routes": [
    { "src": "/api/(.*)", "dest": "/api/$1" },
    { "src": "/(.*)", "dest": "/static/$1" }
  ]
}
Tip
Routes are processed in order, so place more specific patterns before general ones.
3

Add Static Files to the Static Directory

Place your static assets (HTML, CSS, JS, images) in the .vercel/output/static directory. These files will be served directly by Vercel's CDN:

cp -r dist/* .vercel/output/static/
# or
cp index.html .vercel/output/static/
cp -r assets/ .vercel/output/static/
Tip
Static files in this directory are automatically cached and served from Vercel's global CDN.
4

Create Serverless Functions

For serverless functions, create subdirectories in .vercel/output/functions. Each function needs an index.js file and a .vc-config.json configuration:

mkdir .vercel/output/functions/api
echo '{ "runtime": "nodejs18.x" }' > .vercel/output/functions/api/.vc-config.json

Create your function in .vercel/output/functions/api/index.js.
Tip
Each function directory represents an API endpoint and must include the .vc-config.json file.
5

Write Function Code

In your function's index.js file, export a default function that handles the request and response:

export default function handler(request, response) {
  response.status(200).json({
    message: 'Hello from Build Output API',
    method: request.method
  });
}
Tip
Functions receive standard Request/Response objects compatible with Vercel's runtime.
6

Set Build Command to Generate Output

Update your vercel.json or package.json build script to generate the .vercel/output structure. Set buildCommand to null if using custom build:

{
  "buildCommand": null,
  "outputDirectory": ".vercel/output"
}
Tip
Setting buildCommand to null tells Vercel to use your pre-built output directory instead of running a build process.
7

Deploy Using Vercel CLI

Deploy your project using the Vercel CLI. The CLI will detect the .vercel/output directory and use the Build Output API:

vercel deploy
# or for production
vercel deploy --prod

Monitor the deployment logs in your Vercel Dashboard under the Deployments tab.
Tip
Use vercel deploy --debug for verbose output if you encounter issues during deployment.

Troubleshooting

Functions not found or 404 errors
Verify that each function directory contains both index.js and .vc-config.json files. Check that your routes in config.json correctly map to function paths.
Static files not serving correctly
Ensure static files are placed in .vercel/output/static directory and routes in config.json include patterns to serve static content. Check file permissions and paths.
Build output not recognized by Vercel
Confirm the directory structure follows .vercel/output/ exactly. Verify config.json has version: 3 and valid JSON syntax. Check that outputDirectory is set correctly.
Function runtime errors
Check the .vc-config.json specifies the correct runtime version (e.g., nodejs18.x). Verify function exports use correct syntax and handle request/response properly.

Related Guides

More Vercel Tutorials

How to deploy Next.js app

How to deploy Astro site

How to set up custom domain

How to configure environment variables

Other Tool Tutorials

N

Netlify Tutorials

Ready to get started with Vercel?

Put this tutorial into practice. Visit Vercel and follow the steps above.

Visit Vercel →