Node.js Installation

📘

Prerequisites for Hud Integration

Before integrating Hud, please make sure your application meets the requirements.

1. Install SDK package

Run the installation command according to your package manager.

npm install hud-sdk

yarn add hud-sdk

pnpm add hud-sdk

2. Create the Initialization File

Set up Hud by creating an initialization file. This file should register the SDK and initiate a session.

// hud-init.js
const hud = require('hud-sdk/setup');

// Add internal packages from node_modules using glob patterns (e.g., '@your-org/*').
// Hud does not auto-instrument anything inside node_modules unless specified.
hud.register({
  includeModules: [],
});

void hud.initSession(<hud_api_key>, <your_service_name>);

// hud-init.ts
import * as hud from 'hud-sdk/setup' 

// Add internal packages from node_modules using glob patterns (e.g., '@your-org/*').
// Hud does not auto-instrument anything inside node_modules unless specified.
hud.register({
  includeModules: [],
});

void hud.initSession(<hud_api_key>, <your_service_name>);

hud.register({
  includeModules: ['@org/*'],
  debug: true
});

hud.initSession(
  'local_f47da...3eb',
  'main-service'
);

📘

Need to load secrets before initSession()?

If your configuration or environment variables are initialized later in the application lifecycle, you may invoke hud.initSession() at that later stage or from a separate file.

3. Load the init file as early as possible

⚠️

Load Hud Before Anything Else

Hud's SDK needs to be imported as early as possible in your code to make sure it instruments any forthcoming modules' functions. Best practices on how to do it can be found here.

Option A - preferred: preload with --require

node --require ./hud-init.js [YOUR_ENTRY_POINT].js

npx ts-node --require ./hud-init.ts [YOUR_ENTRY_POINT].ts

nest start --exec "node --require ./hud-init.js"

// Create a file called instrumentation.ts with the following code:

export async function register() {
	require('./hud-init.js');
}

//project.json

"my-app": {
  "targets": {
    "serve": {
      "executor": "@nx/js:node",
      "options": {
        "runtimeArgs": ["--require", "./hud-init.js"],
        //...
      },
    },
  }
}

// If using `npm run`, check your package.json and modify the relevant script that runs your backend:
"scripts": {
  "dev": "node --require ./hud-init.js index.js"
}

Option B - simple import

Add the import at the very top of your entrypoint:

require('./hud-init.js'); // must come before any other imports
// …rest of your app

import './hud-init.ts';   // must come before any other imports
// …rest of your app

Note: Functions in the same file won't be instrumented. Use option A for full coverage (--require).

4. Using a Bundler, Transpiler, or Minifier?

Hud uses source maps to reconstruct the original code in your production traces so you get clear, accurate visibility into what ran, where. Hud automatically pick up any source maps you deploy alongside your code.

📘

What are source maps?

Source maps connect your minified or transpiled JavaScript back to the original source code.
They're essential when using tools like Webpack, TSC, or Terser to ensure Hud can display the correct file and function names. These files typically end with .map (e.g., bundle.js.map) and are stored alongside your built JavaScript.

5. Run your service and trigger it!

Start your service and trigger the functions you want to measure - metrics collection will begin automatically.

📘

How to Know If Your Integration Worked

Hud logs success or failure directly to stdout, look for the following logs on success:

• Hud: Hud session started
• Hud: First code mapping sent successfully
• Hud: First invocation sent successfully
• Hud: Your service is sending data successfully

Then, head over to the web app to explore your data live, or install the IDE extension to view it directly alongside your code.