Omnibus Instrument Integration

PostHogOfficialCreated by PostHog

Skill
Tool integration
Data and AI
MIT
Low risk

From the author

Add PostHog SDK integration to your application. Use when setting up PostHog for the first time or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration for any framework.

— the description by PostHog

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured, multi-step procedure for integrating the PostHog SDK into a wide variety of software projects. It guides the agent through detecting the project's framework, installing the appropriate SDK, initializing the client, and configuring environment variables. By leveraging a library of framework-specific reference files, the skill ensures that PostHog is implemented according to best practices for each supported platform, including web, mobile, and backend environments.

What it does

Detects the project's framework and package manager automatically.
Installs the correct PostHog SDK for the identified platform.
Initializes the PostHog client using framework-specific patterns.
Configures environment variables for API keys and host settings.
Implements user identification logic for login and signup events.
Verifies the integration and performs necessary cleanup.

When to use it

When setting up PostHog in a project for the first time.
When reviewing pull requests that require PostHog initialization.
When migrating or adding analytics to an existing codebase.
When you need to ensure PostHog is configured consistently across different frameworks.

Advantages

Supports a broad range of frameworks and languages.
Ensures secure configuration by enforcing the use of environment variables.
Maintains consistency with existing codebase patterns.
Reduces manual effort by automating SDK installation and boilerplate setup.

Usage examples

“Add PostHog to my new Next.js project.”: The agent will detect the Next.js framework, install the PostHog SDK, and provide the necessary initialization code in the appropriate file, such as instrumentation-client.ts.
“Help me set up PostHog in our Android app.”: The agent will identify the Android environment, guide the setup in the Application class, and configure the PostHog instance with the required API keys.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/posthog/omnibus-instrument-integration/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip omnibus-instrument-integration.zip -d .agents/skills

Documentation by PostHog

Add PostHog SDK integration

Use 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.

Supported frameworks: Next.js, React, React Router, Vue, Nuxt, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, Ruby on Rails, Android, Swift, React Native, Expo, Node.js, and vanilla JavaScript.

Instructions

Follow these steps IN ORDER:

STEP 1: Analyze the codebase and detect the platform.

Look for dependency files (package.json, requirements.txt, Gemfile, composer.json, go.mod, etc.) to determine the framework and language.
Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb) to determine the package manager.
Check for existing PostHog setup. If PostHog is already installed and initialized, do not modify its code. Inform the user and skip to verification.

STEP 2: Research integration. 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. 2.2. If no reference matches, fall back to your general knowledge and web search. Use posthog.com/docs as the primary search source.

STEP 3: Install the PostHog SDK.

Add the PostHog SDK package for the detected platform. Do not manually edit package.json — use the package manager's install command.
Always install packages as a background task. Don't await completion; proceed with other work immediately after starting the installation.

STEP 4: Initialize PostHog.

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).
Set up the PostHog provider/wrapper component if the framework requires one.

STEP 5: Identify users.

Add PostHog identify() calls on the client side during login and signup events.
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.

STEP 6: Set up environment variables.

Store the PostHog API key and host in environment variables (e.g. .env or framework-specific env files).
Reference these environment variables in code instead of hardcoding them.

STEP 7: Verify and clean up.

Check the project for errors. Look for type checking or build scripts in package.json.
Ensure any components created were actually used.
Run any linter or prettier-like scripts found in the package.json.

Reference files

