Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions specs/epics/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,6 @@ folder is the adoption; the merge creates the epic in the workspace.

| Epic | Cluster | Status | What it is |
|------|---------|--------|------------|
| [`tanstack-start/`](./tanstack-start/) | **TS** | In progress (TS0) | Vercel's TanStack Start template — the welcome page, server-function todos kept in the visitor's cookie, an API route and the three SSR modes — on Cloudflare Workers + Static Assets via Cloudflare's Vite plugin, and an Orun baseline that instantiates it in one landing (TS2) |

As-built ≠ intent: what shipped lives in each epic's `IMPLEMENTATION-STATUS.md`.
11 changes: 11 additions & 0 deletions specs/epics/tanstack-start/IMPLEMENTATION-STATUS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# tanstack-start — implementation status

| Milestone | State | Landed |
|---|---|---|
| TS0 — the spec | ✅ | TS-1 |
| TS1 — TanStack Start on Workers | planned | TS-2 |
| TS2 — a baseline | planned | TS-3 |

## Departures from the upstream template

Recorded as they land, from TS1 on.
36 changes: 36 additions & 0 deletions specs/epics/tanstack-start/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# tanstack-start — Vercel's TanStack Start template on Cloudflare Workers

**The template is TanStack Start's own starter app — a welcome page, a todo
list read by a GET server function in its loader and changed by a POST one,
an API route, and one server function rendered three ways (full SSR,
data-only, SPA) — so the port is one Worker built by Cloudflare's Vite
plugin, TanStack Start's own Cloudflare target, with the todos moved from a
file on the server's disk into the visitor's own cookie, deployed by Orun to
stage and prod on every merge — and the baseline that makes a copy of it
somebody else's site in one landing.**

