feat(node): update Node.js to v20 LTS and add v22 LTS support

- Update .nvmrc to v20.19.3 (LTS Iron)
- Add support for Node.js v22 LTS (Jod) in CI matrix
- Update minimum Node.js version to v20.0.0 in package.json
- Add NODE-VERSION.md documenting LTS support and features
- Update all documentation files to reflect new version requirements

Author: wilsonwangdev

.github/workflows/lint.yml

@@ -10,6 +10,10 @@ jobs:
   lint:
     name: Lint and Format Check
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['20.19.3', '22.17.0']  # Test with both Node.js v20 LTS and v22 LTS
+      fail-fast: false
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -22,10 +26,10 @@ jobs:
           version: 8.15.4  # Using the version from packageManager in package.json
           run_install: false
 
-      - name: Setup Node.js
+      - name: Setup Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
-          node-version: '20.3.0'
+          node-version: ${{ matrix.node-version }}
           cache: 'pnpm'
 
       - name: Install dependencies

.nvmrc

@@ -1 +1 @@
-20.3.0
+20.19.3

CI.md

@@ -10,7 +10,7 @@ The CI workflow is defined in `.github/workflows/lint.yml` and performs the foll
 
 1. **Checkout Code**: Fetches the repository code with full history for proper lockfile validation
 2. **Setup pnpm**: Installs the pnpm package manager (version 8.15.4)
-3. **Setup Node.js**: Configures Node.js environment (version 20.3.0) with pnpm caching
+3. **Setup Node.js**: Configures Node.js environment (version 22.17.0 LTS) with pnpm caching
 4. **Install Dependencies**: Installs project dependencies using pnpm
 5. **Check Formatting**: Verifies code formatting using Biome
 6. **Run Linting**: Performs code linting using Biome
@@ -26,10 +26,12 @@ The CI workflow is configured to handle the pnpm lockfile (`pnpm-lock.yaml`) pro
 
 ### Node.js Version
 
-The project requires Node.js version 20.3.0 or higher, which is specified in:
+The project supports both Node.js v20 LTS and v22 LTS versions, which is specified in:
 
-- `package.json` via the `engines` field
-- `.nvmrc` file for local development with nvm
+- `package.json` via the `engines` field (set to `>=20.0.0`)
+- `.nvmrc` file for local development with nvm (set to `20.19.3` by default)
+
+Both Node.js v20 LTS (Iron) and v22 LTS (Jod) are fully supported. For more information on Node.js version requirements and benefits of using LTS versions, see [NODE-VERSION.md](./NODE-VERSION.md).
 
 ## Troubleshooting CI Issues
 

CONTRIBUTING.md

