diff --git a/packages/sveltekit/README.md b/packages/sveltekit/README.md index 11b593087bba..a21adc43b836 100644 --- a/packages/sveltekit/README.md +++ b/packages/sveltekit/README.md @@ -10,326 +10,33 @@ [![npm dm](https://img.shields.io/npm/dm/@sentry/sveltekit.svg)](https://www.npmjs.com/package/@sentry/sveltekit) [![npm dt](https://img.shields.io/npm/dt/@sentry/sveltekit.svg)](https://www.npmjs.com/package/@sentry/sveltekit) -## Links - -- [Official SDK Docs](https://docs.sentry.io/platforms/javascript/guides/sveltekit/) - ## Compatibility -The minimum supported version of SvelteKit is `1.0.0`. The SDK works best with Vite 4.2 and newer. Older Vite versions +The minimum supported version of SvelteKit is `2.0.0`. The SDK works best with Vite 4.2 and newer. Older Vite versions might not generate source maps correctly. -The SDK supports the following SvelteKit adapters: - -- `@sveltejs/adapter-auto` - for Vercel with the Node runtime. Other deployment targets might work but we don't - guarantee compatibility. -- `@sveltejs/adapter-vercel` - only for Node (Lambda) runtimes, not yet Vercel's edge runtime -- `@sveltejs/adapter-node` - -If you use the SDK with other adapters, we cannot guarantee that everything works as expected. You might need to -[manually configure source maps upload](#-configuring-source-maps-upload). The SDK is currently not compatible with -none-Node server runtimes, such as Vercel's Edge runtime or Cloudflare workers. +Check our docs for [SvelteKit adapter](https://docs.sentry.io/platforms/javascript/guides/sveltekit/#prerequisites) compatibility. ## General This package is a wrapper around `@sentry/node` for the server and `@sentry/svelte` for the client side, with added functionality related to SvelteKit. -## Automatic Setup +## Installation -We recommend installing the SDK by running the -[Sentry wizard](https://docs.sentry.io/platforms/javascript/guides/sveltekit/#install) in the root directory of your -project: +To get started installing the SDK, use the Sentry Next.js Wizard by running the following command in your terminal or +read the [Getting Started Docs](https://docs.sentry.io/platforms/javascript/guides/nextjs/): ```sh npx @sentry/wizard@latest -i sveltekit ``` -Take a look at the sections below if you want to customize your SDK configuration. - -## Manual Setup - -If the setup through the wizard doesn't work for you, you can also set up the SDK manually. - -### 1. Prerequesits & Installation - -1. Install the Sentry SvelteKit SDK: - - ```bash - # Using npm - npm install @sentry/sveltekit - - # Using yarn - yarn add @sentry/sveltekit - ``` - -### 2. Client-side Setup - -The Sentry SvelteKit SDK mostly relies on [SvelteKit Hooks](https://kit.svelte.dev/docs/hooks) to capture error and -performance data. - -1. If you don't already have a client hooks file, create a new one in `src/hooks.client.(js|ts)`. - -2. On the top of your `hooks.client.(js|ts)` file, initialize the Sentry SDK: - - ```javascript - // hooks.client.(js|ts) - import * as Sentry from '@sentry/sveltekit'; - - Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - // For instance, initialize Session Replay: - replaysSessionSampleRate: 0.1, - replaysOnErrorSampleRate: 1.0, - integrations: [Sentry.replayIntegration()], - }); - ``` - -3. Add our `handleErrorWithSentry` function to the `handleError` hook: - - ```javascript - // hooks.client.(js|ts) - import { handleErrorWithSentry } from '@sentry/sveltekit'; - - const myErrorHandler = ({ error, event }) => { - console.error('An error occurred on the client side:', error, event); - }; - - export const handleError = handleErrorWithSentry(myErrorHandler); - // or alternatively, if you don't have a custom error handler: - // export const handleError = handleErrorWithSentry(); - ``` - -### 3. Server-side Setup - -1. If you don't already have a server hooks file, create a new one in `src/hooks.server.(js|ts)`. - -2. On the top of your `hooks.server.(js|ts)` file, initialize the Sentry SDK: - - ```javascript - // hooks.server.(js|ts) - import * as Sentry from '@sentry/sveltekit'; - - Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - }); - ``` - -3. Add our `handleErrorWithSentry` function to the `handleError` hook: - - ```javascript - // hooks.server.(js|ts) - import { handleErrorWithSentry } from '@sentry/sveltekit'; - - const myErrorHandler = ({ error, event }) => { - console.error('An error occurred on the server side:', error, event); - }; - - export const handleError = handleErrorWithSentry(myErrorHandler); - // or alternatively, if you don't have a custom error handler: - // export const handleError = handleErrorWithSentry(); - ``` - -4. Add our request handler to the `handle` hook in `hooks.server.ts`: - - ```javascript - // hooks.server.(js|ts) - import { sentryHandle } from '@sentry/sveltekit'; - - export const handle = sentryHandle(); - // or alternatively, if you already have a handler defined, use the `sequence` function - // see: https://kit.svelte.dev/docs/modules#sveltejs-kit-hooks-sequence - // export const handle = sequence(sentryHandle(), yourHandler()); - ``` - -### 4. Vite Setup - -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 -// 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. - ---- +The wizard will guide you throuhg logging in to Sentry and setting up the SDK. After the wizard setup is completed, the SDK will automatically capture +unhandled errors, and optionally, traces and replays. -## Uploading Source Maps - -After completing the [Vite Setup](#5-vite-setup), the SDK will automatically upload source maps to Sentry, when you -build your project. However, you still need to specify your Sentry auth token as well as your org and project slugs. You -can either set them as env variables (for example in a `.env` file): - -- `SENTRY_ORG` your Sentry org slug -- `SENTRY_PROJECT` your Sentry project slug -- `SENTRY_AUTH_TOKEN` your Sentry auth token - -Or you can pass them in whatever form you prefer to `sentrySvelteKit`: - -```js -// vite.config.(js|ts) -import { sveltekit } from '@sveltejs/kit/vite'; -import { sentrySvelteKit } from '@sentry/sveltekit'; - -export default { - plugins: [ - sentrySvelteKit({ - sourceMapsUploadOptions: { - org: 'my-org-slug', - project: 'my-project-slug', - authToken: process.env.SENTRY_AUTH_TOKEN, - }, - }), - sveltekit(), - ], - // ... rest of your Vite config -}; -``` - -### Configuring Source maps upload - -Under `sourceMapsUploadOptions`, you can also specify all additional options supported by the -[Sentry Vite Plugin](https://www.npmjs.com/package/@sentry/vite-plugin). This might be useful if you're using adapters -other than the Node adapter or have a more customized build setup. - -```js -// vite.config.(js|ts) -import { sveltekit } from '@sveltejs/kit/vite'; -import { sentrySvelteKit } from '@sentry/sveltekit'; - -export default { - plugins: [ - sentrySvelteKit({ - sourceMapsUploadOptions: { - org: 'my-org-slug', - project: 'my-project-slug', - authToken: process.env.SENTRY_AUTH_TOKEN, - include: ['dist'], - cleanArtifacts: true, - setCommits: { - auto: true, - }, - }, - }), - sveltekit(), - ], - // ... rest of your Vite config -}; -``` - -### Disabling automatic source map upload - -If you don't want to upload source maps automatically, you can disable it as follows: - -```js -// vite.config.(js|ts) -import { sveltekit } from '@sveltejs/kit/vite'; -import { sentrySvelteKit } from '@sentry/sveltekit'; - -export default { - plugins: [ - sentrySvelteKit({ - autoUploadSourceMaps: false, - }), - sveltekit(), - ], - // ... rest of your Vite config -}; -``` - -## 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'; +## Links -export const load = wrapServerLoadWithSentry(event => { - //... your server load code -}); -``` +- [Official SDK Docs](https://docs.sentry.io/platforms/javascript/guides/sveltekit/) +- [Sentry.io](https://sentry.io/?utm_source=github&utm_medium=npm_sveltekit) +- [Sentry Discord Server](https://discord.gg/Ww9hbqr) +- [Stack Overflow](https://stackoverflow.com/questions/tagged/sentry)