references/EXAMPLE-next-app-router.md - next-app-router example project code
references/EXAMPLE-next-pages-router.md - next-pages-router example project code
references/EXAMPLE-react-react-router-6.md - react-react-router-6 example project code
references/EXAMPLE-react-react-router-7-framework.md - react-react-router-7-framework example project code
references/EXAMPLE-react-react-router-7-data.md - react-react-router-7-data example project code
references/EXAMPLE-react-react-router-7-declarative.md - react-react-router-7-declarative example project code
references/EXAMPLE-react-vite.md - react-vite example project code
references/EXAMPLE-nuxt-3.6.md - nuxt-3.6 example project code
references/EXAMPLE-nuxt-4.md - nuxt-4 example project code
references/EXAMPLE-vue-3.md - vue-3 example project code
references/EXAMPLE-react-tanstack-router-file-based.md - react-tanstack-router-file-based example project code
references/EXAMPLE-react-tanstack-router-code-based.md - react-tanstack-router-code-based example project code
references/EXAMPLE-tanstack-start.md - tanstack-start example project code
references/EXAMPLE-sveltekit.md - sveltekit example project code
references/EXAMPLE-astro-static.md - astro-static example project code
references/EXAMPLE-astro-view-transitions.md - astro-view-transitions example project code
references/EXAMPLE-astro-ssr.md - astro-ssr example project code
references/EXAMPLE-astro-hybrid.md - astro-hybrid example project code
references/EXAMPLE-angular.md - angular example project code
references/EXAMPLE-javascript-node.md - javascript-node example project code
references/EXAMPLE-javascript-web.md - javascript-web example project code
references/EXAMPLE-django.md - django example project code
references/EXAMPLE-flask.md - flask example project code
references/EXAMPLE-fastapi.md - fastapi example project code
references/EXAMPLE-python.md - python example project code
references/EXAMPLE-laravel.md - laravel example project code
references/EXAMPLE-ruby-on-rails.md - ruby-on-rails example project code
references/EXAMPLE-ruby.md - ruby example project code
references/EXAMPLE-android.md - android example project code
references/EXAMPLE-swift.md - swift example project code
references/EXAMPLE-react-native.md - react-native example project code
references/EXAMPLE-expo.md - expo example project code
references/next-js.md - Next.js - docs
references/react.md - React - docs
references/react-router-v6.md - React router v6 - docs
references/react-router-v7-framework-mode.md - React router v7 framework mode (remix v3) - docs
references/react-router-v7-data-mode.md - React router v7 data mode - docs
references/react-router-v7-declarative-mode.md - React router v7 declarative mode - docs
references/nuxt-js-3-6.md - Nuxt.js (v3.0 to v3.6) - docs
references/nuxt-js.md - Nuxt.js - docs
references/vue-js.md - Vue.js - docs
references/tanstack-start.md - Tanstack start - docs
references/svelte.md - Svelte - docs
references/astro.md - Astro - docs
references/angular.md - Angular - docs
references/js.md - JavaScript web - docs
references/posthog-js.md - PostHog JavaScript web SDK
references/node.md - Node.js - docs
references/posthog-node.md - PostHog Node.js SDK
references/django.md - Django - docs
references/flask.md - Flask - docs
references/python.md - Python - docs
references/posthog-python.md - PostHog python SDK
references/laravel.md - Laravel - docs
references/ruby-on-rails.md - Ruby on rails - docs
references/ruby.md - Ruby - docs
references/android.md - Android - docs
references/ios.md - Ios - docs
references/react-native.md - React native - docs
references/identify-users.md - Identify users - docs

Each framework reference contains SDK-specific installation, initialization, and usage patterns. Find the one matching the user's stack.

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.
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.

Files

