This feature requires{" "}
{v.name} version {v.version}
{getBoundText(v.bound)}.
)}
;
};
A integração do AppSignal para [Next.js](https://nextjs.org/).
Para relatar tanto traces de back-end quanto erros de front-end, recomenda-se usar o `@appsignal/nodejs` em combinação com o [`@appsignal/javascript`](/front-end) e o [`@appsignal/react`](/front-end/integrations/react) no lado do cliente para monitoramento de desempenho full-stack e rastreamento de erros.
Devido a limitações técnicas do agente AppSignal, não é possível usar o
`@appsignal/nodejs` no ambiente serverless da Vercel. Recomendamos usar nosso
[log drain da Vercel](/vercel/logs) e nossos pacotes de [JavaScript
front-end](/front-end) e [React](/front-end/integrations/react)
no lugar.
## Instalação
Primeiro, siga as [instruções de instalação do `@appsignal/nodejs`](/nodejs/3.x/installation).
Em seguida, modifique o arquivo de configuração `next.config.js` do seu projeto Next para habilitar os hooks de instrumentação:
Se você estiver usando o Next 15:
```javascript JavaScript theme={null}
const nextConfig = {
serverExternalPackages: ["@appsignal/nodejs"],
};
```
Se você estiver usando o 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"],
},
};
```
Depois, adicione o seguinte arquivo na raiz do seu projeto Next.js como `instrumentation.js`:
Se o seu projeto tiver um diretório `src`, então o arquivo `instrumentation.js` deve ser colocado nesse diretório.
Se o seu projeto estiver usando o [App Router do Next.js](https://nextjs.org/docs/app/building-your-application/routing/defining-routes), o arquivo não deve ser colocado dentro da pasta `app`, mas na pasta que contém a pasta `app`.
```javascript JavaScript theme={null}
export function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
require("./appsignal.cjs");
}
}
```
O arquivo do instrumentation hook referencia o arquivo `appsignal.cjs` que foi criado [ao configurar o AppSignal](/nodejs/3.x/configuration#minimal-required-configuration). Certifique-se de que o arquivo `appsignal.cjs` esteja na mesma pasta que o arquivo `instrumentation.js`, ou ajuste o caminho do `require` no arquivo `instrumentation.js` conforme necessário.
Por fim, modifique seu arquivo de configuração `appsignal.cjs` para desativar a instrumentação HTTP, que de outra forma geraria traces redundantes:
```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",
],
});
```
### Suporte a TypeScript
Ao usar TypeScript, os backtraces emitidos pelos erros do Next.js no lado do servidor referenciarão os arquivos JavaScript compilados. Siga estes passos para configurar o Next.js de forma que os backtraces façam referência ao código TypeScript original.
Primeiro, configure o Next.js para emitir source maps adicionando as seguintes linhas ao arquivo `next.config.js` da sua aplicação:
```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;
},
};
```
Em seguida, no seu `package.json`, modifique a forma como a sua aplicação Next.js é iniciada ao executar `npm run start`, usando a variável de ambiente `NODE_OPTIONS` para passar a flag `--enable-source-maps` para o runtime do Node.js:
```json JSON theme={null}
{
"scripts": {
// Modify the `start` script as follows
"start": "NODE_OPTIONS=--enable-source-maps next start"
}
}
```
Por fim, se estiver usando o pacote de integração de front-end `@appsignal/javascript` para rastrear erros do lado do cliente, adicione a opção `productionBrowserSourceMaps` ao arquivo `next.config.js` para que o Next.js emita source maps públicos:
```javascript JavaScript theme={null}
const nextConfig = {
// Add the `productionBrowserSourceMaps` flag
productionBrowserSourceMaps: true,
};
```
## Recursos
A integração com o Next.js enviará ao AppSignal uma amostra de desempenho para cada requisição.
Dentro de cada amostra, a linha do tempo de eventos mostrará eventos, junto com sua duração, correspondendo a:
* Renderização do documento
* Execução da função `getServerSideProps` *(apenas pages router)*
* Execução do route handler
* Execução de requisições HTTP usando o `fetch` do lado do servidor do Next.js *(apenas app router)*
## Saída standalone
Nenhum dado pode ser relatado quando o Next.js está configurado com `output: "standalone"` no `next.config.js`. Quando o Next.js otimiza o tamanho da aplicação para incluir apenas o que é usado pela app, ele omite a extensão e o agente do AppSignal, que relatam os dados aos nossos servidores.
Ao usar o [starter "with-docker" do Next.js](https://github.com/vercel/next.js/tree/canary/examples/with-docker), especificamente o [Dockerfile](https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile), é necessária uma modificação para garantir que a extensão e o agente do AppSignal sejam incluídos na imagem Docker de produção.
Adicione a seguinte linha ao seu `Dockerfile`, depois das linhas `COPY` semelhantes próximas ao final do arquivo:
```docker Dockerfile theme={null}
# Dockerfile
COPY --from=builder --chown=nextjs:nodejs /app/node_modules/@appsignal/nodejs ./node_modules/@appsignal/nodejs
```
A alteração no Git ficará parecida com isto, mas seu Dockerfile pode ser ligeiramente diferente:
```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
```