Stateful iterate config factory

Status#

Done. The package owns the complete stateful Todo runtime, the OS template and real config consumer delegate to it, legacy rows survive the source swap, and the final preview/browser/telemetry proof is healthy.

Why#

The packaged GitHub AI linter proved that a config repo can import event-processing behavior from iterate. The next harder boundary is a stateful HTTP app: one npm-owned factory must carry a SQLite/sqlfu Durable Object and its browser client without asking config to host the source or install its runtime dependencies.

Public shape#

import { TodoApp } from "iterate/starter-apps/todo";
 
export default class ProjectWorker extends IterateWorkerEntrypoint {
  #todoApp = TodoApp.create(this.env);
 
  async fetch(request: Request): Promise<Response> {
    // Config keeps hostname routing and project-member authorization.
    return this.#todoApp.fetch(request);
  }
}

TodoApp.create(env) exposes only fetch(request). The dynamic-worker ref, dispatch header, class name, durable key, physical package entrypoint, sqlfu setup, HTML, and browser bundle are package details.

Checklist#

Invariants#

todo stays project-member-only and keeps its current host route.
Durable identity remains app-todo-live; this is an in-place code change, not a fresh list.
Existing rows remain readable and mutable after sqlfu records its migration.
WebSocket upgrades travel through env.ITX.fetch, not Workers RPC.
Config does not depend on sqlfu, React, the Todo browser code, or Todo server source.
The package build fails if the Todo artifact leaks an unhandled runtime import.

Guesses and assumptions#

A self-serving physical worker is the smallest honest proof that an npm-owned stateful app carries its entire runtime without config or monorepo source.
Jonas named sqlfu because the intended proof includes a nontrivial transitive runtime dependency; raw SQLite alone would under-test it.
The factory is the requested product API; a public StatefulDynamicWorkerRef would leak transport and deployment details.
One production-shaped preview proof is more valuable than adding a second isolated workerd harness to packages/iterate.
Generate or import the prebuilt client as a string module during the package build, keep sqlfu as a normal iterate runtime dependency, and preserve /apps/todo/client.js; these are reversible implementation choices.

Out of scope#

A generic app registry or universal { fetch, processEvent } framework.
Extracting guestbook, the tasks proxy, stateless apps, or other config features.
Changing Todo UX, adding list slugs/rename, or adopting the full apps/tanstack app.
Resetting durable state or changing the Todo schema.
Adding a new Workers test pool only for this package.

Implementation log#

2026-07-24: Started from merged origin/main after the packaged GitHub AI linter landed.
2026-07-24: Factory TDD proved the env.ITX.fetch lane and private app-todo-live ref.
2026-07-24: The artifact gate caught both the initially absent build and an external zod leak; the final worker bundles sqlfu, Cap'n Web, the migration, and the prebuilt browser client.
2026-07-24: Package build/typecheck/169 tests, config-template typecheck, and 11 focused OS template/seed tests pass.
2026-07-24: Root typecheck, lint, format, and full test pass. The first CI run also exposed and fixed an internal type accidentally exported to knip.
2026-07-24: A real deployed red migration spec proved the legacy SQLite row exists before the package source takes over; getTodos() is an internal RPC probe for the green half.
2026-07-24: The first browser preview found a bare react/jsx-runtime import in the standalone client. The existing Playwright spec reproduced the static Loading shell; bundling the JSX runtime and adding a no-bare-import client gate made the same deployed flow green.
2026-07-24: Final preview CI passed: all five deployed apps, 63 Playwright tests, 49 OS Vitest files, and the 12.9s exact Todo migration spec. The Todo browser trace contained no error-level events or failed outcomes.

Was this page helpful?