ATTRIBUTION.mdAdded by AutoGineer998 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md7.6 KiB
references/EXAMPLE-android.md49.7 KiB
references/EXAMPLE-angular.md23.4 KiB
references/EXAMPLE-astro-hybrid.md26.8 KiB
references/EXAMPLE-astro-ssr.md26.7 KiB
references/EXAMPLE-astro-static.md19.4 KiB
references/EXAMPLE-astro-view-transitions.md23.1 KiB
references/EXAMPLE-django.md30.0 KiB
references/EXAMPLE-expo.md35.5 KiB
references/EXAMPLE-fastapi.md40.9 KiB
references/EXAMPLE-flask.md32.0 KiB
references/EXAMPLE-javascript-node.md9.0 KiB
references/EXAMPLE-javascript-web.md11.7 KiB
references/EXAMPLE-laravel.md59.5 KiB
references/EXAMPLE-next-app-router.md17.3 KiB
references/EXAMPLE-next-pages-router.md18.9 KiB
references/EXAMPLE-nuxt-3.6.md22.1 KiB
references/EXAMPLE-nuxt-4.md28.7 KiB
references/EXAMPLE-python.md11.6 KiB
references/EXAMPLE-react-native.md46.4 KiB
references/EXAMPLE-react-react-router-6.md13.5 KiB
references/EXAMPLE-react-react-router-7-data.md20.1 KiB
references/EXAMPLE-react-react-router-7-declarative.md15.0 KiB
references/EXAMPLE-react-react-router-7-framework.md32.2 KiB
references/EXAMPLE-react-tanstack-router-code-based.md19.2 KiB
references/EXAMPLE-react-tanstack-router-file-based.md18.0 KiB
references/EXAMPLE-react-vite.md12.4 KiB
references/EXAMPLE-ruby-on-rails.md37.6 KiB
references/EXAMPLE-ruby.md10.3 KiB
references/EXAMPLE-sveltekit.md18.4 KiB
references/EXAMPLE-swift.md18.6 KiB
references/EXAMPLE-tanstack-start.md28.4 KiB
references/EXAMPLE-vue-3.md17.9 KiB
references/android.md21.7 KiB
references/angular.md12.5 KiB
references/astro.md8.3 KiB
references/django.md6.7 KiB
references/flask.md2.9 KiB
references/identify-users.md8.1 KiB
references/ios.md5.4 KiB
references/js.md12.3 KiB
references/laravel.md2.1 KiB
references/next-js.md12.5 KiB
references/node.md28.8 KiB
references/nuxt-js-3-6.md6.6 KiB
references/nuxt-js.md7.2 KiB
references/posthog-js.md42.3 KiB
references/posthog-node.md23.4 KiB
references/posthog-python.md31.3 KiB
references/python.md31.1 KiB
references/react-native.md43.8 KiB
references/react-router-v6.md11.6 KiB
references/react-router-v7-data-mode.md11.4 KiB
references/react-router-v7-declarative-mode.md11.6 KiB
references/react-router-v7-framework-mode.md14.9 KiB
references/react.md18.5 KiB
references/ruby-on-rails.md10.6 KiB
references/ruby.md18.9 KiB
references/svelte.md7.2 KiB
references/tanstack-start.md5.1 KiB
references/vue-js.md9.1 KiB

references/nuxt-js.md

Nuxt.js - Docs

PostHog makes it easy to get data about usage of your Nuxt.js app. Integrating PostHog into your app enables analytics about user behavior, custom events capture, session replays, feature flags, and more.

This guide covers Nuxt v4.x and v3.7+. For these versions, we recommend using @posthog/nuxt module for client-side capture.

The @posthog/nuxt module provides:

Automatic client-side PostHog initialization
Auto-imported composables for PostHog and feature flags
Automatic exception capture for error tracking
Source map configuration and upload for error tracking

For server-side event capture beyond error tracking, use the posthog-node SDK directly.

Using an older version? See our docs for Nuxt 3.0-3.6 or Nuxt 2.x.

Installation

Install the PostHog Nuxt module using your package manager:

PostHog AI

npm

npm install @posthog/nuxt

Yarn

yarn add @posthog/nuxt

pnpm

pnpm add @posthog/nuxt

Bun

bun add @posthog/nuxt

Identifying users

Identifying users is required. Call posthog.identify('your-user-id') after login to link events to a known user. This is what connects frontend event captures, session replays, LLM traces, and error tracking to the same person — and lets backend events link back too.
See our guide on identifying users for how to set this up.

Configuration

Add the module to your nuxt.config.ts file:

nuxt.config.ts

PostHog AI

export default defineNuxtConfig({
  modules: ['@posthog/nuxt'],
  posthogConfig: {
    publicKey: '<ph_project_token>', // Find it in project settings https://app.posthog.com/settings/project
    host: 'https://us.i.posthog.com', // Optional: defaults to https://us.i.posthog.com. Use https://eu.i.posthog.com for EU region
    clientConfig: {
      // Optional: PostHog client configuration options
    },
  },
})

Usage on the client side

The module provides the usePostHog() composable which is auto-imported and available in all your Vue components:

app/pages/index.vue

PostHog AI

<script setup>
const posthog = usePostHog()
// Capture a custom event
posthog?.capture('button_clicked', { button_name: 'signup' })
</script>

Note: usePostHog() returns undefined on the server side during SSR, so use optional chaining ?. when calling methods.

Usage on the server side

The @posthog/nuxt module initializes a server-side client for error tracking only. For general event capture in Nitro routes, create your own posthog-node SDK client.

The @posthog/nuxt module makes your config available at runtimeConfig.public.posthog.