| | |
|---|---|
| Status | In progress — TS0 on main |
| Upstream | [vercel/vercel › examples/tanstack-start](https://github.com/vercel/vercel/tree/main/examples/tanstack-start), at `84878e5` — Apache-2.0 |
| Reference | [sveltekit-boilerplate](https://github.com/sourceplane/sveltekit-boilerplate) (the Vite-built Worker + Static Assets scaffolding, and the cookie-kept todos) |
| Key | `TS` |

## Read in this order

1. [design.md](design.md) — the template, how each Vercel piece maps to
Cloudflare, the repository and the build, and the alternatives rejected.
2. [implementation-plan.md](implementation-plan.md) — the milestones and
what each one lands.
3. [risks-and-open-questions.md](risks-and-open-questions.md) — what is not
proven, and what was accepted.
4. [IMPLEMENTATION-STATUS.md](IMPLEMENTATION-STATUS.md) — what shipped, and
every departure from the upstream template.

## Milestones

| Milestone | What it lands | Task |
|---|---|---|
| TS0 — the spec | the repository, its intent, CI, tooling and spec index; this doc set | TS-1 |
| TS1 — TanStack Start on Workers | the template in `apps/web` on Cloudflare's Vite plugin, the cookie-kept todos, its tests, the README | TS-2 |
| TS2 — a baseline | the console card, the build document, the context pack and the baseline's tests | TS-3 |
82 changes: 82 additions & 0 deletions specs/epics/tanstack-start/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# tanstack-start — design

## 1. The template

`examples/tanstack-start` in vercel/vercel is the app TanStack's CLI
generates, with Nitro as its Vercel build: TanStack Start 1.133 (React 19,
TanStack Router's file routes), Tailwind CSS 4 and `lucide-react`, Vite 7.

| Route | What it shows |
|---|---|
| `/` | the welcome page: the TanStack Start hero and six feature cards |
| `/demo/start/server-funcs` | a todo list: `getTodos` (a GET server function) runs in the route's loader, `addTodo` (POST) appends one and the route reloads |
| `/demo/start/api-request` | a page whose browser fetches `/demo/api/names` |
| `/demo/api/names` | an API route (a server route handler): `["Alice","Bob","Charlie"]` |
| `/demo/start/ssr/` | links to the three SSR modes |
| `/demo/start/ssr/full-ssr`, `/data-only`, `/spa-mode` | `getPunkSongs` (a GET server function) rendered on the server, loaded on the server and rendered in the browser, and called from the browser |

The header's drawer links them; the root renders TanStack's devtools.
Upstream keeps the todos in `todos.json` beside the server, read and written
with `node:fs`.

## 2. How each Vercel piece maps to Cloudflare

| Vercel | Here | Why |
|---|---|---|
| Nitro (`nitro/vite`) builds the server for Vercel's functions | `@cloudflare/vite-plugin` (`viteEnvironment: ssr`): `vite build` writes the Worker to `dist/server` and the browser's files to `dist/client` | TanStack Start's documented Cloudflare target; `vite dev` runs the server in workerd too |
| The functions' Node runtime | `nodejs_compat` on compatibility date 2026-10-01 | Start's server uses `AsyncLocalStorage` and other `node:` modules |
| `todos.json` on the server's disk | the visitor's own httpOnly cookie, `Path=/`, `SameSite=Lax`, `Secure` over HTTPS (`src/data/todos.ts`) | A Worker has no disk that outlives a request (a Vercel function's is read-only outside `/tmp`, so upstream's `addTodo` fails there too). The cookie needs no database and keeps the demo's point: a GET server function in a loader, a POST one that changes what it reads |
| `public/` and the hashed build on Vercel's CDN | Static Assets (`assets.directory: dist/client`), served ahead of the Worker | Same files, same URLs |
| Deploy on push | Orun's `cloudflare-workers-assets-turbo` component, `<repo>-web-{stage,prod}` | The Cirrus conventions |

TanStack Start 1.133 → 1.169 (with Vite 8, `@vitejs/plugin-react` 6 and
vitest 5): the Cloudflare target is built against the current Start, whose
plugin requires Vite 8. The upgrade renames `.inputValidator` to
`.validator` and infers server-function results more narrowly; both show in
two lines.

## 3. One Worker config for the build and the deploy

The Vite plugin reads `wrangler.jsonc` and writes the deployable config
beside its build (`dist/server/wrangler.json`), with a redirect
(`.wrangler/deploy/config.json`) that a bare `wrangler deploy` follows. The
component's deploy runs `wrangler deploy --config wrangler.jsonc`, and an
explicit `--config` never follows the redirect; its `verify-structure` step
also checks that the config exists before the build. So `wrangler.jsonc` is
the BUILT Worker — `main: dist/server/index.js`, `no_bundle` with the
plugin's `ESModule` rule, `assets.directory: dist/client` — and
`vite.config.ts` names the source entry the plugin builds
(`config: { main: '@tanstack/react-start/server-entry' }`). The plugin drops
`no_bundle` and `rules` under Vite and says so once per build.

A dry-run deploy of either config uploads the same modules. The
end-to-end tier holds the two together on every run: same name,
compatibility date and flags, entry and assets directory, and the same
upload.

## 4. The repository and the build

sveltekit-boilerplate's shape: one component, `apps/web`
(`cloudflare-workers-assets-turbo`, `lane: isolated`), its tests inside the
app (vitest over the site's name and the todo store), the shared
TypeScript/ESLint configuration and the wrangler renderer under `tooling/`,
stack-tectonic 0.19.0, `ci.yml` as turso-starter's (as sveltekit-boilerplate
carries it). The site's name is one seam: `SITE_NAME` in `src/lib/site.ts`,
read by the root route's `<title>` (upstream's `TanStack Start Starter`).
The smoke reads the home page's server-functions link, the API route's JSON
and a 404.

## 5. Alternatives rejected

- **A second, deploy-only config** (`wrangler.deploy.jsonc` beside the
plugin's `wrangler.jsonc`): two files naming one Worker drift; one file
and a test that it matches the plugin's output do not.
- **Deploying the plugin's own `dist/server/wrangler.json`**: the
component's `verify-structure` step checks the config before the build,
and the build has not written it yet.
- **Keeping TanStack Start 1.133 with Vite 7**: the current plugin and Start
are what TanStack documents for Cloudflare; the pinned example is a
year behind.
- **A KV namespace for the todos**: shared, durable state is a database the
template does not have; per-visitor state in a cookie is what the demo
needs, and swapping in KV is a README line.
30 changes: 30 additions & 0 deletions specs/epics/tanstack-start/epic.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# The epic's declaration. metadata.name equals the directory name; metadata.key
# is the task-key prefix this epic reserves (TS → TS-1, TS-2, …). Owner, target
# date and health are the platform's — never written here.
apiVersion: orun.io/v1
kind: Epic
metadata:
name: tanstack-start
key: TS
spec:
title: "Vercel's TanStack Start template on Cloudflare Workers"
summary: "Vercel's TanStack Start template — the welcome page, a todo list read and changed by server functions, an API route and the three SSR modes — runs on Cloudflare Workers + Static Assets through Cloudflare's Vite plugin, TanStack Start's own Cloudflare target, the todos kept in each visitor's own cookie, inside the Cirrus baseline's repository conventions, and becomes an Orun baseline that takes a new TanStack Start site from nothing to live on stage and prod in one landing."
state: started
milestones:
- name: "TS0 — the spec"
exitCriteria:
- "the repository is born with its intent, CI, tooling and spec index, and this doc set and the task contracts are on main"
tasks: [TS-1]
- name: "TS1 — TanStack Start on Workers"
exitCriteria:
- "apps/web is the upstream app on TanStack Start 1.169, built by @cloudflare/vite-plugin into one Worker with Static Assets, deployed by `wrangler deploy --config wrangler.jsonc`"
- "`pnpm typecheck`, `pnpm lint`, `pnpm test` and `pnpm build` are green"
- "`wrangler dev` serves every route: the welcome page, the todos through their GET and POST server functions and the visitor's cookie, the API route, the three SSR modes, the static files and a 404"
- "the README says how to run, test and deploy it, and how every Vercel piece maps to Cloudflare"
tasks: [TS-2]
- name: "TS2 — a baseline"
exitCriteria:
- "blueprint.yaml (the console card) and repo-blueprint.yaml (the build) take a new TanStack Start site from nothing to live on stage and prod in one landing, then record it"
- "a site built from it carries the site only, renamed throughout to its own name, repository and Worker"
- "Baseline CI is green: contract tests, generated component docs, the blueprint read by the pinned orun, the leak gate, the offline bootstrap and the end-to-end tier — the stage lane's steps in a staged job tree, the committed Worker config held to the one the Vite plugin writes, the Worker smoke-tested and walked"
tasks: [TS-3]
44 changes: 44 additions & 0 deletions specs/epics/tanstack-start/implementation-plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# tanstack-start — implementation plan

Three milestones, one task each, each landed as one pull request.

## TS0 — the spec (TS-1)

The repository is born with sveltekit-boilerplate's frame — `intent.yaml`
(dev verify-only, stage, prod after stage; the placeholder workspace
`ws_CHANGE_ME`, so CI plans nothing until it is linked), `ci.yml` byte for
byte turso-starter's (as sveltekit-boilerplate carries it), the shared
TypeScript and ESLint configuration, the wrangler renderer, the pnpm
workspace and turbo pipeline, and the spec index — and this doc set and the
three task contracts land on it.

## TS1 — TanStack Start on Workers (TS-2)

- `apps/web` is upstream's app: `src/` (the routes, the header, the punk
songs, the styles), `public/`, `tsconfig.json`, `biome.json` — on
TanStack Start 1.169, with `@cloudflare/vite-plugin` in place of Nitro, the
todos in the visitor's cookie (`src/data/todos.ts`), the `<title>` read
from `src/lib/site.ts`, and the template's own lint config made to pass.
- `wrangler.jsonc` (the built Worker), `vitest.config.ts`, and
`component.yaml` (`cloudflare-workers-assets-turbo`) with a smoke over
`/`, `/demo/api/names` and a 404.
- Tests (vitest): the site's name, the todo store.
- The README: run, test, deploy; how each Vercel piece maps; the licence and
the files changed.

Done when typecheck, lint, test and build are green, and `wrangler dev`
serves every route — the todos added through their POST server function and
read back with the visitor's cookie.

## TS2 — a baseline (TS-3)

sveltekit-boilerplate's machinery on this tree: the card, the build document
(one landing, `01-product`, then the record, `03-docs`), `.baseline/`
(identity, the site's README, task contracts), the rename engine, the
bootstrap helpers, the deployment-record renderer (probing `/`, the
server-functions demo and the API route), the phase pages, the context pack,
and the baseline's tests — with the end-to-end tier holding the committed
Worker config to the Vite plugin's, and walking every route of the staged
Worker, the server functions called as the browser calls them
(`testing/lib/serverfn-payload.mjs`). Done when every Baseline CI tier is
green; tagged `baseline-v1`.
13 changes: 13 additions & 0 deletions specs/epics/tanstack-start/risks-and-open-questions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# tanstack-start — risks and open questions

| ID | Risk | State |
|---|---|---|
| TS-A | No live bootstrap yet: the repository created and linked, the Cloudflare token minted, a real `wrangler deploy` and the probes are unproven | OPEN — one bootstrap from `baseline-v1` against a workspace closes it |
| TS-B | The committed `wrangler.jsonc` describes the Worker the Vite plugin builds; a plugin release that changes its output (the entry's path, the module rule, the assets directory) would leave the deploy pointing at the wrong files | MITIGATED — the end-to-end tier compares the plugin's `dist/server/wrangler.json` with `wrangler.jsonc` and the two configs' dry-run uploads on every run, so a lockfile bump that changes either fails before a tag |
| TS-C | The plugin warns on every build that `no_bundle` and `rules` are ignored under Vite | ACCEPTED — they are for the deploy; the warning is the cost of one config (design §3, §5) |
| TS-D | Server functions are an internal protocol: `/_serverFn/<id>`, a seroval body, an `Origin` (or `Sec-Fetch-Site`) check that answers 403 otherwise. The end-to-end tier speaks it | ACCEPTED — the tier builds each body with the app's own seroval and reads each id from the build's own resolver, so an upgrade that changes the wire fails the tier, not the site |
| TS-E | TanStack's devtools render in production, as upstream does on Vercel: `@tanstack/react-devtools` has no production switch and the template does not use `@tanstack/devtools-vite` | ACCEPTED — the template's behaviour; an owner removes `<TanStackDevtools>` from `src/routes/__root.tsx` (or adds the devtools Vite plugin) |
| TS-F | The todos are the visitor's own: clearing cookies clears the list, and a list does not follow a visitor to another browser | ACCEPTED — upstream's `todos.json` was one list for everyone, and on Vercel it could not be written at all; per-visitor state needs no database (design §2) |
| TS-G | `nodejs_compat` is required: Start's server imports `node:async_hooks` and friends | ACCEPTED |
| TS-H | stack-tectonic 0.19.0, not 0.20.0: 0.20.0's lane-scoped install links each job's `node_modules` out of its staged tree, and this site's build has not been tried in that layout | ACCEPTED — the pin keeps the layout the end-to-end tier proves |
| TS-I | A custom domain is the owner's step: the site goes live on workers.dev, and attaching a domain needs zone permissions the brokered `workers-deploy` token does not carry | ACCEPTED |
15 changes: 15 additions & 0 deletions tasks/TS-1.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: TS-1
title: "The spec"
spec:
goal: The tanstack-start repository is born with its intent, CI, tooling and spec index, and the tanstack-start epic — declaration, doc set and task contracts — is on main
affects:
- specs/epics/tanstack-start
- specs/epics/README.md
- tasks
doneWhen:
- epic.yaml, README, design, implementation plan, risks and status are on main
- the three task contracts exist
gates: []
17 changes: 17 additions & 0 deletions tasks/TS-2.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: TS-2
title: "TanStack Start on Workers"
spec:
goal: Vercel's TanStack Start template runs on Cloudflare Workers + Static Assets through Cloudflare's Vite plugin — every route, its server functions and API route in the Worker, the todos in the visitor's own cookie — with its tests, and its README saying how it maps to Vercel
affects:
- apps/web
- pnpm-lock.yaml
- pnpm-workspace.yaml
- tooling/catalog
- README.md
doneWhen:
- pnpm typecheck, lint, test and build are green
- wrangler dev serves the welcome page, the todos through their server functions, the API route, the SSR demos and a 404
gates: []
28 changes: 28 additions & 0 deletions tasks/TS-3.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: TS-3
title: "tanstack-start becomes an Orun baseline"
spec:
goal: blueprint.yaml and repo-blueprint.yaml take a new TanStack Start site from nothing to live on stage and prod in one landing, held by Baseline CI
affects:
- blueprint.yaml
- repo-blueprint.yaml
- BOOTSTRAP.md
- .baseline
- .github/workflows/baseline.yml
- .github/workflows/tag.yml
- ai/context
- docs/phases
- hooks
- testing
- tooling/rebrand
- tooling/bootstrap
- tooling/catalog
- apps/web/docs
- specs/epics/tanstack-start
- README.md
doneWhen:
- every Baseline CI tier is green
- a site placed from it carries the site only, branded, its Worker named for it
gates: []
Loading