Skip to content

Commit

Permalink
ref(sveltekit): Improve manual setup code snippets and structure (#11038
Browse files Browse the repository at this point in the history 
)

- 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.
  • Loading branch information
@Lms24
Lms24 authored Aug 9, 2024
1 parent 96d0b78 commit b3a09d1
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 209 deletions.
235 changes: 27 additions & 208 deletions docs/platforms/javascript/guides/sveltekit/manual-setup.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,18 @@ If you're updating your Sentry SDK to the latest version, check out our [migrati

## Configure

The Sentry SDK needs to be initialized and configured in three places: On the client-side, server-side and in your Vite config.

### Client-side Setup

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)`.
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)`.

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.
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.
Also, add the `handleErrorWithSentry` function to the [`handleError` hook](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror):

<SignInNote />

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

Sentry.init({
Expand All @@ -47,39 +50,7 @@ Sentry.init({
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
});
```

```typescript {filename:hooks.client.ts}
import * as Sentry from "@sentry/sveltekit";

Sentry.init({
dsn: "___PUBLIC_DSN___",

// We recommend adjusting this value in production, or using tracesSampler
// for finer control
tracesSampleRate: 1.0,

// Optional: Initialize Session Replay:
integrations: [Sentry.replayIntegration()],
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
});
```

3. Add the `handleErrorWithSentry` function to the [`handleError` hook](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror):

```javascript {filename:hooks.client.js} {5}
const myErrorHandler = ({ error, event }) => {
console.error("An error occurred on the client side:", error, event);
};

export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);

// or alternatively, if you don't have a custom error handler:
// export const handleError = handleErrorWithSentry();
```

```typescript {filename:hooks.client.ts} {5}
const myErrorHandler = ({ error, event }) => {
console.error("An error occurred on the client side:", error, event);
};
Expand All @@ -92,13 +63,15 @@ export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);

### Server-side Setup

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)`.
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)`.

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.
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.
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).
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).

<SignInNote />

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

