create-effect-project 0.1.0

package/templates/alchemy-http/runtime/node/client.ts

@@ -0,0 +1,37 @@
+/**
+ * Client entrypoint — exercises the API with the generated typed client.
+ *
+ * Point it at the deployed Worker, or at `{{runCmd}} dev`:
+ *
+ *   API_URL=https://... {{runCmd}} client
+ */
+import { NodeRuntime } from "@effect/platform-node"
+import { Effect } from "effect"
+import { ApiClient } from "./client/ApiClient.ts"
+import { NoteId } from "./domain/Note.ts"
+
+const program = Effect.gen(function*() {
+  const client = yield* ApiClient
+
+  // `system` is a top level group, so its endpoints sit at the root.
+  yield* client.health()
+  yield* Effect.logInfo("health: ok")
+
+  const created = yield* client.notes.create({ payload: { title: "first", body: "hello" } })
+  yield* Effect.logInfo("created", created)
+
+  const fetched = yield* client.notes.getById({ params: { id: created.id } })
+  yield* Effect.logInfo("getById", fetched)
+
+  const all = yield* client.notes.list()
+  yield* Effect.logInfo("list", all)
+
+  // Errors are typed too: an unknown id fails with `NoteNotFound`, which the
+  // Worker returns as a 404.
+  const missing = yield* client.notes.getById({ params: { id: NoteId.make("nope") } }).pipe(
+    Effect.catchTag("NoteNotFound", () => Effect.succeed("NoteNotFound (404) as expected"))
+  )
+  yield* Effect.logInfo("getById?id=nope", missing)
+}).pipe(Effect.provide(ApiClient.layer))
+
+program.pipe(NodeRuntime.runMain)

package/templates/alchemy-http/runtime/node/http.test.ts

@@ -0,0 +1,48 @@
+import { assert, describe, it } from "@effect/vitest"
+import type { Scope } from "effect"
+import { Effect, Layer, References } from "effect"
+import { HttpServer } from "effect/unstable/http"
+import { HttpApiTest } from "effect/unstable/httpapi"
+import { Api } from "../../api/Api.ts"
+import { NoteId } from "../../domain/Note.ts"
+import { Notes } from "../Notes.ts"
+import { NotesApiHandlersNoDeps } from "./http.ts"
+
+// Handlers wired to the in-memory Notes, so the whole HTTP pipeline runs
+// without a server: same encoding, routing and decoding as production.
+const TestLayer = Layer.mergeAll(
+  NotesApiHandlersNoDeps.pipe(Layer.provide(Notes.layerMemory)),
+  HttpServer.layerServices
+)
+
+const makeClient = HttpApiTest.groups(Api, ["notes"])
+
+const run = <A, E, R>(layer: Layer.Layer<R>, effect: Effect.Effect<A, E, R | Scope.Scope>) =>
+  effect.pipe(
+    Effect.scoped,
+    Effect.provide(layer),
+    // Keep the test output to the assertions; raise this to see app logs.
+    Effect.provideService(References.MinimumLogLevel, "None")
+  )
+
+describe("notes api", () => {
+  it.effect("creates then lists a note", () =>
+    run(TestLayer, Effect.gen(function*() {
+      const client = yield* makeClient
+      const created = yield* client.notes.create({ payload: { title: "first", body: "hello" } })
+      assert.strictEqual(created.title, "first")
+
+      const listed = yield* client.notes.list()
+      assert.strictEqual(listed.length, 1)
+      assert.strictEqual(listed[0]?.id, created.id)
+    })))
+
+  it.effect("fails with NoteNotFound for an unknown id", () =>
+    run(TestLayer, Effect.gen(function*() {
+      const client = yield* makeClient
+      const error = yield* Effect.flip(
+        client.notes.getById({ params: { id: NoteId.make("nope") } })
+      )
+      assert.strictEqual(error._tag, "NoteNotFound")
+    })))
+})

package/templates/alchemy-http/src/worker.ts

