references/web.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Web Error Tracking installation
Canonical URL: https://posthog.com/docs/error-tracking/installation/web
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Choose an installation method
- Send events
- Set up exception autocapture
- Manually capture exceptions
- Verify error tracking
- Upload source maps
-
1
Choose an installation method
Required
You can either add the JavaScript snippet directly to your HTML or install the JavaScript SDK via your package manager.
HTML snippet
Add this snippet to your website within the
<head>tag. This can also be used in services like Google Tag Manager:HTML
<script> !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],Object.defineProperty(u,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e}}),Object.defineProperty(u.people,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(){return u.toString(1)+".people (stub)"}}),o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagResult isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]); posthog.init('<ph_project_token>', { api_host: 'https://us.i.posthog.com', defaults: '2026-08-30', }) </script>JavaScript SDK
Install the PostHog JavaScript library using your package manager. Then, import and initialize the PostHog library with your project token and host:
npm
npm install posthog-jsyarn
yarn add posthog-jspnpm
pnpm add posthog-jsbun
bun add posthog-jsJavaScript
import posthog from 'posthog-js' posthog.init('<ph_project_token>', { api_host: 'https://us.i.posthog.com', defaults: '2026-08-30' }) -
2
Send events
Recommended
Once installed, PostHog will automatically start capturing events. You can also manually send events to test your integration:
Click around and view a couple pages to generate some events. PostHog automatically captures pageviews, clicks, and other interactions for you.
If you'd like, you can also manually capture custom events:
JavaScript
posthog.capture('my_custom_event', { property: 'value' }) -
3
Set up exception autocapture
Recommended
You can enable exception autocapture for the JavaScript Web SDK in the Error tracking section of your project settings.
When enabled, this automatically captures
$exceptionevents when errors are thrown by wrapping thewindow.onerrorandwindow.onunhandledrejectionlisteners. -
4
Manually capture exceptions
Optional
It is also possible to manually capture exceptions using the
captureExceptionmethod:JavaScript
posthog.captureException(error, additionalProperties)This is helpful if you've built your own error handling logic or want to capture exceptions that are handled by your application code.
-
Verify error tracking
Recommended
Confirm events are being sent to PostHog
Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.
Activity feed with events
-
5
Upload source maps
Required
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.