0
# Build Output Processing
1

2
Support for different Build Output API versions (v1, v2, v3) with automatic detection and processing of static files, serverless functions, middleware, and deployment configuration.
3

4
## Constants
5

6
Each Build Output API version uses specific directory names and configuration files:
7

8
```typescript { .api }
9
// Build Output V1 Constants
10
const VERCEL_BUILD_OUTPUT = '.vercel_build_output';
11

12
// Build Output V2 Constants  
13
const BUILD_OUTPUT_DIR = '.output';
14
const CONFIG_FILES = [
15
  'build-manifest.json',
16
  'functions-manifest.json', 
17
  'images-manifest.json',
18
  'prerender-manifest.json',
19
  'routes-manifest.json'
20
];
21

22
// Build Output V3 Constants
23
const BUILD_OUTPUT_DIR = '.vercel/output';
24
const CONFIG_FILE = 'config.json';
25
```
26

27
## Capabilities
28

29
### Build Output API v3
30

31
The latest Build Output API that provides the most comprehensive deployment configuration through `.vercel/output` directory structure.
32

33
```typescript { .api }
34
/**
35
 * Detects Build Output API v3 directory by config.json presence
36
 * @param path - Working directory path
37
 * @returns Path to build output directory or undefined
38
 */
39
function getBuildOutputDirectory(path: string): Promise<string | undefined>;
40

41
/**
42
 * Reads v3 configuration file
43
 * @param path - Working directory path  
44
 * @returns Configuration object with cache settings
45
 */
46
function readConfig(path: string): Promise<any | undefined>;
47

48
/**
49
 * Creates v3 build output result, throws error in dev mode
50
 * @param meta - Build metadata
51
 * @param buildCommand - Build command used
52
 * @param buildOutputPath - Path to build output directory
53
 * @param framework - Detected framework
54
 * @returns Build result with v3 format
55
 */
56
function createBuildOutput(
57
  meta: Meta,
58
  buildCommand: string | null,
59
  buildOutputPath: string,
60
  framework?: Framework
61
): Promise<{\n  buildOutputVersion: 3;\n  buildOutputPath: string;\n}>;
62
```
63

64
**Usage Examples:**
65

66
```typescript
67
import * as BuildOutputV3 from "@vercel/static-build/utils/build-output-v3";
68
import { join } from 'path';
69
import { promises as fs } from 'fs';
70
import { BuildResultV2, Meta } from '@vercel/build-utils';
71
import { Framework } from '@vercel/frameworks';
72

73
// Detect v3 build output
74
const outputDir = await BuildOutputV3.getBuildOutputDirectory("/project");
75
if (outputDir) {
76
  console.log("Found Build Output v3 at:", outputDir);
77
  
78
  // Read configuration
79
  const config = await BuildOutputV3.readConfig("/project");
80
  console.log("Cache patterns:", config?.cache);
81
  
82
  // Create build result
83
  const result = BuildOutputV3.createBuildOutput(
84
    { isDev: false },
85
    "npm run build",
86
    outputDir
87
  );
88
}
89
```
90

91
**V3 Directory Structure:**
92
```
93
.vercel/output/
94
├── config.json          # Global configuration
95
├── static/              # Static files
96
├── functions/           # Serverless functions
97
└── ...
98
```
99

100
### Build Output API v2
101

102
Intermediate Build Output API using `.output` directory with manifest-based configuration.
103

104
```typescript { .api }
105
/**
106
 * Detects Build Output API v2 directory by manifest files
107
 * @param workingDir - Working directory path
108
 * @returns Path to build output directory or undefined
109
 */
110
function getBuildOutputDirectory(workPath: string): Promise<string | undefined>;
111

112
/**
113
 * Reads the BUILD_OUTPUT_DIR directory for middleware and static files
114
 * @param workPath - Working directory path
115
 * @returns Object with staticFiles, functions, and routes
116
 */
117
function readBuildOutputDirectory(options: { workPath: string }): Promise<{
118
  staticFiles: Files | null;
119
  functions: Record<string, EdgeFunction> | null;
120
  routes: Route[] | null;
121
}>;
122

123
/**
124
 * Creates v2 build output result from .output directory
125
 * @param workPath - Working directory path
126
 * @returns Build result with processed files and routes
127
 */
128
function createBuildOutput(workPath: string): Promise<BuildResultV2>;
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
import * as BuildOutputV2 from "@vercel/static-build/utils/build-output-v2";
135
import { pathExists, readJson, appendFile } from 'fs-extra';
136
import { Route } from '@vercel/routing-utils';
137
import { Files, FileFsRef, EdgeFunction, BuildResultV2 } from '@vercel/build-utils';
138

139
// Detect and process v2 build output
140
const outputDir = await BuildOutputV2.getBuildOutputDirectory("/project");
141
if (outputDir) {
142
  const result = await BuildOutputV2.createBuildOutput("/project");
143
  
144
  console.log("Static files:", Object.keys(result.output));
145
  console.log("Routes:", result.routes);
146
}
147
```
148

149
**V2 Directory Structure:**
150
```
151
.output/
152
├── build-manifest.json      # Build configuration
153
├── functions-manifest.json  # Function definitions
154
├── images-manifest.json     # Image optimization
155
├── prerender-manifest.json  # Pre-rendered routes
156
├── routes-manifest.json     # Route configuration
157
├── static/                  # Static assets
158
└── server/                  # Server functions
159
```
160

