This feature requires{" "}
{v.name} version {v.version}
{getBoundText(v.bound)}.
)}
;
};
The AppSignal integration for [Next.js](https://nextjs.org/).
To report both back-end traces and front-end errors, it is recommended to use `@appsignal/nodejs` in combination with [`@appsignal/javascript`](/front-end) and [`@appsignal/react`](/front-end/integrations/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](/vercel/logs) and our [front-end
JavaScript](/front-end) and [React](/front-end/integrations/react)
packages instead.
## Installation
First, follow the [`@appsignal/nodejs` installation instructions](/nodejs/3.x/installation).
Then, modify your Next project's `next.config.js` configuration file in order to enable instrumentation hooks:
If you are using Next 15:
```javascript JavaScript theme={null}
const nextConfig = {
serverExternalPackages: ["@appsignal/nodejs"],
};
```
If you are using Next 13 or 14:
```javascript JavaScript theme={null}
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`:
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](https://nextjs.org/docs/app/building-your-application/routing/defining-routes), the file should not be placed inside the `app` folder, but in the folder that contains the `app` folder.
```javascript JavaScript theme={null}
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](/nodejs/3.x/configuration#minimal-required-configuration). 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 JavaScript theme={null}
const { Appsignal } = require("@appsignal/nodejs");
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:
```javascript JavaScript theme={null}
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:
```json JSON theme={null}
{
"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:
```javascript JavaScript theme={null}
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](https://github.com/vercel/next.js/tree/canary/examples/with-docker), specifically the [Dockerfile](https://github.com/vercel/next.js/blob/canary/examples/with-docker/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 theme={null}
# 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 Diff theme={null}
--- 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
```