@sentry/sveltekit

Official Sentry SDK for SvelteKit

SDK Status

This SDK is currently in Alpha state and we're still experimenting with APIs and functionality. We therefore make no guarantees in terms of semver or breaking changes. If you want to try this SDK and come across a problem, please open a GitHub Issue.

Compatibility

Currently, the minimum supported version of SvelteKit is 1.0.0.

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.

Usage

Although the SDK is not yet stable, you're more than welcome to give it a try and provide us with early feedback.

Here's how to get started:

1. Prerequesits & Installation

1. Ensure you've set up the @sveltejs/adapter-node adapter

2. Install the Sentry SvelteKit SDK:

   # 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 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:

    // 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: [new Sentry.Replay()],
    });
   

3. Add our handleErrorWithSentry function to the handleError hook:

    // 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:

   // 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:

    // 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:

    // 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. Configuring load Functions

1. 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:

   // +page.(js|ts)
   import { wrapLoadWithSentry } from '@sentry/sveltekit';
   
   export const load = wrapLoadWithSentry((event) => {
     //... your load code
   });
   

2. 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:

   // +page.server.(js|ts)
   import { wrapServerLoadWithSentry } from '@sentry/sveltekit';
   
   export const load = wrapServerLoadWithSentry((event) => {
     //... your server load code
   });
   

5. Vite Setup

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:

    // 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 to your Vite config to automatically upload source maps to Sentry.

Uploading Source Maps

After completing the 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:

// 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. This might be useful if you're using adapters other than the Node adapter or have a more customized build setup.

// 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
};

Disabeling automatic source map upload

If you don't want to upload source maps automatically, you can disable it as follows:

// 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
};

Known Limitations

This SDK is still under active development and several features are missing. Take a look at our SvelteKit SDK Development Roadmap 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.