mcpField
I
integration-nextjs-app-router

integration-nextjs-app-router

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

关于 integration-nextjs-app-router

为 Next.js App Router 应用添加 PostHog 分析的开发技能，面向实施集成的开发者。它按阶段提供工作流和参考示例，并强调使用环境变量及尽量少改动现有代码。

主要功能

  1. 01分阶段集成工作流
  2. 02Next.js App Router 配置指导
  3. 03用户识别与事件采集建议
  4. 04错误跟踪集成建议
  5. 05参考示例与文档索引

适用场景

  1. 01为 Next.js 应用接入 PostHog
  2. 02为登录和注册事件识别用户
  3. 03在关键流程中添加错误跟踪

安装

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

$npx skills add https://github.com/posthog/skills --skill integration-nextjs-app-router

安装后在 Claude Code 中输入/integration-nextjs-app-router确认已加载。

包含的文件

除 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
next-js.md

详细介绍

Next.js App Router 的 PostHog 集成

此技能可帮助你将 PostHog 分析添加到 Next.js App Router 应用中。

工作流

按以下步骤的顺序完成集成：

  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 - Next.js App Router 示例项目代码
  • references/next-js.md - Next.js - 文档
  • 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 代码。不要替换或重构现有代码。
  • 遵循示例：实现应尽可能贴合示例项目中的模式。

框架指南

  • 对于 Next.js 15.3 及更高版本，最简单的设置方式是在 instrumentation-client.ts 中初始化 PostHog
  • 对于功能标志，使用 useFeatureFlagEnabled() 或 useFeatureFlagPayload() 钩子——它们会自动处理加载状态和外部同步
  • 在用户操作发生的事件处理程序中添加分析采集，而不是在响应状态变化的 useEffect 中
  • 不要使用 useEffect 转换数据——应在渲染期间计算派生值
  • 不要使用 useEffect 响应用户事件——应将逻辑放在事件处理程序本身中
  • 不要使用 useEffect 链式更新状态——应在事件处理程序中一起计算所有相关更新
  • 不要使用 useEffect 通知父组件——应在事件处理程序中调用 setState 的同时调用父组件的回调
  • 若要在 prop 变化时重置组件状态，请将该 prop 作为组件的 key 传入，而不要使用 useEffect
  • useEffect 仅用于与外部系统同步（非 React 小部件、浏览器 API、网络订阅）

识别用户

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

错误跟踪

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

评论

支持 Markdown