Back to Details

integration-astro-hybrid

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PostHog integration for Astro (Hybrid)

适用于Astro（混合渲染）的PostHog集成方案

This skill helps you add PostHog analytics to Astro (Hybrid) applications.
本技能可帮助你为Astro（混合渲染）应用添加PostHog分析功能。

Workflow

工作流程

Follow these steps in order to complete the integration:
  1. basic-integration-1.0-begin.md
    - PostHog Setup - Begin ← Start here
  2. basic-integration-1.1-edit.md
    - PostHog Setup - Edit
  3. basic-integration-1.2-revise.md
    - PostHog Setup - Revise
  4. basic-integration-1.3-conclude.md
    - PostHog Setup - Conclusion
按以下步骤完成集成：
  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 设置 - 完成

Reference files

参考文件

  • references/EXAMPLE.md
    - Astro (Hybrid) example project code
  • references/astro.md
    - Astro - 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
    - Astro（混合渲染）示例项目代码
  • references/astro.md
    - Astro - 文档
  • 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

框架指南

  • Always use the is:inline directive on PostHog script tags to prevent Astro from processing them and causing TypeScript errors
  • Use PUBLIC_ prefix for client-side environment variables in Astro (e.g., PUBLIC_POSTHOG_PROJECT_TOKEN)
  • Create a posthog.astro component in src/components/ for reusable initialization across pages
  • Import the PostHog component in a Layout and wrap all pages with that layout
  • Use posthog-node in API routes under src/pages/api/ for server-side event tracking
  • Store the posthog-node client instance in a singleton pattern (src/lib/posthog-server.ts) to avoid creating multiple clients
  • In Astro 5, use output static (the default) with an adapter - pages are prerendered by default
  • Use export const prerender = false to opt specific pages into SSR when they need server-side rendering
  • Only pages that need server-side PostHog tracking (like API-backed forms) should opt out of prerendering
  • 务必在PostHog脚本标签上使用is:inline指令，防止Astro处理这些标签导致TypeScript错误
  • 在Astro中，客户端环境变量需使用PUBLIC_前缀（例如：PUBLIC_POSTHOG_PROJECT_TOKEN）
  • 在src/components/目录下创建posthog.astro组件，用于在多个页面中复用初始化逻辑
  • 在布局组件中导入PostHog组件，并使用该布局包裹所有页面
  • 在src/pages/api/下的API路由中使用posthog-node进行服务器端事件追踪
  • 将posthog-node客户端实例存储为单例模式（src/lib/posthog-server.ts），避免创建多个客户端
  • 在Astro 5中，使用默认的output static模式并搭配适配器——页面默认会被预渲染
  • 使用export const prerender = false将特定页面设置为SSR模式，当这些页面需要服务器端渲染时
  • 只有需要服务器端PostHog追踪的页面（如基于API的表单页面）才需要关闭预渲染

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边界处。