create-effect-project 0.1.0

package/templates/fullstack/apps/web/runtime/node/NotesApi.test.ts

@@ -0,0 +1,65 @@
+import { Api } from "@{{name}}/api/api"
+import { Effect, Layer } from "effect"
+import { HttpClient, HttpClientResponse } from "effect/unstable/http"
+import { AsyncResult, Atom, AtomHttpApi, AtomRegistry, Hydration } from "effect/unstable/reactivity"
+import { expect, test } from "vitest"
+import { notesList } from "./NotesApi.ts"
+
+const stubNotes = [{ id: "1", title: "first", body: "hello" }]
+
+let requests = 0
+
+const StubHttpClient = Layer.succeed(
+  HttpClient.HttpClient,
+  HttpClient.make((request) => {
+    requests++
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(
+        request,
+        new Response(JSON.stringify(stubNotes), {
+          status: 200,
+          headers: { "content-type": "application/json" }
+        })
+      )
+    )
+  })
+)
+
+class StubApi extends AtomHttpApi.Service<StubApi>()("test/StubApi", {
+  api: Api,
+  httpClient: StubHttpClient,
+  baseUrl: "http://localhost"
+}) {}
+
+// Same group, endpoint and serializationKey as the shipped atom, so it produces
+// the same registry key: `AtomHttpApi:notes:list:notes/list`.
+const listQuery = Atom.keepAlive(
+  StubApi.query("notes", "list", { serializationKey: "notes/list" })
+)
+
+test("dehydrates a resolved list and hydrates it without refetching", async () => {
+  requests = 0
+
+  const server = AtomRegistry.make()
+  const notes = await Effect.runPromise(AtomRegistry.getResult(listQuery)(server))
+  expect(notes.length).toBe(1)
+  expect(requests).toBe(1)
+
+  const dehydrated = Hydration.toValues(Hydration.dehydrate(server))
+  expect(dehydrated.map((entry) => entry.key)).toContain("AtomHttpApi:notes:list:notes/list")
+
+  const client = AtomRegistry.make()
+  Hydration.hydrate(client, dehydrated)
+
+  const hydrated = client.get(listQuery)
+  expect(AsyncResult.isSuccess(hydrated)).toBe(true)
+  // The whole point: reading the atom on the "client" issued no second request.
+  expect(requests).toBe(1)
+})
+
+// Guards the shipped atom, not just the stub above: without a serializationKey
+// it would not be serializable, dehydrate would skip it, and SSR would silently
+// degrade into a client refetch.
+test("the shipped notesList atom is serializable", () => {
+  expect(Atom.isSerializable(notesList)).toBe(true)
+})

package/templates/fullstack/apps/web/runtime/node/_package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@{{name}}/web",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "//": "`routeTree.gen.ts` is generated by the TanStack Start plugin and gitignored, so a fresh clone has no file for tsc to read. Building first generates it.",
+    "pretypecheck": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@{{name}}/api": "{{workspaceVersion}}",
+    "@effect/atom-react": "4.0.0-rc.112",
+    "@tanstack/react-router": "^1.170.32",
+    "@tanstack/react-start": "^1.168.49",
+    "effect": "4.0.0-rc.112",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "typescript": "7.0.2",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
+  }
+}

package/templates/fullstack/apps/web/runtime/node/_tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src"]
+}

package/templates/fullstack/apps/web/src/atoms/NotesApi.ts

