toolchain-preferences

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Toolchain Preferences

工具链偏好

Default technology stack and tooling choices for new projects.

新项目默认采用的技术栈和工具选择。

Package Management

包管理

pnpm (Default)

pnpm（默认选择）

Why pnpm:

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

Usage:

bash

pnpm install
pnpm add <package>
pnpm dev

为什么选择pnpm：

比npm/yarn更快
通过内容寻址存储实现磁盘高效利用
默认严格模式（无幽灵依赖）
更好的单仓库（monorepo）支持

使用方式：

bash

pnpm install
pnpm add <package>
pnpm dev

Version Management: asdf

版本管理：asdf

Node.js version per project:

undefined

按项目配置Node.js版本：

undefined

.tool-versions

nodejs 22.15.0


Ensures consistent environments across projects and machines.

nodejs 22.15.0


确保跨项目和跨机器的环境一致性。

Core Stack

核心技术栈

Framework: Next.js App Router + TypeScript

框架：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

为什么选择Next.js：

全栈React框架
支持服务端组件、流式渲染、React Server Components（RSC）
出色的开发体验，迭代速度快
零配置路由、API路由、服务端操作

始终使用TypeScript：

从数据库到UI的类型安全
更好的IDE支持，重构更有信心
编译阶段捕获错误

Backend: Convex

后端：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

为什么选择Convex：

实时数据库即服务
从数据库到UI的类型安全（自动生成类型）
带自动缓存的响应式查询
无需API层——直接调用函数
内置认证、文件存储、调度功能

适用场景：

实时功能（聊天、协作、实时更新）
快速原型开发（跳过API样板代码）
类型安全全栈（数据库→UI）

替代方案： 非实时应用使用tRPC + Prisma

Deployment: Vercel

部署：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)

为什么选择Vercel：

Next.js零配置部署
边缘函数、分析功能、预览部署
与Next.js特性（中间件、增量静态再生等）深度集成
出色的开发体验（git推送即可部署）

UI Stack

UI技术栈

Styling: Tailwind CSS + shadcn/ui

样式：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

Tailwind CSS：

实用优先的CSS，迭代速度快
通过
```
tailwind.config.ts
```
实现一致的设计系统
无CSS文件冗余，支持摇树优化
响应式设计、暗黑模式、任意值支持

shadcn/ui：

复制粘贴式组件（无需作为依赖安装）
完全控制组件代码
基于Radix原语构建
默认支持无障碍访问

替代方案： 需要完全自定义时直接使用Radix UI

State Management: Zustand

状态管理：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

为什么选择Zustand：

相比Redux，样板代码极少
API简洁，符合React模式
适用于客户端状态管理（Convex处理服务端状态）

适用场景：

客户端UI状态（模态框、表单、偏好设置）
无需属性透传的跨组件状态

替代方案： 简单场景使用React Context + Hooks

Data Handling: TanStack Query + TanStack Table

数据处理：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

TanStack Query：

服务端状态管理（不使用Convex时）
缓存、重新获取、乐观更新
替代Redux处理服务端数据

TanStack Table：

无头表格逻辑（排序、筛选、分页）
兼容任意UI框架
完全可自定义，支持无障碍访问

Observability Stack

可观测性技术栈

Error Tracking: Sentry (Required)

错误追踪：Sentry（必填）

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:

bash

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

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

为什么选择Sentry：

源映射：将压缩后的错误转换为可读的堆栈跟踪
去重：10000个相同错误→1条告警
面包屑：自动记录崩溃前的用户操作
Vercel集成：自动上传源映射

搭建步骤：

bash

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

免费额度： 每月5000条错误——在获得用户 traction 前足够使用。

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

产品分析：PostHog（面向用户的应用必填）

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:

bash

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.

为什么选择PostHog：

原生支持Terraform：唯一拥有官方Terraform Provider的主流分析工具
一站式：分析+功能开关+会话重放+A/B测试
开发者友好：开源、可自托管、定价透明
支持CLI管理：适配智能代理开发工作流

搭建步骤：

bash

pnpm add posthog-js

免费额度： 每月100万条事件——对大多数应用来说足够慷慨。

仅追踪转化事件： 注册、订阅、导入、关键操作。让自动捕获处理通用点击事件。

NOT Vercel Analytics

请勿使用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.

禁止使用Vercel Analytics，原因如下：

无API访问权限
无CLI访问权限
无MCP服务器
无法通过编程方式查询

这使其完全无法用于AI辅助工作流。PostHog同时处理Web性能指标和产品分析，且支持完整的API/MCP访问。

Structured Logging: Pino

结构化日志：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.

为什么选择Pino：

最快的Node.js日志工具
生产环境输出JSON格式
开发环境输出美观格式

