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 and any relevant integrations to your project:

npx @appsignal/cli install

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

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

Alternatively, you can manually add the @appsignal/nodejs package to your package.json. Then, run yarn install/npm install.

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

Create an appsignal.js file to require and configure AppSignal. This file may also be placed in another file location, like in the src/ directory. Check with your team the best location for this file, but make sure to name it appsignal.js. For more information about the configuration, see our configuration section.

// appsignal.js or src/appsignal.js
const { Appsignal } = require("@appsignal/nodejs");
 
const appsignal = new Appsignal({
  active: true,
  name: "<YOUR APPLICATION NAME>",
  pushApiKey: "<YOUR API KEY>", // Note: renamed from `apiKey` in version 2.2.5
});
 
module.exports = { appsignal };

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

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

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

{
  "name": "test app",
  "private": true,
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "server": "node --require ./appsignal.js index.js"
  }
}

To use the AppSignal client in your app, and configure AppSignal for Node.js integrations, require AppSignal in your app:

// index.js
// Place this at the top
const { appsignal } = require("./appsignal"); // Update to the location used in the previous step
 
// Place your app code below this

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.

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. In the package.json of your app, delete all lines referencing an appsignal package: "*appsignal/*": "*".

2. Run npm install or yarn install to update your package.lock/yarn.lock with the removed packages state.

   • Alternatively, run npm uninstall @appsignal/<package name> or yarn remove @appsignal/<package name> to uninstall an AppSignal package.

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.