Effect HTTP API

In the tutorial, you built a Worker with manual if/else routing and raw request parsing. That works, but as your API grows you lose type safety at the boundary — request payloads aren’t validated, response shapes aren’t enforced, and errors slip through untyped.

Effect’s HttpApi module solves this. You declare endpoints with schemas for payloads, responses, and errors, then implement handlers against those schemas. The result is an HttpEffect — the same type a Worker’s fetch expects — so it plugs in directly.

The mental model we’ll follow is:

1. Define the schema and API outside the Worker. Both are pure descriptions and can be imported by clients.
2. Construct the service inside the Worker’s Init phase. The Init phase runs at plan time and runtime, so we only do pure construction here — we never yield* something that needs a request to exist.
3. Return { fetch } where fetch is an HttpEffect. That’s the value Workers invoke on every request.
4. Bonus: deploy, grab the URL, and call the API from a fully typed client.

1. Define the schema

Start with a domain model. The schema lives outside the Worker so the same file can be imported by clients without pulling in any runtime code.

src/task.ts

import * as Schema from "effect/Schema";

export class Task extends Schema.Class<Task>("Task")({
  id: Schema.String,
  title: Schema.String,
  completed: Schema.Boolean,
}) {}

export class TaskNotFound extends Schema.TaggedClass<TaskNotFound>()(
  "TaskNotFound",
  { id: Schema.String },
) {}

Schema.Class gives you a runtime-validated class with an inferred TypeScript type. Schema.TaggedClass gives you a typed error you can return from handlers and discriminate against on the client.

2. Declare the API

Endpoints are declarations — they describe (method, path, payload, success, error) without implementing anything yet. Putting them in their own file keeps the spec importable from both the server and a typed client.

src/api.ts

import * as Schema from "effect/Schema";
import * as HttpApi from "effect/unstable/httpapi/HttpApi";
import * as HttpApiEndpoint from "effect/unstable/httpapi/HttpApiEndpoint";
import * as HttpApiError from "effect/unstable/httpapi/HttpApiError";
import * as HttpApiGroup from "effect/unstable/httpapi/HttpApiGroup";
import { Task, TaskNotFound } from "./task.ts";

const getTask = HttpApiEndpoint.get("getTask", "/:id", {
  success: Task,
  error: Schema.Union(TaskNotFound, HttpApiError.InternalServerError),
});

const createTask = HttpApiEndpoint.post("createTask", "/", {
  success: Task,
  payload: Schema.Struct({
    title: Schema.String,
  }),
  error: HttpApiError.InternalServerError,
});

export class TasksGroup extends HttpApiGroup.make("Tasks")
  .add(getTask)
  .add(createTask) {}

export class TaskApi extends HttpApi.make("TaskApi").add(TasksGroup) {}

Nothing executes yet — TaskApi is purely a value-level description. The same TaskApi constant is what we’ll hand to the client at the end of this guide.

HttpApiError.InternalServerError is Effect’s built-in 500 error. Declaring it on every endpoint reserves a typed slot for “something went wrong on the server” — much better than the alternative (Effect.orDie everywhere, which drops the cause into a generic 500 with no logging). We’ll wire handlers to it in step 3b.

3. Build the Worker

Now we wire it up. Create src/worker.ts with an empty Init phase:

src/worker.ts

import * as Cloudflare from "alchemy/Cloudflare";
import * as Effect from "effect/Effect";

export default Cloudflare.Worker(
  "Worker",
  { main: import.meta.path },
  Effect.gen(function* () {
    return {};
  }),
);

The generator inside Cloudflare.Worker is the Init phase. It runs both at plan time (when Alchemy builds the deployment graph) and at runtime (when the Worker boots a fresh isolate). Anything you yield* here must be safe in both contexts — typically resource binding factories like R2Bucket.bind(...), never per-request work.

3a. Bind an R2 bucket for storage

Tasks need to live somewhere durable. Declare an R2Bucket resource and bind it inside Init — bind() returns a typed handle whose get / put / delete / list methods we’ll call from the handlers below.

src/bucket.ts

import * as Cloudflare from "alchemy/Cloudflare";

export const Tasks = Cloudflare.R2Bucket("Tasks");

import { Tasks } from "./bucket.ts";

export default Cloudflare.Worker(
  "Worker",
  { main: import.meta.path },
  Effect.gen(function* () {
    const tasks = yield* Cloudflare.R2Bucket.bind(Tasks);

    return {};
  }),
);

