Integration

Beacon for Node.js

Report incidents, update status, and send heartbeats — from any Node.js or TypeScript application. Zero dependencies.

$ npm install @beacon-status/node

Get started free

Quick Start

Up and running in three steps

1

Install

npm install @beacon-status/node

2

Configure

Add your credentials to .env

BEACON_API_TOKEN=your-token
BEACON_BASE_URL=https://api.beacon.example.com
BEACON_PAGE_SLUG=main

3

Initialize

Create a Beacon client instance

import { Beacon } from '@beacon-status/node';

const beacon = new Beacon({
  token: process.env.BEACON_API_TOKEN!,
  baseUrl: process.env.BEACON_BASE_URL,
  pageSlug: process.env.BEACON_PAGE_SLUG!,
});

Code Examples

TypeScript-first, always

Report an Incident

Create an incident on your status page from anywhere in your app.

await beacon.createIncident({
  title: 'Payment processing delays',
  impact: 'major',
  state: 'investigating',
  message: 'Stripe webhook delivery is delayed.',
});

Update Component Status

await beacon.updateComponent(componentId, {
  status: 'degraded',
});

Resolve an Incident

await beacon.resolveIncident(incidentId,
  'Webhook delivery restored.'
);

Heartbeat

import cron from 'node-cron';

cron.schedule('0 * * * *', async () => {
  await processInvoices();
  await beacon.heartbeat('invoice-processing-token');
});

Express Health Check

import { beaconHealthCheck } from '@beacon-status/node/express';

app.get('/health', beaconHealthCheck(beacon));

Error Handler

app.use((err, req, res, next) => {
  if (err.critical) {
    beacon.createIncident({
      title: `Critical: ${err.message}`,
      impact: 'critical',
    });
  }
  next(err);
});

Features

Built for the Node.js ecosystem

TypeScript-first

Full type definitions included. No @types package needed.

Framework-agnostic

Works with Express, Fastify, Next.js, NestJS, and more.

Automatic retries

Exponential backoff on transient failures out of the box.

Zero dependencies

Uses native fetch. No bloat in your node_modules.

ESM + CommonJS

Dual-format package. Import or require — both work.

Start monitoring your Node.js app

Install the package, add your token, and ship status updates from your codebase.

Create free account

Also available: Laravel →