Skip to content

Void Starter: TanStack Start on Void with a prerendered blog and chat - #1

Merged
SweetRetry merged 25 commits into
mainfrom
void-starter
Oct 17, 2026
Merged

SweetRetry merged 25 commits into
mainfrom
void-starter

Conversation

@SweetRetry

@SweetRetry SweetRetry commented Oct 17, 2026 •

Copy link
Copy Markdown
Owner

Summary

Void Starter. One Cloudflare Worker, deployed with Void and TanStack Start, serves a prerendered bilingual blog and a chat app.

  • Stack. TanStack Start on Void, with D1 through Drizzle, R2 and Workers AI through AI Gateway.
  • Blog. / and every post are prerendered to static HTML in English and Chinese. Posts are written as en/harness.html, so their URLs serve without a redirect.
  • Chat. Motif's chat block, maintained as local code. A cookie visitor owns each chat. Files go to R2 and answers stream from Workers AI. The chat domain (limits, the send schema, problem mapping, types) lives in apps/web/src/lib/chat.ts.
  • UI. Retry as the design language on shadcn/ui (Base UI). packages/ui/src/components is byte-frozen and checked by pnpm ui:freeze.
  • Gates. pnpm verify runs format, Markdown, lint, rules, typecheck, test, build and knip. pnpm e2e runs a browser smoke suite in a disposable workspace.
  • Deploy. workers_dev: false, so the public workers.dev URL stays closed and nobody can spend the account's Workers AI allowance through it. Preview URLs stay on because void deploy checks readiness through them. The deploy script works around a Void 1.1.11 prerender bug, reported as Cloudflare deploy: framework prerender inside void deploy's build deletes .wrangler/deploy/config.json (ENOENT) voidzero-dev/void#463.
  • Docs. README in English and Chinese, plus architecture, API, deployment and observability docs.

Verification

  • pnpm verify passed: 0 lint warnings, 27 tests, 4 prerendered pages, knip clean.
  • pnpm e2e passed.
  • Deployed to Cloudflare. Before the route was closed, the blog pages, upload validation (413 and 400), chat with a PNG attachment, the file route and regenerate all worked in production. After closing it, the public workers.dev URL answers 404 with error 1042, and /en/harness, /zh/cloud and /zh/harness answer 200 with no redirect on the version preview URL.

🤖 Generated with Claude Code

SweetRetry and others added 25 commits October 16, 2026 21:01
…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>
@SweetRetry
SweetRetry merged commit 756b491 into main Oct 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant