Installation - Node.js

Before you start, create a project in the DockRay panel. Its settings hold the project token - the public identifier that goes into the ingest URL - and the API keys tab is where you generate a private key. The key is shown once, when it is generated: DockRay stores only its hash. If you do not have a project yet, start with Getting Started.

Requirements

• Node.js 18 or newer - the package uses the built-in fetch and has no dependencies,
• outbound HTTPS connections allowed.

The package is a server-side integration. There is no browser build, and there will not be one - authenticating with the panel requires the project's private key, and that key must stay on the server. Browser errors travel through your own application instead of through this package directly.

Installation

npm install @dockcodes/dock-ray

Edge runtimes

The package's main entry point imports node:fs, node:os and node:zlib, which an edge bundle - Next.js middleware, Cloudflare Workers, Vercel Edge - cannot resolve. Where the code runs outside a full Node process, import the separate entry point instead:

import { DockRayClient } from '@dockcodes/dock-ray/edge';

The API is identical. Events from this entry point lose stack source context and gzip compression, because the runtime has no filesystem and no zlib - nothing else changes.

Constructing the client

import { DockRayClient } from '@dockcodes/dock-ray';

const ray = new DockRayClient({
    token: process.env.RAY_TOKEN,
    privateKey: process.env.RAY_PRIVATE_KEY,
    environment: process.env.NODE_ENV,
    release: process.env.APP_VERSION,
});

Without a token and a key the constructor throws nothing - ray.enabled returns false, and every reporting call resolves to false without attempting a network connection. The package never reads any environment variable on its own - it is your own code, as in the example above, that decides where the token and key come from, so the client can be constructed unconditionally and the credentials left out of your local environment.

Reporting

try {
    await settle(order);
} catch (error) {
    await ray.captureException(error);
}

The first test

await ray.captureMessage('DockRay control message');

The message should appear in the panel under Errors for the project the token points at.