dotfiles/.agents/skills/cloudflare-deploy/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`).

```typescript
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

```typescript
// 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.

```typescript
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.

```typescript
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

```typescript
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.

```typescript
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](./README.md) - CLI commands
- [configuration.md](./configuration.md) - Config
- [patterns.md](./patterns.md) - Testing patterns