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 complete Cloudflare build path
pnpm run deploy:dry-run	Validate a production upload without publishing it
pnpm 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-worker

On Windows PowerShell:

$env:CLOUDFLARE_WORKER_NAME = "my-worker"

Deployment contract

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.

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 Cloudflare static assets, SPA fallback, and preview URLs.
• scripts/build-cloudflare.ts owns the Cloudflare build and Convex deployment selection.
• scripts/deploy-cloudflare.ts owns production, preview, and dry-run uploads.
• 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.