Wrangler Programmatic API

Wrangler exports a programmatic API that allows you to use it as a library in your Node.js applications. This is useful for building custom development tools, testing frameworks, and deployment pipelines.

Installation

npm install wrangler

Core Functions

`startWorker()`

Starts a local development server for a Worker.

import { startWorker } from "wrangler";

const worker = await startWorker({
  name: "my-worker",
  entrypoint: "./src/index.ts",
  compatibilityDate: "2024-01-01",
});

const response = await worker.fetch("/");
console.log(await response.text());

await worker.dispose();

options

StartDevWorkerInput

required

Configuration options for the dev server

Show StartDevWorkerInput properties

name

string

The name of the worker

entrypoint

string

The JavaScript or TypeScript entry-point of the worker. This is the main property of a Wrangler configuration file.

config

string

Path to the Wrangler configuration file

compatibilityDate

string

The compatibility date for the workerd runtime (e.g., “2024-01-01”)

compatibilityFlags

string[]

Array of compatibility flags for the workerd runtime

env

string

Environment to use for operations and selecting .env files

envFiles

string[]

Paths to .env files to load, relative to the project directory

bindings

Record<string, Binding>

Bindings available to the worker on the env object

Show Binding types

{ type: "plain_text"; value: string } - Plain text variable
{ type: "json"; value: unknown } - JSON variable
{ type: "kv_namespace"; id: string } - KV namespace
{ type: "durable_object_namespace"; className: string; scriptName?: string } - Durable Object
{ type: "r2_bucket"; bucketName: string } - R2 bucket
{ type: "d1"; id: string } - D1 database
{ type: "service"; service: string; entrypoint?: string } - Service binding
{ type: "queue"; queueName: string } - Queue

triggers

Trigger[]

Triggers that will cause the worker’s exported handlers to be called

Show Trigger types

HTTP routes (e.g., { type: "route"; pattern: "example.com/*" })
Custom domains

build

object

Options for the worker’s build step

Show Build options

build.bundle

boolean

default:"true"

Whether to bundle the worker and its dependencies

build.minify

boolean

Whether to minify the bundled worker

build.define

Record<string, string>

Replace global identifiers with constant expressions (e.g., { debug: 'true' })

build.alias

Record<string, string>

Alias modules (e.g., { "@/utils": "./src/utils" })

build.moduleRules

Rule[]

Specifies types of modules matched by globs

build.custom

object

Options for custom build steps

Show Custom build options

custom.command

string

Custom shell command to run before bundling

custom.watch

string | string[]

Files to watch for changes to trigger rebuilds

dev

object

Options for the development preview environment

Show Dev options

dev.remote

boolean | 'minimal'

true or "minimal": Run in remote preview session
false: Run locally in workerd simulator
undefined: Run code locally, remote bindings remotely

dev.persist

string

Directory for persisting local storage (KV, DO, R2, D1, etc.)

dev.logLevel

Controls which logs are displayed

dev.watch

boolean

Whether to restart the server on source/config file changes

dev.liveReload

boolean

default:"false"

Insert script tag in HTML responses to reload page on file changes

dev.server

object

Local server configuration

Show Server options

server.hostname

string

Hostname to bind to

server.port

number

Port to listen on

server.secure

boolean

Use HTTPS

dev.inspector

object | false

Inspector server configuration, or false to disable

Show Inspector options

inspector.port

number

Port for inspector

Worker

object

The worker instance

Show Worker properties

ready

Promise<void>

Promise that resolves when the worker is ready

url

Promise<URL>

Promise that resolves to the worker’s URL

inspectorUrl

Promise<URL | undefined>

Promise that resolves to the inspector URL

fetch

(request: Request) => Promise<Response>

Send an HTTP request to the worker

scheduled

(cron?: string) => Promise<void>

Trigger a scheduled event

queue

(queueName: string, messages: Message[]) => Promise<void>

Send messages to a queue consumer

setConfig

(config: StartDevWorkerOptions) => Promise<void>

Replace the entire worker configuration

patchConfig

(config: Partial<StartDevWorkerOptions>) => Promise<void>

Partially update the worker configuration

dispose

() => Promise<void>

Stop the worker and clean up resources

Example Usage

import { startWorker } from "wrangler";

