Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): friendly preflight error on unsupported Node versions (#2545)

Joey644fd34fcb51
diff --git a/packages/cli/bin/xds.mjs b/packages/cli/bin/xds.mjs
old mode 100755
new mode 100644
index 12fbbc12bd..1be8c1b129
--- a/packages/cli/bin/xds.mjs
+++ b/packages/cli/bin/xds.mjs
@@ -1,9 +1,32 @@
#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.
-import {program} from '../src/index.mjs';
-import {isJsonMode, toErrorEnvelope} from '../src/lib/json.mjs';
-import {handleCommanderError} from '../src/lib/json-shim.mjs';
+// ---------------------------------------------------------------------------
+// Node.js version preflight gate.
+//
+// The CLI and its dependencies use `styleText` from `node:util`, added in Node
+// 22.13.0. On older runtimes the lazy-loaded subcommands die with a cryptic
+// ESM error ("...does not provide an export named 'styleText'"). To give users
+// a clear message instead, we check the running version FIRST, using only
+// built-ins, and exit early before importing anything that touches styleText.
+//
+// `node-version.mjs` is intentionally dependency-free so it loads on the
+// unsupported runtimes this guard protects against.
+import {
+ isNodeVersionSupported,
+ unsupportedNodeMessage,
+} from '../src/lib/node-version.mjs';
+
+if (!isNodeVersionSupported(process.versions.node)) {
+ console.error(unsupportedNodeMessage(process.versions.node));
+ process.exit(1);
+}
+
+// Imports that transitively load `styleText` must happen AFTER the gate above,
+// so they are dynamically imported here rather than at the top of the module.
+const {program} = await import('../src/index.mjs');
+const {isJsonMode, toErrorEnvelope} = await import('../src/lib/json.mjs');
+const {handleCommanderError} = await import('../src/lib/json-shim.mjs');
/**
* Top-level error boundary (contract guarantee #4): an uncaught throw must
diff --git a/packages/cli/src/lib/node-version.mjs b/packages/cli/src/lib/node-version.mjs
new file mode 100644
index 0000000000..2569c0a68c
--- /dev/null
+++ b/packages/cli/src/lib/node-version.mjs
@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Node.js version preflight — runtime support gate.
+ *
+ * The CLI (and its dependencies) rely on `styleText` from `node:util`, which
+ * was only added in Node 22.13.0. On older runtimes the lazy-loaded
+ * subcommands die with a cryptic ESM error:
+ *
+ * failed to load: The requested module 'node:util' does not provide an
+ * export named 'styleText'
+ *
+ * This module exposes a tiny, dependency-free comparison helper so the entry
+ * point can gate on the running Node version BEFORE importing anything that
+ * touches `styleText`, and surface a clear "upgrade Node" message instead.
+ *
+ * Kept free of any non-builtin imports so it can run on the unsupported
+ * runtimes it is meant to guard against.
+ */
+
+/** Minimum supported Node.js version. */
+export const MIN_NODE_VERSION = '22.13.0';
+
+/**
+ * Parse a Node.js version string ("22.14.1", "v20.10.0", "16.20.2-nightly")
+ * into a {major, minor, patch} record. Missing or non-numeric segments
+ * default to 0.
+ *
+ * @param {string} version
+ * @returns {{major: number, minor: number, patch: number}}
+ */
+export function parseNodeVersion(version) {
+ const cleaned = String(version).trim().replace(/^v/, '');
+ const [major = 0, minor = 0, patch = 0] = cleaned
+ .split('.')
+ .map((seg) => parseInt(seg, 10) || 0);
+ return {major, minor, patch};
+}
+
+/**
+ * Returns true when `version` is greater than or equal to `minimum`.
+ * Compares major, then minor, then patch.
+ *
+ * @param {string} version - the running Node version (e.g. process.versions.node)
+ * @param {string} [minimum] - the minimum supported version
+ * @returns {boolean}
+ */
+export function isNodeVersionSupported(version, minimum = MIN_NODE_VERSION) {
+ const v = parseNodeVersion(version);
+ const min = parseNodeVersion(minimum);
+ if (v.major !== min.major) return v.major > min.major;
+ if (v.minor !== min.minor) return v.minor > min.minor;
+ return v.patch >= min.patch;
+}
+
+/**
+ * Builds the friendly, human-facing message shown when the runtime is too old.
+ *
+ * @param {string} version - the running Node version
+ * @param {string} [minimum] - the minimum supported version
+ * @returns {string}
+ */
+export function unsupportedNodeMessage(version, minimum = MIN_NODE_VERSION) {
+ const clean = String(version).trim().replace(/^v/, '');
+ return (
+ `xds requires Node.js >=${minimum} (you have v${clean}). ` +
+ `Please upgrade Node and try again.`
+ );
+}
diff --git a/packages/cli/src/lib/node-version.test.mjs b/packages/cli/src/lib/node-version.test.mjs
new file mode 100644
index 0000000000..89618aefc6
--- /dev/null
+++ b/packages/cli/src/lib/node-version.test.mjs
@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the Node.js version preflight gate (`node-version.mjs`).
+ *
+ * The CLI requires Node >=22.13.0 because dependencies import `styleText` from
+ * `node:util`, which only exists from that version onward. These tests lock in
+ * the parsing and comparison logic that decides whether the running runtime is
+ * supported, so the entry-point guard reliably rejects old Node and accepts new
+ * Node across the major.minor.patch boundary.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {
+ MIN_NODE_VERSION,
+ parseNodeVersion,
+ isNodeVersionSupported,
+ unsupportedNodeMessage,
+} from './node-version.mjs';
+
+describe('parseNodeVersion', () => {
+ it('parses a plain semver string', () => {
+ expect(parseNodeVersion('22.14.1')).toEqual({major: 22, minor: 14, patch: 1});
+ });
+
+ it('strips a leading v', () => {
+ expect(parseNodeVersion('v20.10.0')).toEqual({major: 20, minor: 10, patch: 0});
+ });
+
+ it('ignores a prerelease/build suffix on the patch segment', () => {
+ expect(parseNodeVersion('16.20.2-nightly')).toEqual({major: 16, minor: 20, patch: 2});
+ });
+
+ it('defaults missing segments to 0', () => {
+ expect(parseNodeVersion('24')).toEqual({major: 24, minor: 0, patch: 0});
+ });
+});
+
+describe('isNodeVersionSupported', () => {
+ it('rejects clearly old majors', () => {
+ expect(isNodeVersionSupported('16.20.2')).toBe(false);
+ expect(isNodeVersionSupported('20.10.0')).toBe(false);
+ });
+
+ it('rejects the same major but an older minor', () => {
+ expect(isNodeVersionSupported('22.12.0')).toBe(false);
+ });
+
+ it('rejects the same major but an older minor regardless of patch', () => {
+ expect(isNodeVersionSupported('22.12.99')).toBe(false);
+ });
+
+ it('accepts exactly the minimum version', () => {
+ expect(isNodeVersionSupported('22.13.0')).toBe(true);
+ });
+
+ it('accepts a newer patch within the minimum minor', () => {
+ expect(isNodeVersionSupported('22.13.1')).toBe(true);
+ });
+
+ it('accepts a newer minor', () => {
+ expect(isNodeVersionSupported('22.14.1')).toBe(true);
+ });
+
+ it('accepts a newer major', () => {
+ expect(isNodeVersionSupported('24.1.0')).toBe(true);
+ });
+
+ it('handles a v-prefixed running version', () => {
+ expect(isNodeVersionSupported('v22.13.0')).toBe(true);
+ expect(isNodeVersionSupported('v18.0.0')).toBe(false);
+ });
+
+ it('uses MIN_NODE_VERSION (22.13.0) as the default threshold', () => {
+ expect(MIN_NODE_VERSION).toBe('22.13.0');
+ expect(isNodeVersionSupported(MIN_NODE_VERSION)).toBe(true);
+ });
+});
+
+describe('unsupportedNodeMessage', () => {
+ it('names both the required minimum and the running version', () => {
+ const msg = unsupportedNodeMessage('16.20.2');
+ expect(msg).toContain('>=22.13.0');
+ expect(msg).toContain('v16.20.2');
+ expect(msg).toContain('upgrade Node');
+ });
+
+ it('normalizes a v-prefixed running version to a single v', () => {
+ expect(unsupportedNodeMessage('v20.10.0')).toContain('v20.10.0');
+ });
+});