Skip to content

Commit 08af5b7

Browse files
Lms24Lms24
committed
ref(sveltekit): Improve manual setup code snippets and structure
1 parent 96d0b78 commit 08af5b7

File tree

2 files changed

+28
-209
lines changed

2 files changed

+28
-209
lines changed

‎docs/platforms/javascript/guides/sveltekit/manual-setup.mdx

Lines changed: 27 additions & 208 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,18 @@ If you're updating your Sentry SDK to the latest version, check out our [migrati
2424

2525
## Configure
2626

27+
The Sentry SDK needs to be initialized and configured in three places: On the client-side, server-side and in your Vite config.
28+
2729
### Client-side Setup
2830

29-
1. If you don't already have a [client hooks](https://kit.svelte.dev/docs/hooks#shared-hooks) file, create a new one in `src/hooks.client.(js|ts)`.
31+
If you don't already have a [client hooks](https://kit.svelte.dev/docs/hooks#shared-hooks) file, create a new one in `src/hooks.client.(js|ts)`.
3032

31-
2. At the top of your client hooks file, initialize the Sentry SDK as shown in the snippet below. See the [Basic Options](../configuration/options/) page to view other SDK configuration options.
33+
At the top of your client hooks file, import and initialize the Sentry SDK as shown in the snippet below. See the [Basic Options](../configuration/options/) page to view other SDK configuration options.
34+
Also, add the `handleErrorWithSentry` function to the [`handleError` hook](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror):
3235

3336
<SignInNote />
3437

35-
```javascript {filename:hooks.client.js}
38+
```javascript {filename:hooks.client.(js|ts)} {1, 3-14, 20}
3639
import * as Sentry from "@sentry/sveltekit";
3740

3841
Sentry.init({
@@ -47,39 +50,7 @@ Sentry.init({
4750
replaysSessionSampleRate: 0.1,
4851
replaysOnErrorSampleRate: 1.0,
4952
});
50-
```
51-
52-
```typescript {filename:hooks.client.ts}
53-
import * as Sentry from "@sentry/sveltekit";
54-
55-
Sentry.init({
56-
dsn: "___PUBLIC_DSN___",
57-
58-
// We recommend adjusting this value in production, or using tracesSampler
59-
// for finer control
60-
tracesSampleRate: 1.0,
61-
62-
// Optional: Initialize Session Replay:
63-
integrations: [Sentry.replayIntegration()],
64-
replaysSessionSampleRate: 0.1,
65-
replaysOnErrorSampleRate: 1.0,
66-
});
67-
```
68-
69-
3. Add the `handleErrorWithSentry` function to the [`handleError` hook](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror):
70-
71-
```javascript {filename:hooks.client.js} {5}
72-
const myErrorHandler = ({ error, event }) => {
73-
console.error("An error occurred on the client side:", error, event);
74-
};
75-
76-
export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);
7753

78-
// or alternatively, if you don't have a custom error handler:
79-
// export const handleError = handleErrorWithSentry();
80-
```
81-
82-
```typescript {filename:hooks.client.ts} {5}
8354
const myErrorHandler = ({ error, event }) => {
8455
console.error("An error occurred on the client side:", error, event);
8556
};
@@ -92,13 +63,15 @@ export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);
9263

9364
### Server-side Setup
9465

95-
1. If you don't already have a [server hooks](https://kit.svelte.dev/docs/hooks#server-hooks) file, create a new one in `src/hooks.server.(js|ts)`.
66+
If you don't already have a [server hooks](https://kit.svelte.dev/docs/hooks#server-hooks) file, create a new one in `src/hooks.server.(js|ts)`.
9667