@@ -0,0 +1,40 @@
+/**
+ * The web app's data layer: query and mutation atoms derived from the same
+ * `HttpApi` definition the server implements, so a schema change is a compile
+ * error here too.
+ *
+ * This module reads `import.meta.env`, so it belongs to the web app and must
+ * not move into a package the server imports.
+ */
+import { Api } from "@{{name}}/api/api"
+import { FetchHttpClient } from "effect/unstable/http"
+import { Atom, AtomHttpApi } from "effect/unstable/reactivity"
+
+const baseUrl = import.meta.env.VITE_API_URL ?? "http://localhost:3000"
+
+export class NotesApi extends AtomHttpApi.Service<NotesApi>()("web/NotesApi", {
+  api: Api,
+  httpClient: FetchHttpClient.layer,
+  baseUrl
+}) {}
+
+export const notesList = Atom.keepAlive(
+  NotesApi.query("notes", "list", {
+    // The identity for the SSR -> client handoff. Without it the atom is not
+    // serializable, `Hydration.dehydrate` skips it, and the client refetches on
+    // mount — an app that looks right while doing the wrong thing. The
+    // round-trip test in this directory is what guards it.
+    serializationKey: "notes/list"
+  })
+)
+
+// `reactivityKeys` is deliberately absent. Combining it with `serializationKey`
+// breaks hydration in effect 4.0.0-rc.112: the preload seeds a node keyed by
+// object identity rather than the serialization string, so the first client
+// read refetches anyway. To retest after upgrading effect, add
+// `reactivityKeys: ["notes"]` to the query above and to the stub in
+// NotesApi.test.ts — if `expect(requests).toBe(1)` still fails, it is not fixed.
+//
+// Until then the list is refreshed explicitly after a successful mutation; see
+// routes/index.tsx.
+export const createNote = NotesApi.mutation("notes", "create")

package/templates/fullstack/apps/web/src/router.tsx

@@ -0,0 +1,64 @@
+import { RegistryContext } from "@effect/atom-react"
+import { createRouter } from "@tanstack/react-router"
+import { Schema } from "effect"
+import { AtomRegistry, Hydration } from "effect/unstable/reactivity"
+import { routeTree } from "./routeTree.gen"
+
+export interface RouterContext {
+  readonly registry: AtomRegistry.AtomRegistry
+}
+
+// The dehydrated envelope, as a schema rather than a cast. `JSON.parse` returns
+// `any`, and asserting a type onto it would only silence the compiler — this
+// decodes, so the shape that actually crossed the SSR boundary is checked.
+// `value` stays `Unknown` because it varies per atom; `Hydration.hydrate` hands
+// it to that atom's own decoder.
+const DehydratedAtoms = Schema.Array(Schema.Struct({
+  "~effect/reactivity/DehydratedAtom": Schema.Literal(true),
+  key: Schema.String,
+  value: Schema.Unknown,
+  dehydratedAt: Schema.Finite
+}))
+
+const decodeAtoms = Schema.decodeUnknownSync(DehydratedAtoms)
+
+export function getRouter() {
+  // One registry per call. On the server `getRouter` runs per request, so this
+  // is the isolation boundary that keeps one visitor's data out of another's
+  // render; on the client it runs once.
+  const registry = AtomRegistry.make()
+
+  return createRouter({
+    routeTree,
+    scrollRestoration: true,
+    context: { registry } satisfies RouterContext,
+    // Runs on the server after rendering: encodes every serializable atom into
+    // the payload TanStack Start injects into the HTML.
+    //
+    // The atoms are serialized to a string rather than handed over as objects.
+    // Start validates this return type at compile time and rejects any property
+    // typed `unknown`, since it cannot prove it JSON-safe — and
+    // `Hydration.DehydratedAtomValue.value` is `unknown` by design, because its
+    // shape varies per atom. Its contents come from `Schema.encodeSync`, so they
+    // are genuinely JSON-safe; a string says so in a way the type system can
+    // check, which beats widening the return to `any` and asserting it.
+    dehydrate: () => ({ atoms: JSON.stringify(Hydration.toValues(Hydration.dehydrate(registry))) }),
+    // Runs on the client before the first render, so the atoms are already
+    // Success by the time any component reads them.
+    hydrate: (dehydrated: { readonly atoms: string }) => {
+      Hydration.hydrate(registry, decodeAtoms(JSON.parse(dehydrated.atoms)))
+    },
+    // `@effect/atom-react`'s own `RegistryProvider` builds a registry from
+    // options, but ours has to be the per-request one created above — so the
+    // context is provided directly.
+    Wrap: ({ children }: { readonly children: React.ReactNode }) => (
+      <RegistryContext.Provider value={registry}>{children}</RegistryContext.Provider>
+    )
+  })
+}
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: ReturnType<typeof getRouter>
+  }
+}

