0
# Runtime Builder
1

2
The runtime builder provides the core functionality for transforming Node.js and TypeScript source code into AWS Lambda-compatible serverless functions for the Vercel platform.
3

4
## Main Build Function
5

6
Transforms source code into a deployable Lambda function with all dependencies bundled.
7

8
```typescript { .api }
9
function build(options: BuildOptions): Promise<{
10
  output: Lambda;
11
  watch: string[];
12
}>;
13
```
14

15
### Parameters
16

17
- `options.files`: Collection of source files to build
18
- `options.entrypoint`: Path to the main entry file (e.g., "api/handler.js")
19
- `options.workPath`: Working directory for the build process
20
- `options.repoRootPath`: Optional root path of the repository
21
- `options.config`: Optional build configuration
22
- `options.meta`: Optional build metadata and environment info
23

24
### Returns
25

26
- `output`: Lambda deployment artifact ready for execution
27
- `watch`: Array of file paths to watch for changes in development
28

29
### Build Process
30

31
The build function performs these operations:
32
1. Downloads and installs npm/yarn dependencies
33
2. Runs build scripts (`vercel-build` or `now-build`)
34
3. Compiles TypeScript to JavaScript with source maps
35
4. Traces file dependencies to create minimal bundles
36
5. Transforms ES modules to CommonJS
37
6. Creates launcher scripts for runtime execution
38
7. Bundles everything into a Lambda deployment
39

40
## Cache Preparation
41

42
Prepares the node_modules cache for faster subsequent builds.
43

44
```typescript { .api }
45
function prepareCache(options: PrepareCacheOptions): Promise<Files>;
46
```
47

48
### Parameters
49

50
- `options.workPath`: Working directory containing node_modules
51

52
### Returns
53

54
Collection of cached files from node_modules directory.
55

56
### Usage
57

58
```typescript
59
import { prepareCache } from "@vercel/node";
60

61
const cache = await prepareCache({
62
  workPath: "/tmp/build"
63
});
64
```
65

66
## Development Server
67

68
Starts a local development server for testing serverless functions.
69

70
```typescript { .api }
71
function startDevServer(options: StartDevServerOptions): Promise<StartDevServerResult>;
72
```
73

74
### Parameters
75

76
- `options.entrypoint`: Path to the function entry file
77
- `options.workPath`: Working directory
78
- `options.config`: Optional development configuration
79
- `options.meta`: Optional metadata including environment variables
80

81
### Returns
82

83
- `port`: Port number the dev server is running on
84
- `pid`: Process ID of the dev server
85

86
### Development Features
87

88
The development server provides:
89
- Hot reloading when source files change
90
- TypeScript compilation on-the-fly
91
- Environment variable injection
92
- Request/response logging
93
- Error handling and debugging
94

95
### Usage Example
96

97
```typescript
98
import { startDevServer } from "@vercel/node";
99

100
const server = await startDevServer({
101
  entrypoint: "api/users.ts",
102
  workPath: process.cwd(),
103
  config: {
104
    helpers: true
105
  },
106
  meta: {
107
    env: {
108
      NODE_ENV: "development"
109
    }
110
  }
111
});
112

113
console.log(`Dev server running on port ${server.port}`);
114
```
115

116
## Utility Function
117

118
### Should Serve
119

120
Utility function to determine if files should be served during development.
121

122
```typescript { .api }
123
function shouldServe(): boolean;
124
```
125

126
This function is re-exported from `@vercel/build-utils` and is used internally by the Vercel platform. It's typically not called directly by user code.
127

128
## Version
129

130
Runtime version number for platform compatibility.
131

132
```typescript { .api }
133
const version: number;
134
```
135

136
Current version is `3`, indicating the runtime builder API version.
137

138
## Configuration Options
139

140
### Build Config
141

142
```typescript { .api }
143
interface Config {
144
  helpers?: boolean;
145
  includeFiles?: string | string[];
146
  excludeFiles?: string[];
147
  awsLambdaHandler?: string;
148
}
149
```
150

151
- `helpers`: Enable/disable helper methods on request/response objects (default: true)
152
- `includeFiles`: Glob patterns for additional files to include in bundle
153
- `excludeFiles`: Patterns for files to exclude from dependency tracing
154
- `awsLambdaHandler`: Custom AWS Lambda handler name for direct Lambda deployment
155

156
### Build Metadata
157

158
```typescript { .api }
159
interface Meta {
160
  isDev?: boolean;
161
  env?: { [key: string]: string };
162
  buildEnv?: { [key: string]: string };
163
  devCacheDir?: string;
164
}
165
```
166

167
- `isDev`: Whether building for development (skips dependency installation)
168
- `env`: Environment variables for runtime
169
- `buildEnv`: Environment variables for build process
170
- `devCacheDir`: Directory for development caches
171

172
## Error Handling
173

174
Build errors are thrown as standard JavaScript errors. Common error scenarios:
175

176
- **Missing Dependencies**: When required packages are not in package.json
177
- **TypeScript Errors**: Compilation failures in TypeScript code
178
- **File Tracing Errors**: Issues resolving module dependencies
179
- **Build Script Failures**: When `vercel-build` or `now-build` scripts fail
180

181
### Example Error Handling
182

183
```typescript
184
try {
185
  const result = await build({
186
    files: sourceFiles,
187
    entrypoint: "api/handler.ts",
188
    workPath: "/tmp/build"
189
  });
190
  
191
  console.log("Build successful!");
192
} catch (error) {
193
  if (error.message.includes("MODULE_NOT_FOUND")) {
194
    console.error("Missing dependency. Check package.json");
195
  } else {
196
    console.error("Build failed:", error.message);
197
  }
198
}
199
```