effect-app

A reference Effect HTTP API server (Accounts, Groups, People) backed by SQLite, demonstrating the Effect platform HttpApi stack.

Overview

effect-app (package name http-server) is a self-contained reference HTTP API server built on Effect v4 (effect@4.0.0-beta) and @effect/platform-node. It models three domains — Accounts/Users, Groups, and People — as HttpApi groups wired together with layers, backed by SQLite, and instrumented with OpenTelemetry tracing. It exists in the monorepo as a worked example of the Effect platform HTTP stack (HttpApi, HttpApiBuilder, policies, repos, migrations) rather than as a customer-facing product.

Stack

effect + effect/unstable/http, effect/unstable/httpapi, effect/unstable/sql
@effect/platform-node — Node HTTP server and runtime
@effect/sql-sqlite-node — SQLite client + file-system migrator
@effect/opentelemetry + OTLP trace exporter (Honeycomb / OTLP endpoint)
uuid for id generation
tsx (dev/start), Vitest + @effect/vitest (tests)

There is no build script — dev and start both run the TypeScript source directly via tsx, no bundling step is wired up.

Develop

pnpm -F http-server dev

Runs tsx --watch src/main.ts, loading .env if present. The server listens on PORT (default 3004 in code; .env.example sets 3005 to avoid clashing with apps/blog on 3004). Swagger UI is served at /docs and the OpenAPI document at /openapi.json. Copy .env.example to .env first — tracing is optional and only enabled when HONEYCOMB_API_KEY or OTEL_EXPORTER_OTLP_ENDPOINT is set.

Test

pnpm -F http-server test           # vitest (watch)
pnpm -F http-server test:ci        # vitest run + junit report
pnpm -F http-server test:coverage  # v8 coverage
pnpm -F http-server check-types    # tsc -b
pnpm -F http-server lint           # oxlint src/

Build & deploy

No build script exists in package.json — the server runs straight from source: pnpm -F http-server start (node --import tsx src/main.ts) is the production-shaped run command. Internal / not separately deployed.

Structure

src/
  main.ts              # entry: launch HttpLive + tracing
  http.ts              # router, Swagger, CORS, Node HTTP server
  api.ts               # HttpApi composed from the three groups
  client.ts            # example typed HttpApiClient
  Accounts/            # accounts + users: api, http, repos, policy
  Groups/              # groups: api, http, repo, policy
  People/              # people: api, http, repo, policy
  Domain/              # schemas: account, user, group, person, email, ...
  migrations/          # SQLite migrations (users, groups, people)
  lib/                 # shared layer helpers
  sql.ts  tracing.ts  uuid.ts  accounts.ts groups.ts people.ts
  __tests__/           # unit tests + fixtures

See the apps overview and the monorepo overview.