Skip to content

Commit aa77c6e

Browse files
inventarSarahcoolguyzone
inventarSarah
and
coolguyzone
authored
docs(js): Update SvelteKit APIs and Build Options pages (#13997)
<!-- Use this checklist to make sure your PR is ready for merge. You may delete any sections you don't need. --> ## DESCRIBE YOUR PR Moved content from SvelteKit's Manual Quick Start guide to the APIs and Build Options pages. Note: Now that we have started to populate the Build Options page with content, we need to make sure the documentation is complete and add all build options to the page. I'll create an issue closes: #13634 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE <!-- Sentry employees and contractors can delete or ignore this section. --> Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) --------- Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>
1 parent 9339aa1 commit aa77c6e

File tree

5 files changed

+212
-125
lines changed

5 files changed

+212
-125
lines changed

‎docs/platforms/javascript/common/apis.mdx

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1089,6 +1089,79 @@ Wraps a callback with a cron monitor check in. The check in will be sent to Sent
10891089
</SdkApi>
10901090
</PlatformCategorySection>
10911091

1092+
<PlatformSection supported={["javascript.sveltekit"]}>
1093+
## Instrumenting Load Functions
1094+
1095+
SvelteKit's universal and server `load` functions are instrumented automatically by default. If you don't want to use `load` auto-instrumentation, you can [disable it](/platforms/javascript/guides/sveltekit/configuration/build/#auto-instrumentation-options) and manually instrument specific `load` functions using the following function wrappers:
1096+
1097+
<SdkApi
1098+
name="wrapLoadWithSentry"
1099+
signature={`function wrapLoadWithSentry<T extends (...args: any) => any>(
1100+
originalLoad: T
1101+
): T`}
1102+
>
1103+
Wraps a SvelteKit `load` function declared in `+page.(js|ts)` or `+layout.(js|ts)` with Sentry error and performance monitoring.
1104+
1105+
<Expandable title="Examples">
1106+
```javascript
1107+
import { wrapLoadWithSentry } from "@sentry/sveltekit";
1108+
1109+
export const load = wrapLoadWithSentry(({ fetch }) => {
1110+
const res = await fetch("/api/data");
1111+
const data = await res.json();
1112+
return { data };
1113+
});
1114+
```
1115+
1116+
</Expandable>
1117+
</SdkApi>
1118+
1119+
<SdkApi
1120+
name="wrapServerLoadWithSentry"
1121+
signature={`function wrapServerLoadWithSentry<T extends (...args: any) => any>(
1122+
originalServerLoad: T
1123+
): T`}
1124+
>
1125+
Wraps a SvelteKit server-only `load` function declared in`+page.server.(js|ts)` or `+layout.server.(js|ts)` with Sentry error and performance monitoring.
1126+
1127+
<Expandable title="Examples">
1128+
```javascript
1129+
import { wrapServerLoadWithSentry } from "@sentry/sveltekit";
1130+
1131+
export const load = wrapServerLoadWithSentry(({ fetch }) => {
1132+
const res = await fetch("/api/data");
1133+
const data = await res.json();
1134+
return { data };
1135+
});
1136+
```
1137+
</Expandable>
1138+
1139+
</SdkApi>
1140+
1141+
## Instrumenting Server Routes
1142+
1143+
<SdkApi
1144+
name="wrapServerRouteWithSentry"
1145+
signature={`function wrapServerRouteWithSentry<T extends RequestEvent>(
1146+
originalRouteHandler: (request: T) => Promise<Response>
1147+
): (requestEvent: T) => Promise<Response>`}
1148+
>
1149+
Wraps a SvelteKit [server route handler](https://kit.svelte.dev/docs/routing#server) registered in `+server.(js|ts)` with Sentry error and performance monitoring. This is useful if you have custom server routes that you want to trace or if you want to capture `error()` calls within your server routes.
1150+
1151+
<Expandable title="Examples">
1152+
```javascript
1153+
import { wrapServerRouteWithSentry } from "@sentry/sveltekit";
1154+
1155+
export const GET = wrapServerRouteWithSentry(async () => {
1156+
// your endpoint logic
1157+
return new Response("Hello World");
1158+
});
1159+
```
1160+
</Expandable>
1161+
</SdkApi>
1162+
1163+
</PlatformSection>
1164+
10921165
<PlatformSection supported={["javascript.nextjs"]}>
10931166
## Server Actions
10941167

‎docs/platforms/javascript/guides/sveltekit/configuration/build/index.mdx

Lines changed: 125 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,128 @@ keywords:
1818

1919
The Sentry SvelteKit SDK supports automatic code instrumentation and source map upload during your app's build process using the `sentrySvelteKit` Vite plugins in your `vite.config.(js|ts)` file.
2020

21-
For more information on the available configuration options, see [Vite Setup](../../manual-setup/#vite-setup) and the sections on configuring source maps upload and auto instrumentation.
21+
## Available Options
22+
23+
<TableOfContents ignoreIds={["available-options"]} />
24+
25+
## Source Maps Options
26+
27+
<SdkOption name="sourceMapsUploadOptions.org" type="string" envVar="SENTRY_ORG">
28+
29+
The slug of the Sentry organization associated with the app.
30+
31+
</SdkOption>
32+
33+
<SdkOption name="sourceMapsUploadOptions.project" type="string" envVar="SENTRY_PROJECT">
34+
35+
The slug of the Sentry project associated with the app.
36+
37+
</SdkOption>
38+
39+
<SdkOption name="sourceMapsUploadOptions.authToken" type="string" envVar="SENTRY_AUTH_TOKEN">
40+
41+
The authentication token to use for all communication with Sentry. Can be obtained from https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/.
42+
43+
</SdkOption>
44+
45+
<SdkOption name="sourceMapsUploadOptions.url" type="string" envVar="SENTRY_URL" defaultValue="https://sentry.io/">
46+
47+
The base URL of your Sentry instance. Only relevant if you're using a self-hosted or Sentry instance other than sentry.io.
48+
49+
</SdkOption>
50+
51+
<SdkOption name="adapter" type="string">
52+
53+
By default, `sentrySvelteKit` will try to detect your SvelteKit adapter to configure the source maps upload correctly. If you're not using one of the [supported adapters](/platforms/javascript/guides/sveltekit/) or the wrong one is detected, you can override the adapter detection using the `adapter` option.
54+
55+
</SdkOption>
56+
57+
<SdkOption name="autoUploadSourceMaps" type="boolean">
58+
59+
Disable automatic source maps upload by setting `autoUploadSourceMaps` to `false`.
60+
61+
</SdkOption>
62+
63+
## Auto-Instrumentation Options
64+
65+
The SDK primarily uses [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 manually add a Sentry wrapper to each function.
66+
67+
Auto-instrumentation is enabled by default when you add the `sentrySvelteKit()` function call to your `vite.config.(js|ts)`.
68+
However, you can customize the behavior or disable it entirely.
69+
70+
<Alert>
71+
The SDK will only auto-instrument `load` functions in `+page` or `+layout`
72+
files that don't contain any Sentry-related code. If you have custom Sentry
73+
code in these files, you'll have to [manually add a Sentry
74+
wrapper](/platforms/javascript/guides/sveltekit/apis/#load-function-instrumentation)
75+
to your `load` functions.
76+
</Alert>
77+
78+
<SdkOption name="autoInstrument" type="boolean | object" defaultValue="true">
79+
80+
Set `autoInstrument` to `false` to disable auto-instrumentation of any `load` functions. You can still [manually instrument](/platforms/javascript/guides/sveltekit/apis/#load-function-instrumentation) specific `load` functions.
81+
82+
```javascript {filename:vite.config.(js|ts)} {7}
83+
import { sveltekit } from '@sveltejs/kit/vite';
84+
import { sentrySvelteKit } from '@sentry/sveltekit';
85+
86+
export default {
87+
plugins: [
88+
sentrySvelteKit({
89+
autoInstrument: false;
90+
}),
91+
sveltekit(),
92+
],
93+
// ... rest of your Vite config
94+
};
95+
```
96+
97+
Alternatively, you can provide `autoInstrument` with an object to customize which `load` functions should be instrumented.
98+
99+
</SdkOption>
100+
101+
<SdkOption name="autoInstrument.load" type="boolean" defaultValue="true">
102+
103+
Set to `false` to disable auto-instrumentation of `load` functions inside `+page.(js|ts)` or `+layout.(js|ts)`.
104+
105+
```javascript {filename:vite.config.(js|ts)} {7-10}
106+
import { sveltekit } from "@sveltejs/kit/vite";
107+
import { sentrySvelteKit } from "@sentry/sveltekit";
108+
109+
export default {
110+
plugins: [
111+
sentrySvelteKit({
112+
autoInstrument: {
113+
load: false,
114+
},
115+
}),
116+
sveltekit(),
117+
],
118+
// ... rest of your Vite config
119+
};
120+
```
121+
122+
</SdkOption>
123+
124+
<SdkOption name="autoInstrument.serverLoad" type="boolean" defaultValue="true">
125+
126+
Set to `false` to disable auto-instrumentation of server-only `load` functions inside `+page.server.(js|ts)` or `+layout.server.(js|ts)`.
127+
128+
```javascript {filename:vite.config.(js|ts)} {7-10}
129+
import { sveltekit } from "@sveltejs/kit/vite";
130+
import { sentrySvelteKit } from "@sentry/sveltekit";
131+
132+
export default {
133+
plugins: [
134+
sentrySvelteKit({
135+
autoInstrument: {
136+
serverLoad: false,
137+
},
138+
}),
139+
sveltekit(),
140+
],
141+
// ... rest of your Vite config
142+
};
143+
```
144+
145+
</SdkOption>

‎docs/platforms/javascript/guides/sveltekit/index.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@ Our next recommended steps for you are:
7272

7373
- Learn how to [manually capture errors](/platforms/javascript/guides/sveltekit/usage/)
7474
- Continue to [customize your configuration](/platforms/javascript/guides/sveltekit/configuration/)
75+
- Learn how to [manually instrument](/platforms/javascript/guides/sveltekit/apis#load-function-instrumentation) SvelteKit-specific features
76+
- Learn more about [deploying SvelteKit apps to Cloudflare Pages](/platforms/javascript/guides/cloudflare/frameworks/sveltekit/)
7577
- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts
7678

7779
<Expandable permalink={false} title="Are you having problems setting up the SDK?">

‎docs/platforms/javascript/guides/sveltekit/manual-setup.mdx

Lines changed: 11 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,13 @@ description: "Learn how to manually set up Sentry in your SvelteKit app and capt
1616
Choose the features you want to configure, and this guide will show you how:
1717

1818
<OnboardingOptionButtons
19-
options={["error-monitoring", "performance", "session-replay", "user-feedback", "logs"]}
19+
options={[
20+
"error-monitoring",
21+
"performance",
22+
"session-replay",
23+
"user-feedback",
24+
"logs",
25+
]}
2026
/>
2127

2228
<PlatformContent includePath="getting-started-features-expandable" />
@@ -216,131 +222,11 @@ export default {
216222
};
217223
```
218224

219-
## Step 4: Optional Configuration
220-
221-
The points explain additional optional configuration or more in-depth customization of your Sentry SvelteKit SDK setup.
222-
223-
### Auto-Instrumentation
224-
225-
The SDK primarily uses [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.
226-
227-
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.
228-
229-
<Alert>
230-
231-
The SDK will only auto-instrument `load` functions in `+page` or `+layout` files that don't contain any Sentry code.
232-
If you have custom Sentry code in these files, you'll have to [manually](#instrument-load-functions-manually) add the Sentry wrapper to your `load` functions.
233-
234-
</Alert>
235-
236-
#### Customize Auto-instrumentation
237-
238-
By passing the `autoInstrument` option to `sentrySvelteKit` you can disable auto-instrumentation entirely, or customize which `load` functions should be instrumented:
239-
240-
```javascript {filename:vite.config.(js|ts)} {7-10}
241-
import { sveltekit } from "@sveltejs/kit/vite";
242-
import { sentrySvelteKit } from "@sentry/sveltekit";
243-
244-
export default {
245-
plugins: [
246-
sentrySvelteKit({
247-
autoInstrument: {
248-
load: true,
249-
serverLoad: false,
250-
},
251-
}),
252-
sveltekit(),
253-
],
254-
// ... rest of your Vite config
255-
};
256-
```
257-
258-
#### Disable Auto-instrumentation
259-
260-
If you set the `autoInstrument` option to `false`, the SDK won't auto-instrument any `load` functions. You can still [manually instrument](#instrument-load-functions-manually) specific `load` functions.
261-
262-
```javascript {filename:vite.config.(js|ts)} {7}
263-
import { sveltekit } from '@sveltejs/kit/vite';
264-
import { sentrySvelteKit } from '@sentry/sveltekit';
265-
266-
export default {
267-
plugins: [
268-
sentrySvelteKit({
269-
autoInstrument: false;
270-
}),
271-
sveltekit(),
272-
],
273-
// ... rest of your Vite config
274-
};
275-
```
276-
277-
### Manual Instrumentation
278-
279-
Instead or in addition to [Auto Instrumentation](#auto-instrumentation), you can manually instrument certain SvelteKit-specific features with the SDK:
280-
281-
#### Instrument `load` Functions
282-
283-
SvelteKit's universal and server `load` functions are instrumented automatically by default.
284-
If you don't want to use `load` auto-instrumentation, you can [disable it](#disable-auto-instrumentation), and manually instrument specific `load` functions with the SDK's `load` function wrappers.
285-
286-
##### Universal `load` Functions
287-
288-
Use the `wrapLoadWithSentry` function to wrap universal `load` functions declared in `+page.(js|ts)` or `+layout.(js|ts)`
289-
290-
```javascript {filename:+(page|layout).(js|ts)} {1,3}
291-
import { wrapLoadWithSentry } from "@sentry/sveltekit";
292-
293-
export const load = wrapLoadWithSentry(({ fetch }) => {
294-
const res = await fetch("/api/data");
295-
const data = await res.json();
296-
return { data };
297-
});
298-
```
299-
300-
##### Server-only `load` Functions
301-
302-
Or use the `wrapServerLoadWithSentry` function to wrap server-only `load` functions declared in `+page.server.(js|ts)` or `+layout.server.(js|ts)`
303-
304-
```javascript {filename:+(page|layout).server.(js|ts)} {1,3}
305-
import { wrapServerLoadWithSentry } from "@sentry/sveltekit";
306-
307-
export const load = wrapServerLoadWithSentry(({ fetch }) => {
308-
const res = await fetch("/api/data");
309-
const data = await res.json();
310-
return { data };
311-
});
312-
```
313-
314-
#### Instrument Server Routes
315-
316-
<Alert>
317-
318-
Available since `8.25.0`
319-
320-
</Alert>
321-
322-
You can also manually instrument [server (API) routes ](https://kit.svelte.dev/docs/routing#server) with the SDK.
323-
This is useful if you have custom server routes that you want to trace or if you want to capture `error()` calls within your server routes:
324-
325-
```javascript {filename:+server.(js|ts)} {1,3}
326-
import { wrapServerRouteWithSentry } from "@sentry/sveltekit";
327-
328-
export const GET = wrapServerRouteWithSentry(async () => {
329-
// your endpoint logic
330-
return new Response("Hello World");
331-
});
332-
```
333-
334-
## Step 5: Cloudflare Pages Configuration (Optional)
335-
336-
If you're deploying your application to Cloudflare Pages, you need to adjust your server-side setup.
337-
Follow this guide to [configure Sentry for Cloudflare](/platforms/javascript/guides/cloudflare/frameworks/sveltekit/).
338-
339-
## Step 6: Avoid Ad Blockers With Tunneling (Optional)
225+
## Step 4: Avoid Ad Blockers With Tunneling (Optional)
340226

341227
<PlatformContent includePath="getting-started-tunneling" />
342228

343-
## Step 7: Verify Your Setup
229+
## Step 5: Verify Your Setup
344230

345231
Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
346232

@@ -424,6 +310,8 @@ Our next recommended steps for you are:
424310

425311
- Learn how to [manually capture errors](/platforms/javascript/guides/sveltekit/usage/)
426312
- Continue to [customize your configuration](/platforms/javascript/guides/sveltekit/configuration/)
313+
- Learn how to [manually instrument](/platforms/javascript/guides/sveltekit/apis#load-function-instrumentation) SvelteKit-specific features
314+
- Learn more about [deploying SvelteKit apps to Cloudflare Pages](/platforms/javascript/guides/cloudflare/frameworks/sveltekit/)
427315
- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts
428316

429317
<Expandable permalink={false} title="Are you having problems setting up the SDK?">

‎src/components/sdkOption.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ export function SdkOption({
4040
<OptionDefRow label="Default" value={defaultValue} note={defaultNote} />
4141
)}
4242
<PlatformCategorySection supported={['server', 'serverless']}>
43-
<PlatformSection notSupported={['javascript.nextjs']}>
43+
<PlatformSection notSupported={['javascript.nextjs', 'javascript.sveltekit']}>
4444
{envVar && <OptionDefRow label="ENV Variable" value={envVar} />}
4545
</PlatformSection>
4646
</PlatformCategorySection>

0 commit comments

Comments
 (0)