JavaScript Integration

Before you start

Create the project with the `JavaScript / TypeScript` integration type.

What you need	Why it matters
Project API token	Authenticates your app when sending events
Logister instance base URL	Used to build the ingest, check-in, and deployment endpoints
Node 18+ app	Lets you run the published `logister-js` package
Optional GitHub App installation	Lets Logister use `repository`, `commit_sha`, `branch`, and deployment records for source excerpts and deploy links

What you get

Use the JavaScript integration to connect server-side errors, logs, request timing, and deploy context.

Need	What appears in Logister
Catch Express request failures	Inbox issues with structured JavaScript stack frames, request context, route or URL metadata, runtime details, and chained causes when available.
Keep console output visible	`console` activity in the project activity feed, with `console.error(Error)` reported as error events.
Measure server and browser work	Transaction and span events for request handlers, scripts, jobs, browser page loads, resources, and custom operations that feed the performance view.
Correlate logs and errors	Request, trace, session, or user identifiers shared across log and error events so related logs appear in the detail pane.
Resolve source and deploy history	`repository`, `commit_sha`, `branch`, release, and deployment records that let Logister show source excerpts, GitHub links, and "started after deploy" context when a GitHub repository is connected to the project.
Monitor recurring jobs	Check-ins from workers and scripts that show up as monitor status.

Setup flow

Recommended installation path

Create the project and generate an API key.
Install logister-js in the JavaScript or TypeScript app.
Configure the client with the project API key, base URL, environment, release, and source context.
Add the Express middleware and error handler if you run Express, or start with direct shared-client calls in your framework.
Attach instrumentConsole() if you want standard console activity to flow into Logister too.
Use the shared client for custom metrics, logs, transactions, spans, and check-ins.
From CI/CD, call recordDeployment() after a successful deploy so releases map to exact commits.

Tip

JavaScript teams usually get the fastest value by starting with uncaught errors plus request or job timing, then adding request spans, console capture, browser timing, source context, deployment records, and custom events once the noisy operational paths are under control.

Install

Install `logister-js` from npm.

Use the published npm package when you want a Node or TypeScript service to send errors, logs, metrics, transactions, spans, and check-ins into Logister with the package manager your team already uses. The npm listing is the canonical package page for install commands, version history, and package metadata.

shell

npm install logister-js
yarn add logister-js
pnpm add logister-js
bun add logister-js

typescript

import { LogisterClient } from "logister-js";

const client = new LogisterClient({
  apiKey: process.env.LOGISTER_API_KEY ?? "",
  baseUrl: process.env.LOGISTER_BASE_URL ?? "https://your-logister-host.example",
  environment: process.env.LOGISTER_ENVIRONMENT,
  release: process.env.LOGISTER_RELEASE,
  repository: process.env.LOGISTER_REPOSITORY,
  commitSha: process.env.LOGISTER_COMMIT_SHA ?? process.env.GITHUB_SHA,
  branch: process.env.LOGISTER_BRANCH ?? process.env.GITHUB_REF_NAME
});

View the npm package listing for version history and install details.
Use GitHub for source, issues, and changelog history.
Use the main Logister repo if you want to run the self-hosted hub yourself.

Source and deployments

Send repository, commit, branch, and deployment records when you have them.

If the project is connected to the GitHub App, Logister can use event source context to resolve stack frames to repository files. Deployment records are stronger than event-only release strings because they tell Logister which commit was deployed for a release and environment.

typescript

await client.recordDeployment({
  release: process.env.LOGISTER_RELEASE ?? "checkout@2026.06.18",
  environment: process.env.LOGISTER_ENVIRONMENT ?? "production",
  repository: process.env.LOGISTER_REPOSITORY ?? "acme/checkout",
  commitSha: process.env.LOGISTER_COMMIT_SHA ?? process.env.GITHUB_SHA ?? "",
  branch: process.env.LOGISTER_BRANCH ?? process.env.GITHUB_REF_NAME,
  deployedAt: new Date(),
  releaseTag: process.env.GITHUB_REF_NAME,
  workflowRunUrl: process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID
    ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
    : undefined
});

Field	Set it from	Used for
`repository`	`LOGISTER_REPOSITORY` or `GITHUB_REPOSITORY`	Finds the GitHub repository connected to the project.
`commitSha`	`LOGISTER_COMMIT_SHA` or `GITHUB_SHA`	Resolves stack frames and deployment context to the exact commit.
`branch`	`LOGISTER_BRANCH` or `GITHUB_REF_NAME`	Falls back when an event has no commit or deployment record yet.
`release`	Your app version, build ID, tag, or package version	Connects event filters, release health, and deployments.

Verify it

After a deploy, send one test error with the same release. Open the event detail and check for source lookup status, deployment context, and GitHub links. If source is missing, confirm the GitHub App is installed, linked to the project, and the repository is connected; then check that the event has repository plus either commit_sha or a matching deployment record.

Express

Capture requests and uncaught route errors.

typescript

import express from "express";
import { LogisterClient } from "logister-js";
import {
  createLogisterErrorHandler,
  createLogisterMiddleware
} from "logister-js/express";

const app = express();
const client = new LogisterClient({
  apiKey: process.env.LOGISTER_API_KEY ?? "",
  baseUrl: process.env.LOGISTER_BASE_URL ?? "https://your-logister-host.example"
});

