Instrument Integration

1---
2name: instrument-integration
3description: >-
4  Add PostHog SDK integration to your application. Use when setting up PostHog
5  for the first time or reviewing PRs that need PostHog initialization. Covers
6  SDK installation, provider setup, and basic configuration for any framework.
7metadata:
8  author: PostHog
9---
10 
11# Add PostHog SDK integration
12 
13Use this skill to add the PostHog SDK to an application. Use it when setting up PostHog for the first time, or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration. Supports any framework or language.
14 
15Supported frameworks and languages: Next.js, React, React Router, Vue, Nuxt, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, PHP, Ruby on Rails, Go, Elixir, Android, iOS, Swift, Flutter, React Native, Expo, Node.js, and vanilla JavaScript.
16 
17## Instructions
18 
19Follow these steps IN ORDER:
20 
21STEP 1: Analyze the codebase and detect the platform.
22  -
23 Look for dependency files (package.json, pubspec.yaml, Podfile, Package.swift, requirements.txt, Gemfile, composer.json, go.mod, mix.exs, etc.) to determine the framework and language.
24  -
25 Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, go.sum, pubspec.lock, Podfile.lock, Package.resolved, mix.lock) to determine the package manager.
26  - Check for existing PostHog setup. If PostHog is already installed and initialized, do not modify its code. Inform the user and skip to verification.
27 
28STEP 2: Research integration.
29  2.1. Find the reference file below that matches the detected framework — it is the source of truth for SDK initialization, provider setup, and configuration patterns. Read it now.
30  2.2. If no reference matches, fall back to your general knowledge and web search. Use posthog.com/docs as the primary search source.
31 
32STEP 3: Install the PostHog SDK.
33  - Add the PostHog SDK package for the detected platform. Do not manually edit package.json — use the package manager's install command.
34  - Always install packages as a background task. Don't await completion; proceed with other work immediately after starting the installation.
35 
36STEP 4: Initialize PostHog.
37  - Follow the framework reference for where and how to initialize. This varies significantly by framework (e.g., instrumentation-client.ts for Next.js 15.3+, AppConfig.ready() for Django, create_app() for Flask).
38  - Set up the PostHog provider/wrapper component if the framework requires one.
39 
40STEP 5: Identify users.
41  - Add PostHog `identify()` calls on the client side during login and signup events.
42  - If both frontend and backend exist, pass the client-side session and distinct ID using `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` headers to the server-side code.
43 
44STEP 6: Set up environment variables.
45  - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
46  - If the PostHog API key is missing, use the PostHog MCP server's `projects-get` tool to retrieve the project's `api_token`. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead.
47  - For the PostHog host URL, use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud.
48  - Write these values to the appropriate env file (e.g. `.env.local` for Next.js, `.env` for others) using the framework's naming convention.
49  - Reference these environment variables in code instead of hardcoding them.
50 
51STEP 7: Verify and clean up.
52  - Check the project for errors. Look for type checking or build scripts in package.json.
53  - Ensure any components created were actually used.
54  - Run any linter or prettier-like scripts found in the package.json.
55 
56## Reference files
57 
58- `references/EXAMPLE-next-app-router.md` - next-app-router example project code
59- `references/EXAMPLE-next-pages-router.md` - next-pages-router example project code
60- `references/EXAMPLE-react-react-router-6.md` - react-react-router-6 example project code
61- `references/EXAMPLE-react-react-router-7-framework.md` - react-react-router-7-framework example project code
62- `references/EXAMPLE-react-react-router-7-data.md` - react-react-router-7-data example project code
63- `references/EXAMPLE-react-react-router-7-declarative.md` - react-react-router-7-declarative example project code
64- `references/EXAMPLE-react-vite.md` - react-vite example project code
65- `references/EXAMPLE-nuxt-3-6.md` - nuxt-3-6 example project code
66- `references/EXAMPLE-nuxt-4.md` - nuxt-4 example project code
67- `references/EXAMPLE-vue-3.md` - vue-3 example project code
68- `references/EXAMPLE-react-tanstack-router-file-based.md` - react-tanstack-router-file-based example project code
69- `references/EXAMPLE-react-tanstack-router-code-based.md` - react-tanstack-router-code-based example project code
70- `references/EXAMPLE-tanstack-start.md` - tanstack-start example project code
71- `references/EXAMPLE-sveltekit.md` - sveltekit example project code
72- `references/EXAMPLE-astro-static.md` - astro-static example project code
73- `references/EXAMPLE-astro-view-transitions.md` - astro-view-transitions example project code
74- `references/EXAMPLE-astro-ssr.md` - astro-ssr example project code
75- `references/EXAMPLE-astro-hybrid.md` - astro-hybrid example project code
76- `references/EXAMPLE-angular.md` - angular example project code
77- `references/EXAMPLE-javascript-node.md` - javascript-node example project code
78- `references/EXAMPLE-javascript-web.md` - javascript-web example project code
79- `references/EXAMPLE-django.md` - django example project code
80- `references/EXAMPLE-flask.md` - flask example project code
81- `references/EXAMPLE-fastapi.md` - fastapi example project code
82- `references/EXAMPLE-python.md` - python example project code
83- `references/EXAMPLE-laravel.md` - laravel example project code
84- `references/EXAMPLE-php.md` - php example project code
85- `references/EXAMPLE-ruby-on-rails.md` - ruby-on-rails example project code
86- `references/EXAMPLE-ruby.md` - ruby example project code
87- `references/EXAMPLE-android.md` - android example project code
88- `references/EXAMPLE-swift.md` - swift example project code
89- `references/EXAMPLE-react-native.md` - react-native example project code
90- `references/EXAMPLE-expo.md` - expo example project code
91- `references/next-js.md` - Next.js - docs
92- `references/react.md` - React - docs
93- `references/react-router-v6.md` - React router v6 - docs
94- `references/react-router-v7-framework-mode.md` - React router v7 framework mode (remix v3) - docs
95- `references/react-router-v7-data-mode.md` - React router v7 data mode - docs
96- `references/react-router-v7-declarative-mode.md` - React router v7 declarative mode - docs
97- `references/nuxt-js-3-6.md` - Nuxt.js (v3.0 to v3.6) - docs
98- `references/nuxt-js.md` - Nuxt.js - docs
99- `references/vue-js.md` - Vue.js - docs
100- `references/tanstack-start.md` - Tanstack start - docs
101- `references/svelte.md` - Svelte - docs
102- `references/astro.md` - Astro - docs
103- `references/angular.md` - Angular - docs
104- `references/js.md` - JavaScript web - docs
105- `references/posthog-js.md` - PostHog JavaScript web SDK
106- `references/node.md` - Node.js - docs
107- `references/posthog-node.md` - PostHog Node.js SDK
108- `references/django.md` - Django - docs
109- `references/flask.md` - Flask - docs
110- `references/python.md` - Python - docs
111- `references/posthog-python.md` - PostHog python SDK
112- `references/dotnet.md` - .net - docs
113- `references/elixir.md` - Elixir - docs
114- `references/go.md` - Go - docs
115- `references/laravel.md` - Laravel - docs
116- `references/php.md` - Php - docs
117- `references/ruby-on-rails.md` - Ruby on rails - docs
118- `references/ruby.md` - Ruby - docs
119- `references/android.md` - Android - docs
120- `references/ios.md` - Ios - docs
121- `references/usage.md` - Ios SDK usage - docs
122- `references/configuration.md` - Ios SDK configuration - docs
123- `references/flutter.md` - Flutter - docs
124- `references/react-native.md` - React native - docs
125- `references/identify-users.md` - Identify users - docs
126 
127Each framework reference contains SDK-specific installation, initialization, and usage patterns. Find the one matching the user's stack.
128 
129## Key principles
130 
131- **Environment variables**: Always use environment variables for PostHog keys. Never hardcode them.
132- **Minimal changes**: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
133- **Match the example**: Your implementation should follow the example project's patterns as closely as possible.
134- **Analytics contract**: Treat event names, property names, and feature flag keys as part of an analytics contract. Reuse existing names and patterns found in the project. When introducing new ones, make them clear, descriptive, and consistent with existing conventions.
135