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 --name my-worker	Build and validate a production upload without publishing it

Deployment contract

Cloudflare Workers Builds runs pnpm run build for all branches. It then uses:

Branch type	Deploy command	Builds settings	CONVEX_DEPLOY_KEY value
main	pnpm run deploy	Production	Production deploy key
Other branches	pnpm run deploy:preview	Previews Base	Project Preview deploy key

build, deploy, and deploy:preview are the package-script interface used by Samebase. Keep these names when changing their implementation. Cloudflare supplies the appropriate build secrets for each environment. Convex rejects a production key on a preview branch.

scripts/build-cloudflare.ts deploys Convex only inside Workers Builds and uses WORKERS_CI_BRANCH as the stable preview name. Local builds only build the frontend. 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.

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.
• The deploy and deploy:preview package scripts run Wrangler directly.
• 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.