toolchain-preferences（工具链首选项）

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:

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.

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