React error tracking installation

1. Install posthog-js using your package manager:

npm install --save posthog-js

2. Add your environment variables to your .env.local file and to your hosting provider (e.g. Vercel, Netlify, AWS). You can find your project API key and host in your project settings. Including VITE_PUBLIC_ in their names ensures they are accessible in the frontend.

VITE_PUBLIC_POSTHOG_KEY=<ph_project_api_key>
VITE_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

3. Integrate PostHog at the root of your app (such as main.jsx if you are using Vite).

// src/main.jsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'
import { PostHogProvider } from 'posthog-js/react'

const options = {
api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST,
defaults: '2025-05-24',
}

createRoot(document.getElementById('root')).render(
<StrictMode>
    <PostHogProvider apiKey={import.meta.env.VITE_PUBLIC_POSTHOG_KEY} options={options}>
    <App />
    </PostHogProvider>
</StrictMode>,
)

// ... imports

export default defineConfig({
    plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],
    ssr: {
    noExternal: ['posthog-js', 'posthog-js/react']
    }
});

Before proceeding, confirm that you can capture events with PostHog using posthog.capture('test_event').

import { usePostHog } from 'posthog-js/react'
const posthog = usePostHog()
posthog?.capture('test_event')

Note: A minimum SDK version of v1.207.8 is required, but we recommend keeping up to date with the latest version to ensure you have all of error tracking's features.

You can enable exception autocapture for the JavaScript Web SDK in the Error tracking section of your project settings.

When enabled, this automatically captures $exception events when errors are thrown by wrapping the window.onerror and window.onunhandledrejection listeners.

You can use the PostHogErrorBoundary component to capture rendering errors thrown by components:

import { PostHogProvider, PostHogErrorBoundary } from 'posthog-js/react'


const Layout = () => {
  return (
    <PostHogProvider apiKey="<ph_project_api_key>">
      <PostHogErrorBoundary
        fallback={<YourFallbackComponent />} // (Optional) Add a fallback component that's shown when an error happens.
      >
        <YourApp />
      </PostHogErrorBoundary>
    </PostHogProvider>
  )
}

const YourFallbackComponent = ({ error, componentStack, exceptionEvent }) => {
  return <div>Something went wrong. Please try again later.</div>
}

It is also possible to manually capture exceptions using the captureException method:

posthog.captureException(error, additionalProperties)

Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.

Great, you're capturing exceptions! If you serve minified bundles, the next step is to upload source maps to generate accurate stack traces.

Let's continue to the next section.