Glossary / Runtime compatibility matrices

Runtime compatibility matrices

A runtime compatibility matrix records supported versions and environments for JavaScript execution outside or alongside the browser, such as Node.js, Deno, Bun, serverless platforms, embedded engines, and operating systems. It guides module format, API usage, native dependency builds, package metadata, CI, and deployment policy.

Defining support

List runtimes and version ranges, OS/CPU architectures, container base images, serverless provider/runtime generations, and relevant flags or permissions. Separate the runtime version from package-manager/compiler versions. A Node engines range is a declaration, not necessarily an enforced test; CI should exercise the oldest supported and current versions. Native addons and optional dependencies require OS/architecture coverage.

Runtimes may implement different APIs, module resolution, Web APIs, permission models, and timing behavior even when they share V8. Compatibility data should specify features, not just version labels. Check release support status and end-of-life policy regularly, since security support changes over time.

Engineering guidance

Set an explicit minimum version, automate matrix jobs, and test the built package in each supported runtime. Use feature detection for optional APIs when practical. For libraries, avoid unnecessarily narrow ranges but do not claim unsupported compatibility. For services, align runtime pinning, deployment images, local development, and CI; plan upgrades before end of support.

Interview questions

  1. Why include OS/architecture? Native modules and platform APIs vary outside pure JavaScript semantics.
  2. Does engines.node enforce compatibility? Enforcement varies; it should be backed by CI and deployment policy.
  3. Why test oldest supported runtime? It validates the lower boundary where API/syntax gaps are most likely.
  4. Are Node and another V8 runtime interchangeable? No; APIs, resolution, permissions, and host behavior differ.
  5. How keep matrix current? Review release support/EOL schedules and automate upgrade planning.

References