fix(cli): require Node.js >=20 and surface a clear error on older runtimes

.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

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:*",

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',

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",