@@ -0,0 +1,22 @@
+/**
+ * Cloudflare Worker entrypoint.
+ *
+ * The same `AllRoutes` the local server uses, converted to a fetch handler
+ * instead of being bound to a port. Nothing under `src/api`, `src/server` or
+ * `src/client` changes between the two — one HttpApi definition, two targets.
+ */
+import * as Cloudflare from "alchemy/Cloudflare"
+import * as Effect from "effect/Effect"
+import { HttpRouter, HttpServer } from "effect/unstable/http"
+import { AllRoutes } from "./server/http.ts"
+
+export default Cloudflare.Worker(
+  "{{name}}",
+  { main: import.meta.url },
+  Effect.succeed({
+    // `layerServices` supplies the file-serving services the OpenAPI and Scalar
+    // routes ask for, backed by a no-op filesystem — a Worker has no disk, and
+    // those routes serve generated content rather than files.
+    fetch: HttpRouter.toHttpEffect(AllRoutes).pipe(Effect.provide(HttpServer.layerServices))
+  })
+)

package/templates/alchemy-rpc/README.md

@@ -0,0 +1,83 @@
+# {{name}}
+
+An Effect v4 RPC service deployed to a Cloudflare Worker with
+[Alchemy](https://alchemy.run) — infrastructure as Effects, no YAML and no `wrangler.toml`.
+
+## Run it
+
+```bash
+npx alchemy login       # once, connects your Cloudflare account
+{{runCmd}} dev          # local
+{{runCmd}} plan         # what would change
+{{runCmd}} deploy       # apply it — prints the URL
+{{runCmd}} destroy      # tear it down
+```
+
+## RPC instead of HTTP
+
+`src/rpc.ts` declares the contract once. The server's handler types and the client's method
+signatures both come from it, so a rename or a schema change is a compile error on both sides:
+
+```ts
+const getById = Rpc.make("getById", {
+  success: Note,
+  error: NoteNotFound,
+  payload: { id: NoteId }
+})
+```
+
+Calling it is a method call, not a request:
+
+```ts
+const client = yield* RpcClient.make(NotesRpcs)
+const note = yield* client.getById({ id })
+```
+
+The difference from the HttpApi templates is what crosses the wire. `NoteNotFound` arrives as
+**itself** — `Effect.catchTag("NoteNotFound", ...)` on the client — rather than as a 404 the caller
+has to interpret. There are no paths, no verbs and no status codes to agree on. What you give up is
+everything that comes from being ordinary HTTP: no OpenAPI document, no Scalar page, and no `curl`.
+
+Scaffold `--template alchemy-http` instead if you want a public, documented API.
+
+## What's here
+
+| File | What |
+| --- | --- |
+| `src/rpc.ts` | The contract — `Rpc.make` procedures collected into an `RpcGroup` |
+| `src/domain/Note.ts` | The domain: a `Schema.Class`, a branded `NoteId`, a `NoteNotFound` error |
+| `src/server/Notes.ts` | The `Notes` service — plain business logic, knows nothing about RPC |
+| `src/server/Notes/rpc.ts` | The handlers: a thin adapter from the group onto that service |
+| `src/worker.ts` | The Worker — `RpcWorker` takes the group as `schema` |
+| `alchemy.run.ts` | The stack |
+| `src/client.ts` | A runnable demo client |
+
+`src/server/Notes.ts` is the same file the HTTP templates use. Logic lives there and the transport
+adapter is `src/server/Notes/rpc.ts`, so moving between RPC and HTTP touches one file.
+
+## Infrastructure
+
+`alchemy.run.ts` is ordinary TypeScript returning an Effect. Adding a bucket is a value, not a
+config file:
+
+```ts
+const Uploads = Cloudflare.R2.Bucket("Uploads")
+// then, inside the worker's init:
+const uploads = yield* Cloudflare.R2.ReadWriteBucket(Uploads)
+```
+
+## Tests
+
+```bash
+{{runCmd}} test
+```
+
+`RpcTest.makeClient` runs the real encode/decode round trip against the handlers in-process — no
+Worker, no port, and no Cloudflare account. These are the tests CI can run.
+
+## Telemetry
+
+Not wired up. OTLP export from inside a Worker isolate is not the right shape for Cloudflare —
+use [Workers Observability](https://developers.cloudflare.com/workers/observability/) or a
+[tail worker](https://developers.cloudflare.com/workers/observability/logs/tail-workers/), and
+`{{runCmd}} tail` to stream logs. That is why `--otel` does not apply to this template.

package/templates/alchemy-rpc/alchemy.run.ts

@@ -0,0 +1,22 @@
+/**
+ * The stack: what gets deployed, and what it reports back.
+ *
+ *   {{runCmd}} plan      # what would change
+ *   {{runCmd}} deploy    # apply it, prints the URL
+ *   {{runCmd}} destroy   # tear it down
+ *
+ * Deploying needs a Cloudflare account — `npx alchemy login` once.
+ */
+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(
+  "{{name}}",
+  { providers: Cloudflare.providers(), state: Cloudflare.state() },
+  Effect.gen(function*() {
+    const worker = yield* Worker
+    return { url: worker.url }
+  })
+)

package/templates/alchemy-rpc/runtime/bun/_package.json

@@ -0,0 +1,27 @@
+{
+  "name": "{{name}}",
+  "module": "src/worker.ts",
+  "type": "module",
+  "private": true,
+  "engines": { "bun": ">=1.3.0" },
+  "scripts": {
+    "dev": "alchemy dev",
+    "plan": "alchemy plan",
+    "deploy": "alchemy deploy",
+    "destroy": "alchemy destroy",
+    "tail": "alchemy tail",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "client": "bun src/client.ts"
+  },
+  "dependencies": {
+    "@effect/platform-bun": "4.0.0-rc.112",
+    "alchemy": "2.0.0-beta.74",
+    "effect": "4.0.0-rc.112"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260827.0",
+    "@types/bun": "^1.4.0",
+    "typescript": "7.0.2"
+  }
+}

package/templates/alchemy-rpc/runtime/bun/_tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "ESNext",
+      "DOM"
+    ],
+    "target": "ESNext",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "types": [
+      "@cloudflare/workers-types",
+      "bun"
+    ],
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true
+  },
+  "include": [
+    "src",
+    "alchemy.run.ts"
+  ]
+}