First, create a server utility to reuse the PostHog client across requests:

server/utils/posthog.ts

PostHog AI

import { PostHog } from 'posthog-node'
let client: PostHog | null = null
export function useServerPostHog(): PostHog {
  if (!client) {
    const config = useRuntimeConfig()
    client = new PostHog(config.public.posthog.publicKey, {
      host: config.public.posthog.host,
    })
  }
  return client
}

Then use it in your server routes:

server/api/example.ts

PostHog AI

export default defineEventHandler((event) => {
  const posthog = useServerPostHog()
  posthog.capture({
    distinctId: 'user_123',
    event: 'server_event',
  })
  return { success: true }
})

Set up a reverse proxy (recommended)

We recommend setting up a reverse proxy, so that events are less likely to be intercepted by tracking blockers.

We have our own managed reverse proxy service, which is free for all PostHog Cloud users, routes through our infrastructure, and makes setting up your proxy easy.

If you don't want to use our managed service then there are several other options for creating a reverse proxy, including using Cloudflare, AWS Cloudfront, and Vercel.

Grouping products in one project (recommended)

If you have multiple customer-facing products (e.g. a marketing website + mobile app + web app), it's best to install PostHog on them all and group them in one project.

This makes it possible to track users across their entire journey (e.g. from visiting your marketing website to signing up for your product), or how they use your product across multiple platforms.

Add IPs to Firewall/WAF allowlists (recommended)

For certain features like heatmaps, your Web Application Firewall (WAF) may be blocking PostHog’s requests to your site. Add these IP addresses to your WAF allowlist or rules to let PostHog access your site.

EU: 3.75.65.221, 18.197.246.42, 3.120.223.253

US: 44.205.89.55, 52.4.194.122, 44.208.188.173

These are public, stable IPs used by PostHog services (e.g., Celery tasks for snapshots).

Feature flags

The module provides auto-imported composables for feature flags. All composables return reactive refs that automatically update when flags are loaded or changed.

Vue

PostHog AI

<script setup>
const isEnabled = useFeatureFlagEnabled('new-feature')
// returns true, false, or undefined
</script>
<template>
  <div v-if="isEnabled">Feature is enabled!</div>
</template>

Vue

PostHog AI

<script setup>
const variant = useFeatureFlagVariantKey('experiment')
// returns the variant string, true/false, or undefined
</script>
<template>
  <div v-if="variant === 'control'">Control group</div>
  <div v-else-if="variant === 'test'">Test group</div>
</template>

Vue

PostHog AI

<script setup>
const payload = useFeatureFlagPayload('config-flag')
// returns any JSON value or undefined
</script>
<template>
  <div v-if="payload">Config: {{ payload.value }}</div>
</template>

Error Tracking

For a detailed error tracking installation guide, including automatic exception capture and source map configuration, see the Nuxt error tracking installation docs.

Troubleshooting

TypeScript errors in posthog config: Remove the .nuxt directory and rebuild your project to regenerate config types.

PostHog not capturing events: Ensure you're using optional chaining (posthog?.capture()) since usePostHog() returns undefined during server-side rendering.

Next steps

For any technical questions for how to integrate specific PostHog features into Nuxt (such as analytics, feature flags, A/B testing, surveys, etc.), have a look at our JavaScript Web and Node SDK docs.

Alternatively, the following tutorials can help you get started:

Community questions

Ask a question

Was this page useful?

HelpfulCould be better

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an API key, Needs Python, Needs Node.js

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

PostHog

Publisher

PostHog (Official)

Source

PostHog/skills · skills/posthog/all/skills/omnibus-instrument-integration · commit a5d30e7

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by PostHog.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download omnibus-instrument-integration.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by PostHog

Add PostHog SDK integration

Instructions

Reference files

Key principles

Files

references/nuxt-js.md

Nuxt.js - Docs

Installation

npm

Yarn

pnpm

Bun

Identifying users

Configuration

Usage on the client side

Usage on the server side

Feature flags

Error Tracking

Troubleshooting

Next steps

Community questions

Was this page useful?

Requirements and compatibility

Security

Attribution and licence

Related skills

Claude API

Transformers

Open Notebook

Vision Sft

LLM Evaluation

Lora Qlora Recipes

Download ZIP