ref(nextjs): Remove sentry field in Next.js config as a means of configuration

Author: Luca Forstner

MIGRATION.md

@@ -132,6 +132,47 @@ Integrations that are now exported from `@sentry/node` and `@sentry/browser` (or
 - sessionTimingIntegration
 - dedupeIntegration (enabled by default, not pluggable)
 
+## Next.js SDK Changes
+
+### Removal of the `sentry` property in your Next.js options
+
+With version 8 of the Sentry Next.js SDK, the SDK will no longer support passing Next.js options with a `sentry`
+property to `withSentryConfig`. Please use the third argument of `withSentryConfig` to configure the SDK instead:
+
+```ts
+// OLD
+const nextConfig = {
+  // Your Next.js options...
+
+  sentry: {
+    // Your Sentry SDK options...
+  },
+};
+
+module.exports = withSentryConfig(nextConfig, {
+  // Your Sentry Webpack Plugin Options...
+});
+
+// NEW
+const nextConfig = {
+  // Your Next.js options...
+};
+
+module.exports = withSentryConfig(
+  nextConfig,
+  {
+    // Your Sentry Webpack Plugin Options...
+  },
+  {
+    // Your Sentry SDK options...
+  },
+);
+```
+
+The reason for this change is to have one consistent way of defining the SDK options. We hope that this change will
+reduce confusion when setting up the SDK, with the upside that the explicit option is properly typed and will therefore
+have code completion.
+
 # Deprecations in 7.x
 
 You can use the **Experimental** [@sentry/migr8](https://www.npmjs.com/package/@sentry/migr8) to automatically update

packages/nextjs/src/config/types.ts

@@ -4,29 +4,15 @@ import type { DefinePlugin, WebpackPluginInstance } from 'webpack';
 
 export type SentryWebpackPluginOptions = SentryCliPluginOptions;
 export type SentryWebpackPlugin = WebpackPluginInstance & { options: SentryWebpackPluginOptions };
+
 // Export this from here because importing something from Webpack (the library) in `webpack.ts` confuses the heck out of
 // madge, which we use for circular dependency checking. We've manually excluded this file from the check (which is
 // safe, since it only includes types), so we can import it here without causing madge to fail. See
 // https://github.com/pahen/madge/issues/306.
 export type { WebpackPluginInstance };
 
-/**
- * Overall Nextjs config
- */
-
-// The first argument to `withSentryConfig` (which is the user's next config) may contain a `sentry` key, which we'll
-// remove once we've captured it, in order to prevent nextjs from throwing warnings. Since it's only in there
-// temporarily, we don't include it in the main `NextConfigObject` or `NextConfigFunction` types.
-export type ExportedNextConfig = NextConfigObjectWithSentry | NextConfigFunctionWithSentry;
-
-export type NextConfigObjectWithSentry = NextConfigObject & {
-  sentry?: UserSentryOptions;
-};
-
-export type NextConfigFunctionWithSentry = (
-  phase: string,
-  defaults: { defaultConfig: NextConfigObject },
-) => NextConfigObjectWithSentry | PromiseLike<NextConfigObjectWithSentry>;
+// The first argument to `withSentryConfig` (which is the user's next config).
+export type ExportedNextConfig = NextConfigObject | NextConfigFunction;
 
 // Vendored from Next.js (this type is not complete - extend if necessary)
 type NextRewrite = {

packages/nextjs/src/config/withSentryConfig.ts

@@ -1,10 +1,9 @@
 import { isThenable } from '@sentry/utils';
 
 import type {
-  ExportedNextConfig,
+  ExportedNextConfig as NextConfig,
   NextConfigFunction,
   NextConfigObject,
-  NextConfigObjectWithSentry,
   SentryWebpackPluginOptions,
   UserSentryOptions,
 } from './types';
@@ -13,52 +12,51 @@ import { constructWebpackConfigFunction } from './webpack';
 let showedExportModeTunnelWarning = false;
 
 /**
- * Add Sentry options to the config to be exported from the user's `next.config.js` file.
+ * Modifies the passed in Next.js configuration
  *
- * @param exportedUserNextConfig The existing config to be exported prior to adding Sentry
- * @param userSentryWebpackPluginOptions Configuration for SentryWebpackPlugin
- * @param sentryOptions Optional additional options to add as alternative to `sentry` property of config
+ * @param nextConfig The existing config to be exported prior to adding Sentry
+ * @param sentryWebpackPluginOptions Configuration for SentryWebpackPlugin
+ * @param sentrySDKOptions Optional additional options to add as alternative to `sentry` property of config
  * @returns The modified config to be exported
  */
 export function withSentryConfig(
-  exportedUserNextConfig: ExportedNextConfig = {},
-  userSentryWebpackPluginOptions: Partial<SentryWebpackPluginOptions> = {},
-  sentryOptions?: UserSentryOptions,
+  nextConfig: NextConfig = {},
+  sentryWebpackPluginOptions: Partial<SentryWebpackPluginOptions> = {},
+  sentrySDKOptions: UserSentryOptions = {},
 ): NextConfigFunction | NextConfigObject {
-  if (typeof exportedUserNextConfig === 'function') {
+  if (typeof nextConfig === 'function') {
     return function (this: unknown, ...webpackConfigFunctionArgs: unknown[]): ReturnType<NextConfigFunction> {
-      const maybeUserNextConfigObject: NextConfigObjectWithSentry = exportedUserNextConfig.apply(
-        this,
-        webpackConfigFunctionArgs,
-      );
+      const maybePromiseNextConfig: ReturnType<typeof nextConfig> = nextConfig.apply(this, webpackConfigFunctionArgs);
 
-      if (isThenable(maybeUserNextConfigObject)) {
-        return maybeUserNextConfigObject.then(function (userNextConfigObject: NextConfigObjectWithSentry) {
-          const userSentryOptions = { ...userNextConfigObject.sentry, ...sentryOptions };
-          return getFinalConfigObject(userNextConfigObject, userSentryOptions, userSentryWebpackPluginOptions);
+      if (isThenable(maybePromiseNextConfig)) {
+        return maybePromiseNextConfig.then(promiseResultNextConfig => {
+          return getFinalConfigObject(promiseResultNextConfig, sentrySDKOptions, sentryWebpackPluginOptions);
         });
       }
 
-      // Reassign for naming-consistency sake.
-      const userNextConfigObject = maybeUserNextConfigObject;
-      const userSentryOptions = { ...userNextConfigObject.sentry, ...sentryOptions };
-      return getFinalConfigObject(userNextConfigObject, userSentryOptions, userSentryWebpackPluginOptions);
+      return getFinalConfigObject(maybePromiseNextConfig, sentrySDKOptions, sentryWebpackPluginOptions);
     };
   } else {
-    const userSentryOptions = { ...exportedUserNextConfig.sentry, ...sentryOptions };
-    return getFinalConfigObject(exportedUserNextConfig, userSentryOptions, userSentryWebpackPluginOptions);
+    return getFinalConfigObject(nextConfig, sentrySDKOptions, sentryWebpackPluginOptions);
   }
 }
 
 // Modify the materialized object form of the user's next config by deleting the `sentry` property and wrapping the
 // `webpack` property
 function getFinalConfigObject(
-  incomingUserNextConfigObject: NextConfigObjectWithSentry,
+  incomingUserNextConfigObject: NextConfigObject,
   userSentryOptions: UserSentryOptions,
   userSentryWebpackPluginOptions: Partial<SentryWebpackPluginOptions>,
 ): NextConfigObject {
-  // Next 12.2.3+ warns about non-canonical properties on `userNextConfig`.
-  delete incomingUserNextConfigObject.sentry;
+  if ('sentry' in incomingUserNextConfigObject) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[@sentry/nextjs] Setting a `sentry` property on the Next.js config is no longer supported. Please use the `sentrySDKOptions` argument of `withSentryConfig` instead.',
+    );
+
+    // Next 12.2.3+ warns about non-canonical properties on `userNextConfig`.
+    delete incomingUserNextConfigObject.sentry;
+  }
 
   if (userSentryOptions?.tunnelRoute) {
     if (incomingUserNextConfigObject.output === 'export') {