PostHog feature flags pour Next.js

Cette skill vous aide à ajouter des feature flags PostHog à vos applications Next.js.

Fichiers de référence

• references/react.md - Installation des feature flags React - docs
• references/next-js.md - Next.js - docs
• references/adding-feature-flag-code.md - Ajouter du code de feature flag - docs
• references/best-practices.md - Bonnes pratiques des feature flags - docs

Consultez la documentation pour les détails de l'API et les motifs spécifiques au framework.

Principes clés

• Variables d'environnement : Toujours utiliser des variables d'environnement pour les clés PostHog. Ne jamais les hardcoder.
• Changements minimaux : Ajouter le code des feature flags aux côtés de la logique existante. Ne pas remplacer ni restructurer le code existant.
• Boolean flags en priorité : Utiliser par défaut les vérifications de flags booléens sauf si l'utilisateur demande spécifiquement des flags multivariés.
• Server-side quand possible : Préférer l'évaluation des flags côté serveur pour éviter le scintillement de l'UI.

PostHog MCP tools

Vérifier qu'un serveur PostHog MCP est connecté. Si disponible, chercher les tools liés à la gestion des feature flags (créer, lister, mettre à jour, supprimer des flags). Utiliser ces tools pour gérer les flags directement dans PostHog plutôt que de demander à l'utilisateur de le faire manuellement dans le dashboard.

Directives du framework

• Pour Next.js 15.3+, initialiser PostHog dans instrumentation-client.ts pour la configuration la plus simple
• Les React hooks PostHog (useFeatureFlagEnabled, useFeatureFlagPayload) fonctionnent SANS PostHogProvider si posthog-js est déjà initialisé (par exemple via instrumentation-client.ts)
• Dans les client components, importer et utiliser les hooks directement - le contexte React utilise par défaut le singleton posthog-js
• Ne PAS envelopper les composants dans PostHogProvider juste pour les feature flags - c'est inutile si posthog-js est initialisé globalement
• Les Server Components et Route Handlers ne peuvent pas utiliser les React hooks - utiliser le SDK posthog-node à la place
• Créer un client PostHog côté serveur avec posthog-node, appeler getAllFlags() ou getFeatureFlag(), puis await posthog.shutdown()
• Passer les valeurs des flags du serveur aux client components sous forme de props pour éviter les décalages d'hydratation
• Pour les flags qui affectent le rendu initial, évaluer côté serveur et passer sous forme de props pour éviter le scintillement de l'UI
• Les hooks côté client peuvent retourner undefined initialement pendant le chargement des flags - gérer cet état de chargement
• Pour les feature flags, utiliser les hooks useFeatureFlagEnabled() ou useFeatureFlagPayload() - ils gèrent automatiquement les états de chargement et la synchronisation externe
• Ajouter la capture d'analytics dans les event handlers où les actions utilisateur se produisent, PAS dans useEffect réagissant aux changements d'état
• Ne PAS utiliser useEffect pour la transformation de données - calculer les valeurs dérivées lors du rendu à la place
• Ne PAS utiliser useEffect pour réagir aux événements utilisateur - mettre cette logique directement dans l'event handler
• Ne PAS utiliser useEffect pour chaîner les mises à jour d'état - calculer toutes les mises à jour liées ensemble dans l'event handler
• Ne PAS utiliser useEffect pour notifier les composants parents - appeler le callback parent aux côtés de setState dans l'event handler
• Pour réinitialiser l'état du composant quand une prop change, passer la prop en tant que key du composant plutôt que d'utiliser useEffect
• useEffect est UNIQUEMENT pour la synchronisation avec des systèmes externes (widgets non-React, APIs du navigateur, abonnements réseau)