feat(nuxt): Align build-time options to follow bundler plugins structure (#17255)

Aligns the build-time options of the Nuxt SDK and implements the missing
options.

Closes #17064

Author: s1gr1d

packages/core/src/build-time-plugins/buildTimeOptionsBase.ts

@@ -84,6 +84,23 @@ export interface BuildTimeOptionsBase {
    */
   silent?: boolean;
 
+  /**
+   * When an error occurs during release creation or sourcemaps upload, the plugin will call this function.
+   *
+   * By default, the plugin will simply throw an error, thereby stopping the bundling process.
+   * If an `errorHandler` callback is provided, compilation will continue unless an error is
+   * thrown in the provided callback.
+   *
+   * To allow compilation to continue but still emit a warning, set this option to the following:
+   *
+   * ```js
+   * (err) => {
+   *   console.warn(err);
+   * }
+   * ```
+   */
+  errorHandler?: (err: Error) => void;
+
   /**
    * Enable debug information logs about the SDK during build-time.
    * Enabling this will give you, for example, logs about source maps.
@@ -184,7 +201,9 @@ export type UnstableRollupPluginOptions<PluginOptionsType> = {
 
 interface SourceMapsOptions {
   /**
-   * If this flag is `true`, any functionality related to source maps will be disabled.
+   * If this flag is `true`, any functionality related to source maps will be disabled. This includes the automatic upload of source maps.
+   *
+   * By default (`false`), the plugin automatically uploads source maps during a production build if a Sentry auth token is detected.
    *
    * @default false
    */

packages/nuxt/.eslintrc.js

@@ -7,7 +7,7 @@ module.exports = {
     {
       files: ['vite.config.ts'],
       parserOptions: {
-        project: ['tsconfig.test.json'],
+        project: ['tsconfig.vite.json'],
       },
     },
   ],

packages/nuxt/src/common/types.ts

@@ -1,3 +1,4 @@
+import type { BuildTimeOptionsBase } from '@sentry/core';
 import type { init as initNode } from '@sentry/node';
 import type { SentryRollupPluginOptions } from '@sentry/rollup-plugin';
 import type { SentryVitePluginOptions } from '@sentry/vite-plugin';
@@ -26,6 +27,7 @@ type SourceMapsOptions = {
    * Suppresses all logs.
    *
    * @default false
+   * @deprecated Use option `silent` instead of `sourceMapsUploadOptions.silent`
    */
   silent?: boolean;
 
@@ -43,13 +45,17 @@ type SourceMapsOptions = {
    *   console.warn(err);
    * }
    * ```
+   *
+   * @deprecated Use option `errorHandler` instead of `sourceMapsUploadOptions.errorHandler`
    */
   errorHandler?: (err: Error) => void;
 
   /**
    * Options related to managing the Sentry releases for a build.
    *
    * More info: https://docs.sentry.io/product/releases/
+   *
+   * @deprecated Use option `release` instead of `sourceMapsUploadOptions.release`
    */
   release?: {
     /**
@@ -62,6 +68,8 @@ type SourceMapsOptions = {
      * (the latter requires access to git CLI and for the root directory to be a valid repository)
      *
      * If you didn't provide a value and the plugin can't automatically detect one, no release will be created.
+     *
+     * @deprecated Use `release.name` instead of `sourceMapsUploadOptions.release.name`
      */
     name?: string;
   };
@@ -71,6 +79,7 @@ type SourceMapsOptions = {
    * automatically generate and upload source maps to Sentry during a production build.
    *
    * @default true
+   * @deprecated Use option `sourcemaps.disable` instead of `sourceMapsUploadOptions.enabled`
    */
   enabled?: boolean;
 
@@ -81,25 +90,30 @@ type SourceMapsOptions = {
    *
    * To create an auth token, follow this guide:
    * @see https://docs.sentry.io/product/accounts/auth-tokens/#organization-auth-tokens
+   * @deprecated Use option `authToken` instead of `sourceMapsUploadOptions.authToken`
    */
   authToken?: string;
 
   /**
    * The organization slug of your Sentry organization.
    * Instead of specifying this option, you can also set the `SENTRY_ORG` environment variable.
+   * @deprecated Use option `org` instead of `sourceMapsUploadOptions.org`
    */
   org?: string;
 
   /**
    * The URL of your Sentry instance if you're using self-hosted Sentry.
    *
    * @default https://sentry.io by default the plugin will point towards the Sentry SaaS URL
+   * @deprecated Use `sentryUrl` instead of `sourceMapsUploadOptions.url`
    */
   url?: string;
 
   /**
    * The project slug of your Sentry project.
    * Instead of specifying this option, you can also set the `SENTRY_PROJECT` environment variable.
+   *
+   * @deprecated Use option `project` instead of `sourceMapsUploadOptions.project`
    */
   project?: string;
 
@@ -108,11 +122,14 @@ type SourceMapsOptions = {
    * It will not collect any sensitive or user-specific data.
    *
    * @default true
+   * @deprecated Use option `telemetry` instead of `sourceMapsUploadOptions.telemetry`
    */
   telemetry?: boolean;
 
   /**
    * Options related to sourcemaps
+   *
+   * @deprecated Use option `sourcemaps` instead of `sourceMapsUploadOptions.sourcemaps`
    */
   sourcemaps?: {
     /**
@@ -124,6 +141,8 @@ type SourceMapsOptions = {
      *
      * The globbing patterns must follow the implementation of the `glob` package.
      * @see https://www.npmjs.com/package/glob#glob-primer
+     *
+     * @deprecated Use option `sourcemaps.assets` instead of `sourceMapsUploadOptions.sourcemaps.assets`
      */
     assets?: string | Array<string>;
 
@@ -134,6 +153,8 @@ type SourceMapsOptions = {
      * or the default value for `assets` are uploaded.
      *
      * The globbing patterns follow the implementation of the glob package. (https://www.npmjs.com/package/glob)
+     *
+     * @deprecated Use option `sourcemaps.ignore` instead of `sourceMapsUploadOptions.sourcemaps.ignore`
      */
     ignore?: string | Array<string>;
 
@@ -144,6 +165,8 @@ type SourceMapsOptions = {
      * @default [] - By default no files are deleted.
      *
      * The globbing patterns follow the implementation of the glob package. (https://www.npmjs.com/package/glob)
+     *
+     * @deprecated Use option `sourcemaps.filesToDeleteAfterUpload` instead of `sourceMapsUploadOptions.sourcemaps.filesToDeleteAfterUpload`
      */
     filesToDeleteAfterUpload?: string | Array<string>;
   };
@@ -152,7 +175,7 @@ type SourceMapsOptions = {
 /**
  *  Build options for the Sentry module. These options are used during build-time by the Sentry SDK.
  */
-export type SentryNuxtModuleOptions = {
+export type SentryNuxtModuleOptions = BuildTimeOptionsBase & {
   /**
    * Enable the Sentry Nuxt Module.
    *
@@ -165,15 +188,12 @@ export type SentryNuxtModuleOptions = {
    *
    * These options are always read from the `sentry` module options in the `nuxt.config.(js|ts).
    * Do not define them in the `sentry.client.config.(js|ts)` or `sentry.server.config.(js|ts)` files.
+   *
+   * @deprecated  This option was deprecated as it adds unnecessary nesting.
+   *              Put the options one level higher to the root-level of the `sentry` module options.
    */
   sourceMapsUploadOptions?: SourceMapsOptions;
 
-  /**
-   * Enable debug functionality of the SDK during build-time.
-   * Enabling this will give you, for example, logs about source maps.
-   */
-  debug?: boolean;
-
   /**
    *
    * Enables (partial) server tracing by automatically injecting Sentry for environments where modifying the node option `--import` is not possible.

packages/nuxt/src/vite/sourceMaps.ts

@@ -17,10 +17,20 @@ export type SourceMapSetting = boolean | 'hidden' | 'inline';
  *  Setup source maps for Sentry inside the Nuxt module during build time (in Vite for Nuxt and Rollup for Nitro).
  */
 export function setupSourceMaps(moduleOptions: SentryNuxtModuleOptions, nuxt: Nuxt): void {
+  // TODO(v11): remove deprecated options (also from SentryNuxtModuleOptions type)
+
   const isDebug = moduleOptions.debug;
 
+  // eslint-disable-next-line deprecation/deprecation
   const sourceMapsUploadOptions = moduleOptions.sourceMapsUploadOptions || {};
-  const sourceMapsEnabled = sourceMapsUploadOptions.enabled ?? true;
+
+  const sourceMapsEnabled =
+    moduleOptions.sourcemaps?.disable === true
+      ? false
+      : moduleOptions.sourcemaps?.disable === false
+        ? true
+        : // eslint-disable-next-line deprecation/deprecation
+          sourceMapsUploadOptions.enabled ?? true;
 
   // In case we overwrite the source map settings, we default to deleting the files
   let shouldDeleteFilesFallback = { client: true, server: true };
@@ -42,6 +52,8 @@ export function setupSourceMaps(moduleOptions: SentryNuxtModuleOptions, nuxt: Nu
 
       if (
         isDebug &&
+        !moduleOptions.sourcemaps?.filesToDeleteAfterUpload &&
+        // eslint-disable-next-line deprecation/deprecation
         !sourceMapsUploadOptions.sourcemaps?.filesToDeleteAfterUpload &&
         (shouldDeleteFilesFallback.client || shouldDeleteFilesFallback.server)
       ) {
@@ -134,10 +146,13 @@ function normalizePath(path: string): string {
  *
  *  Only exported for Testing purposes.
  */
+// todo(v11): This "eslint-disable" can be removed again once we remove deprecated options.
+// eslint-disable-next-line complexity
 export function getPluginOptions(
   moduleOptions: SentryNuxtModuleOptions,
   shouldDeleteFilesFallback?: { client: boolean; server: boolean },
 ): SentryVitePluginOptions | SentryRollupPluginOptions {
+  // eslint-disable-next-line deprecation/deprecation
   const sourceMapsUploadOptions = moduleOptions.sourceMapsUploadOptions || {};
 
   const shouldDeleteFilesAfterUpload = shouldDeleteFilesFallback?.client || shouldDeleteFilesFallback?.server;
@@ -148,10 +163,17 @@ export function getPluginOptions(
       : []),
   ];
 
-  if (
-    typeof sourceMapsUploadOptions.sourcemaps?.filesToDeleteAfterUpload === 'undefined' &&
-    shouldDeleteFilesAfterUpload
-  ) {
+  // Check for filesToDeleteAfterUpload in new location first, then deprecated location
+  const sourcemapsOptions = moduleOptions.sourcemaps || {};
+  // eslint-disable-next-line deprecation/deprecation
+  const deprecatedSourcemapsOptions = sourceMapsUploadOptions.sourcemaps || {};
+
+  const filesToDeleteAfterUpload =
+    sourcemapsOptions.filesToDeleteAfterUpload ??
+    // eslint-disable-next-line deprecation/deprecation
+    deprecatedSourcemapsOptions.filesToDeleteAfterUpload;
+
+  if (typeof filesToDeleteAfterUpload === 'undefined' && shouldDeleteFilesAfterUpload) {
     consoleSandbox(() => {
       // eslint-disable-next-line no-console
       console.log(
@@ -164,16 +186,28 @@ export function getPluginOptions(
   }
 
   return {
-    org: sourceMapsUploadOptions.org ?? process.env.SENTRY_ORG,
-    project: sourceMapsUploadOptions.project ?? process.env.SENTRY_PROJECT,
-    authToken: sourceMapsUploadOptions.authToken ?? process.env.SENTRY_AUTH_TOKEN,
-    telemetry: sourceMapsUploadOptions.telemetry ?? true,
-    url: sourceMapsUploadOptions.url ?? process.env.SENTRY_URL,
+    // eslint-disable-next-line deprecation/deprecation
+    org: moduleOptions.org ?? sourceMapsUploadOptions.org ?? process.env.SENTRY_ORG,
+    // eslint-disable-next-line deprecation/deprecation
+    project: moduleOptions.project ?? sourceMapsUploadOptions.project ?? process.env.SENTRY_PROJECT,
+    // eslint-disable-next-line deprecation/deprecation
+    authToken: moduleOptions.authToken ?? sourceMapsUploadOptions.authToken ?? process.env.SENTRY_AUTH_TOKEN,
+    // eslint-disable-next-line deprecation/deprecation
+    telemetry: moduleOptions.telemetry ?? sourceMapsUploadOptions.telemetry ?? true,
+    // eslint-disable-next-line deprecation/deprecation
+    url: moduleOptions.sentryUrl ?? sourceMapsUploadOptions.url ?? process.env.SENTRY_URL,
+    headers: moduleOptions.headers,
     debug: moduleOptions.debug ?? false,
-    silent: sourceMapsUploadOptions.silent ?? false,
-    errorHandler: sourceMapsUploadOptions.errorHandler,
+    // eslint-disable-next-line deprecation/deprecation
+    silent: moduleOptions.silent ?? sourceMapsUploadOptions.silent ?? false,
+    // eslint-disable-next-line deprecation/deprecation
+    errorHandler: moduleOptions.errorHandler ?? sourceMapsUploadOptions.errorHandler,
+    bundleSizeOptimizations: moduleOptions.bundleSizeOptimizations, // todo: test if this can be overridden by the user
     release: {
-      name: sourceMapsUploadOptions.release?.name,
+      // eslint-disable-next-line deprecation/deprecation
+      name: moduleOptions.release?.name ?? sourceMapsUploadOptions.release?.name,
+      // Support all release options from BuildTimeOptionsBase
+      ...moduleOptions.release,
       ...moduleOptions?.unstable_sentryBundlerPluginOptions?.release,
     },
     _metaOptions: {
@@ -184,13 +218,16 @@ export function getPluginOptions(
     ...moduleOptions?.unstable_sentryBundlerPluginOptions,
 
     sourcemaps: {
+      disable: moduleOptions.sourcemaps?.disable,
       // The server/client files are in different places depending on the nitro preset (e.g. '.output/server' or '.netlify/functions-internal/server')
       // We cannot determine automatically how the build folder looks like (depends on the preset), so we have to accept that source maps are uploaded multiple times (with the vitePlugin for Nuxt and the rollupPlugin for Nitro).
       // If we could know where the server/client assets are located, we could do something like this (based on the Nitro preset): isNitro ? ['./.output/server/**/*'] : ['./.output/public/**/*'],
-      assets: sourceMapsUploadOptions.sourcemaps?.assets ?? undefined,
-      ignore: sourceMapsUploadOptions.sourcemaps?.ignore ?? undefined,
-      filesToDeleteAfterUpload: sourceMapsUploadOptions.sourcemaps?.filesToDeleteAfterUpload
-        ? sourceMapsUploadOptions.sourcemaps?.filesToDeleteAfterUpload
+      // eslint-disable-next-line deprecation/deprecation
+      assets: sourcemapsOptions.assets ?? deprecatedSourcemapsOptions.assets ?? undefined,
+      // eslint-disable-next-line deprecation/deprecation
+      ignore: sourcemapsOptions.ignore ?? deprecatedSourcemapsOptions.ignore ?? undefined,
+      filesToDeleteAfterUpload: filesToDeleteAfterUpload
+        ? filesToDeleteAfterUpload
         : shouldDeleteFilesFallback?.server || shouldDeleteFilesFallback?.client
           ? fallbackFilesToDelete
           : undefined,