A full-stack React starter template, optimized for AI-assisted development. Configured so LLM agents can understand, modify, and extend the codebase.
| Category | Technology |
|---|---|
| Framework | React Router 7 (framework mode, SSR) |
| UI | React 19, Tailwind CSS v4, Base UI via shadcn |
| Auth | Better Auth (email/password, sessions, middleware) |
| Database | Drizzle ORM + SQLite (better-sqlite3) |
| Validation | Zod |
| Toolchain | Vite+ (dev, build, test, lint, format — unified via vp) |
| Unused code | Knip |
| Commits | Conventional Commits via commitlint |
| Language | TypeScript (strict mode) |
- Server-side rendering with React Router 7 framework mode
- Authentication with email/password sign up, sign in, and session management
- Protected routes via middleware (
requireAuth/requireGuest) - Dark mode without FOUC — inline script sets color-scheme before first paint using a cookie
- Type-safe database with Drizzle ORM, auto-generated route types, and Zod validation
- One-command setup — install, generate env, push schema, seed DB, start dev server
- Auto-formatting on commit via Vite+ staged hooks (
vp staged) - Exact version pinning — no caret or tilde ranges via
.npmrc - 11 custom AI agent skills for React Router, Better Auth, security, design patterns, and more
- 4 MCP servers for component installation, auth docs, library docs, and browser automation
Tip
Deploying to Vercel? Use the deploy/vercel branch — it swaps better-sqlite3 for Turso (libSQL), adds the @vercel/react-router preset, and is ready for serverless deployment. See the live demo.
git clone https://github.com/nikolailehbrink/llm-stack.git
cd llm-stack
vp run setupThis will install dependencies, create a .env file with a generated secret, push the database schema, and seed a demo user ([email protected] / password123).
vp devOpens at http://localhost:5173.
Use vp (Vite+) for all development commands. Built-in commands run directly; package.json scripts run via vp run.
| Command | Description |
|---|---|
vp run setup |
First-time project setup |
vp dev |
Start dev server with HMR |
vp build |
Production build |
vp run start |
Production server |
vp preview |
Preview build |
vp run typecheck |
Generate route types and run tsc |
vp lint |
Lint code |
vp lint --fix |
Lint with auto-fix |
vp fmt |
Format code |
vp fmt --check |
Check formatting |
vp check |
Format + lint |
vp test |
Run tests |
vp run knip |
Check for unused code |
vp run db:push |
Push schema to database |
vp run db:generate |
Generate migration files |
vp run db:migrate |
Run migrations |
vp run db:seed |
Seed database with demo user |
vp run db:studio |
Open Drizzle Studio |
vp run clean |
Remove node_modules, .react-router, and build |
llm-stack/
├── .agents/skills/ # 11 custom AI agent skills
├── .vite-hooks/ # Git hooks (pre-commit, pre-push, commit-msg)
├── .vscode/ # VS Code workspace settings and extensions
├── app/
│ ├── components/
│ │ ├── ui/ # Base UI components (avatar, button, card, dropdown-menu, input, label, tooltip)
│ │ └── color-scheme-toggle.tsx
│ ├── db/
│ │ ├── index.server.ts # Database connection (WAL mode)
│ │ ├── schema.ts # Drizzle schema
│ │ └── seed.ts # Database seeding script
│ ├── lib/
│ │ ├── auth.server.ts # Better Auth instance
│ │ ├── auth-client.ts # Client-side auth (signIn, signUp, signOut, useSession)
│ │ ├── auth-middleware.server.ts # requireAuth & requireGuest
│ │ ├── color-scheme.server.ts # Color scheme cookie handling
│ │ └── utils.ts # cn() utility
│ ├── routes/
│ │ ├── home.tsx # Landing page
│ │ ├── auth.tsx # Sign in / sign up
│ │ ├── protected/
│ │ │ ├── layout.tsx # Auth middleware wrapper
│ │ │ └── dashboard.tsx
│ │ └── api/
│ │ ├── auth/catch-all.ts # Better Auth handler
│ │ └── color-scheme.ts # Color scheme endpoint
│ ├── routes.ts # Route definitions
│ ├── root.tsx # Root layout
│ ├── context.ts # Session context
│ └── app.css # Tailwind v4 theme and styles
├── CLAUDE.md # References AGENTS.md for Claude Code
├── AGENTS.md # Project context, rules, and conventions for AI agents
└── .mcp.json # MCP server configuration
Files suffixed .server.ts are excluded from client bundles.
This project is designed to work with Claude Code. The AI agent configuration consists of three layers:
CLAUDE.md references AGENTS.md, which serves as the single source of truth for AI agents. It covers commands, architecture, auth flow, database, UI components, tooling, and all code rules with skill references in every relevant section.
Located in .agents/skills/, these provide specialized knowledge:
| Skill | Purpose |
|---|---|
react-router-framework-mode |
Routes, loaders, actions, middleware, SSR |
better-auth-best-practices |
Auth flow patterns and integration |
better-auth-security-best-practices |
Rate limiting, CSRF, session security |
email-and-password-best-practices |
Secure email/password auth |
two-factor-authentication-best-practices |
2FA implementation |
create-auth-skill |
Auth layer scaffolding |
organization-best-practices |
Multi-tenant orgs and RBAC |
frontend-design |
Production-grade UI design |
web-design-guidelines |
Accessibility and UX auditing |
vercel-react-best-practices |
React performance optimization |
vercel-composition-patterns |
Component composition and architecture |
Configured in .mcp.json:
| Server | Type | Purpose |
|---|---|---|
| shadcn | CLI | Install and manage Base UI components |
| better-auth | HTTP | Query Better Auth documentation |
| context7 | HTTP | Fetch up-to-date docs for any library |
| chrome-devtools | CLI | Browser automation, performance tracing, debugging |
Hooks are stored in .vite-hooks/ and managed by vp config via the prepare script.
| Hook | What it does |
|---|---|
| pre-commit | Runs vp staged (format + lint on staged files) + knip |
| pre-push | Runs typecheck and tests |
| commit-msg | Enforces conventional commit format |
- User visits
/authto sign up or sign in with email/password - Better Auth handles credentials and creates a session cookie
- Protected routes (e.g.
/dashboard) userequireAuthmiddleware - Session data is passed via React Router context to loaders and components
requireGuestmiddleware redirects authenticated users away from/auth
Auth mutations use clientAction exports (browser-side) because Better Auth's client manages session cookies directly.