Intégration PostHog pour React avec TanStack Router (file-based)

Cette skill vous aide à ajouter l'analytique PostHog à vos applications React avec TanStack Router (file-based).

Workflow

Suivez ces étapes dans l'ordre pour compléter l'intégration :

1. basic-integration-1.0-begin.md - PostHog Setup - Begin ← Commencez ici
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

Fichiers de référence

• references/EXAMPLE.md - React avec TanStack Router (file-based) code du projet exemple
• references/tanstack-start.md - Tanstack start - 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

Le projet exemple montre le pattern d'implémentation cible. Consultez la documentation pour les détails de l'API.

Principes clés

• Variables d'environnement : Utilisez toujours des variables d'environnement pour les clés PostHog. Ne les codez jamais en dur.
• Changements minimaux : Ajoutez le code PostHog aux côtés des intégrations existantes. Ne remplacez ni ne restructurez le code existant.
• Suivez l'exemple : Votre implémentation doit respecter les patterns du projet exemple aussi fidèlement que possible.

Recommandations du framework

• Pour les feature flags, utilisez les hooks useFeatureFlagEnabled() ou useFeatureFlagPayload() - ils gèrent automatiquement les états de chargement et la synchronisation externe
• Ajoutez la capture d'analytique dans les event handlers où les actions utilisateur se produisent, NON dans un useEffect réagissant aux changements d'état
• N'utilisez PAS useEffect pour la transformation de données - calculez les valeurs dérivées lors du rendu
• N'utilisez PAS useEffect pour répondre aux événements utilisateur - mettez cette logique directement dans l'event handler
• N'utilisez PAS useEffect pour chaîner les mises à jour d'état - calculez toutes les mises à jour liées ensemble dans l'event handler
• N'utilisez PAS useEffect pour notifier les composants parents - appelez le callback parent aux côtés de setState dans l'event handler
• Pour réinitialiser l'état du composant quand une prop change, passez la prop comme key du composant au lieu d'utiliser useEffect
• useEffect est UNIQUEMENT pour synchroniser avec les systèmes externes (widgets non-React, APIs du navigateur, subscriptions réseau)
• Utilisez les événements de navigation natifs de TanStack Router pour le pageview tracking au lieu de useEffect
• Utilisez PostHogProvider dans le composant racine défini soit par la convention file-based (__root.tsx) soit par la convention code-based (où createRootRoute() est appelé) afin que toutes les routes enfants aient accès au client PostHog

Identifier les utilisateurs

Identifiez les utilisateurs lors des événements de connexion et d'inscription. Reportez-vous au code exemple et à la documentation pour le bon pattern d'identification pour ce framework. Si du code frontend et backend existe, passez la session côté client et l'ID distinct en utilisant les headers X-POSTHOG-DISTINCT-ID et X-POSTHOG-SESSION-ID pour maintenir la corrélation.

Suivi des erreurs

Ajoutez le suivi des erreurs PostHog aux fichiers pertinents, particulièrement autour des flux utilisateur critiques et des limites d'API.