integration-tanstack-start

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog integration for TanStack Start

适用于TanStack Start的PostHog集成方案

This skill helps you add PostHog analytics to TanStack Start applications.

本技能可帮助你在TanStack Start应用中添加PostHog分析功能。

Workflow

操作流程

Follow these steps in order to complete the integration:

```
basic-integration-1.0-begin.md
```
- PostHog Setup - Begin ← Start here
```
basic-integration-1.1-edit.md
```
- PostHog Setup - Edit
```
basic-integration-1.2-revise.md
```
- PostHog Setup - Revise
```
basic-integration-1.3-conclude.md
```
- PostHog Setup - Conclusion

请按以下步骤完成集成：

```
basic-integration-1.0-begin.md
```
- PostHog 配置 - 开始 ← 从此处启动
```
basic-integration-1.1-edit.md
```
- PostHog 配置 - 编辑
```
basic-integration-1.2-revise.md
```
- PostHog 配置 - 修改
```
basic-integration-1.3-conclude.md
```
- PostHog 配置 - 总结

Reference files

参考文件

```
references/EXAMPLE.md
```
- TanStack Start example project code
```
references/tanstack-start.md
```
- Tanstack start - docs
```
references/identify-users.md
```
- Identify users - docs

references/basic-integration-1.0-begin.md

- PostHog setup - begin

references/basic-integration-1.1-edit.md

- PostHog setup - edit

references/basic-integration-1.2-revise.md

- PostHog setup - revise

references/basic-integration-1.3-conclude.md

- PostHog setup - conclusion

The example project shows the target implementation pattern. Consult the documentation for API details.

```
references/EXAMPLE.md
```
- TanStack Start 示例项目代码
```
references/tanstack-start.md
```
- TanStack Start 文档
```
references/identify-users.md
```
- 用户识别文档

references/basic-integration-1.0-begin.md

- PostHog 配置 - 开始

references/basic-integration-1.1-edit.md

- PostHog 配置 - 编辑

references/basic-integration-1.2-revise.md

- PostHog 配置 - 修改

references/basic-integration-1.3-conclude.md

- PostHog 配置 - 总结

示例项目展示了目标实现模式。如需了解API细节，请查阅相关文档。

Key principles

核心原则

Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
Minimal changes: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
Match the example: Your implementation should follow the example project's patterns as closely as possible.

环境变量：始终使用环境变量存储PostHog密钥，切勿硬编码。
最小改动：在现有集成代码旁添加PostHog代码，不要替换或重构现有代码。
匹配示例：你的实现应尽可能贴近示例项目的模式。

Framework guidelines

框架指南

For feature flags, use useFeatureFlagEnabled() or useFeatureFlagPayload() hooks - they handle loading states and external sync automatically
Add analytics capture in event handlers where user actions occur, NOT in useEffect reacting to state changes
Do NOT use useEffect for data transformation - calculate derived values during render instead
Do NOT use useEffect to respond to user events - put that logic in the event handler itself
Do NOT use useEffect to chain state updates - calculate all related updates together in the event handler
Do NOT use useEffect to notify parent components - call the parent callback alongside setState in the event handler
To reset component state when a prop changes, pass the prop as the component's key instead of using useEffect
useEffect is ONLY for synchronizing with external systems (non-React widgets, browser APIs, network subscriptions)
Use PostHogProvider in the root route (__root.tsx) for client-side tracking
Use posthog-node for server-side event capture in API routes (src/routes/api/) - do NOT use posthog-js on the server
Create a singleton PostHog server client to avoid re-initialization on every request
Use TanStack Router's built-in navigation events for pageview tracking instead of useEffect
Use PostHogProvider in the root component defined in either the file-based convention (__root.tsx) or code-based convention (wherever createRootRoute() is called) so all child routes have access to the PostHog client

对于功能标志，请使用useFeatureFlagEnabled()或useFeatureFlagPayload()钩子——它们会自动处理加载状态和外部同步
在用户操作发生的事件处理程序中添加分析捕获，不要在响应状态变化的useEffect中添加
不要使用useEffect进行数据转换——应在渲染期间计算派生值
不要使用useEffect响应用户事件——将逻辑放在事件处理程序本身中
不要使用useEffect链式更新状态——在事件处理程序中一次性计算所有相关更新
不要使用useEffect通知父组件——在事件处理程序中调用父回调的同时执行setState
当属性变化时重置组件状态，请将该属性作为组件的key传递，而非使用useEffect
useEffect仅用于与外部系统同步（非React组件、浏览器API、网络订阅）
在根路由(__root.tsx)中使用PostHogProvider进行客户端追踪
在API路由(src/routes/api/)中使用posthog-node进行服务端事件捕获——不要在服务端使用posthog-js
创建单例PostHog服务端客户端，避免每次请求都重新初始化
使用TanStack Router内置的导航事件进行页面浏览追踪，而非useEffect
在基于文件约定(__root.tsx)或基于代码约定（调用createRootRoute()的位置）定义的根组件中使用PostHogProvider，以便所有子路由都能访问PostHog客户端

Identifying users

用户识别

Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. If both frontend and backend code exist, pass the client-side session and distinct ID using

X-POSTHOG-DISTINCT-ID

and

X-POSTHOG-SESSION-ID

headers to maintain correlation.

在登录和注册事件期间识别用户。请参考示例代码和文档，了解适用于该框架的正确识别模式。如果同时存在前端和后端代码，请使用

X-POSTHOG-DISTINCT-ID

和

X-POSTHOG-SESSION-ID

标头传递客户端会话和唯一ID，以保持关联。

Error tracking

错误追踪

Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries.

在相关文件中添加PostHog错误追踪，尤其是关键用户流程和API边界附近。