DSN & SDK Setup
Installing the Sentry SDK, initialising it correctly, and verifying errors are being captured in production.
This page connects your React app to Sentry. After completing these steps, every unhandled error in your production app will automatically appear in your Sentry Issues list — no extra code required in your components.
The setup is a one-time task per project. Once it's in place, it runs silently in the background forever.
Install and Configure the SDK
Install the Sentry SDK
Open your project in VS Code, open the terminal, and run the install command for @sentry/react.
This installs the Sentry SDK for React. It adds one package to your package.json and roughly 50KB to your production bundle (minified and compressed — users won't notice).
Create src/lib/instrument.ts
This is the initialisation file. It must be imported before anything else in your app — before React, before your components, before your router. This is intentional: Sentry needs to be active from the very first line of code your app executes, so it can catch errors that happen during initialisation, not just after the app is running.
Create the file at src/lib/instrument.ts. It imports the Sentry SDK, reads your VITE_SENTRY_DSN environment variable, and calls Sentry.init() with basic settings including tracesSampleRate and replaysSessionSampleRate.
Import it first in main.tsx
Open src/main.tsx. The first import in this file must be instrument.ts. Not second. Not third. First.
Why first? If Sentry initialises after your router or components, errors that happen during route setup or the first render won't be captured. By putting it first, Sentry is active before any other code runs. This is a one-line change that can make a significant difference in what you catch — especially during early deploys when everything is new and subtle bugs are common.
src/lib/instrument.ts file exists, main.tsx imports it as the very first line, and VITE_SENTRY_DSN is in your .env file. Confirm all three before deploying.Set User Context After Login
By default, Sentry captures errors but doesn't know who triggered them. To know which user hit a bug, you tell Sentry the user's identity after they log in.
In the component or hook where you handle the Supabase auth state change (typically your AuthContext or AuthProvider), add:
Once this is in place, every error in Sentry's Issues list will show you which user triggered it. When a bug is user-specific — it only happens for one person — you can filter to their errors and see exactly what they did.
The CA analogy: it's like logging the client's name on every entry in your audit trail. Without it, you know something went wrong but not for whom.
Test That It's Working
Before you deploy, confirm Sentry is capturing errors. The safest way is to throw a test error intentionally.
Add this temporarily to any component that loads on page open — for example, the bottom of App.tsx:
Now build and deploy your app (or test on a production-like build with npm run build && npm run preview).
Wait 30–60 seconds. Open your Sentry Dashboard → Issues. You should see a new issue titled something like "This is your first Sentry error!" with your file name in the stack trace.
If it appears: Sentry is working. Delete the test error, redeploy, and move on.
If it doesn't appear after 2 minutes, check the troubleshooting section below.
Why not test in development? The enabled: import.meta.env.PROD line in instrument.ts deliberately disables Sentry in development — errors in dev should appear in the browser console where you can see them in real time. Testing Sentry requires a production build. Use npm run build && npm run preview to run a local production build, or deploy to Vercel's preview URL.
What Happens Automatically
Once the SDK is initialised, you don't need to add error catching to your components. Sentry attaches to the JavaScript runtime and catches:
- Any
throwstatement that isn't caught by atry/catch - Any Promise rejection that isn't handled with
.catch()ortry/catchin anasyncfunction - Any error that reaches the browser's
window.onerrorhandler
The only errors Sentry won't catch automatically are ones you deliberately catch and swallow:
The last pattern — catch, send to Sentry, show a user-friendly message — is the right approach for expected failures like network timeouts. You handle the user experience gracefully while still logging the technical detail for yourself.
Troubleshooting
Error doesn't appear in Sentry after 2 minutes
-
Check
enabled— is the app running in production mode?import.meta.env.PRODis onlytruein production builds. Runnpm run build && npm run previewto test locally with production mode enabled. -
Check the DSN — open the browser DevTools Network tab. After the error occurs, look for a request to
sentry.iooringest.sentry.io. If there's no request, the DSN is missing or invalid. -
Check
instrument.tsis imported first — openmain.tsxand confirm the import order. If anything else is imported before./lib/instrument, move the instrument import to line 1. -
Check the DSN in
.env— open.envand confirmVITE_SENTRY_DSNis set and matches what's in your Sentry project settings. The DSN must start withhttps://.
Errors appear in Sentry but without readable code (minified names)
This means source maps haven't been set up yet. The error shows n.t is not a function at main.abc123.js:1:4892 instead of your actual function and file names. This is normal at this stage — source maps are configured in the Auth Tokens section. Complete that setup, and future errors will show readable code.