You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<!-- Use this checklist to make sure your PR is ready for merge. You may
delete any sections you don't need. -->
## DESCRIBE YOUR PR
In this PR I have:
- reduced the source maps content in SvelteKit's manual quick start
guide and moved it to the Source Maps page
- moved content about CSP to the Troubleshooting page and added an
Expandable to the manual quick start guide
I will move the build options and API content in a new PR (or two) to
keep things focused.
Belongs to: #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)
## EXTRA RESOURCES
- [Sentry Docs contributor guide](https://docs.sentry.io/contributing/)
<Expandablepermalinktitle="Configure CSP for Client-side `fetch` Instrumentation">
99
+
100
+
If you're using a SvelteKit version older than `sveltejs/[email protected]`, the Sentry SDK injects an inline `<script>` tag into the HTML response of the server.
101
+
This script proxies all client-side `fetch` calls so that `fetch` calls inside your `load` functions are captured by the SDK.
102
+
However, if you configured CSP rules to block inline fetch scripts by default, this script will be [blocked by the browser](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_inline_script).
103
+
104
+
You have multiple options to solve this CSP issue:
105
+
106
+
#### Option 1: Upgrade SvelteKit
107
+
108
+
The easiest option is to update `@sveltejs/kit` to at least version `2.16.0` (or newer). The SDK will not inject the fetch proxy script as it's no longer necessary.
109
+
110
+
#### Option 2: Add Script Hash to CSP Policy
111
+
112
+
To enable the script, add an exception for the `sentryHandle` script by adding the hash of the script to your CSP script source rules.
113
+
114
+
If your CSP is defined in `svelte.config.js`, you can add the hash to the `csp.directives.script-src` array:
115
+
116
+
```javascript {filename:svelte.config.js} {5-7}
117
+
constconfig= {
118
+
kit: {
119
+
csp: {
120
+
directives: {
121
+
"script-src": ["sha256-y2WkUILyE4eycy7x+pC0z99aZjTZlWfVwgUAfNc1sY8="], // + rest of your values
122
+
},
123
+
},
124
+
},
125
+
};
126
+
```
127
+
128
+
For external CSP configurations, add the following hash to your `script-src` directive:
We will not change this script any time soon, so the hash will stay
136
+
consistent.
137
+
</Alert>
138
+
139
+
#### Option 3: Disable the `fetch` Proxy Script
140
+
141
+
If you don't want to inject the script responsible for instrumenting client-side `fetch` calls, you can disable injection by passing `injectFetchProxyScript: false` to `sentryHandle`:
Note that if you disable the `fetch` proxy script, the SDK will not be able to capture spans for `fetch` calls made by SvelteKit when your route has a server load function. This also means that potential spans created on the server for these `fetch` calls will not be connected to the client-side trace.
<Expandabletitle="Having CSP issues with `fetch` instrumentation on older SvelteKit versions?">
128
+
129
+
If you're using SvelteKit versions older than `2.16.0` and encounter Content Security Policy (CSP) errors related to Sentry's `fetch` instrumentation, you can find support in our [Troubleshooting guide](/platforms/javascript/guides/sveltekit/troubleshooting/#configure-csp-for-client-side-fetch-instrumentation).
130
+
131
+
</Expandable>
132
+
127
133
### Configure Vite
128
134
129
135
Add the `sentrySvelteKit` plugin **before**`sveltekit` in your `vite.config.(js|ts)` file to automatically upload source maps to Sentry and instrument `load` functions for tracing if it's configured.
By default, `sentrySvelteKit()` will add an instance of the [Sentry Vite Plugin](https://www.npmjs.com/package/@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.
145
-
146
-
However, you still need to specify your Sentry auth token as well as your org and project slugs. There are two ways to set them.
147
-
148
-
You can set them as environment variables, for example in a `.env` file:
149
-
150
-
-`SENTRY_ORG` your Sentry org slug
151
-
-`SENTRY_PROJECT` your Sentry project slug
152
-
-`SENTRY_AUTH_TOKEN` your Sentry auth token (can be obtained from the [Organization Token Settings](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/))
153
-
-`SENTRY_URL` your Sentry instance URL. This is only required if you use your own Sentry instance (as opposed to `https://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](https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2#options).
150
+
To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug in your `vite.config.(js|ts)` file:
// store your auth token in an environment variable
173
163
authToken:process.env.SENTRY_AUTH_TOKEN,
174
-
sourcemaps: {
175
-
assets: ["./build/*/**/*"],
176
-
ignore: ["**/build/client/**/*"],
177
-
filesToDeleteAfterUpload: ["./build/**/*.map"],
178
-
},
179
164
},
180
165
}),
181
166
sveltekit(),
@@ -184,31 +169,17 @@ export default {
184
169
};
185
170
```
186
171
187
-
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](../#compatibility).
188
-
189
-
#### Overriding SvelteKit Adapter detection
172
+
To keep your auth token secure, always store it in an environment variable instead of directly in your files:
190
173
191
-
By default, `sentrySvelteKit` will try to detect your SvelteKit adapter to configure source maps upload correctly.
192
-
If you're not using one of the [supported adapters](../#compatibility) or the wrong one is detected, you can override the adapter detection by passing the `adapter` option to `sentrySvelteKit`:
You can disable automatic source maps upload in your Vite config:
182
+
`sentrySvelteKit` tries to auto-detect your SvelteKit adapter to configure source maps upload correctly. If you're using an unsupported adapter or the wrong one is detected, set it using the `adapter` option:
212
183
213
184
```javascript {filename:vite.config.(js|ts)} {7}
214
185
import { sveltekit } from"@sveltejs/kit/vite";
@@ -217,17 +188,15 @@ import { sentrySvelteKit } from "@sentry/sveltekit";
217
188
exportdefault {
218
189
plugins: [
219
190
sentrySvelteKit({
220
-
autoUploadSourceMaps:false,
191
+
adapter:"vercel",
221
192
}),
222
193
sveltekit(),
223
194
],
224
195
// ... rest of your Vite config
225
196
};
226
197
```
227
198
228
-
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.
229
-
230
-
## Step 3: Optional Configuration
199
+
## Step 4: Optional Configuration
231
200
232
201
The points explain additional optional configuration or more in-depth customization of your Sentry SvelteKit SDK setup.
233
202
@@ -285,60 +254,6 @@ export default {
285
254
};
286
255
```
287
256
288
-
### Configure CSP for Client-side `fetch` Instrumentation
289
-
290
-
<Alert>
291
-
292
-
Only relevant for SvelteKit versions below `@sveltejs/[email protected]`
293
-
294
-
</Alert>
295
-
296
-
If you're using a SvelteKit version older than `sveltejs/[email protected]`, The Sentry SDK injects an inline `<script>` tag into the HTML response of the server.
297
-
This script proxies all client-side `fetch` calls, so that `fetch` calls inside your `load` functions are captured by the SDK.
298
-
However, if you configured CSP rules to block inline fetch scripts by default, this script will be [blocked by the browser](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_inline_script).
299
-
300
-
You have multiple options to solve this CSP issue:
301
-
302
-
#### Upgrade SvelteKit
303
-
304
-
The easiest option is to update `@sveltejs/kit` to at least version `2.16.0` (or newer). The SDK will not inject the fetch proxy script as it's no longer necessary.
305
-
306
-
#### Add Script Hash to CSP policy
307
-
308
-
To enable the script, add an exception for the `sentryHandle` script by adding the hash of the script to your CSP script source rules.
309
-
310
-
If your CSP is defined in `svelte.config.js`, you can add the hash to the `csp.directives.script-src` array:
311
-
312
-
```javascript {filename:svelte.config.js} {5-7}
313
-
constconfig= {
314
-
kit: {
315
-
csp: {
316
-
directives: {
317
-
"script-src": ["sha256-y2WkUILyE4eycy7x+pC0z99aZjTZlWfVwgUAfNc1sY8="], // + rest of your values
318
-
},
319
-
},
320
-
},
321
-
};
322
-
```
323
-
324
-
For external CSP configurations, add the following hash to your `script-src` directive:
We will not make changes to this script any time soon, so the hash will stay consistent.
331
-
332
-
#### Disable `fetch` Proxy Script
333
-
334
-
If you don't want to inject the script responsible for instrumenting client-side `fetch` calls, you can disable injection by passing `injectFetchProxyScript: false` to `sentryHandle`:
Note that if you disable the `fetch` proxy script, the SDK will not be able to capture spans for `fetch` calls made by SvelteKit when your route has a server load function. This also means that potential spans created on the server for these `fetch` calls will not be connected to the client-side trace.
341
-
342
257
### Manual Instrumentation
343
258
344
259
Instead or in addition to [Auto Instrumentation](#auto-instrumentation), you can manually instrument certain SvelteKit-specific features with the SDK:
`@sentry/sveltekit` will generate and upload source maps automatically, so that errors in Sentry will contain readable stack traces.
2
2
3
-
The SvelteKit SDK uses the [Sentry Vite Plugin](https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2) to upload source maps. See the [Manual Configuration](../manual-setup/#source-maps-upload) page and the Sentry [Vite documentation](https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2#configuration) for more details.
3
+
The SvelteKit SDK uses the Sentry Vite Plugin to upload source maps. See the [Sentry Vite Plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin#options) for all available options.
By default, the `sentrySvelteKit()` Vite plugin uploads 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.
4
+
5
+
However, you still need to specify your Sentry auth token as well as your org and project slugs.
6
+
There are two ways to set them:
7
+
8
+
**Option 1**
9
+
10
+
You can set all values as environment variables, for example, in a `.env` file:
11
+
12
+
<OrgAuthTokenNote />
13
+
14
+
```bash {filename: .env}
15
+
# DO NOT commit this file to your repo. The auth token is a secret.
16
+
SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
17
+
SENTRY_ORG=___ORG_SLUG___
18
+
SENTRY_PROJECT=___PROJECT_SLUG___
19
+
# SENTRY_URL is only necessary if you're using a self-hosted Sentry
20
+
# instance (as opposed to `https://sentry.io`)
21
+
SENTRY_URL="https://your-sentry-instance.com"
22
+
```
23
+
24
+
**Option 2**
25
+
26
+
You can also set your org and project slugs by passing a `sourceMapsUploadOptions` object to `sentrySvelteKit`, as seen in the example below. For a full list of available options, see the [Sentry Vite Plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin#options).
// If you're self-hosting Sentry, also add your instance URL:
40
+
// url: "https://your-self-hosted-sentry.com/",
41
+
},
42
+
}),
43
+
sveltekit(),
44
+
],
45
+
// ... rest of your Vite config
46
+
};
47
+
```
48
+
49
+
To keep your auth token secure, always store it in an environment variable instead of directly in your files:
50
+
51
+
<OrgAuthTokenNote />
52
+
53
+
```bash {filename:.env}
54
+
SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
55
+
```
56
+
57
+
### Override SvelteKit Adapter Detection
58
+
59
+
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 by passing the `adapter` option to `sentrySvelteKit`:
If you disable automatic source maps upload, you must explicitly set a `release` value in your `Sentry.init()` configuration. This is important for Sentry features like release health and correctly associating errors with specific deployments.
0 commit comments