How SXO Detects Which JavaScript Runtime (Node, Bun, or Deno) Is Being Used

SXO determines the executing runtime by checking for global objects in a specific order—globalThis.Bun for Bun, globalThis.Deno for Deno, and falling back to Node.js—using the detectRuntime() function in src/js/server/shared/runtime.js.

SXO is a universal JavaScript framework designed to run seamlessly across multiple runtimes. To achieve this compatibility, the gc-victor/sxo repository implements a lightweight detection mechanism that identifies whether the code is executing in Node.js, Bun, or Deno. This capability allows SXO to automatically load runtime-specific adapters without manual configuration.

The Runtime Detection Algorithm

The core detection logic resides in src/js/server/shared/runtime.js. The detectRuntime() function follows a strict precedence order to identify the current environment by checking for runtime-specific global objects.

Detection Precedence Order

The function evaluates three conditions in sequence:

1. Bun – Detected first by verifying the existence of globalThis.Bun.
2. Deno – Detected next by checking for globalThis.Deno.
3. Node.js – If neither global exists, the function defaults to returning "node".

// src/js/server/shared/runtime.js
export function detectRuntime() {
    // Bun provides a global `Bun` object
    if (typeof globalThis.Bun !== "undefined") {
        return "bun";
    }

    // Deno provides a global `Deno` object
    if (typeof globalThis.Deno !== "undefined") {
        return "deno";
    }

    // Fallback is Node.js
    return "node";
}

Boolean Helper Functions for Runtime Checks

In addition to detectRuntime(), the src/js/server/shared/runtime.js module exports three predicate functions that allow for direct boolean checks. These helpers test the same global objects without requiring string comparison.

export function isBun()   { return typeof globalThis.Bun !== "undefined"; }
export function isDeno()  { return typeof globalThis.Deno !== "undefined"; }
export function isNode()  { return !isBun() && !isDeno(); }

These functions enable concise conditional logic when you need to execute runtime-specific code paths without first storing the runtime name in a variable.

Where Runtime Detection Is Used in SXO

The runtime detection mechanism drives dynamic imports of platform-specific adapters throughout the SXO codebase. This ensures that the correct server implementation loads automatically based on the detected environment.

Production and Development Server Entry Points

Both the production and development server entry points utilize detectRuntime() to import runtime-specific adapters. The src/js/server/prod.js and src/js/server/dev.js files follow an identical pattern:

// src/js/server/prod.js (excerpt)
import { detectRuntime } from "./shared/runtime.js";

const runtime = detectRuntime();
console.log(`▶ Starting production server with ${runtime} adapter`);
await import(`./prod/${runtime}.js`);

This pattern allows SXO to maintain separate adapter implementations for each runtime (e.g., prod/node.js, prod/bun.js, prod/deno.js) while presenting a universal entry point to the user.

CLI Process Spawning

The CLI spawn helper located at src/js/cli/spawn.js also leverages detectRuntime() to determine which interpreter to use when launching child processes. This ensures that subprocesses spawn with the same runtime as the parent process, maintaining consistency across the application lifecycle.

Practical Implementation Examples

The following examples demonstrate how to utilize SXO's runtime detection utilities in your own code.

Example 1: Manual Runtime Checking

Import the detection utilities to execute runtime-specific logic within your application:

import { detectRuntime, isNode, isBun, isDeno } from "./server/shared/runtime.js";

const runtime = detectRuntime();
console.log(`Running on ${runtime}`);

if (isNode()) {
  // Node‑specific logic
}
if (isBun()) {
  // Bun‑specific logic
}
if (isDeno()) {
  // Deno‑specific logic
}

Example 2: Custom CLI Script

Create a standalone script that identifies the current runtime:

#!/usr/bin/env node
import { detectRuntime } from "./src/js/server/shared/runtime.js";

const runtime = detectRuntime();
console.log(`SXO started with the ${runtime} runtime`);

Example 3: Dynamic Import Based on Runtime

Load runtime-specific modules dynamically using the detected environment:

import { detectRuntime } from "./src/js/server/shared/runtime.js";

const runtime = detectRuntime();
const { startServer } = await import(`./src/js/server/${runtime}/helper.js`);
await startServer();

Summary

• SXO detects JavaScript runtimes via the detectRuntime() function in src/js/server/shared/runtime.js.
• The detection follows a strict precedence: Bun (globalThis.Bun) → Deno (globalThis.Deno) → Node.js (fallback).
• Boolean helper functions isBun(), isDeno(), and isNode() provide direct predicate checks without string parsing.
• The detection drives dynamic imports in src/js/server/prod.js, src/js/server/dev.js, and src/js/cli/spawn.js to load runtime-specific adapters automatically.

Frequently Asked Questions

How does SXO prioritize which runtime to detect first?

SXO checks for globalThis.Bun first to identify Bun, then checks globalThis.Deno for Deno. If neither global object exists, it defaults to Node.js. This precedence ensures that newer runtimes with distinct global identifiers are recognized before falling back to the traditional Node.js environment.

Can I use SXO's runtime detection in my own application code?

Yes, you can import the utilities directly from src/js/server/shared/runtime.js. The module exports detectRuntime() for string-based checks and isBun(), isDeno(), and isNode() for boolean predicates. These functions allow you to write conditional logic that adapts to the specific runtime executing your code.

What happens if SXO encounters an unsupported JavaScript runtime?

If neither globalThis.Bun nor globalThis.Deno is present, SXO assumes the environment is Node.js. This fallback mechanism means that any runtime mimicking Node.js globals or any unrecognized environment will be treated as Node.js, potentially loading the Node-specific adapter. This design prioritizes stability but assumes Node.js compatibility for unknown environments.

Is the runtime detection mechanism reliable across different versions of Node, Bun, and Deno?

Yes, the detection relies on stable global objects (Bun and Deno) that are fundamental to their respective runtimes and have remained consistent across versions. Since these globals are unique identifiers built into the runtime engines themselves, checking typeof globalThis.Bun and typeof globalThis.Deno provides a robust and version-agnostic detection method.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}