diff --git a/packages/sveltekit/README.md b/packages/sveltekit/README.md index 506e134168a3..3951ffcac04f 100644 --- a/packages/sveltekit/README.md +++ b/packages/sveltekit/README.md @@ -127,47 +127,25 @@ The Sentry SvelteKit SDK mostly relies on [SvelteKit Hooks](https://kit.svelte.d // export const handle = sequence(sentryHandle(), yourHandler()); ``` -### 4. Configuring `load` Functions +### 4. Vite Setup -5. To catch errors and performance data in your universal `load` functions (e.g. in `+page.(js|ts)`), wrap our `wrapLoadWithSentry` function around your load code: +Add `sentrySvelteKit` to your Vite plugins in `vite.config.(js|ts)` file so that the Sentry SDK can apply build-time features. +Make sure that it is added _before_ the `sveltekit` plugin: - ```javascript - // +page.(js|ts) - import { wrapLoadWithSentry } from '@sentry/sveltekit'; - - export const load = wrapLoadWithSentry((event) => { - //... your load code - }); - ``` - -6. To catch errors and performance data in your server `load` functions (e.g. in `+page.server.(js|ts)`), wrap our `wrapServerLoadWithSentry` function around your load code: - - ```javascript - // +page.server.(js|ts) - import { wrapServerLoadWithSentry } from '@sentry/sveltekit'; - - export const load = wrapServerLoadWithSentry((event) => { - //... your server load code - }); - ``` - -### 5. Vite Setup +```javascript +// vite.config.(js|ts) +import { sveltekit } from '@sveltejs/kit/vite'; +import { sentrySvelteKit } from '@sentry/sveltekit'; -1. Add our `sentrySvelteKit` plugins to your `vite.config.(js|ts)` file so that the Sentry SDK can apply build-time features. - Make sure that it is added before the `sveltekit` plugin: +export default { + plugins: [sentrySvelteKit(), sveltekit()], + // ... rest of your Vite config +}; +``` - ```javascript - // vite.config.(js|ts) - import { sveltekit } from '@sveltejs/kit/vite'; - import { sentrySvelteKit } from '@sentry/sveltekit'; - - export default { - plugins: [sentrySvelteKit(), sveltekit()], - // ... rest of your Vite config - }; - ``` +This adds the [Sentry Vite Plugin](https://github.com/getsentry/sentry-javascript-bundler-plugins/tree/main/packages/vite-plugin) to your Vite config to automatically upload source maps to Sentry. - This adds the [Sentry Vite Plugin](https://github.com/getsentry/sentry-javascript-bundler-plugins/tree/main/packages/vite-plugin) to your Vite config to automatically upload source maps to Sentry. +--- ## Uploading Source Maps @@ -252,14 +230,87 @@ export default { }; ``` +## Configure Auto-Instrumentation + +The SDK mostly relies on [SvelteKit's hooks](https://kit.svelte.dev/docs/hooks) to collect error and performance data. However, SvelteKit doesn't yet offer a hook for universal or server-only `load` function calls. Therefore, the SDK uses a Vite plugin to auto-instrument `load` functions so that you don't have to add a Sentry wrapper to each function manually. Auto-instrumentation is enabled by default, as soon as you add the `sentrySvelteKit()` function call to your `vite.config.(js|ts)`. However, you can customize the behavior, or disable it entirely. In this case, you can still manually wrap specific `load` functions with the `withSentry` function. + +Note: The SDK will only auto-instrument `load` functions in `+page` or `+layout` files that do not yet contain any Sentry code. +If you already have custom Sentry code in such files, you'll have to [manually](#instrument-load-functions-manually) add our wrapper to your `load` functions. + + +### Customize Auto-instrumentation + +By passing the `autoInstrument` option to `sentrySvelteKit` you can disable auto-instrumentation entirely, or customize which `load` functions should be instrumented: + +```javascript +// vite.config.(js|ts) +import { sveltekit } from '@sveltejs/kit/vite'; +import { sentrySvelteKit } from '@sentry/sveltekit'; + +export default { + plugins: [ + sentrySvelteKit({ + autoInstrument: { + load: true, // universal load functions + serverLoad: false, // server-only load functions + }, + }), + sveltekit(), + ], + // ... rest of your Vite config +}; +``` + +### Disable Auto-instrumentation + +If you set the `autoInstrument` option to `false`, the SDK won't auto-instrument any `load` function. You can still [manually instrument](#instrument-load-functions-manually) specific `load` functions. + +```javascript +// vite.config.(js|ts) +import { sveltekit } from '@sveltejs/kit/vite'; +import { sentrySvelteKit } from '@sentry/sveltekit'; + +export default { + plugins: [ + sentrySvelteKit({ + autoInstrument: false; + }), + sveltekit(), + ], + // ... rest of your Vite config +}; +``` + +### Instrument `load` Functions Manually + +If you don't want to use auto-instrumentation, you can also manually instrument specific `load` functions with our load function wrappers: + +To instrument your universal `load` functions in `+(page|layout).(js|ts)`, wrap our `wrapLoadWithSentry` function around your load code: + +```javascript +import { wrapLoadWithSentry } from '@sentry/sveltekit'; + +export const load = wrapLoadWithSentry((event) => { + //... your load code +}); +``` + +To instrument server `load` functions in `+(page|layout).server.(js|ts)`, wrap our `wrapServerLoadWithSentry` function around your load code: + +```javascript +import { wrapServerLoadWithSentry } from '@sentry/sveltekit'; + +export const load = wrapServerLoadWithSentry((event) => { + //... your server load code +}); +``` + + ## Known Limitations This SDK is still under active development. -Take a look at our [SvelteKit SDK Development Roadmap](https://github.com/getsentry/sentry-javascript/issues/6692) to follow the progress: +Take a look at our [SvelteKit SDK Development Roadmap](https://github.com/getsentry/sentry-javascript/issues/6692) to follow the progress. - **Adapters** other than `@sveltejs/adapter-node` are currently not supported. We haven't yet tested other platforms like Vercel. This is on our roadmap but it will come at a later time. - -- We're aiming to **simplify SDK setup** in the future so that you don't have to go in and manually add our wrappers to all your `load` functions. - This will be addressed once the SDK supports all Sentry features.