This repository is the starter app that Samebase copies into a new GitHub repository.
It is a small, complete app base. It includes working authentication, real-time data, sharing, and deployment paths without adding product-specific services that a new app might not need.
For the complete provider setup, use the Samebase do-it-yourself guide. This README covers work inside the repository.
- React 19 and TanStack Start in SPA mode
- Convex for the real-time backend, database, and guest authentication
- Cloudflare Workers Static Assets for delivery
- shadcn/ui primitives for the user interface
- Vite+ for development, formatting, linting, tests, and builds
- Node.js 24 for application and automation code
The example app is a public todo list. Guests can sign in without an external identity provider, create todos, see real-time updates, and scan a QR code to open the same list on another device.
Install Vite+ and use the Node.js version in .node-version.
vp install
vp run devThe development command starts Convex and TanStack Start together. It also creates missing Convex
Auth JWT keys in the development deployment. Convex writes VITE_CONVEX_URL to .env.local; do
not set it manually.
For an isolated local agent or worktree backend, use:
vp run dev:worktreeThe core workflow runs on macOS, Linux, and Windows. See
docs/local-setup.md for the local Convex setup and troubleshooting steps.
| Command | Purpose |
|---|---|
vp run check |
Format, lint, type-check, test, and verify generated redirects |
vp run build |
Run the complete Cloudflare build path |
vp run deploy:dry-run |
Validate a production upload without publishing it |
vp run deploy:preview:dry-run |
Validate a preview upload without publishing it |
The dry-run commands need CLOUDFLARE_WORKER_NAME.
On macOS or Linux:
export CLOUDFLARE_WORKER_NAME=my-workerOn Windows PowerShell:
$env:CLOUDFLARE_WORKER_NAME = "my-worker"Cloudflare Workers Builds runs pnpm run build for all branches. It then uses:
| Branch type | Deploy command | Convex key |
|---|---|---|
main |
pnpm run deploy |
CONVEX_DEPLOY_KEY |
| Non-production branches | pnpm run deploy:preview |
PREVIEW_CONVEX_DEPLOY_KEY |
scripts/build-cloudflare.ts selects the Convex key from WORKERS_CI_BRANCH and fails closed when
the branch identity is missing. scripts/verify-current-branch-head.ts prevents an older concurrent
build from deploying backend code after a newer commit reaches the same branch. convex deploy --cmd supplies VITE_CONVEX_URL to the frontend build, so it is not a Cloudflare build variable.
See docs/cloudflare-workers-builds.md for the detailed build
and deploy behavior. Use the
do-it-yourself guide for the provider dashboard setup.
package.jsondefines the supported development, check, build, and deploy commands.vite.config.tsdefines the TanStack Start SPA and prerender behavior.wrangler.jsoncdefines Cloudflare static assets, SPA fallback, and preview URLs.scripts/build-cloudflare.tsowns the Cloudflare build and Convex deployment selection.scripts/deploy-cloudflare.tsowns production, preview, and dry-run uploads.convex/contains the backend, schema, authentication, and generated Convex bindings.src/contains the React application and routes.
src/routeTree.gen.tsis generated by TanStack Router.convex/_generated/api.*,dataModel.d.ts, andserver.*are generated by Convex.convex/_generated/ai/,.agents/skills/,skills-lock.json, and the marked Convex sections inAGENTS.mdandCLAUDE.mdare managed bynpx convex ai-files install.- The marked Vite+ section in
AGENTS.mdis managed byvp config. scripts/generate-cloudflare-redirects.tsowns only the marked generated block inpublic/_redirects. Custom redirect rules can stay outside that block.
Do not hand-edit generated files when their source tool can update them.
When a Convex AI-file update changes the installed source snapshot, confirm its distribution license
and update THIRD_PARTY_NOTICES.md when its third-party material changes.
Licensed under the Apache License 2.0. See
THIRD_PARTY_NOTICES.md for included third-party material.