Skip to content

doc(sveltekit): Streamline Readme and remove outdated information #16824

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 7, 2025
Merged

doc(sveltekit): Streamline Readme and remove outdated information #16824

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
317 changes: 12 additions & 305 deletions packages/sveltekit/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Loading