Next.js

AppSignal for Node.jsThis feature requires version 3.0.14 or higher.
Next.jsThis feature requires version 13.3.0 or higher.

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.

Due to technical limitations of the AppSignal agent, it is not possible to use @appsignal/nodejs on Vercel's serverless environment. We recommend using our Vercel log drain and our front-end JavaScript and React packages instead.

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:

javascript
const nextConfig = { // Add the `experimental` object if not present experimental: { // Add the following line inside the object instrumentationHook: true, }, };

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

If your project has an src directory, then the instrumentation.js file should be placed in that directory.

If your project is using the Next.js App Router, or the experimental Next.js appDir setting, the file should not be placed inside the app folder, but in the folder that contains the app folder.

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

The instrumentation hook file references the appsignal.cjs file that was created by the AppSignal installer or when configuring AppSignal manually. 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:

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

Features

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

Within each trace, the event timeline will show spans for the time taken to render the document, get server-side props, run the route handler or perform HTTP requests using fetch.

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:

docker
# 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:

diff
--- 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