mcpField
I
integration-tanstack-start

integration-tanstack-start

github.com/posthog开发76226 次安装今天更新
代码仓库

关于 integration-tanstack-start

integration-tanstack-start 是帮助开发者在 TanStack Start 应用中集成 PostHog 的技能。它按分阶段流程提供实现指导，并强调环境变量、最小化代码改动及框架适用的客户端与服务端追踪方式。

主要功能

  1. 01按阶段引导 PostHog 集成
  2. 02参考 TanStack Start 示例与文档
  3. 03使用环境变量保存密钥
  4. 04指导客户端与服务端事件采集
  5. 05提供用户识别和错误追踪指导

适用场景

  1. 01为 TanStack Start 应用添加页面追踪
  2. 02在登录和注册流程识别用户
  3. 03在 API 路由中采集服务端事件

安装

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

$npx skills add https://github.com/posthog/skills --skill integration-tanstack-start

安装后在 Claude Code 中输入/integration-tanstack-start确认已加载。

包含的文件

除 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

详细介绍

TanStack Start 的 PostHog 集成

此技能可帮助你在 TanStack Start 应用中添加 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 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 详情。

关键原则

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

框架指南

  • 对于功能标志，请使用 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
  • 在根组件中使用 PostHogProvider。根组件可通过基于文件的约定（__root.tsx）定义，也可通过基于代码的约定定义（调用 createRootRoute() 的位置），确保所有子路由都能访问 PostHog 客户端

用户识别

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

错误跟踪

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

评论

支持 Markdown