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

Cette skill vous aide à ajouter PostHog analytics à vos applications React avec TanStack Router (code-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

Reference files

• references/EXAMPLE.md - React with TanStack Router (code-based) example project code
• 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 hardcodez jamais.
• Changements minimaux : Ajoutez le code PostHog à côté des intégrations existantes. Ne remplacez ni ne restructurez le code existant.
• Suivre l'exemple : Votre implémentation doit suivre les patterns du projet exemple aussi fidèlement que possible.

Directives 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'analytics dans les event handlers où les actions utilisateur se produisent, PAS dans useEffect réagissant aux changements d'état
• N'utilisez PAS useEffect pour la transformation de données - calculez les valeurs dérivées pendant le rendu plutôt que dans useEffect
• N'utilisez PAS useEffect pour réagir 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 associées ensemble dans l'event handler
• N'utilisez PAS useEffect pour notifier les composants parents - appelez le callback parent à côté de setState dans l'event handler
• Pour réinitialiser l'état du composant quand une prop change, passez la prop comme clé du composant au lieu d'utiliser useEffect
• useEffect est UNIQUEMENT pour synchroniser avec des systèmes externes (widgets non-React, APIs du navigateur, souscriptions réseau)
• Utilisez les événements de navigation intégrés de TanStack Router pour le suivi des pageviews au lieu de useEffect
• Utilisez PostHogProvider dans le composant racine défini selon la convention file-based (__root.tsx) ou code-based (là où createRootRoute() est appelé) pour que toutes les routes enfants aient accès au client PostHog

Identifier les utilisateurs

Identifiez les utilisateurs lors des événements de connexion et inscription. Reportez-vous au code exemple et à la documentation pour le pattern d'identification correct pour ce framework. Si du code frontend et backend coexiste, 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.