Installation

Please follow the installation guide 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 page for any system dependencies that may be required.

Installation

First, sign up for an AppSignal account and run our automated install tool, which will install @appsignal/nodejs to your project:

bash
npx @appsignal/cli install

Follow the steps of the installer and then continue by requiring the client.

Manual installation

Alternatively, you can skip the automated tool and add @appsignal/nodejs to your package.json on the command line with npm/yarn:

bash
npm install --save @appsignal/nodejs yarn add @appsignal/nodejs

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

json
// package.json { "name": "my-app", "dependencies": { "@appsignal/nodejs": "^3.0.0" } }

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.

javascript
// appsignal.cjs const { Appsignal } = require("@appsignal/nodejs"); new Appsignal({ active: true, name: "<YOUR APPLICATION NAME>", pushApiKey: "<YOUR API KEY>", });

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:

shell
node --require './appsignal.cjs' index.js

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

json
{ "scripts": { "server": "node --require ./appsignal.cjs index.js" } }

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

For the AppSignal integration to work correctly, the appsignal.cjs file must be required before any other dependencies.

TypeScript support

AppSignal is fully compatible with TypeScript. When using a compiled TypeScript application with node, we recommend using the source-map-support package so that error backtraces in AppSignal refer to locations in the original TypeScript code:

shell
node --require source-map-support/register --require './appsignal.cjs' dist/src/main.js

Import AppSignal Client

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

To use features like custom metrics, you must first import the AppSignal client:

javascript
import { Appsignal } from "@appsignal/nodejs"; // or: const { Appsignal } = require("@appsignal/nodejs"); const client = Appsignal.client;

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.


Continue with our installation guide.

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/yarn remove @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 or yarn install to update your package.lock/yarn.lock with the removed packages state.

  3. Remove any AppSignal 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 on AppSignal.com.

Continue with our uninstall guide.

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:

javascript
import { Appsignal } from "@appsignal/nodejs"; // or: const { Appsignal } = require("@appsignal/nodejs"); Appsignal.client.stop();