Intégration PostHog pour TanStack Start

Cette skill vous aide à ajouter PostHog analytics à vos applications TanStack Start.

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 - Code de projet exemple TanStack Start
• 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 du code PostHog aux côtés 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 étroitement que possible.

Recommandations du framework

• Pour les feature flags, utilisez les hooks useFeatureFlagEnabled() ou useFeatureFlagPayload() - ils gèrent les états de chargement et la synchronisation externe automatiquement
• 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 au render à la place
• N'utilisez PAS useEffect pour réagir aux événements utilisateur - mettez cette logique directement dans l'event handler
• N'utilisez PAS useEffect pour enchaî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 du 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 la synchronisation avec des systèmes externes (widgets non-React, APIs du navigateur, souscriptions réseau)
• Utilisez PostHogProvider dans la route racine (__root.tsx) pour le tracking côté client
• Utilisez posthog-node pour la capture d'événements côté serveur dans les API routes (src/routes/api/) - n'utilisez PAS posthog-js sur le serveur
• Créez un client PostHog serveur singleton pour éviter la réinitialisation à chaque requête
• Utilisez les événements de navigation intégrés du TanStack Router pour le pageview tracking au lieu de useEffect
• Utilisez PostHogProvider dans le composant racine défini soit par la convention basée sur fichiers (__root.tsx) soit par la convention basée sur le code (où createRootRoute() est appelé) pour que toutes les routes enfants aient accès au client PostHog

Identification des utilisateurs

Identifiez les utilisateurs lors des événements de connexion et d'inscription. Consultez le code d'exemple et la documentation pour le pattern d'identification correct pour ce framework. Si du code frontend et backend existe, passez la session côté client et le distinct ID 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.