From d4060a43c597a4e4dff607dfb4db9debb24e7a06 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 29 Mar 2023 16:56:54 +0200 Subject: [PATCH] doc(sveltekit): Update README --- packages/sveltekit/README.md | 79 ++++++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 30 deletions(-) diff --git a/packages/sveltekit/README.md b/packages/sveltekit/README.md index 48a53c1abaae..1efb93716ca1 100644 --- a/packages/sveltekit/README.md +++ b/packages/sveltekit/README.md @@ -19,7 +19,9 @@ TODO: No docs yet, comment back in once we have docs ## 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](https://github.com/getsentry/sentry-javascript/issues/new/choose). +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](https://github.com/getsentry/sentry-javascript/issues/new/choose). ## Compatibility @@ -27,7 +29,7 @@ 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, with added functionality related to SvelteKit. +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 @@ -55,7 +57,7 @@ Although the SDK is not yet stable, you're more than welcome to give it a try an Sentry.init({ dsn: '__DSN__', - + traceSampleRate: 1.0, // For instance, initialize Session Replay: replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, @@ -63,18 +65,8 @@ Although the SDK is not yet stable, you're more than welcome to give it a try an }); ``` -4. Add our `withSentryViteConfig` wrapper around your Vite config so that the Sentry SDK is added to your application in `vite.config.(js|ts)`: - ```javascript - import { sveltekit } from '@sveltejs/kit/vite'; - import { withSentryViteConfig } from '@sentry/sveltekit'; - - export default withSentryViteConfig({ - plugins: [sveltekit()], - // ... - }); - ``` -5. Create a `sentry.server.config.(js|ts)` file in the root directory of your SvelteKit project. +4. Create a `sentry.server.config.(js|ts)` file in the root directory of your SvelteKit project. In this file you can configure the server-side Sentry SDK, like the Sentry Node SDK: ```javascript @@ -82,45 +74,72 @@ Although the SDK is not yet stable, you're more than welcome to give it a try an Sentry.init({ dsn: '__DSN__', + traceSampleRate: 1.0, }); ``` -6. To catch errors in your `load` functions in `+page.(js|ts)`, wrap our `wrapLoadWithSentry` function: - +5. Add our `withSentryViteConfig` wrapper around your Vite config so that the Sentry SDK is added to your application in `vite.config.(js|ts)`: ```javascript - import { wrapLoadWithSentry } from '@sentry/sveltekit'; + import { sveltekit } from '@sveltejs/kit/vite'; + import { withSentryViteConfig } from '@sentry/sveltekit'; - export const load = wrapLoadWithSentry((event) => { - //... + export default withSentryViteConfig({ + plugins: [sveltekit()], + // ... }); ``` -7. In your `hooks.client.(js|ts)` or `hooks.server.(js|ts)`, you can wrap the `handleError` function as follows: +6. In your `hooks.client.(js|ts)` or `hooks.server.(js|ts)`, wrap the `handleError` functions as follows: ```javascript import { handleErrorWithSentry } from '@sentry/sveltekit'; - import type { HandleClientError } from '@sveltejs/kit'; const myErrorHandler = ((input) => { - console.log('This is the client error handler'); - console.log(input.error); - }) satisfies HandleClientError; + console.error('An error occurred on the client-side'); + return error; + }); export const handleError = handleErrorWithSentry(myErrorHandler); - // or alternatively, if you don't have a custom error handler: // export const handleError = handleErrorWithSentry(); ``` +7. To capture performance data on the server-side, add our handler to the `handle` hook in `hooks.server.ts`: + + ```javascript + 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); + ``` + +8. 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: + + ```javascript + import { wrapLoadWithSentry } from '@sentry/sveltekit'; + + export const load = wrapLoadWithSentry((event) => { + //... your load code + }); + ``` + +9. 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 + import { wrapServerLoadWithSentry } from '@sentry/sveltekit'; + + export const load = wrapServerLoadWithSentry((event) => { + //... your server load code + }); + ``` + ## Known Limitations This SDK is still under active development and several features are missing. Take a look at our [SvelteKit SDK Development Roadmap](https://github.com/getsentry/sentry-javascript/issues/6692) to follow the progress: -- **Performance monitoring** is not yet fully supported. - You can add the `BrowserTracing` integration but proper instrumentation for routes, page loads and navigations is still missing. - This will be addressed next, as we release the next alpha builds. - - **Source Maps** upload is not yet working correctly. We already investigated [some options](https://github.com/getsentry/sentry-javascript/discussions/5838#discussioncomment-4696985) but uploading source maps doesn't work automtatically out of the box yet. This will be addressed next, as we release the next alpha builds. @@ -129,5 +148,5 @@ Take a look at our [SvelteKit SDK Development Roadmap](https://github.com/getsen 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 and hooks. +- 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.