diff --git a/docs/platforms/javascript/guides/sveltekit/manual-setup.mdx b/docs/platforms/javascript/guides/sveltekit/manual-setup.mdx index f2bf458b00fab..f76c4580e1c91 100644 --- a/docs/platforms/javascript/guides/sveltekit/manual-setup.mdx +++ b/docs/platforms/javascript/guides/sveltekit/manual-setup.mdx @@ -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): -```javascript {filename:hooks.client.js} +```javascript {filename:hooks.client.(js|ts)} {1, 3-14, 20} import * as Sentry from "@sentry/sveltekit"; Sentry.init({ @@ -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); }; @@ -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). -```javascript {filename:hooks.server.js} +```javascript {filename:hooks.server.(js|ts)} {1, 3-9, 15, 19} import * as Sentry from "@sentry/sveltekit"; Sentry.init({ @@ -108,23 +81,7 @@ 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); }; @@ -132,28 +89,7 @@ const myErrorHandler = ({ 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()); @@ -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"; @@ -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. @@ -212,7 +138,7 @@ SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ -```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"; @@ -236,25 +162,6 @@ 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 @@ -262,22 +169,7 @@ Using the `sourceMapsUploadOptions` object is useful if the default source maps 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"; @@ -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"; @@ -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 @@ -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"; @@ -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'; @@ -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