const worker = await startWorker({
  name: "my-api",
  entrypoint: "./src/index.ts",
  compatibilityDate: "2024-01-01",
  bindings: {
    DB: {
      type: "d1",
      id: "my-database",
    },
    MY_KV: {
      type: "kv_namespace",
      id: "my-kv-namespace",
    },
  },
  dev: {
    persist: ".wrangler/state",
    server: {
      port: 8787,
    },
  },
});

// Wait for worker to be ready
await worker.ready;

// Make a request
const response = await worker.fetch("/api/users");
console.log(await response.json());

// Trigger a scheduled event
await worker.scheduled();

// Clean up
await worker.dispose();

`unstable_dev()`

This API is experimental and may change in future releases.

Starts a Wrangler dev server for testing purposes.

import { unstable_dev } from "wrangler";

const worker = await unstable_dev("src/index.ts", {
  config: "wrangler.toml",
  env: "staging",
  local: true,
});

const response = await worker.fetch("/");
console.log(response.status);

await worker.stop();

script

string

required

Path to the worker script

options

Unstable_DevOptions

Show Options

config

string

Path to .toml configuration file

env

string

Environment to use

local

boolean

default:"true"

Run locally vs. remotely

port

number

Port to listen on

persist

boolean

Enable persistence using default path (.wrangler/state)

vars

Record<string, string>

Environment variables

Unstable_DevWorker

object

Show Properties

port

number

Port the server is running on

address

string

Address the server is bound to

fetch

(input?: RequestInfo, init?: RequestInit) => Promise<Response>

Make a request to the worker

stop

() => Promise<void>

Stop the dev server

waitUntilExit

() => Promise<void>

Wait until the server exits

`getPlatformProxy()`

Get proxy objects for Cloudflare platform bindings in Node.js.

import { getPlatformProxy } from "wrangler";

const { env, dispose } = await getPlatformProxy({
  configPath: "wrangler.toml",
});

// Use bindings
const value = await env.MY_KV.get("key");

await dispose();

options

GetPlatformProxyOptions

Show Options

configPath

string

Path to Wrangler config file. If not specified, searches from current directory upward.

environment

string

Environment name to use

persist

boolean | { path: string }

default:"true"

Whether and where to persist binding data. Defaults to .wrangler/state/v3.

remoteBindings

boolean

default:"true"

Whether remote bindings should be enabled

PlatformProxy

object

Show Properties

env

Env

Environment object containing Cloudflare bindings (KV, D1, R2, etc.)

IncomingRequestCfProperties

Request.cf object with geolocation and other properties

ctx

ExecutionContext

Mock execution context with waitUntil() and passThroughOnException()

caches

CacheStorage

Cache API implementation

dispose

() => Promise<void>

Clean up resources

// Example: Use in a test framework
import { getPlatformProxy } from "wrangler";
import { describe, it, expect, beforeAll, afterAll } from "vitest";

let env, dispose;

beforeAll(async () => {
  ({ env, dispose } = await getPlatformProxy());
});

afterAll(async () => {
  await dispose();
});

it("should store and retrieve from KV", async () => {
  await env.MY_KV.put("test-key", "test-value");
  const value = await env.MY_KV.get("test-key");
  expect(value).toBe("test-value");
});

Configuration Utilities

`unstable_readConfig()`

Read and parse a Wrangler configuration file.

import { unstable_readConfig } from "wrangler";

const config = unstable_readConfig({
  config: "wrangler.toml",
  env: "production",
});

console.log(config.name); // Worker name
console.log(config.compatibility_date); // Compatibility date

options

object

config

string

Path to config file

env

string

Environment to use

config

Config

Parsed configuration object

`unstable_getWorkerNameFromProject()`

Get the worker name from a project directory.

import { unstable_getWorkerNameFromProject } from "wrangler";

const name = unstable_getWorkerNameFromProject("/path/to/project");
console.log(name); // "my-worker"

Binding Utilities

`convertConfigBindingsToStartWorkerBindings()`

Convert Wrangler config bindings to the format expected by startWorker().

import { 
  unstable_readConfig, 
  convertConfigBindingsToStartWorkerBindings 
} from "wrangler";

const config = unstable_readConfig({ config: "wrangler.toml" });
const bindings = convertConfigBindingsToStartWorkerBindings(config);

