This feature requires{" "}
{v.name} version {v.version}
{getBoundText(v.bound)}.
)}
;
};
Die AppSignal-Integration für [Next.js](https://nextjs.org/).
Um sowohl Backend-Traces als auch Frontend-Fehler zu melden, wird empfohlen, `@appsignal/nodejs` in Kombination mit [`@appsignal/javascript`](/front-end) und [`@appsignal/react`](/front-end/integrations/react) auf der Client-Seite zu verwenden, um Full-Stack-Performance-Monitoring und Error-Tracking zu erhalten.
Aufgrund technischer Einschränkungen des AppSignal-Agents ist es nicht möglich,
`@appsignal/nodejs` in der Serverless-Umgebung von Vercel zu verwenden. Wir
empfehlen stattdessen die Verwendung unseres [Vercel-Log-Drain](/vercel/logs)
sowie unserer Pakete [Front-End-JavaScript](/front-end) und
[React](/front-end/integrations/react).
## Installation
Folgen Sie zunächst der [Installationsanleitung für `@appsignal/nodejs`](/nodejs/3.x/installation).
Ändern Sie anschließend die Konfigurationsdatei `next.config.js` Ihres Next-Projekts, um Instrumentation-Hooks zu aktivieren:
Wenn Sie Next 15 verwenden:
```javascript JavaScript theme={null}
const nextConfig = {
serverExternalPackages: ["@appsignal/nodejs"],
};
```
Wenn Sie Next 13 oder 14 verwenden:
```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"],
},
};
```
Fügen Sie anschließend die folgende Datei als `instrumentation.js` im Stammverzeichnis Ihres Next.js-Projekts hinzu:
Wenn Ihr Projekt ein `src`-Verzeichnis hat, sollte die Datei `instrumentation.js` in diesem Verzeichnis abgelegt werden.
Wenn Ihr Projekt den [Next.js App Router](https://nextjs.org/docs/app/building-your-application/routing/defining-routes) verwendet, sollte die Datei nicht im Ordner `app` abgelegt werden, sondern in dem Ordner, der den Ordner `app` enthält.
```javascript JavaScript theme={null}
export function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
require("./appsignal.cjs");
}
}
```
Die Instrumentation-Hook-Datei verweist auf die Datei `appsignal.cjs`, die [bei der Konfiguration von AppSignal](/nodejs/3.x/configuration#minimal-required-configuration) erstellt wurde. Stellen Sie sicher, dass sich die Datei `appsignal.cjs` im selben Ordner wie die Datei `instrumentation.js` befindet, oder passen Sie den Pfad des `require` in der Datei `instrumentation.js` entsprechend an.
Ändern Sie schließlich Ihre Konfigurationsdatei `appsignal.cjs`, um die HTTP-Instrumentierung zu deaktivieren, da sie andernfalls redundante Traces erzeugen würde:
```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-Unterstützung
Bei Verwendung von TypeScript verweisen die Backtraces, die von serverseitigen Next.js-Fehlern erzeugt werden, auf die kompilierten JavaScript-Dateien. Folgen Sie diesen Schritten, um Next.js so zu konfigurieren, dass die Backtraces auf den ursprünglichen TypeScript-Code verweisen.
Konfigurieren Sie Next.js zunächst so, dass Source Maps erzeugt werden, indem Sie die folgenden Zeilen zur Datei `next.config.js` Ihrer Anwendung hinzufügen:
```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;
},
};
```
Ändern Sie anschließend in Ihrer `package.json`, wie Ihre Next.js-Anwendung beim Ausführen von `npm run start` gestartet wird, indem Sie die Umgebungsvariable `NODE_OPTIONS` verwenden, um das Flag `--enable-source-maps` an die Node.js-Laufzeit zu übergeben:
```json JSON theme={null}
{
"scripts": {
// Modify the `start` script as follows
"start": "NODE_OPTIONS=--enable-source-maps next start"
}
}
```
Wenn Sie schließlich das Frontend-Integrationspaket `@appsignal/javascript` verwenden, um clientseitige Fehler zu erfassen, fügen Sie die Option `productionBrowserSourceMaps` zur Datei `next.config.js` hinzu, damit Next.js öffentliche Source Maps erzeugt:
```javascript JavaScript theme={null}
const nextConfig = {
// Add the `productionBrowserSourceMaps` flag
productionBrowserSourceMaps: true,
};
```
## Funktionen
Die Next.js-Integration sendet AppSignal eine Performance-Probe für jede Anfrage.
Innerhalb jeder Probe zeigt die Event-Timeline Ereignisse mit ihrer Dauer an, die Folgendem entsprechen:
* Rendern des Dokuments
* Ausführen der Funktion `getServerSideProps` *(nur Pages Router)*
* Ausführen des Route-Handlers
* Ausführen von HTTP-Anfragen mit dem serverseitigen `fetch` von Next.js *(nur App Router)*
## Standalone-Output
Es werden möglicherweise keine Daten gemeldet, wenn Next.js mit `output: "standalone"` in `next.config.js` konfiguriert ist. Wenn Next.js die App-Größe so optimiert, dass nur das enthalten ist, was von der App verwendet wird, werden die AppSignal-Extension und der Agent ausgelassen, die die Daten an unsere Server melden.
Wenn Sie den [Next.js „with-docker“-Starter](https://github.com/vercel/next.js/tree/canary/examples/with-docker) verwenden, insbesondere das [Dockerfile](https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile), ist eine Änderung erforderlich, um sicherzustellen, dass die AppSignal-Extension und der Agent im Produktions-Docker-Image enthalten sind.
Fügen Sie die folgende Zeile zu Ihrem `Dockerfile` hinzu, nach ähnlichen `COPY`-Zeilen gegen Ende der Datei:
```docker Dockerfile theme={null}
# Dockerfile
COPY --from=builder --chown=nextjs:nodejs /app/node_modules/@appsignal/nodejs ./node_modules/@appsignal/nodejs
```
Die Änderung in Git wird in etwa wie folgt aussehen, Ihr Dockerfile kann jedoch leicht abweichen:
```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
```