Skip to content

Commit b3a09d1

Browse files
Lms24Lms24
authored
ref(sveltekit): Improve manual setup code snippets and structure (#11038)
- streamlined code snippets so that there's only one snippet per file users need to change. Since we can now highlight parts in snippets, I think it's easier for users to identify what they need to change in a file on one glance instead of piecing together two or three snippets. - Removed TS and JS tabs in the snippets because there's no TS-specific syntax in them. - Restructured H2 document structure so that not all optional configuration sections are part of "Configuration". This should help users identify what they have to do vs. what's optional and probably not necessary to read.
1 parent 96d0b78 commit b3a09d1

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)