JavaScript/TypeScript SDK

The core Javascript SDK is lightweight and handles polling logic, caching behavior, and failure handling transparently. It has zero dependencies, is highly universal, and is fully compatible with Node.js, Next.js, Cloudflare Workers, Deno, Bun, and all modern browsers.

Installation

npm install @theruntimehq/js

Integration Example

You will need to provide a runtimeKey for your application. See the Runtime Keys documentation for details on where to find your key and how environments are separated.

Basic Example

import { RuntimeHQClient } from "@theruntimehq/js";

const client = new RuntimeHQClient({
  runtimeKey: "rt_prod_xxxxx"
});

async function loadDashboard() {
  const runtime = await client.getRuntime();
  const reports = runtime.getCapabilityState("advanced-reports");

  if (!reports || reports.state !== "OPERATIONAL") {
    console.log("Hiding advanced reports tab.");
  } else {
    console.log("Showing advanced reports tab.");
  }
}

loadDashboard();

Watch State Change Example

You can also watch for state changes in the background. The SDK will periodically synchronize with the edge and trigger the onUpdate callback whenever the state shifts.

client.watchRuntime({
  intervalSeconds: 60, // optional, defaults to 60 seconds
  onUpdate: (runtime) => {
    console.log(`State changed! New state: ${runtime.state}. Message: ${runtime.message}`);
  }
});

For more advanced use cases, check out the examples directory on GitHub.

Validating the Integration

After installing the SDK and integrating it into your application logic, validate how your application handles operational state transitions during peacetime.

Use Non-Production Simulation to safely test your integration:

1. Use a Non-Production Key: Initialize RuntimeHQClient with your application's non-production runtime key (rt_test_...) in staging or local development. See Runtime Keys for key management.
2. Declare Simulated State: In the RuntimeHQ Console, open your application and locate the Non-Production Simulation State panel. Choose a simulated state (DEGRADED, OUTAGE, or MAINTENANCE), target specific capabilities, and optionally add an operational message.
3. Verify State Handling: Confirm that your application code or background listeners (client.watchRuntime or client.getRuntime()) execute expected fallback paths—such as hiding degraded modules or surfacing operational notices.
4. Reset Simulation: Clear the simulation in the Console to return the non-production state to baseline.

Caching & Failure Handling

The SDK respects edge caching headers natively. If the user's connection drops or fails during a state synchronization attempt, the SDK will automatically return the last known good state along with a dataStatus indicator. This prevents aggressive UI disruptions and ensures the client application remains stable during networking failures.

Links & Resources:

• GitHub Repository
• NPM Package