ChessMerge

ChessMerge uses:

• Convex as your backend (database, server logic)
• TanStack Start with file-based TanStack Router routes
• React and Vite for the frontend
• Tailwind for building great looking UI
• Convex Auth for authentication

License and artwork

The application code uses the Apache License 2.0. The chess piece SVGs use CC BY-SA 3.0, with separate author credits and source links in the artwork notice. The bishop-and-knight site logo was generated by Nicu Chiciuc and is separate from the downloaded chess pieces.

Get started

Install dependencies and start the frontend and Convex backend:

pnpm install
pnpm run dev

Development scripts

Core development

• pnpm run dev - Start both frontend and backend in development mode
• pnpm run dev:frontend - Start only the Vite frontend development server
• pnpm run dev:backend - Start only the Convex backend development server

Type checking

• pnpm run type-check - Check TypeScript types across all projects (frontend, node tooling, and convex)
• pnpm run type-check:convex - Check TypeScript types specifically for Convex backend functions
• pnpm run lint - Run both TypeScript type checking and ESLint linting

Build and deploy

• pnpm run build:app - Type-check and build the browser files into dist/client and the server render into dist/server
• pnpm run deploy - Build, upload the site, and push the functions to the production Convex deployment, or to the deployment of the key in CONVEX_DEPLOY_KEY
• pnpm run deploy:dev - The same for the development deployment in .env.local

Convex serves the site next to the backend with @samebase/convex-hosting, at https://<deployment>.convex.site. A deploy uploads dist/client and then pushes the functions, and the push switches the site. Deploy with these scripts, not with a plain npx convex deploy, which pushes no site version.

GitHub Actions deploys with Alchemy and @samebase/alchemy-convex. alchemy.run.ts is the stack, and .github/workflows/alchemy.yml runs it:

• A push to main deploys the stage prod, the production deployment adorable-weasel-392, which serves https://chessmerge.com.
• A pull request from this repository deploys the stage pr-<number>, a Convex preview with that name, and comments the preview URL on the pull request. Later pushes reuse the preview, so users, games, and sessions stay until the pull request closes, which destroys the stage and deletes the preview.

The stack runs pnpm run deploy only when the functions, the build inputs, package.json, or the lockfile changed, with a deploy key that it creates for that push and deletes after it. The state of every stage is in the alchemyState component of the alchemy-state project of the Convex team nicu (store version 4), under the stack name nicu-chiciuc/chessmerge, so Samebase shows the deployments.

Every run needs one repository secret, CONVEX_ACCESS_TOKEN, a team access token. Without it, the workflow deploys nothing and prints a notice. Set it up once:

1. In the Convex dashboard, open the team nicu, then Settings, Access Tokens, and create a token named nicu-chiciuc/chessmerge alchemy.yml. Copy it and run gh secret set CONVEX_ACCESS_TOKEN, which asks for the pasted value without showing it. No deploy key is stored anywhere.
2. Run alchemy.yml once on main with adopt (gh workflow run alchemy.yml -f adopt=true). The stage prod takes over the existing project chessmerge and its production deployment and pushes to it; nothing is created or deleted. Each push to main deploys from then on.

convex/http.ts imports .convex-hosting/version.js, which a deploy writes, and the server build dist/server/server.js. In a new clone, convex dev cannot push until both exist, so run npx convex dev --skip-push (it creates the development deployment and .env.local without a push), then pnpm run deploy:dev (it builds dist/ and writes the version file), then pnpm run dev.

Note: The type checking setup uses TypeScript project references with separate configurations:

• tsconfig.app.json - Frontend React app (src/ directory)
• tsconfig.node.json - Node.js tooling (vite.config.ts, etc.)
• convex/tsconfig.json - Convex backend functions

The generated Convex bindings in convex/_generated are committed so CI can build without development deployment credentials. Run pnpm exec convex codegen after changing backend modules or the schema.

Convex renders the pages on the server. A path without a file reaches convex/http.ts, which renders it with the TanStack Start server build through @samebase/convex-hosting-tanstack-start. Route loaders load the public Convex data (the lobby's live games, a challenge, a game), so the first HTML contains it, and the browser keeps it live. A missing challenge or game answers 404. Convex Auth keeps the session in the browser's localStorage, so the server always renders signed out, and the visitor's own data (the header name, "My games", a player's controls) appears after the page loads.

/rules is prerendered at build time and served as a file. A prerendered route and its parents must not query Convex, because CI builds with a placeholder VITE_CONVEX_URL.

Authentication email setup

ChessMerge uses Convex Auth with email/password accounts. A new account does not receive a session until the user enters the 8-digit code sent through Cloudflare Email Sending. The same setup handles password reset codes.

This is the beginning of the README. Read the rest at the original. Read the full README ↗