Toolchain Preferences

Default technology stack and tooling choices for new projects.

Package Management

pnpm (Default)

Why pnpm:

• Faster than npm/yarn
• Disk-efficient through content-addressable storage
• Strict by default (no phantom dependencies)
• Better monorepo support

Usage:

pnpm install
pnpm add <package>
pnpm dev

Version Management: asdf

Node.js version per project:

# .tool-versions
nodejs 22.15.0

Ensures consistent environments across projects and machines.

Core Stack

Framework: Next.js App Router + TypeScript

Why Next.js:

• Full-stack React framework
• Server components, streaming, React Server Components (RSC)
• Excellent developer experience, fast iteration
• Zero-config routing, API routes, server actions

Always TypeScript:

• Type safety from database to UI
• Better IDE support, refactoring confidence
• Catches errors at compile time

Backend: Convex

Why Convex:

• Real-time database as a service
• Type-safe from database to UI (auto-generated types)
• Reactive queries with automatic caching
• No API layer needed — direct function calls
• Built-in auth, file storage, scheduling

When to use:

• Real-time features (chat, collaboration, live updates)
• Rapid prototyping (skip API boilerplate)
• Type-safe full-stack (database → UI)

Alternative: tRPC + Prisma for non-real-time apps

Deployment: Vercel

Why Vercel:

• Zero-config Next.js deployment
• Edge functions, analytics, preview deployments
• Tight integration with Next.js features (middleware, ISR, etc.)
• Great DX (git push → deployed)

UI Stack

Styling: Tailwind CSS + shadcn/ui

Tailwind CSS:

• Utility-first CSS for fast iteration
• Consistent design system via tailwind.config.ts
• No CSS file overhead, tree-shakeable
• Responsive, dark mode, arbitrary values

shadcn/ui:

• Copy-paste components (NOT a dependency)
• Full control over component code
• Built on Radix primitives
• Accessible by default

Alternative: Use Radix UI directly for full customization

State Management: Zustand

Why Zustand:

• Minimal boilerplate vs Redux
• Simple API, works with React patterns
• Good for client-side state (Convex handles server state)

When to use:

• Client-side UI state (modals, forms, preferences)
• Cross-component state without prop drilling

Alternative: React Context + hooks for simple cases

Data Handling: TanStack Query + TanStack Table

TanStack Query:

• Server state management (when NOT using Convex)
• Caching, refetching, optimistic updates
• Replaces Redux for server data

TanStack Table:

• Headless table logic (sorting, filtering, pagination)
• Works with any UI framework
• Fully customizable, accessible

Build Tools

Default Build Tool by Project Type

Next.js projects:

• Use Next.js built-in build (Turbopack or webpack)
• Zero config, optimized for framework

Standalone apps (React/Vue/Svelte):

• Vite: Fast, modern, great DX
• HMR, instant server start, optimized builds

Libraries:

• tsup: Simple TypeScript bundler
• unbuild: Clean, minimal builds

Testing

Vitest (Default)

Why Vitest:

• Fast, modern test runner
• Compatible with Jest API (easy migration)
• Great TypeScript support
• Watch mode, coverage, snapshots

When to use:

• Unit tests, integration tests
• Component testing (with @testing-library/react)

E2E Testing:

• Playwright for end-to-end tests

Quick Reference

New Project Setup

# Create Next.js app with TypeScript
npx create-next-app@latest --typescript --tailwind --app

# Use pnpm
pnpm install

# Add Convex
pnpm add convex
npx convex dev

# Add shadcn/ui
npx shadcn@latest init
npx shadcn@latest add button card

# Add Zustand (if needed)
pnpm add zustand

# Add testing
pnpm add -D vitest @testing-library/react @testing-library/jest-dom

Dependency Decision Tree

Need real-time data?

• YES → Convex
• NO → TanStack Query + API layer (or tRPC)

Need complex client state?

• YES → Zustand
• NO → React Context + useState/useReducer

Need data tables?

• YES → TanStack Table
• NO → Plain HTML table or simple list

Need UI components?

• Start with shadcn/ui (copy-paste)
• Customize as needed (you own the code)

When to Deviate

Valid Deviations

Static sites:

• Consider Astro instead of Next.js
• Better for content-heavy, low-interactivity sites

Non-real-time apps:

• tRPC + Prisma instead of Convex
• More control over database schema, migrations

Simple projects:

• React Context instead of Zustand
• Reduce dependencies for small apps

Component libraries:

• Radix UI directly instead of shadcn
• When you need 100% control from start

Anti-Patterns to Avoid

❌ npm/yarn — Use pnpm for consistency

❌ Redux — Too much boilerplate; use Zustand or TanStack Query

❌ Class components — Use function components + hooks

❌ CSS-in-JS (styled-components, Emotion) — Runtime overhead; use Tailwind

❌ Create React App — Deprecated; use Vite or Next.js

❌ Component libraries as dependencies — Prefer shadcn copy-paste approach

Philosophy

Opinionated defaults, pragmatic deviations.

These tools work well together, have been battle-tested, and provide excellent developer experience. But they're defaults, not dogma.

Choose tools that:

1. Solve real problems (not resume-driven development)
2. Have good documentation and community
3. Integrate well with the rest of the stack
4. Match project requirements (not all projects need real-time)

Prefer boring technology that works over shiny technology that might.