package/templates/alchemy-rpc/runtime/bun/client.ts

@@ -0,0 +1,43 @@
+/**
+ * Client entrypoint — calls the RPC group as ordinary typed methods.
+ *
+ * Point it at the deployed Worker, or at `{{runCmd}} dev`:
+ *
+ *   API_URL=https://... {{runCmd}} client
+ */
+import { BunRuntime } from "@effect/platform-bun"
+import { Effect, Layer } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+import { RpcClient, RpcSerialization } from "effect/unstable/rpc"
+import { baseUrl } from "./config.ts"
+import { NoteId } from "./domain/Note.ts"
+import { NotesRpcs } from "./rpc.ts"
+
+const program = Effect.gen(function*() {
+  // The client's methods are derived from the group, so this call is checked
+  // against the server's handler at compile time.
+  const client = yield* RpcClient.make(NotesRpcs)
+
+  const created = yield* client.create({ title: "first", body: "hello" })
+  yield* Effect.logInfo("created", created)
+
+  const fetched = yield* client.getById({ id: created.id })
+  yield* Effect.logInfo("getById", fetched)
+
+  const all = yield* client.list()
+  yield* Effect.logInfo("list", all)
+
+  // The error arrives as `NoteNotFound` itself — no status code to decode.
+  const missing = yield* client.getById({ id: NoteId.make("nope") }).pipe(
+    Effect.catchTag("NoteNotFound", (error) => Effect.succeed(`no note ${error.id} — handled`))
+  )
+  yield* Effect.logInfo("getById?id=nope", missing)
+})
+
+const ClientLayer = Layer.unwrap(Effect.map(baseUrl, (url) =>
+  RpcClient.layerProtocolHttp({ url }).pipe(
+    Layer.provide(FetchHttpClient.layer),
+    Layer.provide(RpcSerialization.layerNdjson)
+  )))
+
+program.pipe(Effect.scoped, Effect.provide(ClientLayer), BunRuntime.runMain)

package/templates/alchemy-rpc/runtime/bun/rpc.test.ts

