Next.js

The AppSignal integration for Next.js.

To report both back-end traces and front-end errors, it is recommended to use @appsignal/nodejs in combination with @appsignal/javascript and @appsignal/react on the client-side for full-stack performance monitoring and error tracking.

Installation

First, follow the @appsignal/nodejs installation instructions.

Then, modify your Next project's next.config.js configuration file in order to enable instrumentation hooks:

If you are using Next 15:

const nextConfig = {
  serverExternalPackages: ["@appsignal/nodejs"],
};

If you are using Next 13 or 14:

const nextConfig = {
  // Add the `experimental` object if not present
  experimental: {
    // Add the following lines inside the object
    instrumentationHook: true,
    serverComponentsExternalPackages: ["@appsignal/nodejs"],
  },
};

Then, add the following file to the root of your Next.js project as instrumentation.js:

export function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    require("./appsignal.cjs");
  }
}

The instrumentation hook file references the appsignal.cjs file that was created when configuring AppSignal. Make sure that the appsignal.cjs file is in the same folder as the instrumentation.js file, or adjust the path of the require in the instrumentation.js file accordingly.

Finally, modify your appsignal.cjs configuration file in order to disable the HTTP instrumentation, which would otherwise generate redundant traces:

new Appsignal({
  // Add the `disableDefaultInstrumentations` list if not present
  disableDefaultInstrumentations: [
    // Add the following line inside the list
    "@opentelemetry/instrumentation-http",
  ],
});

TypeScript support

When using TypeScript, the backtraces emitted by server-side Next.js errors will refer to the compiled JavaScript files. Follow these steps to configure Next.js so that the backtraces refer to the original TypeScript code.

First, configure Next.js to emit source maps by adding the following lines to your application's next.config.js file:

// next.config.js
 
const nextConfig = {
  // Add the `webpack` function if not present
  webpack: (config, { isServer }) => {
    // Add the following lines inside the function
    if (isServer) {
      config.devtool = "eval-source-map";
    }
 
    return config;
  },
};

Then, in your package.json, modify how your Next.js application is started when running npm run start, using the NODE_OPTIONS environment variable to pass the --enable-source-maps flag to the Node.js runtime:

// package.json
 
{
  scripts: {
    // Modify the `start` script as follows
    start: "NODE_OPTIONS=--enable-source-maps next start",
  },
}

Finally, if using the @appsignal/javascript front-end integration package to track client-side errors, add the productionBrowserSourceMaps option to the next.config.js file for Next.js to emit public source maps:

// next.config.js
 
const nextConfig = {
  // Add the `productionBrowserSourceMaps` flag
  productionBrowserSourceMaps: true,
};

Features

The Next.js integration will send AppSignal a performance sample for each request.

Within each sample, the event timeline will show events, along with their duration, corresponding to:

• Rendering the document
• Running the getServerSideProps function (pages router only)
• Running the route handler
• Performing HTTP requests using Next.js' server-side fetch (app router only)

Standalone output

No data may be reported when Next.js is configured with output: "standalone" in next.config.js. When Next.js optimizes its app size to only include what is used by the app, it omits the AppSignal extension and agent, which report the data to our servers.

When using the Next.js "with-docker" starter, specifically the Dockerfile, a modification is required to make sure the AppSignal extension and agent are included in the production Docker image.

Add the following line to your Dockerfile, after similar COPY lines near the end of the file:

# Dockerfile
COPY --from=builder --chown=nextjs:nodejs /app/node_modules/@appsignal/nodejs ./node_modules/@appsignal/nodejs

The change in Git will look something like this, but your Dockerfile may be slightly different:

--- Dockerfile
+++ Dockerfile
@@ -48,6 +48,7 @@ COPY --from=builder /app/public ./public
 # https://nextjs.org/docs/advanced-features/output-file-tracing
 COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
 COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/node_modules/@appsignal/nodejs ./node_modules/@appsignal/nodejs
 
 USER nextjs