0
# @vercel/build-utils
1
2
@vercel/build-utils is a comprehensive TypeScript library providing essential build utilities for the Vercel platform. It serves as the foundation for creating custom builders and managing serverless functions, offering file system operations, Lambda function creation and management, process execution utilities, and framework detection capabilities.
3
4
## Package Information
5
6
- **Package Name**: @vercel/build-utils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vercel/build-utils`
10
- **Version**: 2.7.0
11
- **License**: MIT
12
13
## Core Imports
14
15
```typescript
16
import {
17
FileBlob,
18
FileFsRef,
19
FileRef,
20
Lambda,
21
createLambda,
22
Prerender,
23
download,
24
glob,
25
getWriteableDirectory,
26
rename,
27
streamToBuffer,
28
readConfigFile,
29
spawnAsync,
30
execAsync,
31
spawnCommand,
32
execCommand,
33
installDependencies,
34
runNpmInstall,
35
runPackageJsonScript,
36
walkParentDirs,
37
getNodeVersion,
38
getNodeBinPath,
39
detectBuilders,
40
detectOutputDirectory,
41
detectApiDirectory,
42
detectFramework,
43
DetectorFilesystem,
44
isOfficialRuntime,
45
isStaticRuntime,
46
getPlatformEnv,
47
shouldServe,
48
debug,
49
NowBuildError
50
} from "@vercel/build-utils";
51
```
52
53
For CommonJS:
54
55
```javascript
56
const {
57
FileBlob,
58
FileFsRef,
59
FileRef,
60
Lambda,
61
createLambda,
62
Prerender,
63
download,
64
glob,
65
getWriteableDirectory,
66
rename,
67
streamToBuffer,
68
readConfigFile,
69
spawnAsync,
70
execAsync,
71
spawnCommand,
72
execCommand,
73
installDependencies,
74
runNpmInstall,
75
runPackageJsonScript,
76
walkParentDirs,
77
getNodeVersion,
78
getNodeBinPath,
79
detectBuilders,
80
detectOutputDirectory,
81
detectApiDirectory,
82
detectFramework,
83
DetectorFilesystem,
84
isOfficialRuntime,
85
isStaticRuntime,
86
getPlatformEnv,
87
shouldServe,
88
debug,
89
NowBuildError
90
} = require("@vercel/build-utils");
91
```
92
93
## Basic Usage
94
95
```typescript
96
import {
97
FileBlob,
98
FileFsRef,
99
createLambda,
100
download,
101
glob,
102
spawnAsync,
103
detectBuilders,
104
getPlatformEnv,
105
NowBuildError
106
} from "@vercel/build-utils";
107
108
// Create file references
109
const fileBlob = new FileBlob({ data: "console.log('Hello World')" });
110
const fileFsRef = await FileFsRef.fromFsPath({ fsPath: "/path/to/file.js" });
111
112
// Create a Lambda function
113
const files = { "index.js": fileBlob };
114
const lambda = await createLambda({
115
files,
116
handler: "index.handler",
117
runtime: "nodejs18.x",
118
environment: { NODE_ENV: "production" }
119
});
120
121
// Download files to filesystem
122
const downloadedFiles = await download(files, "/tmp/build", { isDev: false });
123
124
// Find files with patterns
125
const sourceFiles = await glob("**/*.js", "/src");
126
127
// Execute shell commands
128
await spawnAsync("npm", ["install"], { cwd: "/project" });
129
130
// Detect appropriate builders
131
const fileList = ["package.json", "pages/index.js", "api/users.js"];
132
const result = await detectBuilders(fileList);
133
134
// Handle environment variables
135
const deploymentUrl = getPlatformEnv("URL");
136
const region = getPlatformEnv("REGION");
137
138
// Error handling
139
try {
140
await spawnAsync("npm", ["run", "build"]);
141
} catch (error) {
142
if (error instanceof NowBuildError) {
143
console.error(`Build failed [${error.code}]: ${error.message}`);
144
}
145
}
146
```
147
148
## Architecture
149
150
@vercel/build-utils is organized around several key components:
151
152
- **File System**: File abstraction classes (`FileBlob`, `FileFsRef`, `FileRef`) for representing different file sources
153
- **Lambda Management**: Creation and configuration of serverless Lambda functions
154
- **Build Process**: Utilities for downloading, processing, and executing build steps
155
- **Framework Detection**: Automatic detection of project frameworks and appropriate builders
156
- **Process Execution**: Safe execution of user scripts and system commands
157
- **Platform Utilities**: Helper functions for environment variables and runtime detection
158
159
## Capabilities
160
161
### File System Operations
162
163
File handling, downloading, and pattern matching utilities for managing build assets and source files.
164
165
```typescript { .api }
166
function download(files: Files, basePath: string, meta?: Meta): Promise<DownloadedFiles>;
167
function glob(pattern: string, opts: GlobOptions | string, mountpoint?: string): Promise<FsFiles>;
168
```
169
170
[File Operations](./file-operations.md)
171
172
### Lambda Functions
173
174
Creation and management of serverless Lambda functions with ZIP packaging and configuration options.
175
176
```typescript { .api }
177
function createLambda(options: CreateLambdaOptions): Promise<Lambda>;
178
179
interface CreateLambdaOptions {
180
files: Files;
181
handler: string;
182
runtime: string;
183
memory?: number;
184
maxDuration?: number;
185
environment?: Environment;
186
}
187
188
class Lambda {
189
type: 'Lambda';
190
zipBuffer: Buffer;
191
handler: string;
192
runtime: string;
193
memory?: number;
194
maxDuration?: number;
195
environment: Environment;
196
}
197
```
198
199
[Lambda Functions](./lambda.md)
200
201
### Process Execution
202
203
Utilities for executing shell commands, installing dependencies, and running user scripts safely.
204
205
```typescript { .api }
206
function spawnAsync(command: string, args: string[], opts?: SpawnOptionsExtended): Promise<void>;
207
function execAsync(command: string, args: string[], opts?: SpawnOptionsExtended): Promise<{ stdout: string; stderr: string; code: number }>;
208
```
209
210
[Process Execution](./process-execution.md)
211
212
### Builder Detection
213
214
Automatic detection of project frameworks and configuration of appropriate build strategies.
215
216
```typescript { .api }
217
function detectBuilders(files: string[], pkg?: PackageJson, options?: Options): Promise<{
218
builders: Builder[] | null;
219
errors: ErrorResponse[] | null;
220
warnings: ErrorResponse[];
221
defaultRoutes: Route[] | null;
222
redirectRoutes: Route[] | null;
223
rewriteRoutes: Route[] | null;
224
errorRoutes: Route[] | null;
225
}>;
226
```
227
228
[Builder Detection](./builder-detection.md)
229
230
### Platform Utilities
231
232
Helper functions for Vercel platform integration, environment variable handling, and runtime detection.
233
234
```typescript { .api }
235
function isOfficialRuntime(desired: string, name?: string): boolean;
236
function getPlatformEnv(name: string): string | undefined;
237
```
238
239
[Platform Utilities](./platform-utilities.md)
240
241
## Core Types
242
243
```typescript { .api }
244
interface Files {
245
[filePath: string]: File;
246
}
247
248
interface File {
249
type: string;
250
mode: number;
251
contentType?: string;
252
toStream: () => NodeJS.ReadableStream;
253
fsPath?: string;
254
}
255
256
interface Config {
257
[key: string]: string | string[] | boolean | number | { [key: string]: string } | BuilderFunctions | undefined;
258
maxLambdaSize?: string;
259
includeFiles?: string | string[];
260
excludeFiles?: string | string[];
261
bundle?: boolean;
262
functions?: BuilderFunctions;
263
outputDirectory?: string;
264
installCommand?: string;
265
buildCommand?: string;
266
devCommand?: string;
267
framework?: string;
268
nodeVersion?: string;
269
}
270
271
interface Meta {
272
isDev?: boolean;
273
devCacheDir?: string;
274
skipDownload?: boolean;
275
requestPath?: string | null;
276
filesChanged?: string[];
277
filesRemoved?: string[];
278
env?: Env;
279
buildEnv?: Env;
280
}
281
282
interface Env {
283
[name: string]: string | undefined;
284
}
285
286
interface Environment {
287
[key: string]: string;
288
}
289
290
interface BuildOptions {
291
files: Files;
292
entrypoint: string;
293
workPath: string;
294
repoRootPath?: string;
295
config: Config;
296
meta?: Meta;
297
}
298
299
interface AnalyzeOptions {
300
files: {
301
[filePath: string]: FileRef;
302
};
303
entrypoint: string;
304
workPath: string;
305
config: Config;
306
}
307
308
interface PrepareCacheOptions {
309
files: Files;
310
entrypoint: string;
311
workPath: string;
312
cachePath: string;
313
config: Config;
314
}
315
316
interface Builder {
317
use: string;
318
src?: string;
319
config?: Config;
320
}
321
322
interface BuilderFunctions {
323
[key: string]: {
324
memory?: number;
325
maxDuration?: number;
326
runtime?: string;
327
includeFiles?: string;
328
excludeFiles?: string;
329
};
330
}
331
332
interface NodeVersion {
333
major: number;
334
range: string;
335
runtime: string;
336
discontinueDate?: Date;
337
}
338
339
namespace PackageJson {
340
export interface Author {
341
name: string;
342
email?: string;
343
homepage?: string;
344
}
345
346
export interface BinMap {
347
[commandName: string]: string;
348
}
349
350
export interface Repository {
351
type: string;
352
url: string;
353
}
354
355
export interface DependencyMap {
356
[dependencyName: string]: string;
357
}
358
359
export interface ScriptsMap {
360
[scriptName: string]: string;
361
}
362
363
export interface Engines {
364
node?: string;
365
npm?: string;
366
}
367
}
368
369
interface PackageJson {
370
readonly name?: string;
371
readonly version?: string;
372
readonly description?: string;
373
readonly keywords?: string[];
374
readonly homepage?: string;
375
readonly license?: string;
376
readonly author?: string | PackageJson.Author;
377
readonly main?: string;
378
readonly bin?: string | PackageJson.BinMap;
379
readonly repository?: string | PackageJson.Repository;
380
readonly scripts?: PackageJson.ScriptsMap;
381
readonly dependencies?: PackageJson.DependencyMap;
382
readonly devDependencies?: PackageJson.DependencyMap;
383
readonly peerDependencies?: PackageJson.DependencyMap;
384
readonly engines?: PackageJson.Engines;
385
readonly private?: boolean;
386
}
387
```