We’ll provide the runtime side of this binding (Cloudflare.R2BucketBindingLive) in step 3c when we wire up the fetch handler.

3b. Construct the handler group inside Init

HttpApiBuilder.group constructs a Layer that wires handlers into the API spec. It’s pure — it doesn’t run them. That makes it safe to call inside Init.

Don’t yield* HttpApiBuilder.layer(TaskApi) here — building the layer is fine, but actually executing the server requires an incoming request. Init only does construction; the work happens later, on each fetch call.

First, define a single helper that converts any unexpected failure into the typed InternalServerError we just declared, logging the underlying cause on the way out:

  Effect.gen(function* () {
    const tasks = yield* Cloudflare.R2Bucket.bind(Tasks);

    const toInternalError = (cause: unknown) =>
      Effect.logError("Worker handler failed", cause).pipe(
        Effect.andThen(Effect.fail(new HttpApiError.InternalServerError())),
      );

Now build the handlers. Each one ends in Effect.catch(toInternalError) so any unexpected error is logged and turned into a 500 — while typed errors like TaskNotFound stay in the error channel and reach the client unchanged:

    const tasksGroup = HttpApiBuilder.group(TaskApi, "Tasks", (handlers) =>
      handlers
        .handle("getTask", ({ path }) =>
          Effect.gen(function* () {
            const object = yield* tasks.get(path.id);
            if (!object) {
              return yield* Effect.fail(new TaskNotFound({ id: path.id }));
            }
            return Schema.decodeUnknownSync(Task)(JSON.parse(yield* object.text()));
          }).pipe(Effect.catch(toInternalError)),
        )
        .handle("createTask", ({ payload }) =>
          Effect.gen(function* () {
            const task = new Task({
              id: crypto.randomUUID(),
              title: payload.title,
              completed: false,
            });
            yield* tasks.put(task.id, JSON.stringify(task));
            return task;
          }).pipe(Effect.catch(toInternalError)),
        ),
    );

    return {};
  }),

Each handler receives a typed request. path.id is a string because that’s what the endpoint declared, and the return type must satisfy Task (or fail with TaskNotFound | InternalServerError). Mismatches are caught at compile time.

:::tip Prefer Effect.catch(toInternalError) over Effect.orDie Effect.orDie converts failures into defects, which the HttpApi runtime turns into a 500 — but the cause vanishes into the void unless you’ve wired up a separate logger. Effect.catch keeps the failure on the error channel: you log it once on the way out and fail with a typed InternalServerError that the client can discriminate against just like TaskNotFound. :::

3c. Return { fetch }

The return value of Init is the Worker’s surface — for a fetch-style Worker that means an object with a fetch field. The value of fetch must be an HttpEffect: an Effect that, given an HttpServerRequest, produces an HttpServerResponse.

We assemble it in three layers:

• HttpApiBuilder.layer(TaskApi) — the top-level API layer.
• Layer.provide(tasksGroup) — plug in the handlers we just built.
• Layer.provide([HttpPlatform.layer, Etag.layer]) — platform services the builder needs (content negotiation, ETag generation).
• HttpRouter.toHttpEffect — convert the assembled layer into an HttpEffect.

    return {
      fetch: HttpApiBuilder.layer(TaskApi).pipe(
        Layer.provide(tasksGroup),
        Layer.provide([HttpPlatform.layer, Etag.layer]),
        HttpRouter.toHttpEffect,
      ),
    };

Putting it together

Here’s the complete src/worker.ts:

src/worker.ts

import * as Cloudflare from "alchemy/Cloudflare";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Schema from "effect/Schema";
import * as Etag from "effect/unstable/http/Etag";
import * as HttpPlatform from "effect/unstable/http/HttpPlatform";
import * as HttpRouter from "effect/unstable/http/HttpRouter";
import * as HttpApiBuilder from "effect/unstable/httpapi/HttpApiBuilder";
import * as HttpApiError from "effect/unstable/httpapi/HttpApiError";
import { TaskApi } from "./api.ts";
import { Tasks } from "./bucket.ts";
import { Task, TaskNotFound } from "./task.ts";