app.use(createLogisterMiddleware({ client, captureRequestSpans: true }));

app.get("/orders/:id", async (_req, res) => {
  res.json({ ok: true });
});

app.use(createLogisterErrorHandler({ client }));

Important

Register the Logister request middleware before your routes and the Logister error handler before your final Express error response middleware. Set captureRequestSpans: true when you want completed requests to appear in request load waterfall charts.

Browser timing

Capture page-load and resource timing from browser code.

typescript

import { LogisterClient } from "logister-js";
import { capturePageLoad } from "logister-js/browser";

const client = new LogisterClient({
  apiKey: window.LOGISTER_API_KEY,
  baseUrl: "https://your-logister-host.example",
  environment: "production",
  release: window.LOGISTER_RELEASE
});

await capturePageLoad(client, {
  route: window.location.pathname,
  includeResources: true,
  maxResources: 20
});

The browser entrypoint sends a root browser span for page load timing and optional child resource spans for images, scripts, stylesheets, and API calls exposed through the browser performance API.

Console logging

Forward console output without rewriting every call site.

typescript

import { LogisterClient } from "logister-js";
import { instrumentConsole } from "logister-js/console";

const client = new LogisterClient({
  apiKey: process.env.LOGISTER_API_KEY ?? "",
  baseUrl: process.env.LOGISTER_BASE_URL ?? "https://your-logister-host.example"
});

const restoreConsole = instrumentConsole(client, {
  context: { service: "worker" }
});

console.warn("Queue backlog rising", { queue: "emails" });

restoreConsole();

This is the low-friction path when a JavaScript service already leans on console.warn() and console.error() during jobs, scripts, and server-side debugging. The console integration sends console.debug/info/log/warn/error calls as Logister log events and records console.error() calls that include an Error object as error events.

Other frameworks

Use the shared client even if your app is not on Express.

logister-js is first-class for Node, Express, and TypeScript apps today, but other JavaScript developers are not blocked. If your framework can run JavaScript and make HTTP requests, you can still send events into Logister.

Scenario	Recommended path
Custom Node server, Fastify, scripts, workers, cron jobs	Use the shared `LogisterClient` directly and call `captureException`, `captureMessage`, `captureMetric`, `captureTransaction`, `captureSpan`, or `checkIn`.
Framework without a first-class Logister middleware yet	Wrap the framework's request lifecycle or error hooks with the shared client, then add custom events where you need more context.
Runtime where you do not want the SDK yet	Send JSON directly to the HTTP API using the project API key.

typescript

import { LogisterClient } from "logister-js";

const client = new LogisterClient({
  apiKey: process.env.LOGISTER_API_KEY ?? "",
  baseUrl: process.env.LOGISTER_BASE_URL ?? "https://your-logister-host.example"
});

try {
  await runJob();
} catch (error) {
  await client.captureException(error, {
    context: { job: "nightly-import" }
  });
}

await client.captureTransaction("nightly-import", 1824, {
  context: { environment: process.env.NODE_ENV ?? "development" }
});

Need another framework?

If you are on Next.js, NestJS, Fastify, or another JavaScript framework, start with the shared client or the HTTP API. That gives you working ingestion today while the package grows more framework-specific integrations over time.

Custom events

Report metrics, logs, spans, and check-ins from the same client.

typescript

await client.captureMetric("cache.hit_rate", 0.98, {
  unit: "ratio",
  traceId: "trace-123",
  requestId: "req-123",
  context: { service: "checkout-api" }
});

await client.captureSpan("render checkout", 82.1, {
  kind: "render",
  status: "ok",
  traceId: "trace-123",
  parentSpanId: "span-root",
  requestId: "req-123",
  context: { route: "POST /checkout" }
});

await client.captureMessage("Queue backlog rising", {
  level: "warn",
  context: { queue: "emails" }
});

await client.checkIn("nightly-import", "ok", {
  release: "worker@2026.05.21",
  durationMs: 842.7,
  expectedIntervalSeconds: 3600,
  traceId: "trace-123",
  requestId: "req-123",
  context: { environment: "production" }
});

Captured JavaScript exceptions include structured stack frames and chained causes when the original error uses cause. Capture options support per-event environment, release, trace ID, request ID, session ID, and user ID fields; span options add span ID, parent span ID, kind, status, and start/end timestamps; metric events include structured metric context; check-ins send release and monitor metadata to the check-in endpoint.

Verification

Activity page checklist
transactions visible
request spans visible
uncaught route errors visible
console logging events visible
browser page-load spans visible if enabled
custom metrics, spans, and check-ins present

Integrate a JavaScript or TypeScript app with Logister.

Create the project with the JavaScript / TypeScript integration type.

Use the JavaScript integration to connect server-side errors, logs, request timing, and deploy context.

Recommended installation path

Tip

Install logister-js from npm.

Send repository, commit, branch, and deployment records when you have them.

Verify it

Capture requests and uncaught route errors.

Important

Capture page-load and resource timing from browser code.

Forward console output without rewriting every call site.

Use the shared client even if your app is not on Express.

Need another framework?

Report metrics, logs, spans, and check-ins from the same client.

Create the project with the `JavaScript / TypeScript` integration type.

Install `logister-js` from npm.