0
# Build Function
1

2
The primary build functionality that handles framework detection, dependency installation, build execution, and output optimization for static sites and single-page applications.
3

4
## Capabilities
5

6
### Main Build Function
7

8
Executes the complete build process including framework detection, dependency installation, build command execution, and output optimization.
9

10
```typescript { .api }
11
/**
12
 * Primary build function for static sites and single-page applications
13
 * @param options - Build configuration and input files
14
 * @returns Promise resolving to build result with output files, routes, and images
15
 */
16
const build: BuildV2 = async ({
17
  files,
18
  entrypoint,
19
  workPath,
20
  config,
21
  meta = {},
22
}: BuildOptions): Promise<BuildResultV2>;
23

24
interface BuildOptions {
25
  /** Downloaded files from the deployment */
26
  files: Files;
27
  /** Entry point file (typically package.json or build.sh) */
28
  entrypoint: string;
29
  /** Working directory path for the build */
30
  workPath: string;
31
  /** The "Root Directory" is assigned to the workPath so the repoRootPath
32
   * is the Git Repository Root. This is only relevant for Monorepos. */
33
  repoRootPath: string;
34
  /** Build configuration options */
35
  config: Config;
36
  /** Optional build metadata */
37
  meta?: Meta;
38
}
39

40
type BuildResultV2 = BuildResultV2Typical | BuildResultBuildOutput;
41

42
interface BuildResultV2Typical {
43
  /** Route configuration for the deployment */
44
  routes?: Route[];
45
  /** Image optimization configuration */
46
  images?: Images;
47
  /** Static files and serverless functions */
48
  output: {
49
    [key: string]: File | Lambda | Prerender | EdgeFunction;
50
  };
51
  /** Wildcard configuration */
52
  wildcard?: Array<{
53
    domain: string;
54
    value: string;
55
  }>;
56
}
57

58
interface BuildResultBuildOutput {
59
  /** Build Output API version 3 */
60
  buildOutputVersion: 3;
61
  /** Build output directory path */
62
  buildOutputPath: string;
63
}
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
import { build } from "@vercel/static-build";
70
import type { Files, Config, FileFsRef, BuildV2 } from "@vercel/build-utils";
71

72
// Basic static site build
73
const result = await build({
74
  files: {
75
    "package.json": new FileFsRef({ fsPath: "./package.json" }),
76
    "src/index.html": new FileFsRef({ fsPath: "./src/index.html" }),
77
    "src/style.css": new FileFsRef({ fsPath: "./src/style.css" })
78
  },
79
  entrypoint: "package.json",
80
  workPath: "/build/workspace",
81
  repoRootPath: "/build/repo",
82
  config: {
83
    zeroConfig: true,
84
    outputDirectory: "dist"
85
  },
86
  meta: {
87
    isDev: false,
88
    cliVersion: "34.2.0"
89
  }
90
});
91

92
// Development mode with custom configuration
93
const devResult = await build({
94
  files: projectFiles,
95
  entrypoint: "package.json", 
96
  workPath: "/dev/workspace",
97
  repoRootPath: "/dev/repo",
98
  config: {
99
    zeroConfig: true,
100
    buildCommand: "npm run build:dev",
101
    devCommand: "npm run dev",
102
    framework: "nextjs"
103
  },
104
  meta: {
105
    isDev: true,
106
    skipDownload: true
107
  }
108
});
109
```
110

111
### Framework Detection
112

113
The build function automatically detects frameworks based on package.json dependencies and configuration files.
114

115
**Supported Frameworks:**
116
- Next.js, Create React App, Gatsby
117
- Vue.js, Nuxt.js, Vite
118
- Angular, Svelte, SvelteKit
119
- Static site generators (Hugo, Jekyll, etc.)
120
- And 40+ other frameworks
121

122
**Detection Process:**
123
1. Reads package.json dependencies and devDependencies
124
2. Matches against known framework dependency patterns
125
3. Falls back to manual framework specification in config
126
4. Applies framework-specific build optimizations
127

128
### Build Process Flow
129

130
1. **Download and Setup**: Downloads deployment files to working directory
131
2. **Framework Detection**: Identifies framework and applies optimizations
132
3. **Dependency Installation**: Installs npm, pip, bundler dependencies as needed
133
4. **Environment Setup**: Configures PATH, environment variables, and build tools
134
5. **Build Execution**: Runs build command (detected or configured)
135
6. **Output Processing**: Processes build output according to Build Output API version
136
7. **Route Generation**: Generates route configuration for framework
137
8. **Optimization**: Applies production optimizations and analytics injection
138

139
### Development Mode
140

141
When `meta.isDev` is true, the build function starts a development server instead of building static files.
142

143
**Development Features:**
144
- Hot reloading with automatic port detection
145
- Live proxy to development server
146
- Environment variable injection
147
- Framework-specific dev command execution
148

149
```typescript
150
// Development mode configuration
151
const devBuild = await build({
152
  files: {},
153
  entrypoint: "package.json",
154
  workPath: "./project",
155
  repoRootPath: "./",
156
  config: { 
157
    zeroConfig: true,
158
    devCommand: "npm run dev"
159
  },
160
  meta: { 
161
    isDev: true 
162
  }
163
});
164

165
// Returns route configuration proxying to dev server
166
console.log(devBuild.routes); // [{ src: '/(.*)', dest: 'http://localhost:3000/$1' }]
167
```
168

169
### Error Handling
170

171
The build function throws specific errors for common failure scenarios:
172

173
- **STATIC_BUILD_NO_OUT_DIR**: Output directory missing after build
174
- **STATIC_BUILD_NOT_A_DIR**: Output directory is not a directory  
175
- **STATIC_BUILD_EMPTY_OUT_DIR**: Output directory is empty
176
- **STATIC_BUILD_BINARY_NOT_FOUND**: Framework binary version not found
177

178
### Build Configuration Options
179

180
```typescript { .api }
181
interface Config {
182
  /** Enable zero-configuration build mode */
183
  zeroConfig?: boolean;
184
  /** Legacy output directory path (use outputDirectory instead) */
185
  distDir?: string;
186
  /** Output directory (newer alias for distDir) */
187
  outputDirectory?: string;
188
  /** Custom build command */
189
  buildCommand?: string;
190
  /** Custom development command */
191
  devCommand?: string;
192
  /** Custom install command */
193
  installCommand?: string;
194
  /** Framework override */
195
  framework?: string;
196
}
197
```
198

199
### Meta Options
200

201
```typescript { .api }
202
interface Meta {
203
  /** Enable development mode */
204
  isDev?: boolean;
205
  /** Skip file download (for local development) */
206
  skipDownload?: boolean;
207
  /** Vercel CLI version */
208
  cliVersion?: string;
209
  /** Unique build identifier */
210
  buildId?: string;
211
  /** Avoid top-level npm install in monorepos */
212
  avoidTopLevelInstall?: boolean;
213
  /** Development cache directory */
214
  devCacheDir?: string;
215
  /** Request path for the build */
216
  requestPath?: string;
217
  /** Files that have changed */
218
  filesChanged?: string[];
219
  /** Files that have been removed */
220
  filesRemoved?: string[];
221
  /** Environment variables */
222
  env?: Record<string, string>;
223
  /** Build environment variables */
224
  buildEnv?: Record<string, string>;
225
}
226
```