From 22bd9444255fa63ffc86ebc6d15c0b2b178c2879 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 27 Apr 2026 02:47:31 +0000
Subject: [PATCH] fix(cli): require Node.js >=20 and surface a clear error on
 older runtimes

Older Node (e.g. 16) lacks events.addAbortListener, used transitively by
the CLI, which produced a cryptic SyntaxError at module instantiation.
Declare engines.node: ">=20" on both packages so installers warn, and add
an early runtime check in the bin so users get an actionable message
before any modules load.

Closes #433

https://claude.ai/code/session_01N5k5sqBgxYX9XMatM6TGcE
---
 .changeset/cli-require-node-20.md | 15 +++++++++++++++
 packages/cli/package.json         |  3 +++
 packages/cli/src/bin.ts           | 18 +++++++++++++-----
 packages/create/package.json      |  3 +++
 4 files changed, 34 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/cli-require-node-20.md

diff --git a/.changeset/cli-require-node-20.md b/.changeset/cli-require-node-20.md
new file mode 100644
index 00000000..4a5022f7
--- /dev/null
+++ b/.changeset/cli-require-node-20.md
@@ -0,0 +1,15 @@
+---
+'@tanstack/cli': patch
+'@tanstack/create': patch
+---
+
+fix(cli): require Node.js >=20 and surface a clear error on older runtimes
+
+Older Node versions (e.g. Node 16) lack `events.addAbortListener`, which is
+used transitively by the CLI. Running on those versions produced a cryptic
+`SyntaxError: ... does not provide an export named 'addAbortListener'` during
+module instantiation. Both packages now declare `engines.node: ">=20"` so
+package managers warn at install time, and the CLI bin performs an early
+runtime check that prints an actionable message before any modules load.
+
+Closes #433
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 90d997d3..71039dba 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -47,6 +47,9 @@
   "author": "Jack Herrington <jherr@pobox.com>",
   "license": "MIT",
   "packageManager": "pnpm@9.15.5",
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "@clack/prompts": "^0.10.0",
     "@tanstack/create": "workspace:*",
diff --git a/packages/cli/src/bin.ts b/packages/cli/src/bin.ts
index 7b3bdb4d..e5614619 100644
--- a/packages/cli/src/bin.ts
+++ b/packages/cli/src/bin.ts
@@ -1,9 +1,17 @@
 #!/usr/bin/env node
-import { cli } from './cli.js'
-import {
-  createReactFrameworkDefinition,
-  createSolidFrameworkDefinition,
-} from '@tanstack/create'
+const nodeMajor = Number(process.versions.node.split('.')[0])
+if (nodeMajor < 20) {
+  process.stderr.write(
+    `TanStack CLI requires Node.js 20 or higher.\n` +
+      `You are using Node.js ${process.versions.node}.\n` +
+      `Please upgrade Node.js: https://nodejs.org/en/download\n`,
+  )
+  process.exit(1)
+}
+
+const { cli } = await import('./cli.js')
+const { createReactFrameworkDefinition, createSolidFrameworkDefinition } =
+  await import('@tanstack/create')
 
 cli({
   name: 'tanstack',
diff --git a/packages/create/package.json b/packages/create/package.json
index 2335629c..626cb50e 100644
--- a/packages/create/package.json
+++ b/packages/create/package.json
@@ -31,6 +31,9 @@
   "author": "Jack Herrington <jherr@pobox.com>",
   "license": "MIT",
   "packageManager": "pnpm@9.15.5",
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "ejs": "^3.1.10",
     "execa": "^9.5.2",