边缘运行时降级方案： 当Pino不可用时，使用结构化console.log。

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)

❌ Mixpanel/Amplitude —— CLI自动化支持差，规模化后成本高

❌ 自定义分析工具 —— 达到功能对等需要800+小时；免费额度已能满足需求

❌ Google Analytics —— 隐私问题，产品分析能力弱

❌ 仅支持仪表盘的工具 —— 无CLI/API=无法自动化

❌ Vercel Analytics —— 无API、无CLI、无MCP（完全不适用于我们的工作流）

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)

是否为面向用户的应用？

是 → Sentry + PostHog
否（内部工具）→ Sentry + 仅结构化日志

是否需要功能开关？

是 → PostHog功能开关（跳过LaunchDarkly）
否 → 暂时跳过，后续可轻松添加

是否需要会话重放？

是 → PostHog会话重放
否 → 跳过（额外成本）

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

Next.js项目：

使用Next.js内置构建工具（Turbopack或webpack）
零配置，针对框架优化

独立应用（React/Vue/Svelte）：

Vite：快速、现代、出色的开发体验
热模块替换（HMR）、即时服务器启动、优化构建

库项目：

tsup：简洁的TypeScript打包工具
unbuild：干净、极简的构建工具

Testing

测试

Vitest (Default)

Vitest（默认选择）

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

为什么选择Vitest：

快速、现代的测试运行器
兼容Jest API（迁移简单）
出色的TypeScript支持
监听模式、覆盖率、快照

适用场景：

单元测试、集成测试
组件测试（搭配@testing-library/react）

端到端测试：

使用Playwright进行端到端测试

Quick Reference

快速参考

New Project Setup

新项目搭建

bash

undefined

bash

undefined

Create Next.js app with TypeScript

创建带TypeScript的Next.js应用

npx create-next-app@latest --typescript --tailwind --app

Use pnpm

使用pnpm

pnpm install

Add Convex

添加Convex

pnpm add convex npx convex dev

Add shadcn/ui

添加shadcn/ui

npx shadcn@latest init npx shadcn@latest add button card

Add Zustand (if needed)

添加Zustand（如有需要）

pnpm add zustand

Add testing

添加测试依赖

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

undefined

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

undefined

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)

是否需要实时数据？

是 → Convex
否 → TanStack Query + API层（或tRPC）

是否需要复杂客户端状态？

是 → Zustand
否 → React Context + useState/useReducer

是否需要数据表格？

是 → TanStack Table
否 → 普通HTML表格或简单列表

是否需要UI组件？

从shadcn/ui开始（复制粘贴）
根据需要自定义（代码完全由你掌控）

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

静态站点：

考虑用Astro替代Next.js
更适合内容密集、交互性低的站点

非实时应用：

用tRPC + Prisma替代Convex
对数据库模式、迁移有更多控制权

简单项目：

用React Context替代Zustand
减少小型应用的依赖

组件库项目：

直接使用Radix UI替代shadcn
从一开始就需要100%控制时

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

❌ npm/yarn —— 为了一致性，使用pnpm

❌ Redux —— 样板代码过多；使用Zustand或TanStack Query

❌ 类组件 —— 使用函数组件 + Hooks

❌ CSS-in-JS（styled-components、Emotion） —— 运行时开销大；使用Tailwind

❌ Create React App —— 已废弃；使用Vite或Next.js

❌ 作为依赖的组件库 —— 优先选择shadcn的复制粘贴方式

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)

1. 优先CLI优先（必填）

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

工具必须完全支持命令行操作。仅支持仪表盘的工具直接淘汰。

2. API-Native (Required)

2. 原生支持API（必填）

Programmatic access for automation and scripting.

提供编程访问权限，用于自动化和脚本编写。

3. MCP-Ready (Strongly Preferred)

3. 支持MCP（强烈推荐）

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

支持Model Context Protocol服务器，用于AI Agent集成。检查：

官方MCP服务器：
```
@stripe/mcp
```
、
```
@posthog/mcp-server
```
、Sentry MCP
社区维护的MCP服务器：若维护良好则可接受
无MCP支持：仅当CLI/API足够出色时可接受

Current Stack MCP Status

当前技术栈的MCP支持状态

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

服务	MCP支持	说明
PostHog	✅ 官方	`@posthog/mcp-server`
Sentry	✅ 官方	`@sentry/mcp-server`
Stripe	✅ 官方	`@stripe/mcp`
Vercel	✅ 官方	`@vercel/mcp`
GitHub	✅ 官方	`@modelcontextprotocol/server-github`
Clerk	❌	关注其MCP支持进展
Convex	❌	CLI功能完善，但暂无MCP支持