161
**V2 Configuration Files:**
162
- `build-manifest.json`: Build metadata and settings
163
- `functions-manifest.json`: Serverless function definitions
164
- `images-manifest.json`: Image optimization configuration
165
- `prerender-manifest.json`: Pre-rendered page definitions
166
- `routes-manifest.json`: Dynamic route configuration
167

168
### Build Output API v1
169

170
Legacy Build Output API using `.vercel_build_output` directory structure.
171

172
```typescript { .api }
173
/**
174
 * Reads .vercel_build_output directory and returns processed outputs
175
 * @param options - Configuration with workPath and nodeVersion
176
 * @returns Build outputs with static files, functions, routes, images, and build config
177
 */
178
function readBuildOutputDirectory(options: {
179
  workPath: string;
180
  nodeVersion: NodeVersion;
181
}): Promise<BuildOutputV1Result>;
182

183
/**
184
 * Generic config file reader for build output
185
 * @param options - Configuration with workPath and config filename
186
 * @returns Parsed configuration object
187
 */
188
function readBuildOutputConfig<Config>(options: {
189
  workPath: string;
190
  configFileName: string;
191
}): Promise<Config | undefined>;
192

193
interface BuildOutputV1Result {
194
  staticFiles: Files | null;
195
  functions: Record<string, Lambda> | null;
196
  routes: Route[] | null;
197
  images: ImagesConfig | null;
198
  build: BuildConfig | null;
199
}
200
```
201

202
**Usage Examples:**
203

204
```typescript
205
import * as BuildOutputV1 from "@vercel/static-build/utils/build-output-v1";
206
import { Files, Lambda, NodeVersion } from '@vercel/build-utils';
207
import { Route } from '@vercel/routing-utils';
208
import { BuildConfig, ImagesConfig } from './_shared';
209

210
// Process v1 build output
211
const result = await BuildOutputV1.readBuildOutputDirectory({
212
  workPath: "/project",
213
  nodeVersion: { major: 18, range: "18.x", runtime: "nodejs18.x" }
214
});
215

216
if (result.staticFiles) {
217
  console.log("Static files found");
218
}
219

220
if (result.functions) {
221
  console.log("Serverless functions:", Object.keys(result.functions));
222
}
223

224
// Read specific configuration
225
const routes = await BuildOutputV1.readBuildOutputConfig<Route[]>({
226
  workPath: "/project",
227
  configFileName: "routes.json"
228
});
229
```
230

231
**V1 Directory Structure:**
232
```
233
.vercel_build_output/
234
├── config/
235
│   ├── build.json     # Build configuration
236
│   ├── routes.json    # Route definitions
237
│   └── images.json    # Image settings
238
├── static/            # Static files
239
└── functions/         # Serverless functions
240
    └── node/          # Node.js functions (legacy)
241
```
242

243
### Build Output Detection Flow
244

245
The build function automatically detects and processes build output in priority order:
246

247
1. **Check for Build Output v3**: Look for `.vercel/output/config.json`
248
2. **Check for Build Output v2**: Look for `.output/` with manifest files
249
3. **Check for Build Output v1**: Look for `.vercel_build_output/` directory
250
4. **Fall back to traditional**: Process `dist` or configured output directory
251

252
```typescript
253
// Detection flow in build function
254
const buildOutputPathV3 = await BuildOutputV3.getBuildOutputDirectory(outputDirPrefix);
255
if (buildOutputPathV3) {
256
  return BuildOutputV3.createBuildOutput(meta, buildCommand, buildOutputPathV3, framework);
257
}
258

259
const buildOutputPathV2 = await BuildOutputV2.getBuildOutputDirectory(outputDirPrefix);
260
if (buildOutputPathV2) {
261
  return await BuildOutputV2.createBuildOutput(workPath);
262
}
263

264
const extraOutputs = await BuildOutputV1.readBuildOutputDirectory({
265
  workPath,
266
  nodeVersion,
267
});
268
```
269

270
### Serverless Functions Processing
271

272
All Build Output APIs support serverless functions with different configuration approaches:
273

274
**V3 Functions**: Configured in individual function directories
275
**V2 Functions**: Defined in `functions-manifest.json`
276
**V1 Functions**: Configured in `config/functions.json`
277

278
```typescript { .api }
279
interface FunctionConfig {
280
  memory?: number;
281
  maxDuration?: number;
282
  runtime?: string;
283
  handler?: string;
284
  regions?: string[];
285
}
286
```
287

288
### Middleware Support
289

290
Build Output APIs v2 and v3 support Edge middleware:
291

292
```typescript { .api }
293
interface EdgeFunction {
294
  deploymentTarget: 'v8-worker';
295
  entrypoint: string;
296
  files: Files;
297
  name: string;
298
}
299
```
300

301
**Middleware Route Configuration:**
302
```typescript
303
const middlewareRoute = {
304
  src: '/(.*)',
305
  middlewarePath: 'middleware',
306
  continue: true
307
};
308
```
309

310
### Image Optimization Configuration
311

312
All Build Output APIs support image optimization settings:
313

314
```typescript { .api }
315
interface ImagesConfig {
316
  domains: string[];
317
  sizes: number[];
318
}
319
```
320

321
**Example image configuration:**
322
```json
323
{
324
  "domains": ["example.com", "cdn.example.com"],
325
  "sizes": [640, 750, 828, 1080, 1200, 1920, 2048, 3840]
326
}
327
```