97-
2. At the top of your server hooks file, initialize the Sentry SDK as shown in the snippet below. See the [Basic Options](../configuration/options/) page to view other SDK configuration options.
68+
At the top of your server hooks file, import and initialize the Sentry SDK as shown in the snippet below. See the [Basic Options](../configuration/options/) page to view other SDK configuration options.
69+
Add the `handleErrorWithSentry` function to the [`handleError` hook](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror) and add the Sentry request handler to the [`handle` hook](https://kit.svelte.dev/docs/hooks#server-hooks-handle).
70+
If you're already using your own handler(s), use SvelteKit's [`sequence`](https://kit.svelte.dev/docs/modules#sveltejs-kit-hooks-sequence) function to add the Sentry handler _before_ your handler(s).
9871

9972
<SignInNote />
10073

101-
```javascript {filename:hooks.server.js}
74+
```javascript {filename:hooks.server.(js|ts)} {1, 3-9, 15, 19}
10275
import * as Sentry from "@sentry/sveltekit";
10376

10477
Sentry.init({
@@ -108,52 +81,15 @@ Sentry.init({
10881
// for finer control
10982
tracesSampleRate: 1.0,
11083
});
111-
```
112-
113-
```typescript {filename:hooks.server.ts}
114-
import * as Sentry from "@sentry/sveltekit";
115-
116-
Sentry.init({
117-
dsn: "___PUBLIC_DSN___",
118-
119-
// We recommend adjusting this value in production, or using tracesSampler
120-
// for finer control
121-
tracesSampleRate: 1.0,
122-
});
123-
```
124-
125-
3. Add the `handleErrorWithSentry` function to the [`handleError` hook](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror):
12684

127-
```javascript {filename:hooks.server.js} {5}
12885
const myErrorHandler = ({ error, event }) => {
12986
console.error("An error occurred on the server side:", error, event);
13087
};
13188

13289
export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);
13390
// or alternatively, if you don't have a custom error handler:
13491
// export const handleError = handleErrorWithSentry();
135-
```
136-
137-
```typescript {filename:hooks.server.ts} {5}
138-
const myErrorHandler = ({ error, event }) => {
139-
console.error("An error occurred on the server side:", error, event);
140-
};
141-
142-
export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);
143-
// or alternatively, if you don't have a custom error handler:
144-
// export const handleError = handleErrorWithSentry();
145-
```
146-
147-
4. Add the Sentry request handler to the [`handle` hook](https://kit.svelte.dev/docs/hooks#server-hooks-handle).
148-
If you're already using your own handler(s), use SvelteKit's [`sequence`](https://kit.svelte.dev/docs/modules#sveltejs-kit-hooks-sequence) function to add the Sentry handler _before_ your handler(s):
14992

150-
```javascript {filename:hooks.server.js}
151-
export const handle = Sentry.sentryHandle();
152-
// Or use `sequence`:
153-
// export const handle = sequence(Sentry.sentryHandle(), yourHandler());
154-
```
155-
156-
```typescript {filename:hooks.server.ts}
15793
export const handle = Sentry.sentryHandle();
15894
// Or use `sequence`:
15995
// export const handle = sequence(Sentry.sentryHandle(), yourHandler());
@@ -164,17 +100,7 @@ export const handle = Sentry.sentryHandle();
164100
Add the `sentrySvelteKit` plugins to your `vite.config.(js|ts)` file so the Sentry SDK can apply build-time features.
165101
Make sure that it is added _before_ the sveltekit plugin:
166102

167-
```javascript {filename:vite.config.js} {2,5}
168-
import { sveltekit } from "@sveltejs/kit/vite";
169-
import { sentrySvelteKit } from "@sentry/sveltekit";
170-
171-
export default {
172-
plugins: [sentrySvelteKit(), sveltekit()],
173-
// ... rest of your Vite config
174-
};
175-
```
176-
177-
```typescript {filename:vite.config.ts} {2,5}
103+
```javascript {filename:vite.config.(js|ts)} {2,5}
178104
import { sveltekit } from "@sveltejs/kit/vite";
179105
import { sentrySvelteKit } from "@sentry/sveltekit";
180106

@@ -189,7 +115,7 @@ The `sentrySvelteKit()` function adds Vite plugins to your Vite config to:
189115
- Automatically upload source maps to Sentry
190116
- Automatically instrument `load` functions for tracing
191117

192-
### Configure Source Maps Upload
118+
### Source Maps Upload
193119

194120
By default, `sentrySvelteKit()` will add an instance of the [Sentry Vite Plugin](https://www.npmjs.com/package/@sentry/vite-plugin), to upload source maps for both server and client builds. This means that when you run a production build (`npm run build`), source maps will be generated and uploaded to Sentry, so that you get readable stack traces in your Sentry issues.
195121

@@ -212,7 +138,7 @@ SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
212138

213139
<SignInNote />
214140

215-
```javascript {filename:vite.config.js} {7-16}
141+
```javascript {filename:vite.config.(js|ts)} {7-16}
216142
import { sveltekit } from "@sveltejs/kit/vite";
217143
import { sentrySvelteKit } from "@sentry/sveltekit";
218144

@@ -236,48 +162,14 @@ export default {
236162
};
237163
```
238164

239-
```typescript {filename:vite.config.ts} {7-11}
240-
import { sveltekit } from "@sveltejs/kit/vite";
241-
import { sentrySvelteKit } from "@sentry/sveltekit";
242-
243-
export default {
244-
plugins: [
245-
sentrySvelteKit({
246-
sourceMapsUploadOptions: {
247-
org: "___ORG_SLUG___",
248-
project: "___PROJET_SLUG___",
249-
authToken: process.env.SENTRY_AUTH_TOKEN,
250-
},
251-
}),
252-
sveltekit(),
253-
],
254-
// ... rest of your Vite config
255-
};
256-
```
257-
258165
Using the `sourceMapsUploadOptions` object is useful if the default source maps upload doesn't work out of the box, for instance, if you have a customized build setup or if you're using the SDK with a SvelteKit adapter other than the [supported adapters](../#compatibility).
259166

260167
#### Overriding SvelteKit Adapter detection
261168

262169
By default, `sentrySvelteKit` will try to detect your SvelteKit adapter to configure source maps upload correctly.
263170
If you're not using one of the [supported adapters](../#compatibility) or the wrong one is detected, you can override the adapter detection by passing the `adapter` option to `sentrySvelteKit`:
264171

265-
```javascript {filename:vite.config.js} {7}
266-
import { sveltekit } from "@sveltejs/kit/vite";
267-
import { sentrySvelteKit } from "@sentry/sveltekit";
268-
269-
export default {
270-
plugins: [
271-
sentrySvelteKit({
272-
adapter: "vercel",
273-
}),
274-
sveltekit(),
275-
],
276-
// ... rest of your Vite config
277-
};
278-
```
279-
280-
```typescript {filename:vite.config.ts} {7}
172+
```javascript {filename:vite.config.(js|ts)} {7}
281173
import { sveltekit } from "@sveltejs/kit/vite";
282174
import { sentrySvelteKit } from "@sentry/sveltekit";
283175

@@ -296,7 +188,7 @@ export default {
296188

297189
You can disable automatic source maps upload in your Vite config:
298190

299-
```javascript {filename:vite.config.js} {7}
191+
```javascript {filename:vite.config.(js|ts)} {7}
300192
import { sveltekit } from "@sveltejs/kit/vite";
301193
import { sentrySvelteKit } from "@sentry/sveltekit";
302194

@@ -311,22 +203,11 @@ export default {
311203
};
312204
```
313205

314-
```typescript {filename:vite.config.ts} {7}
315-
import { sveltekit } from "@sveltejs/kit/vite";
316-
import { sentrySvelteKit } from "@sentry/sveltekit";
206+
If you disable automatic source maps upload, you must explicitly set a `release` value in your `Sentry.init()` configs. You can also skip the `sentry-cli` configuration step below.
317207

318-
export default {
319-
plugins: [
320-
sentrySvelteKit({
321-
autoUploadSourceMaps: false,
322-
}),
323-
sveltekit(),
324-
],
325-
// ... rest of your Vite config
326-
};
327-
```
208+
## Optional Configuration
328209

329-
If you disable automatic source maps upload, you must explicitly set a `release` value in your `Sentry.init()` configs. You can also skip the `sentry-cli` configuration step below.
210+
The points explain additional optional configuration or more in-depth customization of your Sentry SvelteKit SDK setup.
330211

331212
### Auto-Instrumentation
332213

@@ -345,25 +226,7 @@ If you have custom Sentry code in these files, you'll have to [manually](#instru
345226

346227
By passing the `autoInstrument` option to `sentrySvelteKit` you can disable auto-instrumentation entirely, or customize which `load` functions should be instrumented:
347228

348-
```javascript {filename:vite.config.js} {7-10}
349-
import { sveltekit } from "@sveltejs/kit/vite";
350-
import { sentrySvelteKit } from "@sentry/sveltekit";
351-
352-
export default {
353-
plugins: [
354-
sentrySvelteKit({
355-
autoInstrument: {
356-
load: true,
357-
serverLoad: false,
358-
},
359-
}),
360-
sveltekit(),
361-
],
362-
// ... rest of your Vite config
363-
};
364-
```
365-
366-
```typescript {filename:vite.config.ts} {7-10}
229+
```javascript {filename:vite.config.(js|ts)} {7-10}
367230
import { sveltekit } from "@sveltejs/kit/vite";
368231
import { sentrySvelteKit } from "@sentry/sveltekit";
369232

@@ -385,22 +248,7 @@ export default {
385248

386249
If you set the `autoInstrument` option to `false`, the SDK won't auto-instrument any `load` functions. You can still [manually instrument](#instrument-load-functions-manually) specific `load` functions.
387250

388-
```javascript {filename:vite.config.js} {7}
389-
import { sveltekit } from '@sveltejs/kit/vite';
390-
import { sentrySvelteKit } from '@sentry/sveltekit';
391-
392-
export default {
393-
plugins: [
394-
sentrySvelteKit({
395-
autoInstrument: false;
396-
}),
397-
sveltekit(),
398-
],
399-
// ... rest of your Vite config
400-
};
401-
```
402-
403-
```typescript {filename:vite.config.ts} {7}
251+
```javascript {filename:vite.config.(js|ts)} {7}
404252
import { sveltekit } from '@sveltejs/kit/vite';
405253
import { sentrySvelteKit } from '@sentry/sveltekit';
406254

@@ -430,14 +278,14 @@ To enable the script, you need to add an exception for the `sentryHandle` script
430278

431279
First, specify your nonce in the `fetchProxyScriptNonce` option in your `sentryHandle` call:
432280

433-
```javascript {filename:hooks.server.ts}
281+
```javascript {filename:hooks.server.(js|ts)}
434282
// Add the nonce to the <script> tag:
435283
export const handle = sentryHandle({ fetchProxyScriptNonce: "<your-nonce>" });
436284
```
437285

438286
Then, adjust your [SvelteKit CSP configuration](https://kit.svelte.dev/docs/configuration#csp):
439287

440-
```javascript {svelte.config.js} {5}
288+
```javascript {filename: svelte.config.js} {5}
441289
const config = {
442290
kit: {
443291
csp: {
@@ -453,7 +301,7 @@ const config = {
453301

454302
If you do not want to inject the script responsible for instrumenting client-side `load` calls, you can disable injection by passing `injectFetchProxyScript: false` to `sentryHandle`:
455303

456-
```javascript {filename:hooks.server.ts}
304+
```javascript {filename:hooks.server.(js|ts)}
457305
export const handle = sentryHandle({ injectFetchProxyScript: false });
458306
```
459307

@@ -473,17 +321,7 @@ If you don't want to use `load` auto-instrumentation, you can [disable it](#disa
473321

474322
Use the `wrapLoadWithSentry` function to wrap universal `load` functions declared in `+page.(js|ts)` or `+layout.(js|ts)`
475323

476-
```javascript {filename:+(page|layout).js} {1,3}
477-
import { wrapLoadWithSentry } from "@sentry/sveltekit";
478-
479-
export const load = wrapLoadWithSentry(({ fetch }) => {
480-
const res = await fetch("/api/data");
481-
const data = await res.json();
482-
return { data };
483-
});
484-
```
485-
486-
```typescript {filename:+(page|layout).ts} {1,3}
324+
```javascript {filename:+(page|layout).(js|ts)} {1,3}
487325
import { wrapLoadWithSentry } from "@sentry/sveltekit";
488326

489327
export const load = wrapLoadWithSentry(({ fetch }) => {
@@ -497,7 +335,7 @@ export const load = wrapLoadWithSentry(({ fetch }) => {
497335

498336
Or use the `wrapServerLoadWithSentry` function to wrap server-only `load` functions declared in `+page.server.(js|ts)` or `+layout.server.(js|ts)`
499337

500-
```javascript {filename:+(page|layout).server.js} {1,3}
338+
```javascript {filename:+(page|layout).server.(js|ts)} {1,3}
501339
import { wrapServerLoadWithSentry } from "@sentry/sveltekit";
502340

503341
export const load = wrapServerLoadWithSentry(({ fetch }) => {
@@ -507,16 +345,6 @@ export const load = wrapServerLoadWithSentry(({ fetch }) => {
507345
});
508346
```
509347

510-
```typescript {filename:+(page|layout).server.ts} {1,3}
511-
import { wrapServerLoadWithSentry } from "@sentry/sveltekit";
512-
513-
export const load = wrapServerLoadWithSentry(({ event }) => {
514-
const res = await fetch("/api/data");
515-
const data = await res.json();
516-
return { data };
517-
});
518-
```
519-
520348
#### Instrument Server Routes
521349

522350
<Note>
@@ -528,16 +356,7 @@ Available since `8.25.0`
528356
You can also manually instrument [server (API) routes ](https://kit.svelte.dev/docs/routing#server) with the SDK.
529357
This is useful if you have custom server routes that you want to trace or if you want to capture `error()` calls within your server routes:
530358

531-
```javascript {filename:+server.js} {1,3}
532-
import { wrapServerRouteWithSentry } from "@sentry/sveltekit";
533-
534-
export const GET = wrapServerRouteWithSentry(async () => {
535-
// your endpoint logic
536-
return new Response("Hello World");
537-
});
538-
```
539-
540-
```typescript {filename:+server.ts} {1,3}
359+
```javascript {filename:+server.(js|ts)} {1,3}
541360
import { wrapServerRouteWithSentry } from "@sentry/sveltekit";
542361

543362
export const GET = wrapServerRouteWithSentry(async () => {

0 commit comments

Comments
 (0)