Error Tracking Next.js

Consult the documentation for API details and framework-specific patterns.

Key principles

• Environment variables: Always use environment variables for PostHog keys and host URLs. Never hardcode them.
• Minimal changes: Add error tracking alongside existing error handling. Don’t replace or restructure existing error handling code.
• Autocapture first: Enable exception autocapture in the SDK initialization before adding manual captures.
• Source maps: Upload source maps so stack traces resolve to original source code, not minified bundles.
• Manual capture for boundaries: Use captureException() at error boundaries and catch blocks for errors that don’t propagate to the global handler.

Framework guidelines

• For Next.js 15.3+, initialize PostHog in instrumentation-client.ts for the simplest setup
• For feature flags, use useFeatureFlagEnabled() or useFeatureFlagPayload() hooks - they handle loading states and external sync automatically
• Add analytics capture in event handlers where user actions occur, NOT in useEffect reacting to state changes
• Do NOT use useEffect for data transformation - calculate derived values during render instead
• Do NOT use useEffect to respond to user events - put that logic in the event handler itself
• Do NOT use useEffect to chain state updates - calculate all related updates together in the event handler
• Do NOT use useEffect to notify parent components - call the parent callback alongside setState in the event handler
• To reset component state when a prop changes, pass the prop as the component’s key instead of using useEffect
• useEffect is ONLY for synchronizing with external systems (non-React widgets, browser APIs, network subscriptions)