create-ng-tailwind 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.0] - 2026-06-06
+
+### ✨ New Features
+
+- **Node.js / Angular auto-compatibility**: The CLI now detects the current Node.js runtime and automatically picks the highest compatible Angular CLI release instead of always pulling `@angular/cli@latest`. This fixes the common `EBADENGINE` failure when scaffolding on a Node version below Angular 22's minimum.
+- **`--ng-version <version>` flag**: New CLI flag to pin a specific Angular CLI major (e.g. `--ng-version=21`, `--ng-version=latest`). When omitted, the highest compatible version is selected automatically.
+- **Friendly preflight error**: If no supported Angular version matches the current Node.js, the CLI exits early with a formatted message listing supported Node↔Angular combinations and upgrade hints — instead of forwarding npm's cryptic engine warnings.
+
+### 📋 Supported Angular Versions
+
+| Angular CLI | Required Node.js |
+| ----------- | ---------------- |
+| 22 (latest) | `^22.22.3 \|\| ^24.15.0 \|\| >=26.0.0` |
+| 21          | `^20.19.0 \|\| ^22.12.0 \|\| >=24.0.0` |
+| 20          | `^20.11.1 \|\| ^22.0.0 \|\| ^24.0.0`   |
+| 19          | `^18.19.1 \|\| ^20.11.1 \|\| ^22.0.0`  |
+
+### 🏗️ Internal
+
+- New module `lib/utils/nodeCompat.js` containing the compatibility table, a tiny range matcher, and the resolver.
+- `ProjectManager` now reads `config.angularVersion` instead of hardcoding `@latest` in the scaffold command.
+
+---
+
 ## [4.0.0] - 2025-12-25
 
 ### ✨ New Template

package/README.md

@@ -128,16 +128,34 @@ npx create-ng-tailwind my-app --template=starter --ssr --zoneless
 --template=<minimal|starter|dashboard>
 
 # Other flags