package/templates/fullstack/apps/web/src/routes/__root.tsx

@@ -0,0 +1,38 @@
+import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from "@tanstack/react-router"
+import type { ReactNode } from "react"
+import type { RouterContext } from "../router.tsx"
+import appCss from "../styles.css?url"
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      { title: "Notes" }
+    ],
+    links: [{ rel: "stylesheet", href: appCss }]
+  }),
+  component: RootComponent
+})
+
+function RootComponent() {
+  return (
+    <RootDocument>
+      <Outlet />
+    </RootDocument>
+  )
+}
+
+function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
+  return (
+    <html>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}

package/templates/fullstack/apps/web/src/routes/index.tsx

@@ -0,0 +1,97 @@
+import { useAtomRefresh, useAtomSet, useAtomValue } from "@effect/atom-react"
+import { createFileRoute } from "@tanstack/react-router"
+import { Cause, Effect, Exit } from "effect"
+import { AsyncResult, AtomRegistry } from "effect/unstable/reactivity"
+import { useState } from "react"
+import { createNote, notesList } from "../atoms/NotesApi.ts"
+
+export const Route = createFileRoute("/")({
+  component: Home,
+  loader: async ({ context }) => {
+    // Populate the registry before rendering, so the markup ships with data and
+    // `dehydrate` has something to encode. The loader's job is to run the query,
+    // not to judge it — the outcome is rendered by the onFailure branch below
+    // rather than thrown into an error boundary.
+    //
+    // `Effect.exit`, not `Effect.ignore`: AtomHttpApi *dies* on a transport
+    // error rather than failing, and `ignore` only swallows failures — a defect
+    // escapes it and 500s the whole page when the API is unreachable. `exit`
+    // captures both, so an API that is down renders the error branch.
+    await Effect.runPromise(
+      Effect.exit(AtomRegistry.getResult(notesList)(context.registry))
+    )
+  }
+})
+
+function Home() {
+  const notes = useAtomValue(notesList)
+  const created = useAtomValue(createNote)
+  // `promiseExit` makes the mutation awaitable and hands back an Exit, so the
+  // submit handler can act on the outcome directly.
+  const submit = useAtomSet(createNote, { mode: "promiseExit" })
+  const refreshNotes = useAtomRefresh(notesList)
+  const [title, setTitle] = useState("")
+  const [body, setBody] = useState("")
+
+  return (
+    <main>
+      <h1>Notes</h1>
+
+      <form
+        onSubmit={async (event) => {
+          event.preventDefault()
+          if (title.trim() === "") return
+          const exit = await submit({ payload: { title, body } })
+          // Only a success clears the fields, so a failed submission leaves the
+          // user's input in place to retry. Reactivity keys would normally
+          // refresh the list; see the comment in atoms/NotesApi.ts for why the
+          // refresh is explicit instead.
+          if (Exit.isSuccess(exit)) {
+            refreshNotes()
+            setTitle("")
+            setBody("")
+          }
+        }}
+      >
+        <input
+          aria-label="Title"
+          placeholder="Title"
+          value={title}
+          onChange={(event) => setTitle(event.target.value)}
+        />
+        <textarea
+          aria-label="Body"
+          placeholder="Body"
+          rows={3}
+          value={body}
+          onChange={(event) => setBody(event.target.value)}
+        />
+        <button type="submit">Add note</button>
+      </form>
+
+      {AsyncResult.isFailure(created) && (
+        <p className="error">Could not add note: {Cause.pretty(created.cause)}</p>
+      )}
+
+      {AsyncResult.match(notes, {
+        // Hydration removes the loading state on first paint, but not on a
+        // client-side refetch of a cold atom, so this branch still earns its place.
+        onInitial: () => <p>Loading…</p>,
+        onFailure: (failure) => <p className="error">Could not load notes: {Cause.pretty(failure.cause)}</p>,
+        onSuccess: (success) =>
+          success.value.length === 0
+            ? <p>No notes yet.</p>
+            : (
+              <ul>
+                {success.value.map((note) => (
+                  <li key={note.id}>
+                    <strong>{note.title}</strong>
+                    <div>{note.body}</div>
+                  </li>
+                ))}
+              </ul>
+            )
+      })}
+    </main>
+  )
+}

