Manual Setup
If you can't (or prefer not to) run the automatic setup, you can follow the instructions below to configure the Sentry SvelteKit SDK in your application. This guide is also useful to adjust the pre-set configuration if you used the installation wizard for automatic setup.
Installation
npm install --save @sentry/sveltekit
If you're updating your Sentry SDK to the latest version, check out our migration guide to learn more about breaking changes.
Client-side Setup
If you don't already have a client hooks file, create a new one in
src/hooks.client.(js|ts)
.At the top of your client hooks file, initialize the Sentry SDK as shown in the snippet below. See the Basic Options page to view other SDK configuration options.
hooks.client.js
import * as Sentry from "@sentry/sveltekit";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
// We recommend adjusting this value in production, or using tracesSampler
// for finer control
tracesSampleRate: 1.0,
// Optional: Initialize Session Replay:
integrations: [new Sentry.Replay()],
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
});
- Add the
handleErrorWithSentry
function to thehandleError
hook:
hooks.client.js
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();
Server-side Setup
If you don't already have a server hooks file, create a new one in
src/hooks.server.(js|ts)
.At the top of your server hooks file, initialize the Sentry SDK as shown in the snippet below. See the Basic Options page to view other SDK configuration options.
hooks.server.js
import * as Sentry from "@sentry/sveltekit";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
// We recommend adjusting this value in production, or using tracesSampler
// for finer control
tracesSampleRate: 1.0,
});
- Add the
handleErrorWithSentry
function to thehandleError
hook:
hooks.server.js
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();
- Add the Sentry request handler to the
handle
hook. If you're already using your own handler(s), use SvelteKit'ssequence
function to add the Sentry handler before your handler(s):
hooks.server.js
export const handle = Sentry.sentryHandle();
// Or use `sequence`:
// export const handle = sequence(Sentry.sentryHandle(), yourHandler());
Vite Setup
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:
vite.config.js
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";
export default {
plugins: [sentrySvelteKit(), sveltekit()],
// ... rest of your Vite config
};
The sentrySvelteKit()
function adds Vite plugins to your Vite config to:
- Automatically upload source maps to Sentry
- Automatically instrument
load
functions for performance monitoring
Configure Source Maps Upload
By default, sentrySvelteKit()
will add an instance of the 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.
However, you still need to specify your Sentry auth
You can set them as environment variables, for example in a .env
file:
SENTRY_ORG
your Sentry org slugSENTRY_PROJECT
your Sentry project slugSENTRY_AUTH_TOKEN
your Sentry auth token (can be obtained from the Organization Token Settings)SENTRY_URL
your Sentry instance URL. This is only required if you use your own Sentry instance (as opposed tohttps://sentry.io
).
Or, you can set them by passing a sourceMapsUploadOptions
object to sentrySvelteKit
, as seen in the example below. All available options are documented at the Sentry Vite plugin repo.
.env
SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE
vite.config.js
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";
export default {
plugins: [
sentrySvelteKit({
sourceMapsUploadOptions: {
org: "example-org",
project: "example-project",
authToken: process.env.SENTRY_AUTH_TOKEN,
url: "https://sentry.my-company.com",
cleanArtifacts: true,
rewrite: false,
},
}),
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.
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 or the wrong one is detected, you can override the adapter detection by passing the adapter
option to sentrySvelteKit
:
vite.config.js
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";
export default {
plugins: [
sentrySvelteKit({
adapter: "vercel",
}),
sveltekit(),
],
// ... rest of your Vite config
};
Disable Source Maps Upload
You can disable automatic source maps upload in your Vite config:
vite.config.js
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";
export default {
plugins: [
sentrySvelteKit({
autoUploadSourceMaps: false,
}),
sveltekit(),
],
// ... rest of your Vite config
};
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.
Configure Auto-Instrumentation
The SDK primarily uses SvelteKit's 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 when you add the sentrySvelteKit()
function call to your vite.config.(js|ts)
. However, you can customize the behavior, or disable it entirely. If you disable it you can still manually wrap specific load
functions with the withSentry
function.
The SDK will only auto-instrument load
functions in +page
or +layout
files that don't contain any Sentry code.
If you have custom Sentry code in these files, you'll have to manually add the Sentry 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:
vite.config.js
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
};
Disable Auto-instrumentation
If you set the autoInstrument
option to false
, the SDK won't auto-instrument any load
functions. You can still manually instrument specific load
functions.
vite.config.js
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 the SDK's load
function wrappers.
Universal load
Functions
Use the wrapLoadWithSentry
function to wrap universal load
functions declared in +page.(js|ts)
or +layout.(js|ts)
+(page|layout).js
import { wrapLoadWithSentry } from "@sentry/sveltekit";
export const load = wrapLoadWithSentry((event) => {
//... your load code
});
Server-only load
Functions
Or use the wrapServerLoadWithSentry
function to wrap server-only load
functions declared in +page.server.(js|ts)
or +layout.server.(js|ts)
+(page|layout).server.js
import { wrapServerLoadWithSentry } from "@sentry/sveltekit";
export const load = wrapServerLoadWithSentry((event) => {
//... your load code
});
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").
- Package:
- npm:@sentry/sveltekit
- Version:
- 7.73.0
- Repository:
- https://github.com/getsentry/sentry-javascript