---ssr           # Enable Server-Side Rendering
---zoneless      # Create zoneless application
---ai-config     # Configure AI tools (Claude, Cursor, etc.)
+--ssr                  # Enable Server-Side Rendering
+--zoneless             # Create zoneless application
+--ai-config            # Configure AI tools (Claude, Cursor, etc.)
+--ng-version=<v>       # Pin Angular CLI version (latest|21|20|19).
+                       # Default: auto-pick the highest version compatible
+                       # with your current Node.js runtime.
 ```
 
 ---
 
+## Node.js / Angular Compatibility
+
+This CLI auto-detects your Node.js version and picks the highest compatible Angular CLI release. You don't normally need to think about it — but if you want to pin a specific Angular version, pass `--ng-version=<v>`.
+
+| Angular CLI | Required Node.js                  |
+| ----------- | --------------------------------- |
+| 22 (latest) | `^22.22.3 \|\| ^24.15.0 \|\| >=26.0.0` |
+| 21          | `^20.19.0 \|\| ^22.12.0 \|\| >=24.0.0` |
+| 20          | `^20.11.1 \|\| ^22.0.0 \|\| ^24.0.0`   |
+| 19          | `^18.19.1 \|\| ^20.11.1 \|\| ^22.0.0`  |
+
+If no Angular version supports your Node, the CLI prints an upgrade hint and exits.
+
+---
+
 ## Requirements
 
-- Node.js 18+
+- Node.js 18+ (Node 20.11.1+ recommended for Angular 20+)
 - npm 9+
 
 ---

package/lib/cli/index.js

@@ -3,6 +3,12 @@ const inquirer = require("inquirer");
 const chalk = require("chalk");
 const CLI = require("./interactive");
 const { createLogger } = require("../utils/logger");
+const {
+  ANGULAR_COMPAT,
+  pickAngularVersion,
+  satisfies,
+  buildIncompatMessage,
+} = require("../utils/nodeCompat");
 
 class CLIHandler {
   constructor() {
@@ -27,6 +33,10 @@ class CLIHandler {
         "--ai-config <tools>",
         "AI tools to configure (none, claude, cursor, gemini, copilot, jetbrains, windsurf)",
       )
+      .option(
+        "--ng-version <version>",
+        "Pin Angular CLI version (e.g. latest, 21, 20, 19). Default: auto-pick highest compatible with current Node",
+      )
       .option("--skip-install", "Skip npm install")
       .parse();
 
@@ -167,7 +177,41 @@ class CLIHandler {
     return answers;
   }
 
+  resolveAngularVersion(requested) {
+    const nodeVer = process.versions.node;
+
+    // User explicitly pinned a version — honor it, but warn if known-incompatible.
+    if (requested) {
+      const entry = ANGULAR_COMPAT.find((e) => e.version === requested);
+      if (entry && !satisfies(nodeVer, entry.nodeRanges)) {
+        this.logger.warn(
+          `Angular ${requested} requires Node ${entry.nodeRanges.join(" || ")}, but you're on ${nodeVer}. Proceeding anyway — expect engine warnings.`,
+        );
+      }
+      return { version: requested, label: entry ? entry.label : `Angular ${requested}`, pinned: true };
+    }
+
+    // Auto-pick the highest compatible version.
+    const picked = pickAngularVersion(nodeVer);
+    if (!picked) {
+      console.error(chalk.red("\n❌ Incompatible Node.js version\n"));
+      console.error(buildIncompatMessage(nodeVer));
+      process.exit(1);
+    }
+
+    // Tell the user when we fell back from latest.
+    if (picked.version !== "latest") {
+      this.logger.info(
+        `Node ${nodeVer} doesn't support Angular latest — using ${picked.label}. Pass --ng-version=latest to override.`,
+      );
+    }
+
+    return { ...picked, pinned: false };
+  }
+
   async buildConfiguration(options, projectName, configOptions) {
+    const angular = this.resolveAngularVersion(options.ngVersion);
+
     const config = {
       projectName,
       template: options.template || "starter",
@@ -176,6 +220,7 @@ class CLIHandler {
       ssr: configOptions.ssr || false,
       zoneless: configOptions.zoneless || false,
       aiConfig: configOptions.aiConfig || ["none"], // Array of AI tools
+      angularVersion: angular.version,
       skipInstall: options.skipInstall || false,
       fullPath: require("path").resolve(process.cwd(), projectName),
     };

package/lib/managers/ProjectManager.js

@@ -51,7 +51,8 @@ class ProjectManager {
       const zoneless = this.config.zoneless || false;
       const aiConfig = this.config.aiConfig || ['none'];
 
-      let cmd = `npx @angular/cli@latest new ${this.config.projectName}`;
+      const ngVersion = this.config.angularVersion || "latest";
+      let cmd = `npx @angular/cli@${ngVersion} new ${this.config.projectName}`;
       cmd += ` --routing=${routing}`;
       cmd += ` --style=css`; // Always use CSS (Tailwind v4 official approach)
       cmd += ` --ssr=${ssr}`;

package/lib/utils/nodeCompat.js

@@ -0,0 +1,85 @@
+// Node.js -> Angular CLI compatibility matrix.
+// Ordered newest → oldest. The picker walks this list and returns the first
+// Angular version whose engine ranges accept the current Node runtime.
+const ANGULAR_COMPAT = [
+  {
+    version: "latest",
+    label: "Angular 22 (latest)",
+    nodeRanges: ["^22.22.3", "^24.15.0", ">=26.0.0"],
+  },
+  {
+    version: "21",
+    label: "Angular 21",
+    nodeRanges: ["^20.19.0", "^22.12.0", ">=24.0.0"],
+  },
+  {
+    version: "20",
+    label: "Angular 20",
+    nodeRanges: ["^20.11.1", "^22.0.0", "^24.0.0"],
+  },
+  {
+    version: "19",
+    label: "Angular 19",
+    nodeRanges: ["^18.19.1", "^20.11.1", "^22.0.0"],
+  },
+];
+
+function parseVer(v) {
+  const [maj = 0, min = 0, pat = 0] = v.replace(/^v/, "").split(".").map(Number);
+  return { maj, min, pat };
+}
+
+function gte(a, b) {
+  if (a.maj !== b.maj) return a.maj > b.maj;
+  if (a.min !== b.min) return a.min > b.min;
+  return a.pat >= b.pat;
+}
+
+function matchesRange(nodeVer, range) {
+  const node = parseVer(nodeVer);
+  if (range.startsWith("^")) {
+    const target = parseVer(range.slice(1));
+    return node.maj === target.maj && gte(node, target);
+  }
+  if (range.startsWith(">=")) {
+    const target = parseVer(range.slice(2));
+    return gte(node, target);
+  }
+  return false;
+}
+
+function satisfies(nodeVer, ranges) {
+  return ranges.some((r) => matchesRange(nodeVer, r));
+}
+
+function pickAngularVersion(nodeVer) {
+  for (const entry of ANGULAR_COMPAT) {
+    if (satisfies(nodeVer, entry.nodeRanges)) return entry;
+  }
+  return null;
+}
+
+function formatRanges(entry) {
+  return entry.nodeRanges.join(" || ");
+}
+
+function buildIncompatMessage(nodeVer) {
+  const lines = [
+    `Node ${nodeVer} is not supported by any Angular CLI version this tool knows about.`,
+    "",
+    "Supported combinations:",
+    ...ANGULAR_COMPAT.map((e) => `  • ${e.label.padEnd(22)} requires Node ${formatRanges(e)}`),
+    "",
+    "Options:",
+    "  • Upgrade Node:  nvm install 24 && nvm use 24    (or use Homebrew / nodejs.org)",
+    "  • Or downgrade Angular explicitly via the flag:  --ng-version=20",
+  ];
+  return lines.join("\n");
+}
+
+module.exports = {
+  ANGULAR_COMPAT,
+  pickAngularVersion,
+  satisfies,
+  buildIncompatMessage,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ng-tailwind",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "🚀 A CLI tool to give starter template for angular project with tailwind css",
   "main": "bin/create-ng-tailwind.js",
   "bin": {