Sentry.init({
Expand All @@ -108,52 +81,15 @@ Sentry.init({
// for finer control
tracesSampleRate: 1.0,
});
```

```typescript {filename:hooks.server.ts}
import * as Sentry from "@sentry/sveltekit";

Sentry.init({
dsn: "___PUBLIC_DSN___",

// We recommend adjusting this value in production, or using tracesSampler
// for finer control
tracesSampleRate: 1.0,
});
```

3. Add the `handleErrorWithSentry` function to the [`handleError` hook](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror):

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

export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);
// or alternatively, if you don't have a custom error handler:
// export const handleError = handleErrorWithSentry();
```

```typescript {filename:hooks.server.ts} {5}
const myErrorHandler = ({ error, event }) => {
console.error("An error occurred on the server side:", error, event);
};

export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);
// or alternatively, if you don't have a custom error handler:
// export const handleError = handleErrorWithSentry();
```

4. Add the Sentry request handler to the [`handle` hook](https://kit.svelte.dev/docs/hooks#server-hooks-handle).
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):

```javascript {filename:hooks.server.js}
export const handle = Sentry.sentryHandle();
// Or use `sequence`:
// export const handle = sequence(Sentry.sentryHandle(), yourHandler());
```

```typescript {filename:hooks.server.ts}
export const handle = Sentry.sentryHandle();
// Or use `sequence`:
// export const handle = sequence(Sentry.sentryHandle(), yourHandler());
Expand All @@ -164,17 +100,7 @@ export const handle = Sentry.sentryHandle();
Add the `sentrySvelteKit` plugins to your `vite.config.(js|ts)` file so the Sentry SDK can apply build-time features.
Make sure that it is added _before_ the sveltekit plugin:

```javascript {filename:vite.config.js} {2,5}
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";

export default {
plugins: [sentrySvelteKit(), sveltekit()],
// ... rest of your Vite config
};
```

```typescript {filename:vite.config.ts} {2,5}
```javascript {filename:vite.config.(js|ts)} {2,5}
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";

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

### Configure Source Maps Upload
### Source Maps Upload

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.

Expand All @@ -212,7 +138,7 @@ SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___

<SignInNote />

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

Expand All @@ -236,48 +162,14 @@ export default {
};
```

```typescript {filename:vite.config.ts} {7-11}
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";

export default {
plugins: [
sentrySvelteKit({
sourceMapsUploadOptions: {
org: "___ORG_SLUG___",
project: "___PROJET_SLUG___",
authToken: process.env.SENTRY_AUTH_TOKEN,
},
}),
sveltekit(),
],
// ... rest of your Vite config
};
```

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).

#### Overriding SvelteKit Adapter detection

By default, `sentrySvelteKit` will try to detect your SvelteKit adapter to configure source maps upload correctly.
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`:

```javascript {filename:vite.config.js} {7}
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";

export default {
plugins: [
sentrySvelteKit({
adapter: "vercel",
}),
sveltekit(),
],
// ... rest of your Vite config
};
```

```typescript {filename:vite.config.ts} {7}
```javascript {filename:vite.config.(js|ts)} {7}
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";

Expand All @@ -296,7 +188,7 @@ export default {

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

```javascript {filename:vite.config.js} {7}
```javascript {filename:vite.config.(js|ts)} {7}
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";

Expand All @@ -311,22 +203,11 @@ export default {
};
```

```typescript {filename:vite.config.ts} {7}
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";
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.

export default {
plugins: [
sentrySvelteKit({
autoUploadSourceMaps: false,
}),
sveltekit(),
],
// ... rest of your Vite config
};
```
## Optional Configuration

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.
The points explain additional optional configuration or more in-depth customization of your Sentry SvelteKit SDK setup.

### Auto-Instrumentation

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

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

```javascript {filename:vite.config.js} {7-10}
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";

export default {
plugins: [
sentrySvelteKit({
autoInstrument: {
load: true,
serverLoad: false,
},
}),
sveltekit(),
],
// ... rest of your Vite config
};
```

```typescript {filename:vite.config.ts} {7-10}
```javascript {filename:vite.config.(js|ts)} {7-10}
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";

Expand All @@ -385,22 +248,7 @@ export default {

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.

```javascript {filename:vite.config.js} {7}
import { sveltekit } from '@sveltejs/kit/vite';
import { sentrySvelteKit } from '@sentry/sveltekit';

export default {
plugins: [
sentrySvelteKit({
autoInstrument: false;
}),
sveltekit(),
],
// ... rest of your Vite config
};
```

```typescript {filename:vite.config.ts} {7}
```javascript {filename:vite.config.(js|ts)} {7}
import { sveltekit } from '@sveltejs/kit/vite';
import { sentrySvelteKit } from '@sentry/sveltekit';

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

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

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

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

```javascript {svelte.config.js} {5}
```javascript {filename: svelte.config.js} {5}
const config = {
kit: {
csp: {
Expand All @@ -453,7 +301,7 @@ const config = {

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`:

```javascript {filename:hooks.server.ts}
```javascript {filename:hooks.server.(js|ts)}
export const handle = sentryHandle({ injectFetchProxyScript: false });
```

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

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

```javascript {filename:+(page|layout).js} {1,3}
import { wrapLoadWithSentry } from "@sentry/sveltekit";

export const load = wrapLoadWithSentry(({ fetch }) => {
const res = await fetch("/api/data");
const data = await res.json();
return { data };
});
```

```typescript {filename:+(page|layout).ts} {1,3}
```javascript {filename:+(page|layout).(js|ts)} {1,3}
import { wrapLoadWithSentry } from "@sentry/sveltekit";

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

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

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

export const load = wrapServerLoadWithSentry(({ fetch }) => {
Expand All @@ -507,16 +345,6 @@ export const load = wrapServerLoadWithSentry(({ fetch }) => {
});
```

```typescript {filename:+(page|layout).server.ts} {1,3}
import { wrapServerLoadWithSentry } from "@sentry/sveltekit";

export const load = wrapServerLoadWithSentry(({ event }) => {
const res = await fetch("/api/data");
const data = await res.json();
return { data };
});
```

#### Instrument Server Routes

<Note>
Expand All @@ -528,16 +356,7 @@ Available since `8.25.0`
You can also manually instrument [server (API) routes ](https://kit.svelte.dev/docs/routing#server) with the SDK.
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:

```javascript {filename:+server.js} {1,3}
import { wrapServerRouteWithSentry } from "@sentry/sveltekit";

export const GET = wrapServerRouteWithSentry(async () => {
// your endpoint logic
return new Response("Hello World");
});
```

```typescript {filename:+server.ts} {1,3}
```javascript {filename:+server.(js|ts)} {1,3}
import { wrapServerRouteWithSentry } from "@sentry/sveltekit";

export const GET = wrapServerRouteWithSentry(async () => {
Expand Down
Loading

0 comments on commit b3a09d1

Please sign in to comment.