Ultimate Starter

This starter is designed for me by me with all the shiny new things! (as of now)

To finish setup, run Replace All to replace startername with name of your project. Also, make sure to customize AGENTS.md with a description of your project so that agentic tools work efficiently.

Agentic Tooling

Both GitHub Copilot and Claude Code (or any AGENTS.md-aware agent) read from the same skill library under .agents/skills/*/SKILL.md:

• .github/copilot-instructions.md and .github/agents/*.md (Copilot custom agents) point into .agents/skills/.
• AGENTS.md (with CLAUDE.md symlinked to it) is the always-on guide for Claude Code and other AGENTS.md-aware tools, and points into the same .agents/skills/ directory.
• .claude/settings.json configures default tool permissions for Claude Code.

Update .agents/skills/ once and both flows pick up the change.

Project Overview

• Contract-first development. API endpoints start as shared zod schemas in packages/server-contract, ensuring server and client stay type-safe.
• Real-time challenge lifecycle. Hono-based routes expose public and authenticated procedures, backed by PostgreSQL via Drizzle ORM.
• Typed React client. The web app consumes the generated oRPC client, TanStack Router, and Query utilities for fully typed data interactions.
• Developer-focused tooling. Node.js 24, pnpm workspaces, and Husky hooks enable quick local feedback loops and consistent commits.

Tech Stack

• Runtime & Tooling: Node.js 24, pnpm workspaces, Commitizen, Husky
• Backend: TypeScript, Hono, oRPC, Drizzle ORM/PostgreSQL, Better Auth, Zod, Vitest
• Frontend: React 19, Vite, TanStack Stack/Query/Form, Tailwind CSS, Vitest
• Server Contracts: @startername/server-contract with oRPC + OpenAPI generation

Repository Structure

• apps/server – Node.js + Hono API, oRPC routers, Drizzle schema, Better Auth setup
• apps/web – React 19 client, TanStack Router tree, authentication flows, Tailwind config
• packages/server-contract – API contract definitions and schema exports
• packages/common – Shared utilities, types, constants, and helpers
• docs – Product requirements, roadmap, risk registers, and supporting documentation
• postgres-data – Docker-managed PostgreSQL volume (keep uncommitted)
• tsconfig*.json – TypeScript project references

Prerequisites

• Git ≥ 2.40
• Docker Desktop (required for the PostgreSQL container)
• Node.js exactly v24 (use nvm or similar)
• pnpm 11.5.0

Install Node.js v24

Using nvm:

nvm install 24
nvm use 24

Or using the .nvmrc file in the repo:

nvm use

Install pnpm

corepack enable
corepack prepare pnpm@11.5.0 --activate

Or via npm:

npm install -g pnpm@11.5.0

Getting Started

git clone https://github.com/CatOfJupit3r/startername.git
cd startername
pnpm install

1. Copy environment templates: duplicate .env.example to .env in both apps/server and apps/web.
2. Start Docker Desktop so PostgreSQL can launch.
3. Boot everything with pnpm run dev:
   • Web client: http://localhost:3030
   • API + Better Auth: http://localhost:5050
   • PostgreSQL starts via docker compose -f docker-compose.dev.yml --profile postgres up -d --wait

Workspace Commands

• pnpm run dev – start API, web app, and PostgreSQL
• pnpm run db:generate – generate a Drizzle migration from the schema
• pnpm run db:migrate – apply Drizzle migrations to PostgreSQL
• pnpm run db:push – push the schema directly during local development
• pnpm run check-types – TypeScript project references (server + shared)
• pnpm run lint – ESLint across the monorepo
• pnpm run prettify – format workspace source files
• pnpm run prepare – reinstall Husky hooks if they go missing
• pnpm test – run all tests with Vitest

Development Workflow

1. Create a GitHub issue describing the work.
2. Branch off main as <issue-number>-<short-slug> (e.g., 42-improve-login-flow).
3. Stage changes and run git cz (or pnpm commit) for conventional commits.
4. Push the branch and open a PR targeting main; request review from @CatOfJupit3r.

Pre-commit Hooks & Troubleshooting

• Husky runs pnpm exec lint-staged on commit to format, lint, and type-check staged files.
• Re-run failed checks locally with:

  pnpm exec lint-staged --no-stash

• Typical fixes:
  • Missing deps: pnpm install
  • Formatting issues: pnpm run prettier then re-stage
  • Lint errors: pnpm run lint
  • Type errors: pnpm run check-types

Tips & Conventions

• Keep pnpm run dev active regularly to keep local PostgreSQL available.
• Avoid rebasing on main; prefer merging.
• Use the shared contract utilities (tanstackRPC helpers, shared schemas) instead of duplicating types or query keys.
• When extending the API, register new routes in apps/server/src/routers/index.ts and add error codes to apps/server/src/enums/errors.ts.