mcpField
I
integration-react-tanstack-router-code-based

integration-react-tanstack-router-code-based

github.com/posthog数据与数据库7698 次安装今天更新
代码仓库

关于 integration-react-tanstack-router-code-based

这项技能指导在使用代码式 TanStack Router 的 React 应用中接入 PostHog 分析，并通过分阶段流程和框架规范引导实现。

主要功能

  1. 01分阶段接入流程
  2. 02代码式路由规范指导
  3. 03使用导航事件跟踪页面浏览
  4. 04用户识别与错误跟踪
  5. 05通过环境变量管理密钥

适用场景

  1. 01为 React 应用接入 PostHog
  2. 02埋点跟踪路由页面浏览
  3. 03跟踪登录和注册用户身份

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/skills --skill integration-react-tanstack-router-code-based

安装后在 Claude Code 中输入/integration-react-tanstack-router-code-based确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
basic-integration-1.0-begin.md
basic-integration-1.1-edit.md
basic-integration-1.2-revise.md
basic-integration-1.3-conclude.md
EXAMPLE.md
identify-users.md
tanstack-start.md

详细介绍

React 与 TanStack Router（基于代码）的 PostHog 集成

此技能可帮助你在 React 与 TanStack Router（基于代码）应用中添加 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 - React 与 TanStack Router（基于代码）示例项目代码
  • 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 通知父组件——应在事件处理程序中设置状态的同时调用父组件回调
  • 若要在 prop 变化时重置组件状态，请将该 prop 作为组件的 key 传入，而不是使用 useEffect
  • useEffect 仅用于与外部系统同步（非 React 小部件、浏览器 API、网络订阅）
  • 页面浏览跟踪应使用 TanStack Router 内置的导航事件，而不是 useEffect
  • 在根组件中使用 PostHogProvider，该组件可以按基于文件的约定定义（__root.tsx），也可以按基于代码的约定定义（调用 createRootRoute() 的位置），这样所有子路由都能访问 PostHog 客户端

识别用户

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

错误跟踪

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

评论

支持 Markdown