@@ -0,0 +1,40 @@
+import { expect, test } from "bun:test"
+import { Effect, type Layer, References, type Scope } from "effect"
+import { RpcTest } from "effect/unstable/rpc"
+import { NoteId } from "../../domain/Note.ts"
+import { NotesRpcs } from "../../rpc.ts"
+import { NotesRpcHandlers } from "./rpc.ts"
+
+// `RpcTest.makeClient` runs the real encode/decode round trip against the
+// handlers in-process: no Worker, no port, no Cloudflare account.
+//
+// `runPromise` demands a fully-provided effect, so R is pinned to exactly what
+// NotesRpcHandlers supplies rather than left generic.
+type Handlers = Layer.Success<typeof NotesRpcHandlers>
+
+const run = <A, E>(effect: Effect.Effect<A, E, Handlers | Scope.Scope>) =>
+  effect.pipe(
+    Effect.provide(NotesRpcHandlers),
+    // Keep the output to the assertions; raise this to see app logs.
+    Effect.provideService(References.MinimumLogLevel, "None"),
+    Effect.scoped,
+    Effect.runPromise
+  )
+
+test("creates then lists a note", () =>
+  run(Effect.gen(function*() {
+    const client = yield* RpcTest.makeClient(NotesRpcs)
+    const created = yield* client.create({ title: "first", body: "hello" })
+    expect(created.title).toBe("first")
+
+    const listed = yield* client.list()
+    expect(listed.length).toBe(1)
+    expect(listed[0]?.id).toBe(created.id)
+  })))
+
+test("fails with NoteNotFound for an unknown id", () =>
+  run(Effect.gen(function*() {
+    const client = yield* RpcTest.makeClient(NotesRpcs)
+    const error = yield* Effect.flip(client.getById({ id: NoteId.make("nope") }))
+    expect(error._tag).toBe("NoteNotFound")
+  })))

package/templates/alchemy-rpc/runtime/node/_package.json

@@ -0,0 +1,28 @@
+{
+  "name": "{{name}}",
+  "type": "module",
+  "private": true,
+  "engines": { "node": ">=22.6.0" },
+  "scripts": {
+    "dev": "alchemy dev",
+    "plan": "alchemy plan",
+    "deploy": "alchemy deploy",
+    "destroy": "alchemy destroy",
+    "tail": "alchemy tail",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "client": "node --experimental-strip-types src/client.ts"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-rc.112",
+    "alchemy": "2.0.0-beta.74",
+    "effect": "4.0.0-rc.112"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260827.0",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/node": "^26.4.0",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11"
+  }
+}

package/templates/alchemy-rpc/runtime/node/_tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "ESNext",
+      "DOM"
+    ],
+    "target": "ESNext",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "types": [
+      "@cloudflare/workers-types",
+      "node"
+    ],
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true
+  },
+  "include": [
+    "src",
+    "alchemy.run.ts"
+  ]
+}

package/templates/alchemy-rpc/runtime/node/client.ts

@@ -0,0 +1,43 @@
+/**
+ * Client entrypoint — calls the RPC group as ordinary typed methods.
+ *
+ * Point it at the deployed Worker, or at `{{runCmd}} dev`:
+ *
+ *   API_URL=https://... {{runCmd}} client
+ */
+import { NodeRuntime } from "@effect/platform-node"
+import { Effect, Layer } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+import { RpcClient, RpcSerialization } from "effect/unstable/rpc"
+import { baseUrl } from "./config.ts"
+import { NoteId } from "./domain/Note.ts"
+import { NotesRpcs } from "./rpc.ts"
+
+const program = Effect.gen(function*() {
+  // The client's methods are derived from the group, so this call is checked
+  // against the server's handler at compile time.
+  const client = yield* RpcClient.make(NotesRpcs)
+
+  const created = yield* client.create({ title: "first", body: "hello" })
+  yield* Effect.logInfo("created", created)
+
+  const fetched = yield* client.getById({ id: created.id })
+  yield* Effect.logInfo("getById", fetched)
+
+  const all = yield* client.list()
+  yield* Effect.logInfo("list", all)
+
+  // The error arrives as `NoteNotFound` itself — no status code to decode.
+  const missing = yield* client.getById({ id: NoteId.make("nope") }).pipe(
+    Effect.catchTag("NoteNotFound", (error) => Effect.succeed(`no note ${error.id} — handled`))
+  )
+  yield* Effect.logInfo("getById?id=nope", missing)
+})
+
+const ClientLayer = Layer.unwrap(Effect.map(baseUrl, (url) =>
+  RpcClient.layerProtocolHttp({ url }).pipe(
+    Layer.provide(FetchHttpClient.layer),
+    Layer.provide(RpcSerialization.layerNdjson)
+  )))
+
+program.pipe(Effect.scoped, Effect.provide(ClientLayer), NodeRuntime.runMain)