Event Types

The Worker object emits events during its lifecycle.

`ErrorEvent`

Emitted when an error occurs.

type ErrorEvent = {
  type: "error";
  error: SerializedError;
};

`ConfigUpdateEvent`

Emitted when configuration changes.

type ConfigUpdateEvent = {
  type: "config-update";
  config: StartDevWorkerOptions;
};

`BundleStartEvent` / `BundleCompleteEvent`

Emitted during bundling.

type BundleStartEvent = {
  type: "bundle-start";
};

type BundleCompleteEvent = {
  type: "bundle-complete";
  bundle: Bundle;
};

`ReadyEvent`

Emitted when the worker is ready.

type ReadyEvent = {
  type: "ready";
  url: URL;
  inspectorUrl?: URL;
};

Pages API

`unstable_pages.deploy()`

Deploy a Pages project programmatically.

import { unstable_pages } from "wrangler";

const result = await unstable_pages.deploy({
  directory: "./dist",
  projectName: "my-site",
  accountId: "your-account-id",
});

console.log(`Deployed to: ${result.url}`);

mTLS Certificate Management

`uploadMTlsCertificate()`

Upload an mTLS certificate from a buffer.

import { uploadMTlsCertificate } from "wrangler";
import fs from "fs";

const cert = fs.readFileSync("cert.pem");
const key = fs.readFileSync("key.pem");

const result = await uploadMTlsCertificate(
  "my-cert",
  cert,
  key,
  "account-id"
);

`listMTlsCertificates()`

List all mTLS certificates.

import { listMTlsCertificates } from "wrangler";

const certs = await listMTlsCertificates("account-id");

`deleteMTlsCertificate()`

Delete an mTLS certificate.

import { deleteMTlsCertificate } from "wrangler";

await deleteMTlsCertificate("cert-id", "account-id");

Type Definitions

All types are exported from the main package:

import type {
  Worker,
  StartDevWorkerInput,
  StartDevWorkerOptions,
  Binding,
  Trigger,
  GetPlatformProxyOptions,
  PlatformProxy,
} from "wrangler";

Wrangler API

Miniflare API

Testing

Integrations

Installation

Core Functions

`startWorker()`

Example Usage

`unstable_dev()`

`getPlatformProxy()`

Configuration Utilities

`unstable_readConfig()`

`unstable_getWorkerNameFromProject()`

Binding Utilities

`convertConfigBindingsToStartWorkerBindings()`

Event Types

`ErrorEvent`

`ConfigUpdateEvent`

`BundleStartEvent` / `BundleCompleteEvent`

`ReadyEvent`

Pages API

`unstable_pages.deploy()`

mTLS Certificate Management

`uploadMTlsCertificate()`

`listMTlsCertificates()`

`deleteMTlsCertificate()`

Type Definitions

Build docs developers (and LLMs) love

Wrangler API

Miniflare API

Testing

Integrations

​Installation

​Core Functions

​startWorker()

​Example Usage

​unstable_dev()

​getPlatformProxy()

​Configuration Utilities

​unstable_readConfig()

​unstable_getWorkerNameFromProject()

​Binding Utilities

​convertConfigBindingsToStartWorkerBindings()

​Event Types

​ErrorEvent

​ConfigUpdateEvent

​BundleStartEvent / BundleCompleteEvent

​ReadyEvent

​Pages API

​unstable_pages.deploy()

​mTLS Certificate Management

​uploadMTlsCertificate()

​listMTlsCertificates()

​deleteMTlsCertificate()

​Type Definitions

Build docs developers (and LLMs) love

Installation

Core Functions

`startWorker()`

Example Usage

`unstable_dev()`

`getPlatformProxy()`

Configuration Utilities

`unstable_readConfig()`

`unstable_getWorkerNameFromProject()`

Binding Utilities

`convertConfigBindingsToStartWorkerBindings()`

Event Types

`ErrorEvent`

`ConfigUpdateEvent`

`BundleStartEvent` / `BundleCompleteEvent`

`ReadyEvent`

Pages API

`unstable_pages.deploy()`

mTLS Certificate Management

`uploadMTlsCertificate()`

`listMTlsCertificates()`

`deleteMTlsCertificate()`

Type Definitions