CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-std-env

Runtime agnostic JavaScript utility library for environment detection, platform information, CI/CD provider detection, and runtime identification.

Pending
Overview
Eval results
Files

runtime-detection.mddocs/

Runtime Detection

JavaScript runtime identification following the WinterCG Runtime Keys proposal, with support for Node.js, Deno, Bun, and various edge computing platforms.

Capabilities

Node.js Runtime Detection

Detects Node.js runtime, including compatibility mode in other runtimes.

/**
 * Indicates if running in Node.js or a Node.js compatible runtime
 * Note: When running code in Bun and Deno with Node.js compatibility mode,
 * isNode flag will be true, indicating running in a Node.js compatible runtime.
 * Use runtime === "node" for strict Node.js runtime check.
 */
const isNode: boolean;

Usage Examples:

import { isNode, runtime } from "std-env";

if (isNode) {
  console.log("Running in Node.js or Node.js compatible runtime");
  // Can use Node.js APIs
  const fs = require('fs');
}

// Strict Node.js check
if (runtime === "node") {
  console.log("Running in actual Node.js runtime");
}

Deno Runtime Detection

Detects Deno runtime based on global Deno object.

/**
 * Indicates if running in Deno runtime
 * Based on presence of globalThis.Deno
 */
const isDeno: boolean;

Usage Examples:

import { isDeno } from "std-env";

if (isDeno) {
  console.log("Running in Deno");
  // Use Deno-specific APIs
  const text = await Deno.readTextFile("./file.txt");
  // Use Deno permissions
  await Deno.permissions.query({ name: "read" });
}

Bun Runtime Detection

Detects Bun runtime based on global Bun object or process versions.

/**
 * Indicates if running in Bun runtime
 * Based on globalThis.Bun or process.versions.bun
 */
const isBun: boolean;

Usage Examples:

import { isBun } from "std-env";

if (isBun) {
  console.log("Running in Bun");
  // Use Bun-specific APIs
  const file = Bun.file("./data.json");
  const data = await file.json();
}

Fastly Compute Runtime Detection

Detects Fastly Compute@Edge runtime.

/**
 * Indicates if running in Fastly Compute@Edge runtime
 * Based on globalThis.fastly
 */
const isFastly: boolean;

Usage Examples:

import { isFastly } from "std-env";

if (isFastly) {
  console.log("Running in Fastly Compute@Edge");
  // Use Fastly-specific APIs
  // Handle edge requests
}

Netlify Edge Runtime Detection

Detects Netlify Edge Functions runtime.

/**
 * Indicates if running in Netlify Edge Functions runtime
 * Based on globalThis.Netlify
 */
const isNetlify: boolean;

Usage Examples:

import { isNetlify } from "std-env";

if (isNetlify) {
  console.log("Running in Netlify Edge Functions");
  // Use Netlify-specific context
  // Access geo-location data
}

Vercel Edge Runtime Detection

Detects Vercel Edge Runtime (EdgeLight).

/**
 * Indicates if running in EdgeLight (Vercel Edge) runtime
 * Based on globalThis.EdgeRuntime
 */
const isEdgeLight: boolean;

Usage Examples:

import { isEdgeLight } from "std-env";

if (isEdgeLight) {
  console.log("Running in Vercel Edge Runtime");
  // Use edge-specific optimizations
  // Handle streaming responses
}

Cloudflare Workers Runtime Detection

Detects Cloudflare Workers runtime based on user agent.

/**
 * Indicates if running in Cloudflare Workers runtime
 * Based on navigator.userAgent === "Cloudflare-Workers"
 */
const isWorkerd: boolean;

Usage Examples:

import { isWorkerd } from "std-env";

if (isWorkerd) {
  console.log("Running in Cloudflare Workers");
  // Use Cloudflare Workers APIs
  // Access KV storage
  // Handle fetch events
}

Runtime Information

Structured runtime information following WinterCG Runtime Keys proposal.

/**
 * Current runtime name following WinterCG Runtime Keys proposal
 * Empty string if runtime cannot be determined
 */
const runtime: RuntimeName;

/**
 * Detected runtime information object
 * undefined if runtime cannot be determined
 */
const runtimeInfo: RuntimeInfo | undefined;

type RuntimeName = 
  | "workerd"      // Cloudflare Workers
  | "deno"         // Deno
  | "netlify"      // Netlify Edge Functions  
  | "node"         // Node.js
  | "bun"          // Bun
  | "edge-light"   // Vercel Edge Runtime
  | "fastly"       // Fastly Compute@Edge
  | "";            // Unknown/undetected

interface RuntimeInfo {
  name: RuntimeName;
}

Usage Examples:

import { runtime, runtimeInfo } from "std-env";

console.log(`Detected runtime: ${runtime}`);

// Runtime-specific logic
switch (runtime) {
  case "node":
    console.log("Node.js specific features available");
    break;
  case "deno":
    console.log("Deno specific features available");
    break;
  case "bun":
    console.log("Bun specific features available");
    break;
  case "workerd":
    console.log("Cloudflare Workers features available");
    break;
  case "edge-light":
    console.log("Vercel Edge Runtime features available");
    break;
  default:
    console.log("Unknown or undetected runtime");
}

// Check if runtime info is available
if (runtimeInfo) {
  console.log(`Runtime info: ${JSON.stringify(runtimeInfo)}`);
}

Runtime Detection Priority

Runtime detection follows this priority order (first match wins):

  1. Netlify (isNetlify) - globalThis.Netlify
  2. EdgeLight (isEdgeLight) - globalThis.EdgeRuntime
  3. Cloudflare Workers (isWorkerd) - navigator.userAgent === "Cloudflare-Workers"
  4. Fastly (isFastly) - globalThis.fastly
  5. Deno (isDeno) - globalThis.Deno
  6. Bun (isBun) - globalThis.Bun or process.versions.bun
  7. Node.js (isNode) - process.release.name === "node"

Runtime-Specific Usage Patterns

Cross-Runtime File Reading

import { runtime, isNode, isDeno, isBun } from "std-env";

async function readFile(path: string): Promise<string> {
  switch (runtime) {
    case "node":
    case "bun":
      const fs = await import('fs/promises');
      return fs.readFile(path, 'utf-8');
    
    case "deno":
      return Deno.readTextFile(path);
    
    default:
      throw new Error(`File reading not supported in ${runtime} runtime`);
  }
}

Runtime-Specific HTTP Clients

import { runtime } from "std-env";

async function fetchData(url: string) {
  switch (runtime) {
    case "node":
      // Use Node.js native fetch (v18+) or polyfill
      return fetch(url);
    
    case "deno":
    case "bun":
    case "workerd":
    case "edge-light":
      // Native fetch available
      return fetch(url);
    
    default:
      throw new Error(`HTTP requests not supported in ${runtime} runtime`);
  }
}

Install with Tessl CLI

npx tessl i tessl/npm-std-env

docs

environment-detection.md

environment-variables.md

index.md

platform-detection.md

provider-detection.md

runtime-detection.md

tile.json