Repository navigation
Releases
v1.0.0
node-xray v1.0.0
First stable release of the @node-xray package family — a live runtime inspector for Node.js backends.
Packages
| Package | Version |
|---|---|
@node-xray/types |
1.0.0 |
@node-xray/core |
1.0.0 |
@node-xray/dashboard |
1.0.0 |
@node-xray/express |
1.0.0 |
@node-xray/fastify |
1.0.0 |
@node-xray/nestjs |
1.0.0 |
Features
- One-line integration for Express, Fastify, and NestJS
- Request/response body capture with automatic redaction of sensitive fields (passwords, tokens, cookies)
- Per-request call stacks — sanitized, sampled at configurable rate
- Event-loop health — real-time lag (p50/p99/max), utilization sampling
- Live WebSocket dashboard at
/node-xraywith real-time stats bar - AsyncLocalStorage context — correlates all async ops within a single request
- Bounded memory — in-memory ring buffer with configurable size (default 200 requests)
- Configurable auth — basic, bearer, or custom auth for non-dev environments
- Production safety — refuses to mount without auth in production
Install
npm install --save-dev @node-xray/express # or /fastify or /nestjsQuick start
const express = require('express');
const { xray } = require('@node-xray/express');
const app = express();
app.use(xray());
app.listen(3000);
// Dashboard: http://localhost:3000/node-xrayRequirements
- Node.js >= 20.18
- Express ^4.19 || ^5, Fastify ^4 || ^5, or NestJS ^10
@node-xray/nestjs@0.3.0
Minor Changes
-
52b70ca: Fix five critical defects found in an internal implementation audit:
- Packaging: tsup no longer inlines
@node-xray/coreinto adapter dists (pnpm workspace symlinks defeatedskipNodeModulesBundle, shipping a private copy of core and an undeclaredrequire('ws')that crashed the published fastify/nestjs packages under pnpm). Workspace packages andwsare now externalized;rxjsis a declared NestJS peer dependency; packaging regression tests parse each dist and verify every bare require is declared. - AsyncLocalStorage context: all three adapters now wrap downstream execution in the request context —
getContext()works inside handlers (acrossawaitand timers), andwithTags()tags persist onto the finishedRequestRecordvia the newRECORD_TAGS_REFaccumulator. - Custom
path: the dashboard client derives its WebSocket endpoint fromlocation.pathnameinstead of a hardcoded/node-xray, so custom mount paths (e.g. the examples'/_xray) get live data. - Auth: the dashboard HTML and static assets served by the Express middleware, Fastify routes, and NestJS listener are now gated by the configured
auth(401 +WWW-Authenticatefor basic). Core gainsverifyDashboardAuth()and aserveHttp: falsemount option so exactly one writer owns each dashboard response. enabled: false: Express and Fastify adapters are true no-ops when disabled — no more per-requestonErrorspam from the muted core.
- Packaging: tsup no longer inlines
Patch Changes
@node-xray/fastify@0.3.0
Minor Changes
-
52b70ca: Fix five critical defects found in an internal implementation audit:
- Packaging: tsup no longer inlines
@node-xray/coreinto adapter dists (pnpm workspace symlinks defeatedskipNodeModulesBundle, shipping a private copy of core and an undeclaredrequire('ws')that crashed the published fastify/nestjs packages under pnpm). Workspace packages andwsare now externalized;rxjsis a declared NestJS peer dependency; packaging regression tests parse each dist and verify every bare require is declared. - AsyncLocalStorage context: all three adapters now wrap downstream execution in the request context —
getContext()works inside handlers (acrossawaitand timers), andwithTags()tags persist onto the finishedRequestRecordvia the newRECORD_TAGS_REFaccumulator. - Custom
path: the dashboard client derives its WebSocket endpoint fromlocation.pathnameinstead of a hardcoded/node-xray, so custom mount paths (e.g. the examples'/_xray) get live data. - Auth: the dashboard HTML and static assets served by the Express middleware, Fastify routes, and NestJS listener are now gated by the configured
auth(401 +WWW-Authenticatefor basic). Core gainsverifyDashboardAuth()and aserveHttp: falsemount option so exactly one writer owns each dashboard response. enabled: false: Express and Fastify adapters are true no-ops when disabled — no more per-requestonErrorspam from the muted core.
- Packaging: tsup no longer inlines
Patch Changes
@node-xray/express@0.3.0
Minor Changes
-
52b70ca: Fix five critical defects found in an internal implementation audit:
- Packaging: tsup no longer inlines
@node-xray/coreinto adapter dists (pnpm workspace symlinks defeatedskipNodeModulesBundle, shipping a private copy of core and an undeclaredrequire('ws')that crashed the published fastify/nestjs packages under pnpm). Workspace packages andwsare now externalized;rxjsis a declared NestJS peer dependency; packaging regression tests parse each dist and verify every bare require is declared. - AsyncLocalStorage context: all three adapters now wrap downstream execution in the request context —
getContext()works inside handlers (acrossawaitand timers), andwithTags()tags persist onto the finishedRequestRecordvia the newRECORD_TAGS_REFaccumulator. - Custom
path: the dashboard client derives its WebSocket endpoint fromlocation.pathnameinstead of a hardcoded/node-xray, so custom mount paths (e.g. the examples'/_xray) get live data. - Auth: the dashboard HTML and static assets served by the Express middleware, Fastify routes, and NestJS listener are now gated by the configured
auth(401 +WWW-Authenticatefor basic). Core gainsverifyDashboardAuth()and aserveHttp: falsemount option so exactly one writer owns each dashboard response. enabled: false: Express and Fastify adapters are true no-ops when disabled — no more per-requestonErrorspam from the muted core.
- Packaging: tsup no longer inlines
Patch Changes
@node-xray/dashboard@0.2.2
Patch Changes
-
88305f1: Dashboard "clear" now clears the server-side ring buffer too — previously it only wiped the browser's copy, so reloading the page brought the whole history back from the snapshot. The client sends a
{ v: 1, t: 'clear' }frame; the server empties the store and rebroadcasts an empty snapshot to every connected tab (documented in docs/EVENTS.md, covered by new WS contract tests). Malformed or unknown client frames are dropped without affecting the socket.Dashboard layout polish: the page now fills the full browser viewport (an unsized
html/bodychain made the root collapse to its 600px min-height, leaving dead space below), the root's border-radius is removed, and the Runtime panels show muted placeholder hints ("select a request to inspect", "idle") instead of blank canvas when no request is selected.Fix a long-standing dashboard crash: the reset path emptied
#loop-box, deleting the Event Loop ring and labels from the DOM, so everyloopframe (twice a second) threwTypeError: Cannot set properties of nullinrenderLoopand the Event Loop panel rendered as an empty rectangle. The loop box is no longer cleared (it is process telemetry, not per-request state) andrenderLoopis null-safe.Dashboard assets are now served with
cache-control: no-cachein the Express and Fastify adapters (previouslymax-age=3600) — an hour-long browser cache kept stale, crashing bundles alive across dashboard updates until a hard refresh. -
52b70ca: Fix five critical defects found in an internal implementation audit:
- Packaging: tsup no longer inlines
@node-xray/coreinto adapter dists (pnpm workspace symlinks defeatedskipNodeModulesBundle, shipping a private copy of core and an undeclaredrequire('ws')that crashed the published fastify/nestjs packages under pnpm). Workspace packages andwsare now externalized;rxjsis a declared NestJS peer dependency; packaging regression tests parse each dist and verify every bare require is declared. - AsyncLocalStorage context: all three adapters now wrap downstream execution in the request context —
getContext()works inside handlers (acrossawaitand timers), andwithTags()tags persist onto the finishedRequestRecordvia the newRECORD_TAGS_REFaccumulator. - Custom
path: the dashboard client derives its WebSocket endpoint fromlocation.pathnameinstead of a hardcoded/node-xray, so custom mount paths (e.g. the examples'/_xray) get live data. - Auth: the dashboard HTML and static assets served by the Express middleware, Fastify routes, and NestJS listener are now gated by the configured
auth(401 +WWW-Authenticatefor basic). Core gainsverifyDashboardAuth()and aserveHttp: falsemount option so exactly one writer owns each dashboard response. enabled: false: Express and Fastify adapters are true no-ops when disabled — no more per-requestonErrorspam from the muted core.
- Packaging: tsup no longer inlines
-
Updated dependencies [88305f1]
-
Updated dependencies [d77d8d5]
-
Updated dependencies [52b70ca]
- @node-xray/core@0.4.0
@node-xray/core@0.4.0
Minor Changes
-
88305f1: Dashboard "clear" now clears the server-side ring buffer too — previously it only wiped the browser's copy, so reloading the page brought the whole history back from the snapshot. The client sends a
{ v: 1, t: 'clear' }frame; the server empties the store and rebroadcasts an empty snapshot to every connected tab (documented in docs/EVENTS.md, covered by new WS contract tests). Malformed or unknown client frames are dropped without affecting the socket.Dashboard layout polish: the page now fills the full browser viewport (an unsized
html/bodychain made the root collapse to its 600px min-height, leaving dead space below), the root's border-radius is removed, and the Runtime panels show muted placeholder hints ("select a request to inspect", "idle") instead of blank canvas when no request is selected.Fix a long-standing dashboard crash: the reset path emptied
#loop-box, deleting the Event Loop ring and labels from the DOM, so everyloopframe (twice a second) threwTypeError: Cannot set properties of nullinrenderLoopand the Event Loop panel rendered as an empty rectangle. The loop box is no longer cleared (it is process telemetry, not per-request state) andrenderLoopis null-safe.Dashboard assets are now served with
cache-control: no-cachein the Express and Fastify adapters (previouslymax-age=3600) — an hour-long browser cache kept stale, crashing bundles alive across dashboard updates until a hard refresh. -
52b70ca: Fix five critical defects found in an internal implementation audit:
- Packaging: tsup no longer inlines
@node-xray/coreinto adapter dists (pnpm workspace symlinks defeatedskipNodeModulesBundle, shipping a private copy of core and an undeclaredrequire('ws')that crashed the published fastify/nestjs packages under pnpm). Workspace packages andwsare now externalized;rxjsis a declared NestJS peer dependency; packaging regression tests parse each dist and verify every bare require is declared. - AsyncLocalStorage context: all three adapters now wrap downstream execution in the request context —
getContext()works inside handlers (acrossawaitand timers), andwithTags()tags persist onto the finishedRequestRecordvia the newRECORD_TAGS_REFaccumulator. - Custom
path: the dashboard client derives its WebSocket endpoint fromlocation.pathnameinstead of a hardcoded/node-xray, so custom mount paths (e.g. the examples'/_xray) get live data. - Auth: the dashboard HTML and static assets served by the Express middleware, Fastify routes, and NestJS listener are now gated by the configured
auth(401 +WWW-Authenticatefor basic). Core gainsverifyDashboardAuth()and aserveHttp: falsemount option so exactly one writer owns each dashboard response. enabled: false: Express and Fastify adapters are true no-ops when disabled — no more per-requestonErrorspam from the muted core.
- Packaging: tsup no longer inlines
Patch Changes
- d77d8d5: Ignore Chrome DevTools'
/.well-known/appspecific/probe requests by default — with DevTools open, Chrome fires one per page load and each showed up in the dashboard as a 404, polluting the request list and error count.