0
# @vercel/node (Vercel Node.js Runtime)
1

2
@vercel/node is a Vercel runtime builder that enables serverless execution of JavaScript and TypeScript code as AWS Lambda functions. It provides automatic dependency bundling, TypeScript compilation, ES module transformation, and development server capabilities for Node.js serverless functions.
3

4
## Package Information
5

6
- **Package Name**: @vercel/node
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: Automatic via Vercel platform
10
- **Version**: 1.8.5
11

12
## Core Imports
13

14
The package exports runtime builder functions and types for Vercel platform integration:
15

16
```typescript
17
import { build, prepareCache, startDevServer, version, shouldServe } from "@vercel/node";
18
import { NowRequest, NowResponse, NowApiHandler } from "@vercel/node";
19
```
20

21
Note: This package is typically used internally by the Vercel platform rather than directly imported by user code.
22

23
## Basic Usage
24

25
### Runtime Builder Usage
26

27
```typescript
28
import { build } from "@vercel/node";
29

30
// Build a serverless function
31
const result = await build({
32
  files: fileMap,
33
  entrypoint: "api/handler.js",
34
  workPath: "/tmp/build",
35
  config: {},
36
  meta: {}
37
});
38

39
// result.output contains the Lambda deployment
40
// result.watch contains files to watch for changes
41
```
42

43
### API Handler Usage
44

45
```typescript
46
import { NowRequest, NowResponse } from "@vercel/node";
47

48
export default function handler(req: NowRequest, res: NowResponse) {
49
  // Access parsed query parameters
50
  const { name } = req.query;
51
  
52
  // Access parsed cookies
53
  const token = req.cookies.auth_token;
54
  
55
  // Access parsed body (JSON, form data, etc.)
56
  const data = req.body;
57
  
58
  // Send JSON response
59
  res.status(200).json({ message: `Hello ${name}` });
60
  
61
  // Or send plain text
62
  res.send("Hello World");
63
  
64
  // Or redirect
65
  res.redirect("/login");
66
}
67
```
68

69
## Architecture
70

71
The @vercel/node runtime is built around several key components:
72

73
- **Build System**: Processes source files, installs dependencies, and creates Lambda deployments
74
- **TypeScript Compiler**: Compiles TypeScript to JavaScript with source map support
75
- **File Tracer**: Analyzes dependencies to create minimal deployment bundles
76
- **Development Server**: Local testing environment with hot reloading
77
- **Request/Response Abstractions**: Enhanced HTTP interfaces for serverless functions
78
- **Launcher System**: Bridges between Vercel platform and user code
79

80
## Capabilities
81

82
### Runtime Builder
83

84
Core build functionality for creating Lambda deployments from Node.js/TypeScript source code. Handles dependency installation, compilation, and bundling.
85

86
```typescript { .api }
87
function build(options: BuildOptions): Promise<{
88
  output: Lambda;
89
  watch: string[];
90
}>;
91

92
function prepareCache(options: PrepareCacheOptions): Promise<Files>;
93

94
function startDevServer(options: StartDevServerOptions): Promise<StartDevServerResult>;
95

96
const version: number;
97

98
function shouldServe(): boolean;
99
```
100

101
[Runtime Builder](./runtime-builder.md)
102

103
### API Handler Types
104

105
Type definitions for serverless function handlers with enhanced request/response objects that provide automatic parsing and convenience methods.
106

107
```typescript { .api }
108
type NowRequest = IncomingMessage & {
109
  query: NowRequestQuery;
110
  cookies: NowRequestCookies;
111
  body: NowRequestBody;
112
};
113

114
type NowResponse = ServerResponse & {
115
  send: (body: any) => NowResponse;
116
  json: (jsonBody: any) => NowResponse;
117
  status: (statusCode: number) => NowResponse;
118
  redirect: (statusOrUrl: string | number, url?: string) => NowResponse;
119
};
120

121
type NowApiHandler = (req: NowRequest, res: NowResponse) => void;
122
```
123

124
Note: All types including `NowApiHandler` are exported from the main package.
125

126
[API Handler Types](./api-handler-types.md)
127

128
## Types
129

130
### Build Configuration Types
131

132
```typescript { .api }
133
interface BuildOptions {
134
  files: Files;
135
  entrypoint: string;
136
  workPath: string;
137
  repoRootPath?: string;
138
  config?: Config;
139
  meta?: Meta;
140
}
141

142
interface PrepareCacheOptions {
143
  workPath: string;
144
}
145

146
interface StartDevServerOptions {
147
  entrypoint: string;
148
  workPath: string;
149
  config?: Config;
150
  meta?: Meta;
151
}
152

153
interface StartDevServerResult {
154
  port: number;
155
  pid: number;
156
}
157
```
158

159
### Request/Response Types
160

161
```typescript { .api }
162
type NowRequestCookies = { [key: string]: string };
163
type NowRequestQuery = { [key: string]: string | string[] };
164
type NowRequestBody = any;
165
```
166

167
### External Dependencies
168

169
This package depends on types from `@vercel/build-utils`:
170

171
- `Files`: Collection of files for build process
172
- `Meta`: Build metadata and environment information  
173
- `Config`: Build configuration options
174
- `Lambda`: Serverless function deployment artifact