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.

This page covers the Node runtime. For local execution inside a web app, follow the experimental browser guide instead: it uses BrowserStation and IndexedDB with explicit worker hosts.

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-daemonpnpm add -D station-runtime-cli station-dashboard

station-signal is where you define jobs; station-daemon is how you run them — it is Station's entry point for the runners and API. The CLI and dashboard are separate clients.

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 stationd process discovers what is there and runs it.

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

pnpm exec stationd

That command starts the signal runner and the v1 API on http://localhost:4400. Add broadcastsDir and beaconsDir later and the matching runners are wired the same way, including the shutdown ordering between them.

# Run in another terminal; the dashboard has its own lifecycleSTATION_DAEMON_URL=http://127.0.0.1:4400 PORT=4401 STATION_DASHBOARD_HOST=127.0.0.1 pnpm exec station-dashboard

Open http://127.0.0.1:4401. A remote daemon uses the same dashboard with a different STATION_DAEMON_URL.

Embedding: constructing a runner yourself

SignalRunner is also exported directly, for the cases station-daemon 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-daemon";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-daemon";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