0
# Vercel Static Build
1
2
Vercel Static Build is a comprehensive build runtime for Vercel that automatically detects frontend frameworks and builds static websites and single-page applications with zero configuration. It supports automatic framework detection for popular tools like Next.js, React, Vue, Angular, and static site generators, handles dependency installation across multiple package managers, executes build commands with proper environment setup, and optimizes output for production deployment.
3
4
## Package Information
5
6
- **Package Name**: @vercel/static-build
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: This package is typically used as a Vercel build runtime, not directly installed in user projects
10
11
## Core Imports
12
13
```typescript
14
import { build, prepareCache, version } from "@vercel/static-build";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { build, prepareCache, version } = require("@vercel/static-build");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { build, prepareCache, version } from "@vercel/static-build";
27
import type { Files, Config, Meta, BuildV2, PrepareCache } from "@vercel/build-utils";
28
29
// Primary build function for static sites and SPAs
30
const buildResult = await build({
31
files: downloadedFiles, // Files from deployment
32
entrypoint: "package.json", // Entry point file
33
workPath: "/build/workspace", // Working directory
34
repoRootPath: "/build/repo", // Repository root path
35
config: { // Build configuration
36
zeroConfig: true,
37
outputDirectory: "dist"
38
},
39
meta: { // Build metadata
40
isDev: false,
41
skipDownload: false,
42
cliVersion: "34.2.0"
43
}
44
});
45
46
// Result contains optimized files, routes, and images
47
console.log(buildResult.output); // Static files and serverless functions
48
console.log(buildResult.routes); // Route configuration
49
console.log(buildResult.images); // Image optimization config
50
```
51
52
## Architecture
53
54
Vercel Static Build is designed around several key components:
55
56
- **Framework Detection**: Automatic detection of 50+ frontend frameworks using package.json dependencies
57
- **Zero Configuration**: Intelligent defaults for build commands, output directories, and deployment optimization
58
- **Multi-Language Support**: Handles JavaScript/TypeScript, Python, Ruby, and Go-based static site generators
59
- **Build Output APIs**: Supports v1, v2, and v3 Build Output APIs for different deployment targets
60
- **Development Mode**: Integrated dev server support with hot reloading and port management
61
- **Caching Strategy**: Intelligent caching for dependencies, build artifacts, and framework-specific assets
62
63
## Capabilities
64
65
### Primary Build Function
66
67
Core build functionality that handles framework detection, dependency installation, build execution, and output optimization for static sites and single-page applications.
68
69
```typescript { .api }
70
const build: BuildV2 = async ({
71
files,
72
entrypoint,
73
workPath,
74
repoRootPath,
75
config,
76
meta = {},
77
}: BuildOptions): Promise<BuildResultV2>;
78
79
interface BuildOptions {
80
files: Files;
81
entrypoint: string;
82
workPath: string;
83
repoRootPath: string;
84
config: Config;
85
meta?: Meta;
86
}
87
88
type BuildResultV2 = BuildResultV2Typical | BuildResultBuildOutput;
89
90
interface BuildResultV2Typical {
91
output: Files;
92
routes?: Route[];
93
images?: Images;
94
wildcard?: Array<{ domain: string; value: string; }>;
95
}
96
97
interface BuildResultBuildOutput {
98
buildOutputVersion: 3;
99
buildOutputPath: string;
100
}
101
```
102
103
[Build Function](./build-function.md)
104
105
### Cache Management
106
107
Cache preparation functionality for optimizing build performance across deployments with framework-specific caching strategies.
108
109
```typescript { .api }
110
function prepareCache(options: PrepareCacheOptions): Promise<Files>;
111
112
interface PrepareCacheOptions {
113
files: Files;
114
entrypoint: string;
115
repoRootPath: string;
116
workPath: string;
117
config: Config;
118
}
119
```
120
121
[Cache Management](./cache-management.md)
122
123
### Build Output Processing
124
125
Support for different Build Output API versions (v1, v2, v3) with automatic detection and processing of static files, serverless functions, and middleware.
126
127
```typescript { .api }
128
// Build Output V1
129
function readBuildOutputDirectory(options: {
130
workPath: string;
131
nodeVersion: NodeVersion;
132
}): Promise<BuildOutputV1Result>;
133
134
// Build Output V2
135
function getBuildOutputDirectory(workingDir: string): Promise<string | undefined>;
136
function createBuildOutput(workPath: string): Promise<BuildResultV2>;
137
138
// Build Output V3
139
function getBuildOutputDirectory(path: string): Promise<string | undefined>;
140
function readConfig(path: string): Promise<{ cache?: string[] } | undefined>;
141
```
142
143
[Build Output Processing](./build-output.md)
144
145
### Framework Integration
146
147
Specialized utilities for framework-specific optimizations including analytics plugin injection for Gatsby and Nuxt.js applications.
148
149
```typescript { .api }
150
// Gatsby utilities
151
function injectVercelAnalyticsPlugin(dir: string): Promise<void>;
152
153
// Nuxt utilities
154
function injectVercelAnalyticsPlugin(dir: string): Promise<void>;
155
```
156
157
[Framework Integration](./framework-integration.md)
158
159
## Core Types
160
161
```typescript { .api }
162
interface Config {
163
zeroConfig?: boolean;
164
distDir?: string;
165
outputDirectory?: string;
166
buildCommand?: string;
167
devCommand?: string;
168
installCommand?: string;
169
framework?: string;
170
}
171
172
interface Meta {
173
isDev?: boolean;
174
skipDownload?: boolean;
175
cliVersion?: string;
176
buildId?: string;
177
}
178
179
interface Files {
180
[filePath: string]: FileFsRef | FileBlob | Lambda | EdgeFunction;
181
}
182
183
// File system reference for static files
184
interface FileFsRef {
185
fsPath: string;
186
contentType?: string;
187
}
188
189
// Binary file blob for in-memory files
190
interface FileBlob {
191
data: Buffer;
192
contentType?: string;
193
}
194
195
// Serverless function configuration
196
interface Lambda {
197
files: Files;
198
handler: string;
199
runtime: string;
200
memory?: number;
201
maxDuration?: number;
202
regions?: string[];
203
}
204
205
// Edge function configuration
206
interface EdgeFunction {
207
deploymentTarget: 'v8-worker';
208
entrypoint: string;
209
files: Files;
210
name: string;
211
}
212
213
interface Route {
214
src: string;
215
dest?: string;
216
headers?: { [key: string]: string };
217
methods?: string[];
218
status?: number;
219
continue?: boolean;
220
middlewarePath?: string;
221
}
222
223
interface ImagesConfig {
224
domains: string[];
225
sizes: number[];
226
}
227
228
interface NodeVersion {
229
major: number;
230
range: string;
231
runtime: string;
232
}
233
234
interface BuildOutputV1Result {
235
staticFiles: Files | null;
236
functions: Record<string, Lambda> | null;
237
routes: Route[] | null;
238
images: ImagesConfig | null;
239
build: BuildConfig | null;
240
}
241
242
interface BuildResultV2 {
243
output: Files;
244
routes?: Route[];
245
images?: ImagesConfig;
246
buildOutputVersion?: number;
247
buildOutputPath?: string;
248
}
249
250
interface BuildConfig {
251
cache: string[];
252
}
253
254
const version: 2;
255
```