package/templates/alchemy-rpc/runtime/node/rpc.test.ts

@@ -0,0 +1,41 @@
+import { assert, describe, it } from "@effect/vitest"
+import { Effect, type Layer, References, type Scope } from "effect"
+import { RpcTest } from "effect/unstable/rpc"
+import { NoteId } from "../../domain/Note.ts"
+import { NotesRpcs } from "../../rpc.ts"
+import { NotesRpcHandlers } from "./rpc.ts"
+
+// `RpcTest.makeClient` runs the real encode/decode round trip against the
+// handlers in-process: no Worker, no port, no Cloudflare account.
+//
+// R is pinned to exactly what NotesRpcHandlers supplies rather than left
+// generic, so an unprovided requirement is a compile error here.
+type Handlers = Layer.Success<typeof NotesRpcHandlers>
+
+const run = <A, E>(effect: Effect.Effect<A, E, Handlers | Scope.Scope>) =>
+  effect.pipe(
+    Effect.provide(NotesRpcHandlers),
+    // Keep the output to the assertions; raise this to see app logs.
+    Effect.provideService(References.MinimumLogLevel, "None"),
+    Effect.scoped
+  )
+
+describe("notes rpc", () => {
+  it.effect("creates then lists a note", () =>
+    run(Effect.gen(function*() {
+      const client = yield* RpcTest.makeClient(NotesRpcs)
+      const created = yield* client.create({ title: "first", body: "hello" })
+      assert.strictEqual(created.title, "first")
+
+      const listed = yield* client.list()
+      assert.strictEqual(listed.length, 1)
+      assert.strictEqual(listed[0]?.id, created.id)
+    })))
+
+  it.effect("fails with NoteNotFound for an unknown id", () =>
+    run(Effect.gen(function*() {
+      const client = yield* RpcTest.makeClient(NotesRpcs)
+      const error = yield* Effect.flip(client.getById({ id: NoteId.make("nope") }))
+      assert.strictEqual(error._tag, "NoteNotFound")
+    })))
+})

package/templates/alchemy-rpc/src/rpc.ts

@@ -0,0 +1,29 @@
+/**
+ * The RPC contract.
+ *
+ * One declaration produces the server's handler types and the client's method
+ * signatures, so a rename or a schema change is a compile error on both sides —
+ * the same guarantee `HttpApi` gives, without HTTP semantics in the way.
+ */
+import { Schema } from "effect"
+import { Rpc, RpcGroup } from "effect/unstable/rpc"
+import { Note, NoteCreate, NoteId, NoteNotFound } from "./domain/Note.ts"
+
+const list = Rpc.make("list", {
+  success: Schema.Array(Note)
+})
+
+const getById = Rpc.make("getById", {
+  success: Note,
+  // Typed failures cross the wire as themselves: the client gets a
+  // `NoteNotFound`, not a status code it has to interpret.
+  error: NoteNotFound,
+  payload: { id: NoteId }
+})
+
+const create = Rpc.make("create", {
+  success: Note,
+  payload: NoteCreate.fields
+})
+
+export class NotesRpcs extends RpcGroup.make(list, getById, create) {}

package/templates/alchemy-rpc/src/server/Notes/rpc.ts

@@ -0,0 +1,17 @@
+import { Effect, Layer } from "effect"
+import { NotesRpcs } from "../../rpc.ts"
+import { Notes } from "../Notes.ts"
+
+/**
+ * The handlers are a thin adapter over the `Notes` service — the same service
+ * the HTTP templates use. Business logic lives in `src/server/Notes.ts` and
+ * knows nothing about RPC, so swapping the transport touches only this file.
+ */
+export const NotesRpcHandlers = NotesRpcs.toLayer(Effect.gen(function*() {
+  const notes = yield* Notes
+  return {
+    list: () => notes.list,
+    getById: ({ id }) => notes.getById(id),
+    create: (payload) => notes.create(payload)
+  }
+})).pipe(Layer.provide(Notes.layerMemory))

package/templates/alchemy-rpc/src/worker.ts

