Getting started

This guide walks through Station from first install to a production-ready setup with persistence, recurring jobs, multi-step pipelines, and lifecycle observers.

Prerequisites

• Node.js 18 or later
• A package manager (pnpm, npm, or yarn)
• A TypeScript project configured for ES modules ("type": "module" in your package.json)

1. Install

pnpm add station-signal station-kit

station-signal is where you define jobs; station-kit is how you run them — it is Station's entry point, and it wires the runners, dashboard, and API for you.

2. Define a signal

A signal is a named, type-safe background job definition. It declares an input schema, execution constraints, and a handler function using a builder pattern. Signals are defined in their own files so the runner can auto-discover them.

// signals/send-email.tsimport { signal, z } from "station-signal"; export const sendEmail = signal("sendEmail")  .input(z.object({    to: z.string(),    subject: z.string(),    body: z.string(),  }))  .timeout(30_000)  .retries(2)  .run(async (input) => {    console.log(`Sending email to ${input.to}`);    // Your email sending logic here  });

Builder methods

3. Run it

Station apps are configured in one file and started with one command. defineConfig points Station at your signal directory; the station CLI discovers what is there and runs it.

// station.config.tsimport { defineConfig } from "station-kit"; export default defineConfig({  signalsDir: "./signals",});

npx station

That one command starts the signal runner, serves the dashboard on http://localhost:4400, and exposes the authenticated v1 API — so you can watch runs, inspect logs, and trigger jobs without writing any of that yourself. Add broadcastsDir and beaconsDir later and the matching runners are wired the same way, including the shutdown ordering between them.

Embedding: constructing a runner yourself

SignalRunner is also exported directly, for the cases station-kit deliberately doesn't cover: embedding Station inside a server process you already own, a headless worker that must not bind a port, or tests. Reach for it only then — you take on wiring the storage, subscribers, and shutdown ordering yourself.

// runner.ts — the escape hatch, not the defaultimport path from "node:path";import { SignalRunner } from "station-signal"; const runner = new SignalRunner({  signalsDir: path.join(import.meta.dirname, "signals"),}); runner.start();

4. Trigger a signal

import { sendEmail } from "./signals/send-email.js"; const runId = await sendEmail.trigger({  to: "user@example.com",  subject: "Welcome",  body: "Thanks for signing up.",}); console.log(`Enqueued run: ${runId}`);

5. Add persistence (SQLite)

The default in-memory adapter loses all jobs on process restart. For anything beyond local development, use the SQLite adapter.

pnpm add station-adapter-sqlite

// station.config.tsimport { defineConfig } from "station-kit";import { SqliteAdapter } from "station-adapter-sqlite"; export default defineConfig({  signalsDir: "./signals",  adapter: new SqliteAdapter({ dbPath: "./jobs.db" }),});

Shared adapter for separate processes

When triggers happen in a different process than the runner (common in web servers), both processes need access to the same adapter instance. Use the configure() function to set a global default.

// config.tsimport { configure } from "station-signal";import { SqliteAdapter } from "station-adapter-sqlite"; configure({  adapter: new SqliteAdapter({ dbPath: "./jobs.db" }),});

Import the config module before any signal imports in your trigger process:

// In your web server or trigger processimport "./config.js"; // Run configure() firstimport { sendEmail } from "./signals/send-email.js"; await sendEmail.trigger({  to: "user@example.com",  subject: "Order confirmation",  body: "Your order has been placed.",});

6. Recurring signals

Signals can run on a fixed interval. The runner handles scheduling, re-enqueuing, and retry logic automatically.

// signals/health-check.tsimport { signal } from "station-signal"; export const healthCheck = signal("healthCheck")  .every("5m")  .run(async () => {    const res = await fetch("https://api.example.com/health");    if (!res.ok) throw new Error(`Health check failed: ${res.status}`);  });

7. Multi-step signals

For pipelines where each stage transforms data for the next, use steps instead of a single handler.

// signals/process-order.tsimport { signal, z } from "station-signal"; export const processOrder = signal("processOrder")  .input(z.object({ orderId: z.string(), amount: z.number() }))  .step("validate", async (input) => {    if (input.amount <= 0) throw new Error("Invalid amount");    return { ...input, validated: true };  })  .step("charge", async (prev) => {    const chargeId = await payments.charge(prev.amount);    return { orderId: prev.orderId, chargeId };  })  .step("notify", async (prev) => {    await notify(`Order ${prev.orderId} charged: ${prev.chargeId}`);  })  .build();

8. Subscribers

Subscribers observe the signal lifecycle. Use them for logging, metrics, alerting, or any side effect that should not live inside a handler.

Register them in station.config.ts. Yours run alongside the subscribers Station wires for the dashboard and event stream — additive, never instead of them.

// station.config.tsimport { defineConfig } from "station-kit";import { ConsoleSubscriber } from "station-signal"; export default defineConfig({  signalsDir: "./signals",  subscribers: {    signal: [      new ConsoleSubscriber(), // Built-in: logs all events to stdout      {        onRunStarted({ run }) {          metrics.increment("signal.started", { name: run.signalName });        },        onRunCompleted({ run }) {          metrics.increment("signal.completed", { name: run.signalName });        },        onRunFailed({ run, error }) {          alerting.send(`Signal ${run.signalName} failed: ${error}`);        },      },    ],    // broadcast: [...] and beacon: [...] take their own subscriber shapes  },});

Next steps