Node.js quickstart
Add tracing, endpoint health, and error groups to your Node.js app without changing its code. Install the SDK, set your API key, and add one flag to your start command. To report background jobs as job runs, wrap each job once you are set up.
Set up with an AI agent
Using a coding agent such as Claude Code, Codex or Cursor? Paste this prompt into it from the root of your project. It installs and configures the SDK for you, and leaves the API key for you to add.
Run `curl -fsSL https://vigilon.io/agents/install.md` and follow the instructions in that file to set up Vigilon in this project.Install the SDK
Use Node.js 20.6 or later. One package sets up tracking for Express, Fastify, PostgreSQL, MySQL, MongoDB, Redis, and outgoing HTTP calls.
npm install @vigilon/nodeConfigure the environment
Get an ingest API key for your project from Vigilon: open the project's Settings page, then the API Keys tab. Set these environment variables in your shell or deployment settings:
export VIGILON_API_KEY="[YOUR_API_KEY]"
export VIGILON_ENVIRONMENT="production"
Vigilon reads your service name and version from your package.json, so most apps need nothing else. To use different values, set VIGILON_SERVICE_NAME and VIGILON_SERVICE_VERSION. The Configuration guide lists every setting.
If VIGILON_ENVIRONMENT is not set, Vigilon falls back to ENVIRONMENT, ENV, and then NODE_ENV. NODE_ENV is often production on staging servers too, so set VIGILON_ENVIRONMENT to keep your environments apart.
Start the SDK
Add the --import flag to your start command. It starts Vigilon before any of your application code runs, which is what lets it track your framework and database libraries. The same flag works for CommonJS and ES module apps.
{
"scripts": {
"start": "node --import @vigilon/node/register server.js"
}
}
Add the flag to the start script in package.json, then start your app as usual, for example with npm start. Replace server.js with your app's entry file.
Keeping your variables in a .env file? Vigilon starts before your app, so it cannot see variables that your code loads with dotenv. Let Node load the file instead: node --env-file=.env --import @vigilon/node/register server.js.
Run and verify
Start your app. Vigilon prints one line that shows the values it is using and where each one came from:
Vigilon started: service.name=checkout-api (package.json), deployment.environment=production (VIGILON_ENVIRONMENT), service.version=1.4.2 (package.json), endpoint=https://ingest.vigilon.io
Then make a few requests to a normal route in your app. Open the matching project in Vigilon, and data should start coming in within 30-45 seconds.
Use a normal application route, not /health, /ready, or /favicon.ico, which are left out by default. If the line is missing or no data arrives, follow the Troubleshooting guide.