Runtime Builder

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.

Main Build Function

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

function build(options: BuildOptions): Promise<{
  output: Lambda;
  watch: string[];
}>;

Parameters

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

Returns

• output: Lambda deployment artifact ready for execution
• watch: Array of file paths to watch for changes in development

Build Process

The build function performs these operations:

1. Downloads and installs npm/yarn dependencies
2. Runs build scripts (vercel-build or now-build)
3. Compiles TypeScript to JavaScript with source maps
4. Traces file dependencies to create minimal bundles
5. Transforms ES modules to CommonJS
6. Creates launcher scripts for runtime execution
7. Bundles everything into a Lambda deployment

Cache Preparation

Prepares the node_modules cache for faster subsequent builds.

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

Parameters

• options.workPath: Working directory containing node_modules

Returns

Collection of cached files from node_modules directory.

Usage

import { prepareCache } from "@vercel/node";

const cache = await prepareCache({
  workPath: "/tmp/build"
});

Development Server

Starts a local development server for testing serverless functions.

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

Parameters

• options.entrypoint: Path to the function entry file
• options.workPath: Working directory
• options.config: Optional development configuration
• options.meta: Optional metadata including environment variables

Returns

• port: Port number the dev server is running on
• pid: Process ID of the dev server

Development Features

The development server provides:

• Hot reloading when source files change
• TypeScript compilation on-the-fly
• Environment variable injection
• Request/response logging
• Error handling and debugging

Usage Example

import { startDevServer } from "@vercel/node";

const server = await startDevServer({
  entrypoint: "api/users.ts",
  workPath: process.cwd(),
  config: {
    helpers: true
  },
  meta: {
    env: {
      NODE_ENV: "development"
    }
  }
});

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

Utility Function

Should Serve

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

function shouldServe(): boolean;

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.

Version

Runtime version number for platform compatibility.

const version: number;

Current version is 3, indicating the runtime builder API version.

Configuration Options

Build Config

interface Config {
  helpers?: boolean;
  includeFiles?: string | string[];
  excludeFiles?: string[];
  awsLambdaHandler?: string;
}

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

Build Metadata

interface Meta {
  isDev?: boolean;
  env?: { [key: string]: string };
  buildEnv?: { [key: string]: string };
  devCacheDir?: string;
}

• isDev: Whether building for development (skips dependency installation)
• env: Environment variables for runtime
• buildEnv: Environment variables for build process
• devCacheDir: Directory for development caches

Error Handling

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

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

Example Error Handling

try {
  const result = await build({
    files: sourceFiles,
    entrypoint: "api/handler.ts",
    workPath: "/tmp/build"
  });
  
  console.log("Build successful!");
} catch (error) {
  if (error.message.includes("MODULE_NOT_FOUND")) {
    console.error("Missing dependency. Check package.json");
  } else {
    console.error("Build failed:", error.message);
  }
}