How to Configure Worker Loader Binding for Worker-Shell and Worker-JavaScript Backends

The worker-shell and worker-javascript backends require a Worker Loader binding declared in wrangler.jsonc, typed in worker-configuration.d.ts, and passed to the backend constructor via env.LOADER.

The Cloudflare Computer repository provides two backends that execute code inside Dynamic Workers: WorkerShellBackend for shell commands and WorkerJavaScriptBackend for JavaScript modules. Both depend on a WorkerLoader binding to mint fresh Dynamic Workers at runtime. This guide walks through the three-step configuration that applies to both backends.

Add the Loader Binding in wrangler.jsonc

First, declare the worker_loaders array in your Wrangler configuration. This instructs Wrangler to generate a WorkerLoader instance accessible from the Worker's environment.

// ── wrangler.jsonc ──
{
  "name": "my-example",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-26",
  "worker_loaders": [{ "binding": "LOADER" }],
  "durable_objects": {
    "bindings": [{ "name": "ContainerExample", "class_name": "ContainerExample" }]
  }
}

The binding name (commonly "LOADER") becomes the key in env. Both examples/worker-shell/wrangler.jsonc and examples/worker-javascript/wrangler.jsonc demonstrate this identical pattern.

Type the Binding in worker-configuration.d.ts

For TypeScript projects, extend the Env interface to include LOADER: WorkerLoader. This provides type safety and autocompletion when accessing the binding in your Durable Object.

// ── worker-configuration.d.ts ──
interface Env {
  // Durable Object namespace for the workspace
  ContainerExample: DurableObjectNamespace<import("./src/index.js").ContainerExample>;
  // ← Loader binding created by wrangler.jsonc
  LOADER: WorkerLoader;
  // Optional: other bindings
  Bucket: R2Bucket;
}

The example at examples/worker-shell/worker-configuration.d.ts shows this declaration in practice.

Pass the Loader to the Backend Constructor

Inside your Durable Object's constructor or withWorkspace mixin, instantiate the backend and supply env.LOADER as the loader option.

Worker-Shell Backend

// ── Durable Object with worker-shell backend ──
export class ContainerExample extends withWorkspace(class extends DurableObject<Env> {}, (self) => {
  const { ctx, env } = self as unknown as { ctx: DurableObjectState; env: Env };
  return {
    storage: ctx.storage as unknown as DurableObjectStorageLike,
    backends: [
      new WorkerShellBackend({
        loader: env.LOADER,
        workspace: { binding: "ContainerExample", id: ctx.id.toString() },
        ctx,
        // Optional: restrict to specific command groups
        commands: [/* import @cloudflare/computer/shell/... */],
      }),
    ],
    mounts: { "/workspace/r2": R2Bucket(env.Bucket) },
  };
}) {}

The constructor signature at packages/computer/src/backends/worker-shell/worker-shell.ts accepts loader as a required option. Real-world usage appears in examples/worker-shell/src/index.ts at lines 66-70.

Worker-JavaScript Backend

// ── Durable Object with worker-javascript backend ──
export class ContainerExample extends withWorkspace(class extends DurableObject<Env> {}, (self) => {
  const { ctx, env } = self as unknown as { ctx: DurableObjectState; env: Env };
  return {
    storage: ctx.storage as unknown as DurableObjectStorageLike,
    backends: [
      new WorkerJavaScriptBackend({
        loader: env.LOADER,
        // Optional: customize compatibility settings
        compatibilityDate: "2026-05-23",
        compatibilityFlags: ["nodejs_compat"],
      }),
    ],
    mounts: { "/workspace/r2": R2Bucket(env.Bucket) },
  };
}) {}

The WorkerJavaScriptBackend constructor at packages/computer/src/backends/worker-javascript/worker-javascript.ts (lines 45-51) consumes the same loader option.

Optional: Adjust Compatibility Settings

Both backends accept compatibilityDate and compatibilityFlags to control the Dynamic Worker's runtime behavior. Default values are defined in the source code:

• WorkerShellBackend: DEFAULT_COMPAT_DATE and DEFAULT_COMPAT_FLAGS at packages/computer/src/backends/worker-shell/worker-shell.ts lines 37-38
• WorkerJavaScriptBackend: DEFAULT_COMPAT_DATE and DEFAULT_COMPAT_FLAGS at packages/computer/src/backends/worker-javascript/worker-javascript.ts lines 83-86

Override these when you need specific runtime compatibility for your use case.

Deploy the Worker

Run wrangler publish to deploy, or npm run dev for local testing. With the loader binding configured, your Worker can now create Dynamic Workers on-demand. The WorkerLoader implements a minimal Cloudflare Workers API (WorkerLoader.get(...)) that the backend uses to request a fresh Dynamic Worker for each execution request.

Summary

• Declare the worker_loaders binding in wrangler.jsonc — both backends use the same configuration pattern
• Type the LOADER property in worker-configuration.d.ts for TypeScript safety
• Pass env.LOADER to the WorkerShellBackend or WorkerJavaScriptBackend constructor
• Optionally override compatibilityDate and compatibilityFlags per backend
• Deploy with wrangler publish to enable dynamic Worker creation

Frequently Asked Questions

What happens if I forget to add the worker_loaders binding?

The backend will fail at runtime with an undefined loader error. Both WorkerShellBackend and WorkerJavaScriptBackend require loader as a mandatory constructor option — no default fallback exists. The TypeScript type system will flag this if you've properly declared LOADER: WorkerLoader in your Env interface.

Can I use the same loader binding for multiple backends?

Yes. A single LOADER binding in wrangler.jsonc can be passed to multiple backend instances or even both backend types within the same Durable Object. The WorkerLoader is stateless and serves only as a factory for Dynamic Workers.

How do I troubleshoot Dynamic Worker creation failures?

Check the compatibilityDate and compatibilityFlags passed to your backend. The shell backend defaults to values defined at worker-shell.ts lines 37-38, while the JavaScript backend uses values at worker-javascript.ts lines 83-86. Mismatched or outdated compatibility settings often cause module loading failures in the spawned Dynamic Worker.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}