Repository navigation
Void Starter: TanStack Start on Void with a prerendered blog and chat - #1
Merged
Merged
Conversation
…y packages Void on Cloudflare replaces the split web/server processes: one Worker, D1 instead of Postgres, Workers Observability instead of the Node OTel SDK. ADRs and the stale TS 7 research note are deleted; their reasoning moves into docs/ in a later commit. Biome is replaced by Vite+ (vp fmt / vp lint). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
apps/web is a TanStack Start app; voidPlugin() provisions Cloudflare bindings and deploys it. Vite+ replaces Biome and bare Vitest; the shadcn design lint rules move from .oxlintrc.json into the root vite.config.ts. The migration spec lives in docs/future/void-starter.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
retry.css and packages/ui/retry/DESIGN.md are synced byte-for-byte from SweetRetry/retry-design at the commit pinned in packages/ui/retry/lock.json (scripts/sync-retry-design.js). globals.css only layers tw-animate-css, shadcn and Tailwind sources on top. rules/web-design is retired in favor of Retry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…eze) Approved unfreeze for Retry: Button drops the outline variant (internal callers move to secondary) and uses tone hovers and Retry's disabled state; Card loses border and shadow; Input and Textarea are filled with a soft focus ring; Skeleton uses surface-2; Sonner drops next-themes. Baseline accepted with pnpm ui:freeze:update. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Void-managed auth is unavailable in framework mode, so the app wires Better Auth itself: Drizzle sqlite adapter over void/db, /api/auth/$ server route, tanstackStartCookies. A social provider turns on only when both its credentials exist. db/schema.ts holds the Better Auth tables plus note; the first migration is checked in. predev writes a local .env with a random BETTER_AUTH_SECRET so a fresh clone runs with no setup. Verified locally: sign-up 200, session read back, wrong password 401. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Upstream regeneration, no local edits: shadcn 4.21.5 with --base base and the base-nova preset replaces the Radix new-york set. form is an empty item in the Base UI registry (forms use Field + react-hook-form Controller), so form.tsx goes and field.tsx plus input-group.tsx arrive. Radix, vaul and react-hook-form leave packages/ui. Baseline accepted with ui:freeze:update. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d unfreeze) scripts/apply-retry-deltas.js encodes Retry's Components section as exact class swaps, so a future shadcn regeneration reapplies Retry in one step and fails loudly when an upstream anchor moves. Deltas: no outline Button variant (callers move to secondary), tone hovers and disabled states, global focus outline, borderless Card, filled fields with a soft ring, surface-tone toggles and Skeleton, surface-2 active Tabs, bordered rounded-md floating layers, Dialog/Sheet on bg-background, top-ruled table rows, Sonner without next-themes. Baseline accepted with ui:freeze:update. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The root file was a router to rules that no longer exist; agents read DESIGN.md at the root by convention. sync-retry-design.js now writes it there directly, and the pin moves to packages/ui/retry.lock.json. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…oating layers (recorded unfreeze) AlertDialog follows Dialog (bg-background, border, rounded-lg); context menu, hover card, menubar and navigation menu popups trade their ring for a border. Re-ran the codemod on the pristine base-nova output from 2075d9a: the earlier 19 components came out byte-identical, only these five changed. Also aligns packages/ui on @types/react 19.3. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The reference feature, one deletable slice per Cloudflare product: - D1: notes CRUD through server functions, scoped by user id; another user's note answers 404. - R2: one attachment per note under users/<uid>/<noteId>/<uuid>, 10 MB and a type allowlist, served with nosniff and content-disposition. - Workers AI through AI Gateway: /api/notes/$noteId/summary streams SSE, saves the summary once the stream finishes, maps UsageLimit to 429 and a clone that isn't connected to Cloudflare yet to 503 with the fix. - RFC 9457 problem+json for every /api/* error, instance = urn:cf-ray. - void.config.ts turns on Workers Logs and Traces and the gateway id. UI follows DESIGN.md (Retry): sign-in/up with react-hook-form + Field, a sidebar layout, skeletons after 300 ms, AlertDialog for delete. Also: `pnpm connect` (void connect --platform cloudflare), a plugin-free vitest config so tests stop scaffolding .void/ at the repo root, the freeze manifest kept out of the formatter, and the unused TanStack Query deps removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The /api/* contract stays RFC 9457 problem+json but drops what nothing used:
- `type` is omitted (RFC 9457 reads it as about:blank). The old type URIs
pointed at this repo's docs, which is wrong for every fork.
- FORBIDDEN and CONFLICT had no call sites; the type/slug round trip and
isProblemDetails only served their own tests.
- Codes are typed string literals instead of a mirrored const object.
Also:
- predev runs `void db migrate`. The dev server never applies migrations,
so a fresh clone's first sign-up would hit an empty D1. Exposed as
`pnpm db:migrate`.
- knip no longer loads apps/web/vite.config.ts; from the repo root,
voidPlugin() scaffolded .void/ there.
- api.failed logs an Error's name, message and stack (a raw Error
serializes to {}).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Docs, all in English: - README with the quick start, deploy steps and a disclaimer that this is not an official Void template; MIT LICENSE. - docs/architecture.md absorbs the decision log (Void framework mode + TanStack Start, one Worker, D1, Better Auth, Base UI, Retry, Vite+). - docs/api.md (routes and the error contract), docs/deployment.md (connect, secrets, OAuth, AI Gateway, provider models, rollback) and docs/observability.md (local SQL explorer, Workers Logs and Traces). - AGENTS.md, CONTEXT.md, rules/, scripts/ and the freeze messages translated. rules/api-contract.md folds into docs/api.md. - CI drops Postgres: install, then `pnpm verify`. Markdown gate (set up by the maintainer): markdownlint-cli2 joins `pnpm verify` as md:check and runs on staged Markdown in pre-commit. Retry: DESIGN.md and retry.css are now this repo's own files. The sync script and its lock pointed at a private repo no user of an open-source starter can reach, so they are gone and both files are formatted and linted like everything else (values unchanged; only number formatting). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
.agents/skills/void is a relative symlink to the skill that ships inside the installed `void` package, the same link `void init` creates. It resolves after `pnpm install` and always matches the installed version. markdownlint skips .agents/** because those files belong to dependencies. The quick start gains `git init`: giget delivers no repository, and the rule scripts and git hooks need one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A fresh clone failed `pnpm verify`: typecheck runs before anything generates routeTree.gen.ts, so every route lost its types. TanStack Router recommends committing the file; the dev server and build keep it current. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On a fresh clone pnpm can reuse a cached lefthook build without rerunning its postinstall, so no hooks were installed and knip flagged lefthook as unused. `prepare: lefthook install` runs on every first install. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Verified against a real Cloudflare account: - `void secret put` needs a Worker name, so void.config.ts sets cloudflare.name = "void-starter". - Workers AI rejects a gateway id the account hasn't created (AiGatewayError 2001). The summary route now answers 503 naming the gateway to create, and README and docs/deployment.md add the step. With the gateway in place, dev summaries stream and show up in the gateway's logs. - void.lock.json records the deployer's account id. The template ignores it so forks don't inherit it; the docs tell app authors to commit theirs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- `_auth` layout route: one centered group with the form on the left and a watercolor (Verdant Notes) on the right, hidden below lg. It owns the signed-in redirect and loads the social providers once for both pages. - The artwork ships as two square WebP crops (1000 px, 164 KB; 1600 px, 364 KB) from the 3840x2160 original, picked by srcset. - Pages: a description line, social buttons above the email form when configured, a Show/Hide password toggle on the label row, server errors shown inline with role="alert" instead of a toast, and a specific message for an email that already has an account. - No base component changes: InputGroup lacks Retry's filled style, so the toggle lives beside the label. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The reference feature is now a chat app built on the Motif chat-app block, with no accounts. Each chat lives at /c/<uuid>. - D1 holds chats, turns and attachment text. The migration history is rewritten, since nothing was deployed yet. - R2 holds uploads (4 files, 5 MB each), served with CSP sandbox. - ai.toMarkdown() turns PDFs, images and Office files into text for the model. - Answers stream from free Workers AI models (Llama 3.3, Qwen3, gpt-oss, Mistral Small) through AI Gateway, with reasoning saved beside the answer. - The stream parser reads OpenAI-style deltas, reasoning_content, and numeric `response` frames. QwQ sent digits as JSON numbers, which the old parser dropped. - Motif components were adapted from Radix to Base UI: render instead of asChild, closeOnClick on radio items, and no outline buttons. - The composer and the thread share one centred column with matching gutters. The scroll rail sits out of flow and hides below sm. - The vendored Motif files are exempt from lint and knip, like upstream shadcn/ui. - Better Auth, its env and secret script, and the auth artwork are removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
pnpm deploy is pnpm's own command, so the root script and the docs use pnpm run deploy. The first deploy left the Worker's workers.dev route off; void.config.ts now sets workers_dev, and the docs say how to recover. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The root page is a Markdown blog post prerendered to static HTML, with an anchor nav that tracks the reading position and a shared site header that links to the playground. Each browser gets a random visitor id in an HttpOnly cookie, with no sign-in or fingerprinting. The first turn ties a chat to its visitor; every chat route answers 404 for another visitor's chat and 400 without the cookie. The chat page keeps the site header and shows the visitor's sessions in a left sidebar. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The anchor nav now starts on the header's left edge and the post fills the rest of the row, so its widest point lines up with the Playground button. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…dev route - Blog: post table in components/blog/posts.ts, /$lang/$post routes, zh translations and the harness post. Prerender writes en/harness.html (autoSubfolderIndex: false), so post URLs serve without a redirect. - Chat: limits, the send schema, problem mapping and types live in lib/chat.ts; readAiStream cancels the body when the reader stops; routes parse params at the boundary through chatRoute. - Motif components are maintained as local code: lint and knip ignores removed, no-restyle fixes per DESIGN.md, dead exports deleted. - Composer adopts text typed before hydration. - use-mobile reads the media query through useSyncExternalStore. - Deploy: workers_dev off so the public URL cannot spend the AI allowance; preview URLs stay on for Void's readiness check. The deploy script drops a stale prerender pointer (Void 1.1.11 ENOENT). - pnpm e2e: browser smoke suite in a disposable workspace, plus the verify-web skill. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ev URL README.zh.md mirrors README.md, and each links to the other. Both now cover the prerendered blog, the Node and pnpm versions, a command table, pnpm e2e, and that the public workers.dev URL starts closed (1042) until workers_dev is set to true. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nstalled today Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ajors The e2e job installs Playwright Chromium (cached by version) and runs pnpm e2e --screenshots. On failure it uploads .verification/ as evidence. Dependabot bumps the actions monthly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Void Starter. One Cloudflare Worker, deployed with Void and TanStack Start, serves a prerendered bilingual blog and a chat app.
/and every post are prerendered to static HTML in English and Chinese. Posts are written asen/harness.html, so their URLs serve without a redirect.apps/web/src/lib/chat.ts.packages/ui/src/componentsis byte-frozen and checked bypnpm ui:freeze.pnpm verifyruns format, Markdown, lint, rules, typecheck, test, build and knip.pnpm e2eruns a browser smoke suite in a disposable workspace.workers_dev: false, so the publicworkers.devURL stays closed and nobody can spend the account's Workers AI allowance through it. Preview URLs stay on becausevoid deploychecks readiness through them. The deploy script works around a Void 1.1.11 prerender bug, reported as Cloudflare deploy: framework prerender insidevoid deploy's build deletes.wrangler/deploy/config.json(ENOENT) voidzero-dev/void#463.Verification
pnpm verifypassed: 0 lint warnings, 27 tests, 4 prerendered pages, knip clean.pnpm e2epassed.workers.devURL answers 404 with error 1042, and/en/harness,/zh/cloudand/zh/harnessanswer 200 with no redirect on the version preview URL.🤖 Generated with Claude Code