@@ -0,0 +1,24 @@
+/**
+ * Cloudflare Worker entrypoint.
+ *
+ * `RpcWorker` takes the group as `schema`, so the deployed Worker and any
+ * consumer that imports this class agree on the contract by construction.
+ */
+import * as Cloudflare from "alchemy/Cloudflare"
+import { Effect, Layer } from "effect"
+import { RpcSerialization, RpcServer } from "effect/unstable/rpc"
+import { NotesRpcs } from "./rpc.ts"
+import { NotesRpcHandlers } from "./server/Notes/rpc.ts"
+
+export default class Worker extends Cloudflare.RpcWorker<Worker>()(
+  "{{name}}",
+  { main: import.meta.url, schema: NotesRpcs },
+  // `Effect.succeed` rather than `Effect.gen`: the outer effect is one-time
+  // init, the inner one serves each request. Returning the inner effect from a
+  // generator produces the same nesting but reads like a mistake.
+  Effect.succeed(
+    RpcServer.toHttpEffect(NotesRpcs).pipe(
+      Effect.provide(Layer.mergeAll(NotesRpcHandlers, RpcSerialization.layerNdjson))
+    )
+  )
+) {}

package/templates/basic/README.md

@@ -0,0 +1,53 @@
+# {{name}}
+
+A plain Effect v4 program — a service, a typed error, and a `main` that runs and exits.
+No server, no build step: the runtime executes TypeScript directly.
+
+## Run it
+
+```bash
+{{runCmd}} dev      # watch mode
+{{runCmd}} start    # once
+{{runCmd}} test
+```
+
+## What's here
+
+| File | What |
+| --- | --- |
+| `src/domain/User.ts` | The domain: a `Schema.Class`, a branded `UserId`, and a `UserNotFound` error |
+| `src/Users.ts` | A `Context.Service` — an interface, a tag, and `layerMemory` supplying it |
+| `src/main.ts` | The program: create, fetch, list, and handle the failure |
+| `src/Users.test.ts` | Tests against the real layer |
+
+## The shape to copy
+
+`src/Users.ts` is the pattern worth reusing. The interface is what callers depend on;
+`layerMemory` is one implementation of it. Replacing it with a database-backed layer is a
+change to that one file — `main.ts` and the tests keep compiling, because neither mentions
+the implementation.
+
+Failures work the same way. `getById` returns `Effect<User, UserNotFound>`, so the error is
+part of the type. `main.ts` has to handle it; deleting the `Effect.catchTag` is a compile
+error rather than an unhandled rejection in production.
+
+## Tests
+
+```bash
+{{runCmd}} test
+```
+
+They run against `Users.layerMemory` — the real implementation, not a mock. When you add a
+database layer, keep the in-memory one for tests: the seam is the layer, so nothing needs
+stubbing.
+
+## Telemetry
+
+`src/observability.ts` exports logs, metrics and traces over OTLP/HTTP. It is a no-op unless
+`OTEL_EXPORTER_OTLP_ENDPOINT` is set:
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 {{runCmd}} start
+```
+
+The `Effect.fn("Users.getById")` names in `src/Users.ts` are the span names you will see.

package/templates/basic/runtime/bun/Users.test.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "bun:test"
+import { Effect, References } from "effect"
+import { UserId } from "./domain/User.ts"
+import { Users } from "./Users.ts"
+
+// Tests run against the real layer, not a mock: `layerMemory` IS the seam.
+const run = <A, E>(effect: Effect.Effect<A, E, Users>) =>
+  effect.pipe(
+    Effect.provide(Users.layerMemory),
+    // Keep the output to the assertions; raise this to see app logs.
+    Effect.provideService(References.MinimumLogLevel, "None"),
+    Effect.runPromise
+  )
+
+test("creates then lists a user", () =>
+  run(Effect.gen(function*() {
+    const users = yield* Users
+    const created = yield* users.create({ name: "Ada", email: "ada@example.com" })
+    expect(created.name).toBe("Ada")
+
+    const listed = yield* users.list
+    expect(listed.length).toBe(1)
+    expect(listed[0]?.id).toBe(created.id)
+  })))
+
+test("fails with UserNotFound for an unknown id", () =>
+  run(Effect.gen(function*() {
+    const users = yield* Users
+    const error = yield* Effect.flip(users.getById(UserId.make("nope")))
+    expect(error._tag).toBe("UserNotFound")
+  })))