sentry-svelte-sdk
Original:🇺🇸 English
Not Translated
Full Sentry SDK setup for Svelte and SvelteKit. Use when asked to "add Sentry to Svelte", "add Sentry to SvelteKit", "install @sentry/sveltekit", or configure error monitoring, tracing, session replay, or logging for Svelte or SvelteKit applications.
1installs
Sourcegetsentry/agent-skills
Added on
NPX Install
npx skill4agent add getsentry/agent-skills sentry-svelte-sdkSKILL.md Content
Sentry Svelte SDK
Opinionated wizard that scans your project and guides you through complete Sentry setup for Svelte and SvelteKit.
Invoke This Skill When
- User asks to "add Sentry to Svelte" or "set up Sentry" in a Svelte/SvelteKit app
- User wants error monitoring, tracing, session replay, or logging in Svelte or SvelteKit
- User mentions ,
@sentry/svelte, or Sentry SDK for Svelte@sentry/sveltekit
Note: SDK versions and APIs below reflect current Sentry docs at time of writing (≥10.8.0, SvelteKit ≥2.31.0). Always verify against docs.sentry.io/platforms/javascript/guides/sveltekit/ before implementing.@sentry/sveltekit
Phase 1: Detect
Run these commands to understand the project before making any recommendations:
bash
# Detect framework type
cat package.json | grep -E '"svelte"|"@sveltejs/kit"|"@sentry/svelte"|"@sentry/sveltekit"'
# Check for SvelteKit indicators
ls svelte.config.js svelte.config.ts vite.config.ts vite.config.js 2>/dev/null
# Check SvelteKit version (determines which setup pattern to use)
cat package.json | grep '"@sveltejs/kit"'
# Check if Sentry is already installed
cat package.json | grep '"@sentry/'
# Check existing hook files
ls src/hooks.client.ts src/hooks.client.js src/hooks.server.ts src/hooks.server.js \
src/instrumentation.server.ts 2>/dev/null
# Detect logging libraries (Node side)
cat package.json | grep -E '"pino"|"winston"|"consola"'
# Detect if there's a backend (Go, Python, Ruby, etc.) in adjacent directories
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile 2>/dev/null | head -3What to determine:
| Question | Impact |
|---|---|
| SvelteKit path vs. plain Svelte path |
| SvelteKit ≥2.31.0? | Modern ( |
| Skip install, go straight to feature config |
| Source map upload via Vite plugin available |
| Backend directory found? | Trigger Phase 4 cross-link suggestion |
Phase 2: Recommend
Present a concrete recommendation based on what you found. Don't ask open-ended questions — lead with a proposal:
Recommended (core coverage):
- ✅ Error Monitoring — always; auto-captures unhandled errors on client and server
- ✅ Tracing — SvelteKit has both client-side navigation spans and server-side request spans; always recommend
- ✅ Session Replay — recommended for user-facing SvelteKit apps (client-side only)
Optional (enhanced observability):
- ⚡ Logging — structured logs via ; recommend when app uses server-side logging or needs log-to-trace correlation
Sentry.logger.*
Recommendation logic:
| Feature | Recommend when... |
|---|---|
| Error Monitoring | Always — non-negotiable baseline |
| Tracing | Always for SvelteKit (client + server); for plain Svelte when calling APIs |
| Session Replay | User-facing app, login flows, or checkout pages present |
| Logging | App already uses server-side logging, or structured log search is needed |
Propose: "I recommend setting up Error Monitoring + Tracing + Session Replay. Want me to also add structured Logging?"
Phase 3: Guide
Determine Setup Path
| Your project | Package | Setup complexity |
|---|---|---|
| SvelteKit (≥2.31.0) | | 5 files to create/modify |
| SvelteKit (<2.31.0) | | 3 files (init in hooks.server.ts) |
Plain Svelte (no | | Single entry point |
Path A: SvelteKit (Recommended — Modern, ≥2.31.0)
Option 1: Wizard (Easiest)
bash
npx @sentry/wizard@latest -i sveltekitThe wizard creates all necessary files automatically, uploads source maps, and adds a for verification. Skip to Verification after running it.
/sentry-example-pageOption 2: Manual Setup
Step 1 — Install
bash
npm install @sentry/sveltekit --saveStep 2 — — Enable instrumentation
svelte.config.jsjavascript
import adapter from "@sveltejs/adapter-auto";
const config = {
kit: {
adapter: adapter(),
experimental: {
instrumentation: { server: true },
tracing: { server: true },
},
},
};
export default config;Step 3 — — Server-side init (runs once at startup)
src/instrumentation.server.tstypescript
import * as Sentry from "@sentry/sveltekit";
Sentry.init({
dsn: process.env.SENTRY_DSN,
environment: process.env.SENTRY_ENVIRONMENT,
release: process.env.SENTRY_RELEASE,
sendDefaultPii: true,
tracesSampleRate: 1.0, // lower to 0.1–0.2 in production
enableLogs: true,
});Step 4 — — Client-side init
src/hooks.client.tstypescript
import * as Sentry from "@sentry/sveltekit";
Sentry.init({
dsn: import.meta.env.PUBLIC_SENTRY_DSN ?? import.meta.env.VITE_SENTRY_DSN,
environment: import.meta.env.MODE,
sendDefaultPii: true,
tracesSampleRate: 1.0,
integrations: [
Sentry.replayIntegration({
maskAllText: true,
blockAllMedia: true,
}),
],
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
enableLogs: true,
});
export const handleError = Sentry.handleErrorWithSentry();Step 5 — — Server hooks (no init here in modern setup)
src/hooks.server.tstypescript
import * as Sentry from "@sentry/sveltekit";
import { sequence } from "@sveltejs/kit/hooks";
export const handleError = Sentry.handleErrorWithSentry();
// sentryHandle() instruments incoming requests and creates root spans
export const handle = Sentry.sentryHandle();
// If you have other handle functions, compose with sequence():
// export const handle = sequence(Sentry.sentryHandle(), myAuthHandle);Step 6 — — Source maps (requires )
vite.config.tsSENTRY_AUTH_TOKENtypescript
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [
// sentrySvelteKit MUST come before sveltekit()
sentrySvelteKit({
org: process.env.SENTRY_ORG,
project: process.env.SENTRY_PROJECT,
authToken: process.env.SENTRY_AUTH_TOKEN,
}),
sveltekit(),
],
});Add to (never commit):
.envbash
SENTRY_AUTH_TOKEN=sntrys_...
SENTRY_ORG=my-org-slug
SENTRY_PROJECT=my-project-slugPath B: SvelteKit Legacy (<2.31.0 or @sentry/sveltekit
<10.8.0)
@sentry/sveltekitSkip and changes. Instead, put directly in :
instrumentation.server.tssvelte.config.jsSentry.init()hooks.server.tstypescript
// src/hooks.server.ts (legacy — init goes here)
import * as Sentry from "@sentry/sveltekit";
Sentry.init({
dsn: process.env.SENTRY_DSN,
tracesSampleRate: 1.0,
enableLogs: true,
});
export const handleError = Sentry.handleErrorWithSentry();
export const handle = Sentry.sentryHandle();hooks.client.tsvite.config.tsPath C: Plain Svelte (no SvelteKit)
Install:
bash
npm install @sentry/svelte --saveConfigure in entry point ( or ) before mounting the app:
src/main.tssrc/main.jstypescript
import * as Sentry from "@sentry/svelte";
import App from "./App.svelte";
Sentry.init({
dsn: import.meta.env.VITE_SENTRY_DSN,
environment: import.meta.env.MODE,
sendDefaultPii: true,
integrations: [
Sentry.browserTracingIntegration(),
Sentry.replayIntegration({
maskAllText: true,
blockAllMedia: true,
}),
],
tracesSampleRate: 1.0,
tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
enableLogs: true,
});
const app = new App({ target: document.getElementById("app")! });
export default app;Optional: Svelte component tracking (auto-injects tracking into all components):
javascript
// svelte.config.js
import { withSentryConfig } from "@sentry/svelte";
export default withSentryConfig(
{ compilerOptions: {} },
{ componentTracking: { trackComponents: true } }
);For Each Agreed Feature
Walk through features one at a time. Load the reference file, follow its steps, then verify before moving on:
| Feature | Reference | Load when... |
|---|---|---|
| Error Monitoring | | Always (baseline) |
| Tracing | | API calls / distributed tracing needed |
| Session Replay | | User-facing app |
| Logging | | Structured logs / log-to-trace correlation |
For each feature: , follow steps exactly, verify it works.
Read ${SKILL_ROOT}/references/<feature>.mdSvelteKit File Summary
| File | Purpose | Modern | Legacy |
|---|---|---|---|
| Server | ✅ Required | ❌ |
| Client | ✅ Required | ✅ Required |
| | ✅ Required | ✅ Init goes here |
| Enable | ✅ Required | ❌ |
| | ✅ Recommended | ✅ Recommended |
| | ✅ For source maps | ✅ For source maps |
Configuration Reference
Key Sentry.init()
Options
Sentry.init()| Option | Type | Default | Notes |
|---|---|---|---|
| | — | Required. Use env var; SDK is disabled when empty |
| | | e.g., |
| | — | e.g., |
| | | Includes IP addresses and request headers |
| | — | 0–1; use |
| | — | Per-transaction sampling; overrides |
| | — | URLs that receive distributed tracing headers |
| | — | Fraction of all sessions recorded (client only) |
| | — | Fraction of error sessions recorded (client only) |
| | | Enable |
| | — | Filter/modify logs before send |
| | | Verbose SDK output to console |
Server-Only Options (instrumentation.server.ts
/ hooks.server.ts
)
instrumentation.server.tshooks.server.ts| Option | Type | Notes |
|---|---|---|
| | Hostname tag on server events |
| | Attach local vars to stack frames |
| | ms to flush events before process exit (default: 2000) |
Adapter Compatibility
| Adapter | Support |
|---|---|
| ✅ Full |
| ✅ Full |
| ⚠️ Partial — requires extra setup |
| Vercel Edge Runtime | ❌ Not supported |
Verification
After setup, trigger test events to confirm Sentry is receiving data:
svelte
<!-- src/routes/sentry-test/+page.svelte -->
<script>
import * as Sentry from "@sentry/sveltekit";
</script>
<button onclick={() => { throw new Error("Sentry client test"); }}>
Test Client Error
</button>
<button onclick={() => Sentry.captureMessage("Sentry test message", "info")}>
Test Message
</button>typescript
// src/routes/sentry-test/+server.ts
export const GET = () => {
throw new Error("Sentry server test");
};Check the Sentry dashboard:
- Issues → both errors should appear within seconds
- Traces → look for route-based transactions
- Replays → session recording visible after page interaction
- Logs → structured log entries (if logging enabled)
If nothing appears, set in and check the browser/server console for SDK output.
debug: trueSentry.init()Phase 4: Cross-Link
After completing Svelte/SvelteKit setup, check for a companion backend missing Sentry coverage:
bash
# Look for backend in adjacent directories
ls ../backend ../server ../api ../go ../python 2>/dev/null
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3If a backend exists without Sentry configured, suggest the matching skill:
| Backend detected | Suggest skill |
|---|---|
Go ( | |
Python ( | |
Ruby ( | |
| Node.js (Express, Fastify, etc.) | Use |
Troubleshooting
| Issue | Solution |
|---|---|
| Events not appearing | Set |
| Source maps not working | Run |
| Server errors not captured | Ensure |
| Client errors not captured | Ensure |
| Session replay not recording | Confirm |
| Wrap with |
| Ad-blocker blocking events | Set |
| SvelteKit instrumentation not activating | Confirm |
| Cloudflare adapter issues | Consult docs.sentry.io/platforms/javascript/guides/sveltekit/ for adapter-specific notes |
| These are legacy wrappers — remove them; |