Ajouter l'intégration du SDK PostHog

Utilise cette skill pour ajouter le SDK PostHog à une application. Utilise-la lors de la première configuration de PostHog ou lors de la révision de PRs qui nécessitent l'initialisation de PostHog. Couvre l'installation du SDK, la configuration du provider et la configuration de base. Supporte n'importe quel framework ou langage.

Frameworks supportés : 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 et JavaScript vanilla.

Instructions

Suis ces étapes DANS L'ORDRE :

ÉTAPE 1 : Analyse la base de code et détecte la plateforme.

• Cherche les fichiers de dépendances (package.json, requirements.txt, Gemfile, composer.json, go.mod, etc.) pour déterminer le framework et le langage.
• Cherche les fichiers de verrouillage (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb) pour déterminer le gestionnaire de paquets.
• Vérifie s'il existe une configuration PostHog existante. Si PostHog est déjà installé et initialisé, ne modifie pas son code. Informe l'utilisateur et passe à la vérification.

ÉTAPE 2 : Recherche l'intégration. 2.1. Trouve le fichier de référence ci-dessous qui correspond au framework détecté — c'est la source de vérité pour l'initialisation du SDK, la configuration du provider et les motifs de configuration. Lis-le maintenant. 2.2. S'il n'existe pas de référence correspondante, appuie-toi sur tes connaissances générales et une recherche web. Utilise posthog.com/docs comme source de recherche principale.

ÉTAPE 3 : Installe le SDK PostHog.

• Ajoute le paquet SDK PostHog pour la plateforme détectée. Ne modifie pas manuellement package.json — utilise la commande d'installation du gestionnaire de paquets.
• Installe toujours les paquets comme une tâche de fond. Ne pas attendre la fin de l'installation ; procède avec d'autres travaux immédiatement après son démarrage.

ÉTAPE 4 : Initialise PostHog.

• Suis la référence du framework pour savoir où et comment initialiser. Cela varie considérablement selon le framework (par ex., instrumentation-client.ts pour Next.js 15.3+, AppConfig.ready() pour Django, create_app() pour Flask).
• Configure le composant provider/wrapper PostHog si le framework l'exige.

ÉTAPE 5 : Identifie les utilisateurs.

• Ajoute des appels PostHog identify() côté client lors des événements de connexion et d'inscription.
• Si à la fois le frontend et le backend existent, passe la session côté client et l'ID distinct en utilisant les headers X-POSTHOG-DISTINCT-ID et X-POSTHOG-SESSION-ID au code côté serveur.

ÉTAPE 6 : Configure les variables d'environnement.

• Stocke la clé API PostHog et l'hôte dans les variables d'environnement (par ex. .env ou fichiers env spécifiques au framework).
• Référence ces variables d'environnement dans le code au lieu de les coder en dur.

ÉTAPE 7 : Vérifie et nettoie.

• Vérifie les erreurs du projet. Cherche les scripts de vérification de type ou de compilation dans package.json.
• Assure-toi que tous les composants créés ont été réellement utilisés.
• Exécute tout script de linter ou de type prettier trouvé dans package.json.

Fichiers de référence

• references/EXAMPLE-next-app-router.md - code du projet exemple next-app-router
• references/EXAMPLE-next-pages-router.md - code du projet exemple next-pages-router
• references/EXAMPLE-react-react-router-6.md - code du projet exemple react-react-router-6
• references/EXAMPLE-react-react-router-7-framework.md - code du projet exemple react-react-router-7-framework
• references/EXAMPLE-react-react-router-7-data.md - code du projet exemple react-react-router-7-data
• references/EXAMPLE-react-react-router-7-declarative.md - code du projet exemple react-react-router-7-declarative
• references/EXAMPLE-react-vite.md - code du projet exemple react-vite
• references/EXAMPLE-nuxt-3.6.md - code du projet exemple nuxt-3.6
• references/EXAMPLE-nuxt-4.md - code du projet exemple nuxt-4
• references/EXAMPLE-vue-3.md - code du projet exemple vue-3
• references/EXAMPLE-react-tanstack-router-file-based.md - code du projet exemple react-tanstack-router-file-based
• references/EXAMPLE-react-tanstack-router-code-based.md - code du projet exemple react-tanstack-router-code-based
• references/EXAMPLE-tanstack-start.md - code du projet exemple tanstack-start
• references/EXAMPLE-sveltekit.md - code du projet exemple sveltekit
• references/EXAMPLE-astro-static.md - code du projet exemple astro-static
• references/EXAMPLE-astro-view-transitions.md - code du projet exemple astro-view-transitions
• references/EXAMPLE-astro-ssr.md - code du projet exemple astro-ssr
• references/EXAMPLE-astro-hybrid.md - code du projet exemple astro-hybrid
• references/EXAMPLE-angular.md - code du projet exemple angular
• references/EXAMPLE-javascript-node.md - code du projet exemple javascript-node
• references/EXAMPLE-javascript-web.md - code du projet exemple javascript-web
• references/EXAMPLE-django.md - code du projet exemple django
• references/EXAMPLE-flask.md - code du projet exemple flask
• references/EXAMPLE-fastapi.md - code du projet exemple fastapi
• references/EXAMPLE-python.md - code du projet exemple python
• references/EXAMPLE-laravel.md - code du projet exemple laravel
• references/EXAMPLE-ruby-on-rails.md - code du projet exemple ruby-on-rails
• references/EXAMPLE-ruby.md - code du projet exemple ruby
• references/EXAMPLE-android.md - code du projet exemple android
• references/EXAMPLE-swift.md - code du projet exemple swift
• references/EXAMPLE-react-native.md - code du projet exemple react-native
• references/EXAMPLE-expo.md - code du projet exemple expo
• 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

Chaque référence de framework contient les motifs d'installation, d'initialisation et d'utilisation spécifiques au SDK. Trouve celle qui correspond à la stack de l'utilisateur.

Principes clés

• Variables d'environnement : Utilise toujours les variables d'environnement pour les clés PostHog. Ne les code jamais en dur.
• Changements minimes : Ajoute le code PostHog aux intégrations existantes. Ne remplace ni ne restructure le code existant.
• Respecte l'exemple : Ton implémentation doit suivre les motifs du projet exemple aussi étroitement que possible.
• Contrat analytique : Traite les noms d'événements, les noms de propriétés et les clés de feature flag comme faisant partie d'un contrat analytique. Réutilise les noms et motifs existants trouvés dans le projet. Quand tu en introduces de nouveaux, rends-les clairs, descriptifs et cohérents avec les conventions existantes.