# Lisa Parity Sentry Sdk Setup

> Install and configure the Sentry SDK for a project — detect the framework/runtime, add the correct @sentry/<framework> package, initialize the client, wire the DSN through env, enable error + performance monitoring, and set up source map upload for readable stack traces. One consolidated skill covering react, nextjs, node, nestjs, express, python, django, react-native, and more. Lisa-native reimplementation of Sentry's SDK-setup suite. Use when adding Sentry to a project or fixing an existing Sentry install.

- Skill: `codyswanngt/lisa-parity-sentry-sdk-setup-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add codyswanngt/lisa-parity-sentry-sdk-setup-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codyswanngt/lisa-parity-sentry-sdk-setup-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: codyswanngt (https://skillmd.com/u/codyswanngt)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/codyswanngt/lisa-parity-sentry-sdk-setup-2

---


# Sentry SDK Setup

Detect a project's framework and runtime, then install and configure the correct
Sentry SDK with sensible, production-ready defaults: client initialization, DSN
via environment variable, error capture, performance/tracing, and source map
upload so stack traces are readable.

## Consolidation note

The upstream `sentry@claude-plugins-official` plugin ships **~30 separate
per-SDK setup skills** (one per framework/runtime). This **single** Lisa-native
skill consolidates all of them: instead of one thin skill per SDK, it detects the
framework and applies the matching case below. The behavior is reimplemented from
scratch against Lisa conventions — it is **not** a translation of the upstream
skills. Pinned to `sentry@claude-plugins-official@1.0.0` via `synced-from` so the
parity drift detector tracks it as one unit.

## Step 1 — Detect framework & runtime

Inspect the project before choosing an SDK. Read `package.json`
(dependencies/scripts), config files, and lockfiles:

- `next` dependency or `next.config.*` → **Next.js**
- `@nestjs/core` → **NestJS**
- `react-native` / `expo` → **React Native / Expo**
- `react` + a bundler (vite/webpack) without Next → **React (browser)**
- `express` / `fastify` / `koa` and a Node entrypoint → **Node server**
- `vue` / `@angular/core` / `svelte` → that browser framework
- `pyproject.toml` / `requirements.txt`; `django`/`flask`/`fastapi` →
  **Python** (and which web framework)
- A plain Node library/CLI → **Node**

If the runtime is genuinely ambiguous, ask which app to instrument rather than
guessing. Respect the project's package manager (bun/npm/pnpm/yarn — match the
lockfile) and module system (ESM vs CJS).

## Step 2 — Install the package

Use the project's package manager. Examples (swap `bun add` for your manager):

| Framework | Package |
| --- | --- |
| React (browser) | `@sentry/react` |
| Next.js | `@sentry/nextjs` |
| Node / Express / Fastify | `@sentry/node` (+ `@sentry/profiling-node` for profiling) |
| NestJS | `@sentry/nestjs` (+ `@sentry/node`) |
| React Native / Expo | `@sentry/react-native` |
| Vue | `@sentry/vue` |
| Angular | `@sentry/angular` |
| Svelte / SvelteKit | `@sentry/svelte` / `@sentry/sveltekit` |
| Python (generic) | `sentry-sdk` |
| Django | `sentry-sdk[django]` |
| Flask | `sentry-sdk[flask]` |
| FastAPI | `sentry-sdk[fastapi]` |

For Next.js, prefer the official wizard when available — it scaffolds the config
files and source-map upload for you:

```bash
npx @sentry/wizard@latest -i nextjs
```

## Step 3 — Initialize the client

Initialize **as early as possible** in the app's lifecycle, before other code
runs. Always read the DSN from the environment (see Step 4) — never hard-code it.

**React (browser)** — `src/instrument.ts`, imported first in the entrypoint:

```ts
import * as Sentry from "@sentry/react";

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,
  integrations: [Sentry.browserTracingIntegration()],
  tracesSampleRate: 0.1, // tune per traffic; 1.0 in dev
});
```

**Node / Express** — `instrument.ts`, required at the very top of the entrypoint
(`import "./instrument";` must be the first import):

```ts
import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.1,
});
```

Then, after routes are defined: `Sentry.setupExpressErrorHandler(app);`

**NestJS** — import `./instrument` first in `main.ts`, then add Sentry's module:

```ts
// main.ts — FIRST line
import "./instrument";
// ...
// app.module.ts
import { SentryModule } from "@sentry/nestjs/setup";
@Module({ imports: [SentryModule.forRoot()] })
export class AppModule {}
```

**Next.js** — config lives in `sentry.client.config.ts`,
`sentry.server.config.ts`, `sentry.edge.config.ts`, and `next.config.js` is
wrapped with `withSentryConfig`. The wizard (Step 2) writes these; verify the DSN
is read from `process.env.NEXT_PUBLIC_SENTRY_DSN` / `process.env.SENTRY_DSN`.

**React Native / Expo** — wrap the root component:

```ts
import * as Sentry from "@sentry/react-native";
Sentry.init({
  dsn: process.env.EXPO_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 0.2,
});
export default Sentry.wrap(App);
```

**Python (Django/Flask/FastAPI/generic)** — initialize at startup
(`settings.py`, app factory, or main module):

```python
import os
import sentry_sdk

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    environment=os.environ.get("ENVIRONMENT", "production"),
    traces_sample_rate=0.1,
    send_default_pii=False,
)
```

Framework-specific integrations (e.g. `DjangoIntegration`, `FastApiIntegration`)
are auto-enabled by the matching extra installed in Step 2.

## Step 4 — DSN via environment

- Store the DSN in an environment variable, never in committed source.
- Add it to `.env.example` (with a placeholder) so the requirement is documented,
  but keep the real value in `.env`/secrets and confirm `.env` is gitignored.
- Use the framework's public-env convention for client-side code:
  `NEXT_PUBLIC_SENTRY_DSN` (Next.js), `VITE_SENTRY_DSN` (Vite),
  `EXPO_PUBLIC_SENTRY_DSN` (Expo). Server-only code uses `SENTRY_DSN`.
- For source-map upload (Step 6) the build also needs `SENTRY_AUTH_TOKEN`,
  `SENTRY_ORG`, and `SENTRY_PROJECT` — these are **build/CI** secrets, not
  shipped to the client.

## Step 5 — Error + performance monitoring

- **Errors**: unhandled exceptions/rejections are captured automatically once
  `init` runs; add the framework error handler where required (Express:
  `setupExpressErrorHandler`; React: an error boundary via
  `Sentry.ErrorBoundary`; NestJS: `SentryModule`). Use
  `Sentry.captureException(err)` for caught-but-notable errors.
- **Performance/tracing**: set a `tracesSampleRate` (start ~0.1 in production,
  `1.0` in dev) and enable the framework tracing integration (browser tracing,
  HTTP/DB auto-instrumentation on the server). Optionally add profiling on Node
  via `@sentry/profiling-node` and `profilesSampleRate`.
- Set `environment` and (ideally) `release` so issues are grouped per deploy.

## Step 6 — Source maps (readable stack traces)

Minified/transpiled traces are useless without source maps. Configure upload at
build time:

- **Next.js**: handled by `withSentryConfig` in `next.config.js` (the wizard sets
  it up); ensure `SENTRY_AUTH_TOKEN`/`SENTRY_ORG`/`SENTRY_PROJECT` exist in CI.
- **Vite/Webpack/Rollup/esbuild**: add the Sentry bundler plugin
  (`@sentry/vite-plugin`, `@sentry/webpack-plugin`, etc.) with `sourcemaps`
  upload enabled and the same auth env vars.
- **Node**: build with source maps emitted and upload via
  `sentry-cli sourcemaps upload` (or the bundler plugin) in the release step.
- **React Native**: source maps upload through the Sentry Metro/Gradle/Xcode
  integration added by the SDK's setup.
- Tie uploads to a **release** identifier (commit SHA or version) and inject the
  same release into `Sentry.init({ release })` so traces map to the right build.

## Step 7 — Verify

- Build/typecheck to confirm the SDK wiring compiles:
  `bun run build` / `bun run typecheck` (or the project's equivalents).
- Trigger a deliberate test error in a non-production environment and confirm it
  appears in Sentry with a **readable** (source-mapped) stack trace.
- Confirm a transaction/trace shows up to validate performance monitoring.
- Remove the test error afterward.

## Rules

- **Do not port or copy upstream plugin code** — reimplement from scratch.
- Never hard-code or commit a DSN or `SENTRY_AUTH_TOKEN`; route everything
  through env/secrets and update `.env.example`.
- Match the project's package manager and module system; do not introduce a new
  one to install Sentry.
- Initialize Sentry before any other application code runs.
- Tune sample rates for the environment — do not ship `tracesSampleRate: 1.0` to
  high-traffic production by default.
- Verify with a real captured event and a source-mapped trace before declaring
  setup complete.