Samebase app

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.

Stack

• 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.

Local development

Install Vite+ and use it to supply the Node.js version in .node-version. Run corepack enable once to make the pinned pnpm version available.

corepack enable
pnpm install
pnpm run dev

The development command starts Convex and TanStack Start together. It also creates missing Convex Auth JWT keys in the development deployment. In a linked Git worktree, the same command automatically uses an isolated local backend. Convex writes VITE_CONVEX_URL to .env.local; do not set it manually.

To force the isolated backend outside a linked worktree, use:

pnpm run dev:worktree

The core workflow runs on macOS, Linux, and Windows. See docs/local-setup.md for the local Convex setup and troubleshooting steps.

Checks and builds

Command	Purpose
pnpm run check	Format, lint, type-check, test, and verify generated redirects
pnpm run build	Run the provider build contract. A local run only checks and builds the app
pnpm run deploy	Publish the production Worker
pnpm run deploy:preview	Publish a Worker Preview
pnpm run deploy:dry-run	Build the app and validate a production Worker upload

build, deploy, and deploy:preview are the stable Samebase deployment interface. Samebase and Cloudflare call these commands. The scripts behind them can change when a repository needs a different deployment sequence.

Outside Cloudflare Workers Builds, pnpm run build does not write to a remote provider. It runs the internal application build. Workers Builds uses the same command to deploy the selected Convex backend before it builds the application.

Deployment contract

Cloudflare Workers Builds uses:

Dashboard field	Command
Build command	pnpm run build
Deploy command	pnpm run deploy
Preview command	pnpm run deploy:preview

The production and Preview build settings each store their Convex key under CONVEX_DEPLOY_KEY. scripts/build-cloudflare.ts gives a non-production build the WORKERS_CI_BRANCH Preview name. It fails closed when Workers Builds does not provide a branch or the canonical key. 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.

Cloudflare supplies the connected Worker name through WRANGLER_CI_OVERRIDE_NAME. Wrangler uses that value for production deploys. scripts/deploy-worker-preview.ts passes the same value to wrangler preview --worker-name. This keeps the Worker name out of the repository.

Enable Preview builds for non-production branches, but keep the Preview command set to pnpm run deploy:preview. Cloudflare can still show an Enable Worker Previews banner because it cannot inspect the package script. The repository adapter already runs wrangler preview.

See docs/cloudflare-workers-builds.md for the detailed build and deploy behavior. Use the do-it-yourself guide for the provider dashboard setup.

Important files

• package.json defines the supported development, check, build, and deploy commands.
• prerender.config.ts defines the public pages shared by TanStack Start and Cloudflare.
• vite.config.ts defines the TanStack Start SPA and prerender behavior.
• wrangler.jsonc defines static assets, SPA fallback, and preview URLs.
• scripts/build-cloudflare.ts owns the Workers Build Convex deployment and application build sequence.
• scripts/deploy-worker-preview.ts passes the connected Worker name to Wrangler Preview.
• convex/ contains the backend, schema, authentication, and generated Convex bindings.
• src/ contains the React application and routes.

Generated and managed files

• src/routeTree.gen.ts is generated by TanStack Router.
• convex/_generated/api.*, dataModel.d.ts, and server.* are generated by Convex.
• convex/_generated/ai/, .agents/skills/, skills-lock.json, and the marked Convex sections in AGENTS.md and CLAUDE.md are managed by npx convex ai-files install.
• The marked Vite+ section in AGENTS.md is generated by vp config. The package prepare command uses --no-agent, so installs do not rewrite it.
• scripts/generate-cloudflare-redirects.ts owns only the marked generated block in public/_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.

License

Licensed under the Apache License 2.0. See THIRD_PARTY_NOTICES.md for included third-party material.