> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação

Por favor, siga primeiro o [guia de instalação](/guides/new-application) ao adicionar uma nova aplicação ao AppSignal.

## Requisitos

Antes de compilar o pacote AppSignal, certifique-se de que as ferramentas de build/compilação estejam instaladas para o seu sistema. Por favor, confira a página de [Sistemas Operacionais Suportados](/support/operating-systems) para ver quaisquer dependências de sistema que possam ser necessárias.

## Instalação

Primeiro, [cadastre-se](https://appsignal.com/users/sign_up) para obter uma conta AppSignal. Em seguida, instale o AppSignal seguindo as instruções para o seu gerenciador de pacotes.

### Usando npm

<CodeGroup>
  ```bash Bash theme={null}
  npm install @appsignal/nodejs
  ```
</CodeGroup>

Também é possível adicionar manualmente o pacote `@appsignal/nodejs` ao seu `package.json`. Em seguida, execute `npm install`.

<CodeGroup>
  ```json JSON theme={null}
  {
    "name": "my-app",
    "dependencies": {
      "@appsignal/nodejs": "^3.0.0"
    }
  }
  ```
</CodeGroup>

Crie um arquivo `appsignal.cjs` para fazer o require e configurar o AppSignal. Esse arquivo também pode ser colocado em outro local, como no diretório `src/`. Para mais informações sobre a configuração, veja nossa [seção de configuração](/nodejs/3.x/configuration).

<CodeGroup>
  ```javascript Node.js theme={null}
  // appsignal.cjs
  const { Appsignal } = require("@appsignal/nodejs");

  new Appsignal({
    active: true,
    name: "<YOUR APPLICATION NAME>",
    pushApiKey: "<YOUR API KEY>",
  });
  ```
</CodeGroup>

### Usando pnpm

O pnpm suprime scripts de lifecycle de dependências por padrão. O pacote `@appsignal/nodejs` depende de um script de lifecycle `install` para baixar e compilar sua extensão nativa. Sem ele, a extensão não será carregada e o AppSignal não reportará nenhum dado.

Para instalar o pacote e permitir que seu script de lifecycle seja executado:

<CodeGroup>
  ```bash Bash theme={null}
  pnpm --allow-build=@appsignal/nodejs add @appsignal/nodejs
  ```
</CodeGroup>

### Fazendo require do cliente AppSignal

Agora, você pode executar sua aplicação como faria normalmente, mas use a flag `--require` para carregar a instrumentação do AppSignal antes de qualquer outra biblioteca:

<CodeGroup>
  ```shell Shell theme={null}
  node --require './appsignal.cjs' index.js
  ```
</CodeGroup>

Recomendamos adicionar a flag `--require` em qualquer script que inicialize seu app:

<CodeGroup>
  ```json JSON theme={null}
  {
    "scripts": {
      "server": "node --require ./appsignal.cjs index.js"
    }
  }
  ```
</CodeGroup>

Você também pode usar a flag `--require` com ferramentas como `ts-node` e `nodemon`.

Quando usar uma CLI wrapper, como `nest start` ou `fastify start`, para iniciar sua aplicação, use a variável de ambiente `NODE_OPTIONS` para passar a flag para o runtime do Node.js:

<CodeGroup>
  ```sh Shell theme={null}
  NODE_OPTIONS='--require ./appsignal.cjs' nest start
  ```
</CodeGroup>

<Warning>
  Para que a integração do AppSignal funcione corretamente, o arquivo `appsignal.cjs`
  **precisa** ser carregado via require antes de qualquer outra dependência.
</Warning>

### Suporte a TypeScript

O AppSignal é totalmente compatível com TypeScript. Ao executar uma aplicação TypeScript compilada com `node`, recomendamos usar [a flag `--enable-source-maps` do Node.js](https://nodejs.org/api/cli.html#--enable-source-maps) para que os backtraces de erros no AppSignal apontem para as posições no código TypeScript original:

<CodeGroup>
  ```sh Shell theme={null}
  node --enable-source-maps --require './appsignal.cjs' dist/src/main.js
  ```
</CodeGroup>

Quando usar uma CLI wrapper, como `nest start` ou `fastify start`, para iniciar sua aplicação, use a variável de ambiente `NODE_OPTIONS` para passar a flag para o runtime do Node.js:

<CodeGroup>
  ```sh Shell theme={null}
  NODE_OPTIONS='--enable-source-maps --require ./appsignal.cjs' nest start
  ```
</CodeGroup>

### Importar o cliente AppSignal

O cliente AppSignal é acessado a partir do objeto global exportado `Appsignal.client`.

Para usar recursos como [métricas customizadas](/metrics/custom), primeiro você precisa importar o cliente AppSignal:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Appsignal } from "@appsignal/nodejs";
  // or: const { Appsignal } = require("@appsignal/nodejs");

  const client = Appsignal.client;
  ```
</CodeGroup>

### Adicionando integrações

O AppSignal suporta várias bibliotecas e frameworks com pacotes adicionais, como Express, Koa, Next.js e outros. Instruções de instalação adicionais para esses pacotes podem ser encontradas na [seção de integrações para Node.js](/nodejs/3.x/integrations).

***

<Note>
  📖 Continue com nosso [guia de instalação](/guides/new-application).
</Note>

## Desinstalando o AppSignal para Node.js

Desinstale o AppSignal do seu app seguindo os passos abaixo. Quando estes passos forem concluídos, seu app não enviará mais dados para os servidores do AppSignal.

1. Execute `npm uninstall @appsignal/nodejs` para desinstalar a integração AppSignal para Node.js, ou exclua a linha dentro do bloco `dependencies` do arquivo `package.json` da sua aplicação que referencia o pacote `@appsignal/nodejs`.

2. Execute `npm install` para atualizar seu `package.lock` com o estado dos pacotes removidos.

3. Remova qualquer [configuração](/nodejs/3.x/configuration/) do AppSignal do seu app.

4. Faça commit, deploy e reinicie seu app.
   * Isso garantirá que os servidores do AppSignal não continuem recebendo dados do seu app.

5. Por fim, [remova o app](/guides/application/deleting-applications) no AppSignal.com.

<Note>
  📖 Continue com nosso [guia de
  desinstalação](/guides/application/deleting-applications).
</Note>

## Parando o cliente AppSignal

O AppSignal será parado automaticamente quando sua aplicação ou máquina parar de rodar. No entanto, se você quiser parar o AppSignal manualmente, pode executar o seguinte comando:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Appsignal } from "@appsignal/nodejs";
  // or: const { Appsignal } = require("@appsignal/nodejs");

  Appsignal.client.stop();
  ```
</CodeGroup>