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

> Learn how to configure Worker Loader binding for worker-shell and worker-javascript backends. Master this crucial step for effective Cloudflare Worker deployment with wrangler.jsonc and TypeScript.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-08-16

---

**The worker-shell and worker-javascript backends require a Worker Loader binding declared in `wrangler.jsonc`, typed in [`worker-configuration.d.ts`](https://github.com/cloudflare/computer/blob/main/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.

```jsonc
// ── 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.

```typescript
// ── 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`](https://github.com/cloudflare/computer/blob/main/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

```typescript
// ── 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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/examples/worker-shell/src/index.ts) at lines 66-70.

### Worker-JavaScript Backend

```typescript
// ── 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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/worker-shell.ts) lines 37-38, while the JavaScript backend uses values at [`worker-javascript.ts`](https://github.com/cloudflare/computer/blob/main/worker-javascript.ts) lines 83-86. Mismatched or outdated compatibility settings often cause module loading failures in the spawned Dynamic Worker.