dotfiles/dot_agents/skills/cloudflare/references/wrangler/api.md

Wrangler Programmatic API

Node.js APIs for testing and development.

startWorker (Testing)

Starts Worker with real local bindings for integration tests. Stable API (replaces unstable_startWorker).

import { startWorker } from "wrangler";
import { describe, it, before, after } from "node:test";
import assert from "node:assert";

describe("worker", () => {
  let worker;
  
  before(async () => {
    worker = await startWorker({
      config: "wrangler.jsonc",
      environment: "development"
    });
  });
  
  after(async () => {
    await worker.dispose();
  });
  
  it("responds with 200", async () => {
    const response = await worker.fetch("http://example.com");
    assert.strictEqual(response.status, 200);
  });
});

Options

Option	Type	Description
config	string	Path to wrangler.jsonc
environment	string	Environment name from config
persist	boolean | { path: string }	Enable persistent state
bundle	boolean	Enable bundling (default: true)
remote	false | true | "minimal"	Remote mode: false (local), true (full remote), "minimal" (remote bindings only)

Remote Mode

// Local mode (default) - fast, simulated
const worker = await startWorker({ config: "wrangler.jsonc" });

// Full remote mode - production-like, slower
const worker = await startWorker({ 
  config: "wrangler.jsonc",
  remote: true 
});

// Minimal remote mode - remote bindings, local Worker
const worker = await startWorker({ 
  config: "wrangler.jsonc",
  remote: "minimal"
});

getPlatformProxy

Emulate bindings in Node.js without starting Worker.

import { getPlatformProxy } from "wrangler";

const { env, dispose, caches } = await getPlatformProxy<Env>({
  configPath: "wrangler.jsonc",
  environment: "production",
  persist: { path: ".wrangler/state" }
});

// Use bindings
const value = await env.MY_KV.get("key");
await env.DB.prepare("SELECT * FROM users").all();
await env.ASSETS.put("file.txt", "content");

// Platform APIs
await caches.default.put("https://example.com", new Response("cached"));

await dispose();

Use for unit tests (test functions, not full Worker) or scripts that need bindings.

Type Generation

Generate types from config: wrangler types → creates worker-configuration.d.ts

Event System

Listen to Worker lifecycle events for advanced workflows.

import { startWorker } from "wrangler";

const worker = await startWorker({
  config: "wrangler.jsonc",
  bundle: true
});

// Bundle events
worker.on("bundleStart", (details) => {
  console.log("Bundling started:", details.config);
});

worker.on("bundleComplete", (details) => {
  console.log("Bundle ready:", details.duration);
});

// Reconfiguration events
worker.on("reloadStart", () => {
  console.log("Worker reloading...");
});

worker.on("reloadComplete", () => {
  console.log("Worker reloaded");
});

await worker.dispose();

Dynamic Reconfiguration

import { startWorker } from "wrangler";

const worker = await startWorker({ config: "wrangler.jsonc" });

// Replace entire config
await worker.setConfig({
  config: "wrangler.staging.jsonc",
  environment: "staging"
});

// Patch specific fields
await worker.patchConfig({
  vars: { DEBUG: "true" }
});

await worker.dispose();

unstable_dev (Deprecated)

Use startWorker instead.

Multi-Worker Registry

Test multiple Workers with service bindings.

import { startWorker } from "wrangler";

const auth = await startWorker({ config: "./auth/wrangler.jsonc" });
const api = await startWorker({
  config: "./api/wrangler.jsonc",
  bindings: { AUTH: auth }  // Service binding
});

const response = await api.fetch("http://example.com/api/login");
// API Worker calls AUTH Worker via env.AUTH.fetch()

await api.dispose();
await auth.dispose();

Best Practices

• Use startWorker for integration tests (tests full Worker)
• Use getPlatformProxy for unit tests (tests individual functions)
• Use remote: true when debugging production-specific issues
• Use remote: "minimal" for faster tests with real bindings
• Enable persist: true for debugging (state survives runs)
• Run wrangler types after config changes
• Always dispose() to prevent resource leaks
• Listen to bundle events for build monitoring
• Use multi-worker registry for testing service bindings

See Also

• README.md - CLI commands
• configuration.md - Config
• patterns.md - Testing patterns