integration-react-tanstack-router-file-based

使用 TanStack Router（基于文件路由）的 React PostHog 集成

此技能可帮助你在使用 TanStack Router（基于文件路由）的 React 应用中添加 PostHog 分析功能。

工作流

按顺序完成以下步骤：

1. basic-integration-1.0-begin.md - PostHog 设置 - 开始 ← 从这里开始
2. basic-integration-1.1-edit.md - PostHog 设置 - 编辑
3. basic-integration-1.2-revise.md - PostHog 设置 - 修订
4. basic-integration-1.3-conclude.md - PostHog 设置 - 总结

参考文件

• references/EXAMPLE.md - 使用 TanStack Router（基于文件路由）的 React 示例项目代码
• 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 详情。

关键原则

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

框架指南

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

识别用户

在登录和注册事件期间识别用户。请参阅示例代码和文档，了解此框架的正确识别模式。如果前端和后端代码都存在，请通过 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 请求头传递客户端会话和 distinct ID，以保持关联。

错误跟踪

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