> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Track dashboard errors

> Send admin dashboard and seller panel errors to Sentry with the official plugin, or to another service with your own.

## Sentry

`@spree/dashboard-sentry` reports errors from the admin dashboard and the seller panel. Install it in each app you deploy:

```bash theme={"theme":"night-owl"}
pnpm add @spree/dashboard-sentry
```

Then start it from the app's entry module, `src/main.tsx`, before the app renders:

```tsx theme={"theme":"night-owl"}
import { initDashboardSentry } from '@spree/dashboard-sentry'

initDashboardSentry({ dsn: import.meta.env.VITE_SENTRY_DSN })
```

Use the DSN of a browser (React) Sentry project. It is public by design, and with no DSN the call does nothing, so the same build runs with Sentry on or off. `initDashboardSentry` takes any [Sentry browser option](https://docs.sentry.io/platforms/javascript/guides/react/configuration/options/), plus:

| Option | Default | Purpose |
| - | - | - |
| `environment` | The Vite mode, such as `production` | Environment name on each event |
| `enableInDevelopment` | `false` | Report from the dev server too. Development builds stay quiet otherwise |

`VITE_` values are compiled into the browser bundle, so set them when you build, not only when you run the server. Call it the same way in the seller panel's `src/main.tsx`.

What gets reported:

* Uncaught errors and unhandled promise rejections.
* Errors a page throws while rendering or loading data, including the ones the panel's error screen catches and shows.
* The signed-in user's ID and email, cleared on sign-out.
* A `panel` tag, `admin` or `seller`, so both apps can share one Sentry project. Events raised while the app starts are tagged too.

Not-found pages and redirects are not errors and are skipped. Single-use tokens in password reset, email confirmation and invitation links are replaced with `redacted` in error events and breadcrumbs before they leave the browser, after your own `beforeSend` and `beforeBreadcrumb` run.

The plugin turns on error reporting only. Tracing, Session Replay and other Sentry features stay off unless you pass their options. Token redaction does not cover them: replays and trace spans can record the page URL, including a reset or invitation token.

### Readable stack traces

A production build is minified, so its stack traces are unreadable until Sentry has the build's source maps. Upload them at build time with Sentry's Vite plugin:

```bash theme={"theme":"night-owl"}
pnpm add -D @sentry/vite-plugin
```

```ts theme={"theme":"night-owl"}
// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin'

export default defineConfig({
  build: { sourcemap: 'hidden' },
  plugins: [
    spreeDashboardPlugin(),
    react(),
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
      sourcemaps: { filesToDeleteAfterUpload: ['./dist/**/*.map'] },
    }),
  ],
})
```

* `SENTRY_AUTH_TOKEN` is read only while building, in Node, so it never reaches the browser bundle. Keep it out of `VITE_` variables, which are.
* `sourcemap: 'hidden'` writes the maps without linking them from the bundle, and `filesToDeleteAfterUpload` removes them once uploaded, so they are not deployed with the app.
* The plugin also sets the release on each event, so `initDashboardSentry` needs no `release` option.
* Without `SENTRY_AUTH_TOKEN` the plugin skips the upload, so local builds work without it.

Use the seller panel's `spreeSellerDashboardPlugin()` in its own `vite.config.ts` the same way.

## Another service

An error-tracking plugin needs two things from the dashboard:

* `errorReporters` in `defineDashboardPlugin`, keyed by a unique id. Each one is called with every error the panel's error screens catch. These errors never reach `window.onerror`, where most error trackers listen.
* The [`app.root` slot](https://spreecommerce.org/docs/developer/dashboard/slots-catalog#app-root), rendered once inside the signed-in session, to attach the user to reports.

```tsx theme={"theme":"night-owl"}
import { APP_ROOT_SLOT, type AppRootSlotContext, defineDashboardPlugin, useAuth } from '@spree/dashboard-core'
import { useEffect } from 'react'
import { tracker } from './tracker'

function TrackerUser({ panel }: AppRootSlotContext) {
  const { user, isInitializing } = useAuth()
  useEffect(() => {
    if (isInitializing) return
    tracker.setUser(user ? { id: user.id, panel } : null)
  }, [user, panel, isInitializing])
  return null
}

defineDashboardPlugin({
  errorReporters: { tracker: (error) => tracker.capture(error) },
  slots: { [APP_ROOT_SLOT]: [{ id: 'tracker-user', component: TrackerUser as never }] },
})
```

An error boundary of your own reports the same way: pass `reportCaughtError` from `@spree/dashboard-core` as the `onCatch` of `RouteErrorBoundary` or TanStack Router's `CatchBoundary`.

Call `defineDashboardPlugin` from a function the host calls in its entry module, as `initDashboardSentry` does, or mark the package as a dashboard plugin so both panels load it on install — see [Distributing plugins](https://spreecommerce.org/docs/developer/dashboard/plugins/distributing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.