Next.js docs for v8.0.0

[dorin-flooz]

Is there an existing issue for this?

• [X] I have checked for existing issues https://github.com/getsentry/sentry-javascript/issues
• [X] I have reviewed the documentation https://docs.sentry.io/
• [X] I am using the latest SDK release https://github.com/getsentry/sentry-javascript/releases

How do you use Sentry?

Sentry Saas (sentry.io)

Which SDK are you using?

@sentry/nextjs

SDK Version

8.0.0

Framework Version

React latest

Link to Sentry event

No response

SDK Setup

No response

Steps to Reproduce

After upgrading to @sentry/nextjs 8.0.0, we get the following message in our yarn next build log:

Creating an optimized production build ...
[@sentry/nextjs] It appears you've configured a `sentry.server.config.ts` file. Please ensure to put this file's content into the `register()` function of a Next.js instrumentation hook instead. To ensure correct functionality of the SDK, `Sentry.init` must be called inside `instrumentation.ts`. Learn more about setting up an instrumentation hook in Next.js: https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation. You can safely delete the `sentry.server.config.ts` file afterward.
[@sentry/nextjs] It appears you've configured a `sentry.edge.config.ts` file. Please ensure to put this file's content into the `register()` function of a Next.js instrumentation hook instead. To ensure correct functionality of the SDK, `Sentry.init` must be called inside `instrumentation.ts`. Learn more about setting up an instrumentation hook in Next.js: https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation. You can safely delete the `sentry.edge.config.ts` file afterward.
[@sentry/nextjs - Node.js] Info: Sending error and performance telemetry data to Sentry. To disable telemetry, set `options.telemetry` to `false`.

We tried following the documentation at https://docs.sentry.io/platforms/javascript/guides/nextjs to fix these issues, but it seems to be out of sync:

• No results for sentrySDKOptions
• No results for options.telemetry
• No results for telemetry
• Docs recommend using sentry.server.config.ts - https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/#integration-usage-in-nextjs

Expected Result

• up to date docs following the release
• version selector in the docs - without this it's impossible for users to follow version-specific documentation or to even determine if documentation is available for a specific version

Actual Result

...

[HazAT]

Hey, sorry about that - we are jumping on this as we speak.

in the meantime, to unblock you, can you create a file instrumentation.ts and do this:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./sentry.server.config');
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./sentry.edge.config');
  }
}

as outlined here https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/#create-initialization-config-files

[s1gr1d]

@dorin-flooz Thanks for pointing this out! I updated the docs so they are in line with v8.

I guess the warning won't go away if you import the files like in the snippet @HazAT suggested. You have to delete the server.config and edge.config files. The contents of the files need to be added to the register() function like this:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    Sentry.init({
      dsn: env.DSN
      tracesSampleRate: 1.0,
    });
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    Sentry.init({
      dsn: env.DSN
      tracesSampleRate: 1.0,
    });
  }
}

[dorin-flooz]

hey @HazAT / @s1gr1d, thanks for the quick reply! What about versioned docs - any plans to have that implemented? We have postponed the upgrade to 8.0.0 due to the issues above, but if I understand correctly you have now overwritten https://docs.sentry.io/platforms/javascript/guides/nextjs to match the v8.0.0 API - in this case how would we access the v7.00-specific documentation until we upgrade?

[HazAT]

@dorin-flooz we discussed this internally and probably going to work on them but since this is a bit of a larger project it will take a while but keep an eye out. Thanks for the feedback!

[kbsali]

the doc concerning "telemetry" is still missing, no? How to tackle To disable telemetry, setoptions.telemetrytofalse. ?

Thanks for the hints

[s1gr1d]

Hello @kbsali, do you mean this section: https://docs.sentry.io/platforms/javascript/guides/astro/sourcemaps/#disabeling-telemetry-data-collection

[kbsali]

@s1gr1d this is specific to Astro/vite apparently, we are running a nextjs project

[s1gr1d]

@kbsali I am not 100% sure if we are talking about the same thing. You are right, it is currently not directly documented when the Next.js docs talk about extending the configuration. However, Astro and Next.js both use the vite-plugin and provide the same build options (you can find them here for vite and here for webpack). Is this what you were searching for? We can elaborate on this in the docs.

[kbsali]

as far as I can tell

• @sentry/nextjs uses @sentry/webpack-plugin
• @sentry/astro uses @sentry/vite-plugin

I see options for webpack-plugin but i'm not sure how to apply it in the context of @sentry/nextjs

[s1gr1d]

Oh yes, Next.js is using webpack, but the options are the same. The options specifically for the webpack plugin are defined here. And the docs show you how to configure your build options (the link I posted in my previous comment).

I think, what you want to achieve is this in your next.config.ts:

export default withSentryConfig(nextConfig, {
  // your other options...
  telemetry: false
});

Is this helping you? If yes, we will add this to the docs.

[briantweed]

Adding the following to next.config.js solved my issue. Don't see this mentioned on the installation page but it is on the migrate from 7 to 8 docs

experimental: { instrumentationHook: true }

[s1gr1d]

Thanks @briantweed, this will be added to the "Manual Setup" docs as well: https://github.com/getsentry/sentry-docs/pull/11140