> ## 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.

# Installation

Please follow the [installation guide](/guides/new-application) first, when adding a new application to AppSignal.

## Requirements

Before you can compile the AppSignal package, make sure the build/compilation tools are installed for your system. Please check the [Supported Operating Systems](/support/operating-systems) page for any system dependencies that may be required.

## Installation

First, [sign up](https://appsignal.com/users/sign_up) for an AppSignal account. Then, install AppSignal by following the instructions for your package manager.

### Using npm

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

It's also possible to manually add the `@appsignal/nodejs` package to your `package.json`. Then, run `npm install`.

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

Create an `appsignal.cjs` file to require and configure AppSignal. This file may also be placed in another location, like in the `src/` directory. For more information about the configuration, see our [configuration section](/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>

### Using pnpm

pnpm suppresses lifecycle scripts for dependencies by default. The `@appsignal/nodejs` package relies on an `install` lifecycle script to download and compile its native extension. Without it, the extension won't load and AppSignal won't report any data.

To install the package and allow its lifecycle script to run:

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

### Requiring the AppSignal client

Now, you can run your application like you normally would, but use the `--require` flag to load AppSignal's instrumentation before any other library:

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

We recommend adding the `--require` flag to any script that starts your app:

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

You can also use the `--require` flag with tools such as `ts-node` and `nodemon`.

When using a wrapper CLI, such as `nest start` or `fastify start`, to start your application, use the `NODE_OPTIONS` environment variable to pass the flag to the Node.js runtime:

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

<Warning>
  For the AppSignal integration to work correctly, the `appsignal.cjs` file
  **must** be required before any other dependencies.
</Warning>

### TypeScript support

AppSignal is fully compatible with TypeScript. When running a compiled TypeScript application with `node`, we recommend using [the `--enable-source-maps` Node.js flag](https://nodejs.org/api/cli.html#--enable-source-maps) so that error backtraces in AppSignal refer to locations in the original TypeScript code:

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

When using a wrapper CLI, such as `nest start` or `fastify start`, to start your application, use the `NODE_OPTIONS` environment variable to pass the flag to the Node.js runtime:

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

### Import AppSignal Client

The AppSignal client is accessed from the globally exported `Appsignal.client` object.

To use features like [custom metrics](/metrics/custom), you must first import the AppSignal client:

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

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

### Adding integrations

AppSignal supports several libraries and frameworks with additional packages, such as Express, Koa, Next.js and more. Additional installation instructions for these packages can be found in the [Node.js integrations section](/nodejs/3.x/integrations).

***

<Note>
  📖 Continue with our [installation guide](/guides/new-application).
</Note>

## Uninstalling AppSignal for Node.js

Uninstall AppSignal from your app by following the steps below. When these steps are completed your app will no longer send data to the AppSignal servers.

1. Run `npm uninstall @appsignal/nodejs` to uninstall the AppSignal for Node.js integration, or delete the line within the `dependencies` block of your application's `package.json` file referencing the `@appsignal/nodejs` package.

2. Run `npm install` to update your `package.lock` with the removed packages state.

3. Remove any AppSignal [configuration](/nodejs/3.x/configuration/) from your app.

4. Commit, deploy and restart your app.
   * This will make sure the AppSignal servers won't continue to receive data from your app.

5. Finally, [remove the app](/guides/application/deleting-applications) on AppSignal.com.

<Note>
  📖 Continue with our [uninstall
  guide](/guides/application/deleting-applications).
</Note>

## Stopping The AppSignal Client

AppSignal will stop automatically when your application or machine stops running. However, if you want to stop AppSignal manually you can run the following command:

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

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