feat(sveltekit): Export unstable_sentryVitePluginOptions for full Vite plugin customization (#10930)

We decided to provide an escape hatch to the reduced (but therefore 
version-agnostic) Vite plugin option API in the SvelteKit version of the 
plugin (`sentrySvelteKit()`). By specifying options in `unstable_vitePluginOptions`, 
users can still set and override all options the Vite plugin can take. 
We explicitly warn that keys in `unstable_vitePluginOptions` do not 
follow semver and might be removed or changed at any time.

Author: Lms24

MIGRATION.md

@@ -254,6 +254,7 @@ We now support the following integrations out of the box:
 - [Browser SDK](./MIGRATION.md#browser-sdk-browser-react-vue-angular-ember-etc)
 - [Server-side SDKs (Node, Deno, Bun)](./MIGRATION.md#server-side-sdks-node-deno-bun-etc)
 - [Next.js SDK](./MIGRATION.md#nextjs-sdk)
+- [SvelteKit SDK](./MIGRATION.md#sveltekit-sdk)
 - [Astro SDK](./MIGRATION.md#astro-sdk)
 
 ### General
@@ -581,6 +582,78 @@ Sentry.init({
 });
 ```
 
+### SvelteKit SDK
+
+#### Breaking `sentrySvelteKit()` changes
+
+We upgraded the `@sentry/vite-plugin` which is a dependency of the SvelteKit SDK from version 0.x to 2.x. With this
+change, resolving uploaded source maps should work out of the box much more often than before
+([more information](https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/)).
+
+To allow future upgrades of the Vite plugin without breaking stable and public APIs in `sentrySvelteKit`, we modified
+the `sourceMapsUploadOptions` to remove the hard dependency on the API of the plugin. While you previously could specify
+all [version 0.x Vite plugin options](https://www.npmjs.com/package/@sentry/vite-plugin/v/0.6.1), we now reduced them to
+a subset of [2.x options](https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2#options). All of these options are
+optional just like before but here's an example of using the new options.
+
+```js
+// Before (v7):
+sentrySvelteKit({
+  sourceMapsUploadOptions: {
+    org: process.env.SENTRY_ORG,
+    project: process.env.SENTRY_PROJECT,
+    authToken: process.env.SENTRY_AUTH_TOKEN,
+    release: '1.0.1',
+    injectRelease: true,
+    include: ['./build/*/**/*'],
+    ignore: ['**/build/client/**/*']
+  },
+}),
+
+// After (v8):
+sentrySvelteKit({
+  sourceMapsUploadOptions: {
+    org: process.env.SENTRY_ORG,
+    project: process.env.SENTRY_PROJECT,
+    authToken: process.env.SENTRY_AUTH_TOKEN,
+    release: {
+	    name: '1.0.1',
+	    inject: true
+    },
+    sourcemaps: {
+	    assets: ['./build/*/**/*'],
+	    ignore: ['**/build/client/**/*'],
+	    filesToDeleteAfterUpload: ['./build/**/*.map']
+    },
+  },
+}),
+```
+
+In the future, we might add additional [options](https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2#options)
+from the Vite plugin but if you would like to specify some of them directly, you can do this by passing in an
+`unstable_sentryVitePluginOptions` object:
+
+```js
+sentrySvelteKit({
+  sourceMapsUploadOptions: {
+    // ...
+    release: {
+	    name: '1.0.1',
+    },
+    unstable_sentryVitePluginOptions: {
+      release: {
+        setCommits: {
+          auto: true
+        }
+      }
+    }
+  },
+}),
+```
+
+Important: we DO NOT guarantee stability of `unstable_sentryVitePluginOptions`. They can be removed or updated at any
+time, including breaking changes within the same major version of the SDK.
+
 ## 5. Behaviour Changes
 
 - [Updated behaviour of `tracePropagationTargets` in the browser](./MIGRATION.md#updated-behaviour-of-tracepropagationtargets-in-the-browser-http-tracing-headers--cors)

packages/sveltekit/src/vite/sentryVitePlugins.ts

@@ -1,5 +1,6 @@
 import type { Plugin } from 'vite';
 
+import type { SentryVitePluginOptions } from '@sentry/vite-plugin';
 import type { AutoInstrumentSelection } from './autoInstrument';
 import { makeAutoInstrumentationPlugin } from './autoInstrument';
 import type { SupportedSvelteKitAdapters } from './detectAdapter';
@@ -114,6 +115,21 @@ type SourceMapsUploadOptions = {
        */
       inject?: boolean;
     };
+
+    /**
+     * Options to further customize the Sentry Vite Plugin (@sentry/vite-plugin) behavior directly.
+     * Options specified in this object take precedence over the options specified in
+     * the `sourcemaps` and `release` objects.
+     *
+     * @see https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2#options which lists all available options.
+     *
+     * Warning: Options within this object are subject to change at any time.
+     * We DO NOT guarantee semantic versioning for these options, meaning breaking
+     * changes can occur at any time within a major SDK version.
+     *
+     * Furthermore, some options are untested with SvelteKit specifically. Use with caution.
+     */
+    unstable_sentryVitePluginOptions?: Partial<SentryVitePluginOptions>;
   };
 };
 
@@ -196,15 +212,35 @@ export async function sentrySvelteKit(options: SentrySvelteKitPluginOptions = {}
   }
 
   if (mergedOptions.autoUploadSourceMaps && process.env.NODE_ENV !== 'development') {
-    const sourceMapsUploadOptions = mergedOptions.sourceMapsUploadOptions;
+    const { unstable_sentryVitePluginOptions, ...sourceMapsUploadOptions } =
+      mergedOptions.sourceMapsUploadOptions || {};
 
-    const sentryVitePlugins = await makeCustomSentryVitePlugins({
+    const sentryVitePluginsOptions = {
       ...sourceMapsUploadOptions,
 
+      ...unstable_sentryVitePluginOptions,
+
       adapter: mergedOptions.adapter,
       // override the plugin's debug flag with the one from the top-level options
       debug: mergedOptions.debug,
-    });
+    };
+
+    if (sentryVitePluginsOptions.sourcemaps) {
+      sentryVitePluginsOptions.sourcemaps = {
+        ...sourceMapsUploadOptions?.sourcemaps,
+        ...unstable_sentryVitePluginOptions?.sourcemaps,
+      };
+    }
+
+    if (sentryVitePluginsOptions.release) {
+      sentryVitePluginsOptions.release = {
+        ...sourceMapsUploadOptions?.release,
+        ...unstable_sentryVitePluginOptions?.release,
+      };
+    }
+
+    const sentryVitePlugins = await makeCustomSentryVitePlugins(sentryVitePluginsOptions);
+
     sentryPlugins.push(...sentryVitePlugins);
   }
 

packages/sveltekit/test/vite/sentrySvelteKitPlugins.test.ts

@@ -113,6 +113,63 @@ describe('sentrySvelteKit()', () => {
     });
   });
 
+  it('passes user-specified vite plugin options to the custom sentry source maps plugin', async () => {
+    const makePluginSpy = vi.spyOn(sourceMaps, 'makeCustomSentryVitePlugins');
+    await getSentrySvelteKitPlugins({
+      debug: true,
+      sourceMapsUploadOptions: {
+        org: 'my-org',
+        sourcemaps: {
+          assets: ['nope/*.js'],
+          filesToDeleteAfterUpload: ['baz/*.js'],
+        },
+        release: {
+          inject: false,
+          name: '2.0.0',
+        },
+        unstable_sentryVitePluginOptions: {
+          org: 'other-org',
+          sourcemaps: {
+            assets: ['foo/*.js'],
+            ignore: ['bar/*.js'],
+          },
+          release: {
+            name: '3.0.0',
+            setCommits: {
+              auto: true,
+            },
+          },
+          headers: {
+            'X-My-Header': 'foo',
+          },
+        },
+      },
+      autoInstrument: false,
+      adapter: 'vercel',
+    });
+
+    expect(makePluginSpy).toHaveBeenCalledWith({
+      debug: true,
+      org: 'other-org',
+      sourcemaps: {
+        assets: ['foo/*.js'],
+        ignore: ['bar/*.js'],
+        filesToDeleteAfterUpload: ['baz/*.js'],
+      },
+      release: {
+        inject: false,
+        name: '3.0.0',
+        setCommits: {
+          auto: true,
+        },
+      },
+      headers: {
+        'X-My-Header': 'foo',
+      },
+      adapter: 'vercel',
+    });
+  });
+
   it('passes user-specified options to the auto instrument plugin', async () => {
     const makePluginSpy = vi.spyOn(autoInstrument, 'makeAutoInstrumentationPlugin');
     const plugins = await getSentrySvelteKitPlugins({