This feature requires{" "}
{v.name} version {v.version}
{getBoundText(v.bound)}.
)}
;
};
L'intégration AppSignal pour [Next.js](https://nextjs.org/).
Pour rapporter à la fois les traces back-end et les erreurs front-end, il est recommandé d'utiliser `@appsignal/nodejs` en combinaison avec [`@appsignal/javascript`](/front-end) et [`@appsignal/react`](/front-end/integrations/react) côté client pour une surveillance complète des performances et un suivi des erreurs sur l'ensemble de la pile.
En raison de limitations techniques de l'agent AppSignal, il n'est pas possible
d'utiliser `@appsignal/nodejs` dans l'environnement serverless de Vercel. Nous
recommandons d'utiliser à la place notre [Vercel log drain](/vercel/logs) et
nos packages [JavaScript front-end](/front-end) et
[React](/front-end/integrations/react).
## Installation
Tout d'abord, suivez les [instructions d'installation de `@appsignal/nodejs`](/nodejs/3.x/installation).
Ensuite, modifiez le fichier de configuration `next.config.js` de votre projet Next afin d'activer les hooks d'instrumentation :
Si vous utilisez Next 15 :
```javascript JavaScript theme={null}
const nextConfig = {
serverExternalPackages: ["@appsignal/nodejs"],
};
```
Si vous utilisez Next 13 ou 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"],
},
};
```
Puis, ajoutez le fichier suivant à la racine de votre projet Next.js sous le nom `instrumentation.js` :
Si votre projet a un répertoire `src`, alors le fichier `instrumentation.js` doit être placé dans ce répertoire.
Si votre projet utilise le [Next.js App Router](https://nextjs.org/docs/app/building-your-application/routing/defining-routes), le fichier ne doit pas être placé dans le dossier `app`, mais dans le dossier qui contient le dossier `app`.
```javascript JavaScript theme={null}
export function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
require("./appsignal.cjs");
}
}
```
Le fichier de hook d'instrumentation référence le fichier `appsignal.cjs` qui a été créé [lors de la configuration d'AppSignal](/nodejs/3.x/configuration#minimal-required-configuration). Assurez-vous que le fichier `appsignal.cjs` se trouve dans le même dossier que le fichier `instrumentation.js`, ou ajustez le chemin du `require` dans le fichier `instrumentation.js` en conséquence.
Enfin, modifiez votre fichier de configuration `appsignal.cjs` afin de désactiver l'instrumentation HTTP, qui générerait sinon des traces redondantes :
```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",
],
});
```
### Prise en charge de TypeScript
Lorsque vous utilisez TypeScript, les backtraces émises par les erreurs Next.js côté serveur feront référence aux fichiers JavaScript compilés. Suivez ces étapes pour configurer Next.js de sorte que les backtraces se réfèrent au code TypeScript original.
Tout d'abord, configurez Next.js pour émettre des source maps en ajoutant les lignes suivantes au fichier `next.config.js` de votre application :
```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;
},
};
```
Puis, dans votre `package.json`, modifiez la façon dont votre application Next.js est démarrée lors de l'exécution de `npm run start`, en utilisant la variable d'environnement `NODE_OPTIONS` pour passer l'indicateur `--enable-source-maps` au runtime Node.js :
```json JSON theme={null}
{
"scripts": {
// Modify the `start` script as follows
"start": "NODE_OPTIONS=--enable-source-maps next start"
}
}
```
Enfin, si vous utilisez le package d'intégration front-end `@appsignal/javascript` pour suivre les erreurs côté client, ajoutez l'option `productionBrowserSourceMaps` au fichier `next.config.js` pour que Next.js émette des source maps publiques :
```javascript JavaScript theme={null}
const nextConfig = {
// Add the `productionBrowserSourceMaps` flag
productionBrowserSourceMaps: true,
};
```
## Fonctionnalités
L'intégration Next.js enverra à AppSignal un échantillon de performance pour chaque requête.
Au sein de chaque échantillon, la chronologie des événements affichera des événements, avec leur durée, correspondant à :
* Le rendu du document
* L'exécution de la fonction `getServerSideProps` *(pages router uniquement)*
* L'exécution du gestionnaire de route
* La réalisation de requêtes HTTP via le `fetch` côté serveur de Next.js *(app router uniquement)*
## Sortie standalone
Aucune donnée ne peut être rapportée lorsque Next.js est configuré avec `output: "standalone"` dans `next.config.js`. Lorsque Next.js optimise la taille de son application pour n'inclure que ce qui est utilisé par l'application, il omet l'extension et l'agent AppSignal, qui rapportent les données à nos serveurs.
Lorsque vous utilisez le [starter Next.js « with-docker »](https://github.com/vercel/next.js/tree/canary/examples/with-docker), en particulier le [Dockerfile](https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile), une modification est nécessaire pour s'assurer que l'extension et l'agent AppSignal sont inclus dans l'image Docker de production.
Ajoutez la ligne suivante à votre `Dockerfile`, après des lignes `COPY` similaires près de la fin du fichier :
```docker Dockerfile theme={null}
# Dockerfile
COPY --from=builder --chown=nextjs:nodejs /app/node_modules/@appsignal/nodejs ./node_modules/@appsignal/nodejs
```
Le changement dans Git ressemblera à quelque chose comme ceci, mais votre Dockerfile peut être légèrement différent :
```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
```