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

Observability Stack

Error Tracking: Sentry (Required)

Why Sentry:

• Source maps: Translates minified errors to readable stack traces

• Deduplication: 10,000 identical errors → 1 alert

• Breadcrumbs: Auto-records user actions before crash

• Vercel integration: Automatic source map uploads

Setup:

pnpm add @sentry/nextjs npx @sentry/wizard@latest -i nextjs

Free tier: 5K errors/month — enough until you have traction.

Product Analytics: PostHog (Required for user-facing apps)

Why PostHog:

• Terraform-native: Only major analytics with official Terraform provider

• All-in-one: Analytics + feature flags + session replay + A/B testing

• Developer-first: Open source, self-hostable, transparent pricing

• CLI-manageable: Fits agentic development workflow

Setup:

pnpm add posthog-js

Free tier: 1M events/month — generous for most apps.

Track conversion events only: signup, subscription, import, key actions. Let autocapture handle generic clicks.

NOT Vercel Analytics

Do NOT use Vercel Analytics. It has:

• No API access

• No CLI access

• No MCP server

• No way to query programmatically

This makes it completely unusable for AI-assisted workflows. PostHog handles web vitals AND product analytics with full API/MCP access.

Structured Logging: Pino

Why Pino:

• Fastest Node.js logger

• JSON output in production

• Pretty output in development

Edge runtime fallback: Use structured console.log when Pino not available.

Avoid

❌ Mixpanel/Amplitude — Poor CLI automation, expensive at scale

❌ Custom analytics — 800+ hours to reach feature parity; free tiers cover you

❌ Google Analytics — Privacy concerns, poor product analytics

❌ Dashboard-only tools — No CLI/API = not automatable

❌ Vercel Analytics — No API, no CLI, no MCP (completely unusable for our workflow)

Decision Tree

User-facing app?

• YES → Sentry + PostHog

• NO (internal tool) → Sentry + structured logging only

Need feature flags?

• YES → PostHog feature flags (skip LaunchDarkly)

• NO → Skip for now, easy to add later

Need session replay?

• YES → PostHog session replay

• NO → Skip (costs extra)

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:

• Solve real problems (not resume-driven development)

• Have good documentation and community

• Integrate well with the rest of the stack

• Match project requirements (not all projects need real-time)

Prefer boring technology that works over shiny technology that might.

Tool Selection Criteria

Evaluate tools against these requirements (priority order):

1. CLI-First (Required)

Tool must be fully operable from command line. Dashboard-only = rejected.

2. API-Native (Required)

Programmatic access for automation and scripting.

3. MCP-Ready (Strongly Preferred)

Model Context Protocol server for AI agent integration. Check:

• Official MCP server: @stripe/mcp , @posthog/mcp-server , Sentry MCP

• Community MCP server: acceptable if maintained

• No MCP: acceptable only if CLI/API are excellent

Current Stack MCP Status

Service MCP Notes

PostHog ✅ Official @posthog/mcp-server

Sentry ✅ Official @sentry/mcp-server

Stripe ✅ Official @stripe/mcp

Vercel ✅ Official @vercel/mcp

GitHub ✅ Official @modelcontextprotocol/server-github

Clerk ❌ Monitor for MCP support

Convex ❌ CLI is good, no MCP yet