@@ -64,10 +64,12 @@ export const toolName: Tool = {
 
 ### Prerequisites
 
-- Node.js (v20.3.0 or newer)
+- Node.js LTS:
+  - v20 LTS (v20.0.0 or newer, default v20.19.3)
+  - v22 LTS (v22.0.0 or newer, also supported v22.17.0)
 - pnpm (v8.0.0 or newer)
 
-> **Note:** This project requires pnpm as the package manager. We recommend using Corepack (built into Node.js 20+) to manage pnpm:
+> **Note:** This project requires pnpm as the package manager. We recommend using Corepack (built into Node.js) to manage pnpm:
 > ```sh
 > # Enable Corepack
 > corepack enable
@@ -76,7 +78,7 @@ export const toolName: Tool = {
 > corepack prepare pnpm@latest --activate
 > ```
 >
-> For more details on our package manager and Node.js requirements, see [PACKAGE-MANAGER.md](./PACKAGE-MANAGER.md).
+> For more details on our package manager and Node.js requirements, see [PACKAGE-MANAGER.md](./PACKAGE-MANAGER.md) and [NODE-VERSION.md](./NODE-VERSION.md).
 
 ### Setup Steps
 
@@ -96,6 +98,10 @@ export const toolName: Tool = {
    # Alternative: If you have network issues with Corepack
    npm install -g [email protected]
    pnpm install
+   
+   # Note: Ensure you're using Node.js v22 LTS
+   # Check your version with: node -v
+   # If needed, install the LTS version from nodejs.org
    ```
 
    > If you encounter network issues with Corepack during git operations, see the [Troubleshooting section in PACKAGE-MANAGER.md](./PACKAGE-MANAGER.md#troubleshooting).

LOCKFILE-MANAGEMENT.md

@@ -43,6 +43,42 @@ Common causes:
 2. Different pnpm versions generating incompatible lockfiles
 3. Merge conflicts in the lockfile that weren't properly resolved
 
+### ERR_PNPM_UNSUPPORTED_ENGINE
+
+This error occurs when there's a mismatch between your Node.js version and what a dependency requires. The error message looks like:
+
+```
+ERR_PNPM_UNSUPPORTED_ENGINE  Unsupported environment (bad pnpm and/or Node.js version)
+
+Your Node version is incompatible with "<package-name>".
+
+Expected version: <expected-version-range>
+Got: <your-version>
+```
+
+Common causes:
+1. Using a Node.js version that's incompatible with a dependency's requirements
+2. Dependencies requiring newer Node.js versions than specified in your project
+3. Outdated dependencies with strict Node.js version requirements
+
+#### Example: nopt Package Requirements
+
+A common example is the `nopt` package (used by many development tools) which requires:
+```
+^18.17.0 || >=20.5.0
+```
+
+If your project uses Node.js v20.3.0 but has dependencies that use `[email protected]` (directly or indirectly), you'll encounter this error. The solution is to update your Node.js version to v20.5.0 or higher.
+
+### Using LTS Versions
+
+This project now uses Node.js v22 LTS (codename 'Jod'), which provides several benefits for dependency management:
+
+1. **Longer support window**: LTS versions receive security updates and bug fixes for a longer period (30 months total)
+2. **Wider compatibility**: Most npm packages are tested against LTS versions first
+3. **Fewer dependency conflicts**: LTS versions have more stable APIs, reducing the likelihood of compatibility issues
+4. **Predictable upgrade path**: Clear timeline for when to plan the next major version upgrade
+
 ## Best Practices
 
 ### For Local Development
@@ -75,6 +111,8 @@ Common causes:
 
 ## Troubleshooting
 
+### Lockfile Issues
+
 If you encounter lockfile issues:
 
 1. **Update your local environment**:
@@ -101,6 +139,44 @@ If you encounter lockfile issues:
    git commit -m "Update lockfile"
    ```
 
+### Node.js Version Issues
+
+If you encounter `ERR_PNPM_UNSUPPORTED_ENGINE` errors:
+
+1. **Check your Node.js version**:
+   ```bash
+   node -v
+   ```
+
+2. **Update Node.js to the required LTS version**:
+   - If using nvm:
+     ```bash
+     # Install the required LTS version
+     nvm install 22.17.0  # Current LTS version
+     
+     # Use the installed version
+     nvm use 22.17.0
+     ```
+   - If using Corepack (recommended):
+     ```bash
+     # Enable Corepack if not already enabled
+     corepack enable
+     
+     # Update Node.js using your system's package manager or from nodejs.org
+     ```
+   - If using other Node.js installation methods, download and install the LTS version from [nodejs.org](https://nodejs.org/)
+
+3. **Update project configuration** (if necessary):
+   - Update `.nvmrc` to specify the LTS Node.js version (currently 22.17.0)
+   - Update `engines` field in `package.json` to require Node.js >=22.0.0
+   - Consider adding a note in your README about using the LTS version
+
+4. **Reinstall dependencies with the correct Node.js version**:
+   ```bash
+   rm -rf node_modules
+   pnpm install
+   ```
+
 ## Additional Resources
 
 - [pnpm Documentation on Lockfile](https://pnpm.io/lockfile)

NODE-VERSION.md

@@ -0,0 +1,109 @@
+# Node.js Version Requirements
+
+This project supports both Node.js v20 LTS (codename 'Iron') and Node.js v22 LTS (codename 'Jod') to ensure stability, security, and access to modern features. This document explains our Node.js version requirements and how to set up your environment.
+
+### What is LTS?
+
+LTS stands for "Long Term Support." The Node.js project maintains multiple release lines simultaneously:
+
+- **Current**: The latest features but may have breaking changes (odd-numbered versions like v23)
+- **Active LTS**: Stable release recommended for most users (even-numbered versions like v20 and v22)
+- **Maintenance LTS**: Older LTS versions receiving critical fixes only
+
+Our supported LTS versions have the following support schedules:
+
+- **Node.js v20 (Iron)**: Entered LTS on October 24, 2023, with active support until April 2025, followed by maintenance support until April 2026.
+- **Node.js v22 (Jod)**: Entered LTS on October 29, 2024, with active support until October 2025, followed by maintenance support until April 2027.
+
+### Benefits of Using LTS
+
+1. **Stability**: LTS versions prioritize stability over new features, making them ideal for production applications
+2. **Security**: LTS versions receive security updates for a longer period (30 months total)
+3. **Compatibility**: Most npm packages are tested against LTS versions first
+4. **Performance**: Each LTS version includes performance improvements over previous versions
+5. **Predictable upgrade path**: Clear timeline for when to plan the next major version upgrade
+
+### Supported LTS Features
+
+#### Node.js v20 LTS (Iron) Features
+
+1. **Permission Model**: Enhanced security with the experimental permission model
+2. **Single Executable Applications**: Improved support for creating standalone executables
+3. **Stable Test Runner**: Built-in test runner for easier testing
+4. **Stable WebStreams**: Improved streaming capabilities
+5. **V8 JavaScript Engine**: Includes V8 11.3 with performance improvements
+
+#### Node.js v22 LTS (Jod) Features
+
+1. **Built-in WebSocket Client**: Now enabled by default for browser compatibility
+2. **Stable Watch Mode**: The `--watch` flag is now stable, eliminating the need for tools like nodemon
+3. **ESM Graphs in require()**: Simplified module interoperability
+4. **Simplified Script Execution**: The experimental `--run` flag provides faster script execution
+5. **V8 Engine Upgrade**: Improved performance and new JavaScript features
+
+## Version Requirements
+
+- **Minimum required version**: v20.0.0
+- **Recommended versions**: 
+  - v20.19.3 (LTS - Iron) - Default version in .nvmrc
+  - v22.17.0 (LTS - Jod) - Also fully supported
+
+## Setting Up the Correct Version
+
+### Using nvm (Node Version Manager)
+
+```bash
+# Install the default LTS version (v20 LTS - Iron)
+nvm install 20.19.3
+
+# Use the installed version
+nvm use 20.19.3
+
+# Or install and use Node.js v22 LTS (Jod)
+nvm install 22.17.0
+nvm use 22.17.0
+```
+
+### Using Corepack (Recommended)
+
+```bash
+# Enable Corepack if not already enabled
+corepack enable
+
+# Update Node.js using your system's package manager or from nodejs.org
+```
+
+### Direct Installation
+
+Download and install the LTS version from [nodejs.org](https://nodejs.org/).
+
+## Troubleshooting
+
+If you encounter version-related issues:
+
+1. Check your current Node.js version:
+   ```bash
+   node -v
+   ```
+
+2. If using nvm, ensure you're using one of the supported LTS versions:
+   ```bash
+   # For Node.js v20 LTS (default)
+   nvm use 20
+   
+   # Or for Node.js v22 LTS
+   nvm use 22
+   ```
+
+3. If you cannot upgrade to a supported version immediately, you can try using the `--no-engine-strict` flag with pnpm:
+   ```bash
+   pnpm install --no-engine-strict
+   ```
+   Note: This is not recommended for long-term use.
+
+## Additional Resources
+
+- [Node.js Release Schedule](https://github.com/nodejs/Release)
+- [Node.js LTS Documentation](https://nodejs.org/en/about/previous-releases)
+- [Package Manager Documentation](./PACKAGE-MANAGER.md)
+- [Lockfile Management](./LOCKFILE-MANAGEMENT.md)

PACKAGE-MANAGER.md

@@ -8,10 +8,21 @@ This project enforces specific requirements for the development environment to e
 
 ### Node.js Version
 
-- **Minimum required version**: v20.3.0
-- **Recommended version**: v22.x (LTS)
+- **Minimum required version**: v20.0.0
+- **Recommended versions**: 
+  - v20.19.3 (LTS - Iron) - Default version in .nvmrc
+  - v22.17.0 (LTS - Jod) - Also fully supported
 
-This requirement is based on Astro's compatibility with Node.js versions. Astro 5.x requires Node.js v20.3.0 or higher.
+This project supports both current LTS (Long Term Support) versions of Node.js for maximum stability and security:
+
+- **Node.js v20 LTS (Iron)**: Active support until April 2025, maintenance until April 2026
+- **Node.js v22 LTS (Jod)**: Active support until October 2025, maintenance until April 2027
+
+Benefits of using the LTS version:
+1. Longer support window with security updates
+2. Greater stability for production environments
+3. Compatibility with the latest dependencies
+4. Performance improvements over previous versions
 
 ### Package Manager
 

README.md

@@ -45,10 +45,12 @@ Frontend Tools Explorer is a curated collection of essential tools, libraries, a
 
 ### Prerequisites
 
-- Node.js (v20.3.0 or newer)
+- Node.js LTS:
+  - v20 LTS (v20.0.0 or newer, default v20.19.3)
+  - v22 LTS (v22.0.0 or newer, also supported v22.17.0)
 - pnpm (v8.0.0 or newer)
 
-> **Note:** This project requires specific Node.js and package manager versions. For more details, see [PACKAGE-MANAGER.md](./PACKAGE-MANAGER.md).
+> **Note:** This project requires specific Node.js and package manager versions. For more details, see [PACKAGE-MANAGER.md](./PACKAGE-MANAGER.md) and [NODE-VERSION.md](./NODE-VERSION.md).
 
 ### Installation
 
@@ -70,6 +72,10 @@ Frontend Tools Explorer is a curated collection of essential tools, libraries, a
    # Alternative: If you have network issues with Corepack
    npm install -g [email protected]
    pnpm install
+   
+   # Note: Ensure you're using Node.js v22 LTS
+   # Check your version with: node -v
+   # If needed, install the LTS version from nodejs.org
    ```
 
    > **Note:** This project requires pnpm as the package manager. We recommend using Corepack (built into Node.js 20+) to manage pnpm. See [PACKAGE-MANAGER.md](./PACKAGE-MANAGER.md) for more details and troubleshooting.

package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "version": "0.0.1",
   "engines": {
-    "node": ">=20.3.0",
+    "node": ">=20.0.0",
     "pnpm": ">=8.0.0"
   },
   "packageManager": "[email protected]",