Getting Started

Capture your first Node.js request from installation to an authenticated local trace.

What you will build

You will initialize one ServerDevTools instance before application dependencies load, mount its middleware, run a request, and inspect the trace at /_devtools.

The middleware does not activate instrumentation by itself. await devtools.start() must run before your application imports the database clients or other instrumented dependencies.

Prerequisites

Node.js 20 or newer. The SDK package declares node >=20.
An application using native Node.js HTTP, Express, or NestJS.
A username and password for the local dashboard.
An encryption key if you want sensitive values encrypted in SQLite.

Install


npm install server-devtools
npm install -D tsx

Generate a 32-byte base64 encryption key:


node -e 'console.log(require("node:crypto").randomBytes(32).toString("base64"))'

Set the values in your shell or .env file:


SERVER_DEVTOOLS_USERNAME=dev
SERVER_DEVTOOLS_PASSWORD=replace-with-a-local-password
SERVER_DEVTOOLS_ENCRYPTION_KEY=replace-with-the-generated-key

Initialize before application imports

Create server-devtools.ts at the project root:


import ServerDevTools from "server-devtools";
 
export const devtools = new ServerDevTools({
  auth: {
    username: process.env.SERVER_DEVTOOLS_USERNAME!,
    password: process.env.SERVER_DEVTOOLS_PASSWORD!,
  },
  encryption: {
    key: process.env.SERVER_DEVTOOLS_ENCRYPTION_KEY!,
  },
});
 
await devtools.start();

auth is required by the constructor. encryption is optional, but the key must decode to exactly 32 bytes when provided.

Mount the middleware

Use the same initialized instance in your server:


import { createServer } from "node:http";
import { devtools } from "../server-devtools";
 
const server = createServer((req, res) => {
  devtools.middleware(req, res, () => {
    res.statusCode = 200;
    res.end("Hello from Node");
  });
});
 
server.listen(3000, () => {
  console.log("Listening on http://localhost:3000");
});

Start with the initialization file preloaded:


npx tsx watch --import ./server-devtools.ts src/main.ts

Inspect the first request

Open the dashboard

Visit http://localhost:3000/_devtools and sign in with the credentials from your environment.

Trigger a request

Open http://localhost:3000/ or call the route with your preferred HTTP client.

Open the trace

Select the new request in the dashboard. The trace shows the HTTP span, timing, response, and any child operations captured by the initialized instrumentations.

If nothing appears

Check the troubleshooting guide, especially preload order, dashboard authentication, and Node.js compatibility. If you are using a framework, continue with the Express or NestJS guide.