Next.js docs for v8.0.0

[dorin-flooz]

Is there an existing issue for this?

• I have checked for existing issues https://github.com/getsentry/sentry-javascript/issues
• I have reviewed the documentation https://docs.sentry.io/
• 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, set options.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: getsentry/sentry-docs#11140

[OmBharti999]

I pasted this part in my next.config.js file

/** @type {import('next').NextConfig} */
const { withSentryConfig } = require("@sentry/nextjs");
const nextConfig = {
//your additional configs
}

const sentryWebpackPluginOptions = {
  org: "grippi-frontend",
  project: "javascript-nextjs",
  telemetry: false,
};

const sentryOptions = {
  // Upload additional client files (increases upload size)
  widenClientFileUpload: true,

  // Hides source maps from generated client bundles
  hideSourceMaps: true,
};

module.exports = withSentryConfig(
  nextConfig,
  sentryWebpackPluginOptions,
  sentryOptions
);

[devuxer]

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

@HazAT, What you are saying here matches the docs, but it appears these sentry.*.config files are not compatible with NextJS 15, at least with Turbopack.

[s1gr1d]

Hello, please check this issue regarding Turbopack support: #8105

You can add your Sentry server configuration in instrumentation.ts and your client-side instrumentation in instrumentation-client.ts which is available after v15.3 (Next.js docs).

If something does not work with this setup please open a new issue describing your problem as this is not connected to this issue title anymore.

[devuxer]

Hello, please check this issue regarding Turbopack support: #8105

You can add your Sentry server configuration in instrumentation.ts and your client-side instrumentation in instrumentation-client.ts which is available after v15.3 (Next.js docs).

If something does not work with this setup please open a new issue describing your problem as this is not connected to this issue title anymore.

Thank you, @s1gr1d, are there docs on good Sentry defaults to use for instrumentation.ts and intrumentation-client.ts?

I have my instrumentation.ts set up like this so far:

import * as Sentry from "@sentry/nextjs";

const dsn = process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN;

export function register() {
    switch (process.env.NEXT_RUNTIME) {
        case "nodejs":
            Sentry.init({ dsn, sendDefaultPii: true });
            break;
        case "edge":
            Sentry.init({ dsn, sendDefaultPii: true });
            break;
    }
}

export const onRequestError = Sentry.captureRequestError;

Is this a good starting point?

How would my instrumentation-client.ts file differ?

[s1gr1d]

You can find all the information about setting up the instrumentation filed in the docs here: https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/#initialize-sentry-client-side-and-server-side-sdks

[devuxer]

You can find all the information about setting up the instrumentation filed in the docs here: https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/#initialize-sentry-client-side-and-server-side-sdks

Hi @s1gr1d,

I have referred to those docs several times, but they do not seem to cover my use case, which is Turbopack for development + Webpack for production + Pages router.

I believe I need two files: instrumentation.ts and instrumentation-client.ts. (And note that I get errors if I try include a sentry.server.config.ts or sentry.edge.config.ts file.)

From the NextJS docs, it looks like I am not supposed to export a register function from instrumentation-client.ts.

From the Sentry docs, it looks like there are two different event handlers (onRequestError for the server and onRouterTransitionStart for the client), but onRequestError only applies if using the App Router (not the Pages Router).

If the above is correct, a basic setup would look like this:

instrumentation.ts:

import * as Sentry from "@sentry/nextjs";

const dsn = process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN;

export function register() {
    Sentry.init({ dsn, sendDefaultPii: true });

    /* for custom setup for Node vs. Edge, use this:
        switch (process.env.NEXT_RUNTIME) {
            case "nodejs":
            case "edge":
        }
    */
}

instrumentation-client.ts:

import * as Sentry from "@sentry/nextjs";

const dsn = process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN;

Sentry.init({ dsn, sendDefaultPii: true });

export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

Does this seem correct?