mirror of
https://github.com/BillyOutlast/posthog.com.git
synced 2026-02-06 12:21:21 +01:00
139 lines
4.2 KiB
Plaintext
139 lines
4.2 KiB
Plaintext
---
|
|
title: React error tracking installation
|
|
showStepsToc: true
|
|
---
|
|
|
|
import InstallReactPackageManagers from "../../integrate/_snippets/install-react-package-managers.mdx"
|
|
import StepVerifyErrorTracking from "./_snippets/step-verify-error-tracking.mdx"
|
|
import StepUploadSourceMaps from "./_snippets/step-upload-source-maps.tsx"
|
|
|
|
> For Next.js, we recommend following the [Next.js integration guide](/docs/integrate/next-js) instead.
|
|
|
|
<Steps>
|
|
<Step title="Install PostHog web SDK" badge="required">
|
|
|
|
|
|
1. Install [`posthog-js`](https://github.com/posthog/posthog-js) and `@posthog/react` using your package manager:
|
|
|
|
<InstallReactPackageManagers />
|
|
|
|
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](https://app.posthog.com/settings/project). Including `VITE_PUBLIC_` in their names ensures they are accessible in the frontend.
|
|
|
|
```shell file=.env.local
|
|
VITE_PUBLIC_POSTHOG_KEY=<ph_project_api_key>
|
|
VITE_PUBLIC_POSTHOG_HOST=<ph_client_api_host>
|
|
```
|
|
|
|
3. Integrate PostHog at the root of your app (such as `main.jsx` if you are using Vite).
|
|
|
|
```react
|
|
// 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/react'
|
|
|
|
const options = {
|
|
api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST,
|
|
defaults: '<ph_posthog_js_defaults>',
|
|
}
|
|
|
|
createRoot(document.getElementById('root')).render(
|
|
<StrictMode>
|
|
<PostHogProvider apiKey={import.meta.env.VITE_PUBLIC_POSTHOG_KEY} options={options}>
|
|
<App />
|
|
</PostHogProvider>
|
|
</StrictMode>,
|
|
)
|
|
```
|
|
|
|
<details>
|
|
<summary>Using React Router v7?</summary>
|
|
|
|
You need to set `posthog-js` and `@posthog/react` as external packages in your `vite.config.ts` file to avoid SSR errors.
|
|
|
|
```ts file=vite.config.ts
|
|
// ... imports
|
|
|
|
export default defineConfig({
|
|
plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],
|
|
ssr: {
|
|
noExternal: ['posthog-js', '@posthog/react']
|
|
}
|
|
});
|
|
```
|
|
|
|
See our [Remix docs](/docs/libraries/remix) for more details.
|
|
</details>
|
|
|
|
</Step>
|
|
|
|
<Step checkpoint title="Verify PostHog is initialized" subtitle="Confirm you can capture events with PostHog">
|
|
|
|
Before proceeding, confirm that you can capture events with PostHog using `posthog.capture('test_event')`.
|
|
|
|
```tsx
|
|
import { usePostHog } from '@posthog/react'
|
|
const posthog = usePostHog()
|
|
posthog?.capture('test_event')
|
|
```
|
|
|
|
</Step>
|
|
|
|
<Step title="Set up exception autocapture" badge="recommended">
|
|
|
|
> **Note:** A minimum SDK version of v1.207.8 is required, but we recommend [keeping up to date with the latest version](/docs/sdk-doctor) 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](https://app.posthog.com/settings/project-error-tracking#exception-autocapture).
|
|
|
|
When enabled, this automatically captures `$exception` events when errors are thrown by wrapping the `window.onerror` and `window.onunhandledrejection` listeners.
|
|
|
|
</Step>
|
|
|
|
<Step title="Set up error boundaries" badge="optional">
|
|
|
|
You can use the `PostHogErrorBoundary` component to capture rendering errors thrown by components:
|
|
|
|
```javascript
|
|
import { PostHogProvider, PostHogErrorBoundary } from '@posthog/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>
|
|
}
|
|
```
|
|
|
|
</Step>
|
|
|
|
<Step title="Manually capture exceptions" badge="optional">
|
|
|
|
It is also possible to manually capture exceptions using the `captureException` method:
|
|
|
|
```js
|
|
posthog.captureException(error, additionalProperties)
|
|
```
|
|
|
|
</Step>
|
|
|
|
<StepVerifyErrorTracking />
|
|
|
|
<Step title="Upload source maps" badge="required">
|
|
|
|
<StepUploadSourceMaps urlPath="react" framework="React" />
|
|
|
|
</Step>
|
|
|
|
</Steps> |