package/templates/fullstack/apps/web/src/styles.css

@@ -0,0 +1,40 @@
+:root {
+  color-scheme: light dark;
+  font-family: ui-sans-serif, system-ui, sans-serif;
+  line-height: 1.5;
+}
+
+body {
+  margin: 0;
+  padding: 2rem;
+  max-width: 40rem;
+}
+
+form {
+  display: grid;
+  gap: 0.5rem;
+  margin-block: 1.5rem;
+}
+
+input,
+textarea,
+button {
+  font: inherit;
+  padding: 0.5rem;
+}
+
+button {
+  justify-self: start;
+}
+
+ul {
+  padding-left: 1rem;
+}
+
+li {
+  margin-block: 0.75rem;
+}
+
+.error {
+  color: #b00020;
+}

package/templates/fullstack/apps/web/vite.config.ts

@@ -0,0 +1,11 @@
+import { tanstackStart } from "@tanstack/react-start/plugin/vite"
+import viteReact from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+  server: {
+    // Must match WEB_ORIGIN in apps/api, which CORS is scoped to.
+    port: 3001
+  },
+  plugins: [tanstackStart(), viteReact()]
+})

package/templates/fullstack/lint.package.json

@@ -0,0 +1,12 @@
+{
+  "scripts": {
+    "prepare": "effect-tsgo patch --typescript",
+    "lint": "oxlint apps"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/tsgo": "0.37.0",
+    "oxlint": "1.80.0",
+    "typescript": "7.0.2"
+  }
+}

package/templates/http-server/README.md