export default Cloudflare.Worker(
  "Worker",
  { main: import.meta.path },
  Effect.gen(function* () {
    const tasks = yield* Cloudflare.R2Bucket.bind(Tasks);

    const toInternalError = (cause: unknown) =>
      Effect.logError("Worker handler failed", cause).pipe(
        Effect.andThen(Effect.fail(new HttpApiError.InternalServerError())),
      );

    const tasksGroup = HttpApiBuilder.group(TaskApi, "Tasks", (handlers) =>
      handlers
        .handle("getTask", ({ path }) =>
          Effect.gen(function* () {
            const object = yield* tasks.get(path.id);
            if (!object) {
              return yield* Effect.fail(new TaskNotFound({ id: path.id }));
            }
            return Schema.decodeUnknownSync(Task)(
              JSON.parse(yield* object.text()),
            );
          }).pipe(Effect.catch(toInternalError)),
        )
        .handle("createTask", ({ payload }) =>
          Effect.gen(function* () {
            const task = new Task({
              id: crypto.randomUUID(),
              title: payload.title,
              completed: false,
            });
            yield* tasks.put(task.id, JSON.stringify(task));
            return task;
          }).pipe(Effect.catch(toInternalError)),
        ),
    );

    return {
      fetch: HttpApiBuilder.layer(TaskApi).pipe(
        Layer.provide(tasksGroup),
        Layer.provide([HttpPlatform.layer, Etag.layer]),
        HttpRouter.toHttpEffect,
      ),
    };
  }).pipe(Effect.provide(Cloudflare.R2BucketBindingLive)),
);

4. Add to the Stack

alchemy.run.ts

import * as Alchemy from "alchemy";
import * as Cloudflare from "alchemy/Cloudflare";
import * as Effect from "effect/Effect";
import Worker from "./src/worker.ts";

export default Alchemy.Stack(
  "TaskApi",
  { providers: Cloudflare.providers() },
  Effect.gen(function* () {
    const worker = yield* Worker;
    return { url: worker.url };
  }),
);

5. Deploy

alchemy deploy

You can hit it directly with curl:

curl -X POST https://your-worker.workers.dev/ \
  -H "Content-Type: application/json" \
  -d '{"title": "Write docs"}'
# → {"id":"...","title":"Write docs","completed":false}

curl https://your-worker.workers.dev/<id>
# → {"id":"...","title":"Write docs","completed":false}

Invalid payloads get automatic 400 responses with structured validation errors — no manual checking needed.

Bonus: call it from a typed client

Because TaskApi is just a value, the same spec drives a fully typed client. There’s no codegen step — HttpApiClient.make produces methods whose argument and return types come straight from the endpoint schemas.

scripts/client.ts

import * as Effect from "effect/Effect";
import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
import { TaskApi } from "../src/api.ts";

const program = Effect.gen(function* () {
  const client = yield* HttpApiClient.make(TaskApi, {
    baseUrl: process.env.TASK_API_URL!,
  });

  const created = yield* client.Tasks.createTask({
    payload: { title: "Write docs" },
  });
  console.log("Created:", created.id);

  const fetched = yield* client.Tasks.getTask({
    path: { id: created.id },
  });
  console.log("Fetched:", fetched.title);
});

Effect.runPromise(program);

Get the URL from the deploy output and run it:

TASK_API_URL=https://your-worker.workers.dev bun scripts/client.ts

client.Tasks.getTask returns Effect<Task, TaskNotFound | InternalServerError | HttpClientError>. Each branch is a real typed value you can pattern-match on with Effect.catchTag — not an HTTP status code you have to interpret. InternalServerError is exactly what you’d otherwise have to guess from a bare 500.

Recap

• The schema (Task, TaskNotFound) and the API spec (TaskApi) live outside the Worker — they’re pure descriptions.
• Every endpoint declares error: HttpApiError.InternalServerError (or a union with it), so unexpected failures have a typed home — never Effect.orDie.
• The handlers are constructed inside the Worker’s Init phase closure. We build a Layer with HttpApiBuilder.group but never yield* the running server — that only makes sense per-request. Each handler ends in Effect.catch(toInternalError) so unexpected errors are logged and wrapped in InternalServerError.
• The Worker’s surface is { fetch }, where fetch is an HttpEffect produced by HttpRouter.toHttpEffect.
• The same TaskApi value drives a fully typed client via HttpApiClient.make — no codegen, no string URLs. Errors come back as discriminated typed values, including InternalServerError for the server-side 500 case.