@@ -0,0 +1,56 @@
+# {{name}}
+
+A schema-first HTTP API built with Effect v4 — server, OpenAPI docs, and a typed client
+generated from one definition.
+
+## Run it
+
+```bash
+{{runCmd}} dev      # watch mode
+{{runCmd}} start    # once
+```
+
+| Route | What |
+| --- | --- |
+| `GET /health` | Liveness probe (204) |
+| `GET /notes` | List notes |
+| `POST /notes` | Create a note |
+| `GET /notes/:id` | Fetch one (404 `NoteNotFound` if absent) |
+| `GET /openapi.json` | Generated OpenAPI document |
+| `GET /docs` | Scalar API reference |
+
+The port comes from `PORT`, defaulting to 3000.
+
+## The typed client
+
+`src/client/ApiClient.ts` derives its shape from `src/api/Api.ts`, so renaming an endpoint
+or changing a schema is a compile error on both sides. `src/client.ts` is a runnable demo:
+
+```bash
+{{runCmd}} dev       # one terminal
+{{runCmd}} client    # another
+```
+
+## Adding an endpoint
+
+1. Declare it in `src/api/Notes.ts` (or a new group added to `src/api/Api.ts`).
+2. Implement it in `src/server/Notes/http.ts` — the handler list is type-checked against the
+   declaration, so a missing handler will not compile.
+
+## Tests
+
+```bash
+{{runCmd}} test
+```
+
+Tests use `HttpApiTest.groups`, which runs the real request encoding, routing and response
+decoding against the handlers with no server and no port.
+
+## 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}} dev
+```

package/templates/http-server/runtime/bun/_package.json

@@ -0,0 +1,22 @@
+{
+  "name": "{{name}}",
+  "module": "src/index.ts",
+  "type": "module",
+  "private": true,
+  "engines": { "bun": ">=1.3.0" },
+  "scripts": {
+    "dev": "bun --hot src/index.ts",
+    "start": "bun src/index.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "client": "bun src/client.ts"
+  },
+  "dependencies": {
+    "effect": "4.0.0-rc.112",
+    "@effect/platform-bun": "4.0.0-rc.112"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "typescript": "7.0.2"
+  }
+}

package/templates/http-server/runtime/bun/_tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"], "target": "ESNext", "module": "Preserve",
+    "moduleDetection": "force", "types": ["bun"],
+    "moduleResolution": "bundler", "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true, "noEmit": true, "strict": true,
+    "skipLibCheck": true, "noUncheckedIndexedAccess": true, "noImplicitOverride": true
+  },
+  "include": ["src"]
+}

package/templates/http-server/runtime/bun/client.ts

@@ -0,0 +1,40 @@
+/**
+ * Client entrypoint — exercises the running server with the generated client.
+ *
+ *   {{runCmd}} dev      # in one terminal
+ *   {{runCmd}} client   # in another
+ */
+import { BunRuntime } from "@effect/platform-bun"
+import { Effect, Layer } from "effect"
+import { ApiClient } from "./client/ApiClient.ts"
+import { NoteId } from "./domain/Note.ts"
+import * as Observability from "./observability.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
+  // server 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.withSpan("client-demo"),
+  Effect.provide(Layer.mergeAll(ApiClient.layer, Observability.layer("notes-client")))
+)
+
+program.pipe(BunRuntime.runMain)

package/templates/http-server/runtime/bun/http.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from "bun:test"
+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"
+
+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"),
+    Effect.runPromise
+  )
+
+test("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" } })
+    expect(created.title).toBe("first")
+
+    const listed = yield* client.notes.list()
+    expect(listed.length).toBe(1)
+    expect(listed[0]?.id).toBe(created.id)
+  })))
+
+test("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") } })
+    )
+    expect(error._tag).toBe("NoteNotFound")
+  })))

package/templates/http-server/runtime/bun/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Server entrypoint.
+ *
+ * A schema-first API (`src/api`) is implemented by handlers (`src/server`),
+ * served over Bun, and consumed by a generated typed client (`src/client`).
+ *
+ *   {{runCmd}} dev     # http://localhost:3000/docs
+ */
+import { BunHttpServer, BunRuntime } from "@effect/platform-bun"
+import { Layer } from "effect"
+import { HttpRouter } from "effect/unstable/http"
+import { port } from "./config.ts"
+import * as Observability from "./observability.ts"
+import { AllRoutes } from "./server/http.ts"
+
+const HttpServerLayer = HttpRouter.serve(AllRoutes).pipe(
+  Layer.provide(BunHttpServer.layerConfig({ port }))
+)
+
+const Main = HttpServerLayer.pipe(
+  // Provided at the very end, so every span the app creates is exported.
+  Layer.provide(Observability.layer("{{name}}"))
+)
+
+Layer.launch(Main).pipe(BunRuntime.runMain)

package/templates/http-server/runtime/node/_package.json

@@ -0,0 +1,23 @@
+{
+  "name": "{{name}}",
+  "type": "module",
+  "private": true,
+  "engines": { "node": ">=22.6.0" },
+  "scripts": {
+    "dev": "node --experimental-strip-types --watch src/index.ts",
+    "start": "node --experimental-strip-types src/index.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "client": "node --experimental-strip-types src/client.ts"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-rc.112",
+    "effect": "4.0.0-rc.112"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/node": "^26.4.0",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11"
+  }
+}

package/templates/http-server/runtime/node/_tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "ESNext"
+    ],
+    "target": "ESNext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "moduleDetection": "force",
+    "types": [
+      "node"
+    ],
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true
+  },
+  "include": [
+    "src"
+  ]
+}