build: enforce pnpm and node.js version requirements

Add configuration files (.nvmrc, .npmrc, .pnpmrc) and update package.json to enforce specific Node.js and pnpm versions. Update CI workflow to use pnpm and Corepack. Add documentation in PACKAGE-MANAGER.md explaining the requirements and setup process.

Author: wilsonwangdev

.gitattributes

@@ -0,0 +1,21 @@
+# Set default behavior to automatically normalize line endings
+* text=auto eol=lf
+
+# Denote all files that are truly binary and should not be modified
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.webp binary
+*.woff binary
+*.woff2 binary
+*.eot binary
+*.ttf binary
+*.otf binary
+*.mp4 binary
+*.webm binary
+*.mp3 binary
+*.zip binary
+*.gz binary
+*.tar binary

.github/workflows/lint.yml

@@ -17,14 +17,17 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          cache: 'npm'
+          node-version: '20.3.0'
+          cache: 'pnpm'
 
-      - name: Install dependencies
-        run: npm ci
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Setup pnpm
+        run: corepack prepare pnpm@latest --activate
 
-      - name: Install Biome
-        run: npm install -g @biomejs/biome
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
 
       - name: Check formatting
         run: biome format --write=false .

.husky/pre-commit

@@ -1 +1,9 @@
-pnpm lint-staged
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Run lint-staged with available pnpm
+pnpm lint-staged || (
+  echo "Error: Failed to run lint-staged. Make sure pnpm is installed."
+  echo "You can install pnpm globally with: npm install -g [email protected]"
+  exit 1
+)

.npmrc

@@ -0,0 +1,4 @@
+engine-strict=true
+use-node-version=20.3.0
+strict-peer-dependencies=false
+auto-install-peers=true

.nvmrc

@@ -0,0 +1 @@
+20.3.0

.pnpmrc

@@ -0,0 +1,4 @@
+strict-peer-dependencies=false
+auto-install-peers=true
+engine-strict=true
+node-version=>=20.3.0

CONTRIBUTING.md

@@ -62,6 +62,24 @@ export const toolName: Tool = {
 
 ## Development Setup
 
+### Prerequisites
+
+- Node.js (v20.3.0 or newer)
+- 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:
+> ```sh
+> # Enable Corepack
+> corepack enable
+> 
+> # Activate pnpm
+> corepack prepare pnpm@latest --activate
+> ```
+>
+> For more details on our package manager and Node.js requirements, see [PACKAGE-MANAGER.md](./PACKAGE-MANAGER.md).
+
+### Setup Steps
+
 1. Clone the repository
    ```sh
    git clone https://github.com/wilsonwangdev/frontend-tools-explorer.git
@@ -70,20 +88,21 @@ export const toolName: Tool = {
 
 2. Install dependencies
    ```sh
-   npm install
-   # or
+   # Using Corepack (recommended)
+   corepack enable
+   corepack prepare pnpm@latest --activate
+   pnpm install
+   
+   # Alternative: If you have network issues with Corepack
+   npm install -g [email protected]
    pnpm install
-   # or
-   yarn install
    ```
+   
+   > If you encounter network issues with Corepack during git operations, see the [Troubleshooting section in PACKAGE-MANAGER.md](./PACKAGE-MANAGER.md#troubleshooting).
 
 3. Start the development server
    ```sh
-   npm run dev
-   # or
    pnpm dev
-   # or
-   yarn dev
    ```
 
 4. Open your browser and visit `http://localhost:4321`

PACKAGE-MANAGER.md

@@ -0,0 +1,119 @@
+# Package Manager and Node.js Requirements
+
+## Overview
+
+This project enforces specific requirements for the development environment to ensure consistency across all contributors and deployments.
+
+## Requirements
+
+### Node.js Version
+
+- **Minimum required version**: v20.3.0
+- **Recommended version**: v22.x (LTS)
+
+This requirement is based on Astro's compatibility with Node.js versions. Astro 5.x requires Node.js v20.3.0 or higher.
+
+### Package Manager
+
+- **Required package manager**: pnpm v8.0.0 or higher
+- **Current version used**: pnpm v8.15.4
+
+## Why pnpm?
+
+We've chosen pnpm as the required package manager for this project for several reasons:
+
+1. **Disk space efficiency**: pnpm uses a content-addressable store which saves disk space and speeds up installation.
+2. **Strict dependency resolution**: pnpm creates a non-flat `node_modules` structure that prevents access to packages that aren't explicitly declared as dependencies.
+3. **Performance**: pnpm is generally faster than npm and Yarn Classic for installation operations.
+4. **Consistency**: Using a single package manager ensures consistent dependency resolution across all development environments.
+
+## Configuration Files
+
+The following files enforce these requirements:
+
+- `.nvmrc`: Specifies the Node.js version for tools like nvm
+- `.npmrc`: Contains npm-related configurations
+- `.pnpmrc`: Contains pnpm-specific configurations
+- `package.json`: Contains the `engines` and `packageManager` fields
+
+## Enforcement
+
+These requirements are enforced through:
+
+1. The `engines` field in `package.json`
+2. The `packageManager` field in `package.json`
+3. A simple preinstall script that prevents npm/yarn usage
+4. Configuration in `.npmrc` and `.pnpmrc`
+
+## Installation
+
+Since we require Node.js 20.3.0 or higher, we recommend using Corepack to manage pnpm. Corepack is included with Node.js 20+ and provides native package manager version management.
+
+### Using Corepack (Recommended)
+
+```bash
+# Enable Corepack (only needed once)
+corepack enable
+
+# Use the latest pnpm version
+corepack prepare pnpm@latest --activate
+```
+
+This approach has several advantages:
+1. No need to install pnpm globally
+2. Automatically uses the correct version specified in package.json
+3. Built into Node.js 20+
+4. Ensures consistent package manager versions across all developers
+
+### Alternative Installation
+
+If you prefer not to use Corepack, you can install pnpm globally:
+
+```bash
+npm install -g pnpm
+```
+
+## Troubleshooting
+
+### Common Issues
+
+If you encounter issues related to Node.js version or package manager:
+
+1. Check your Node.js version with `node -v`
+2. Install the required Node.js version
+3. Enable Corepack with `corepack enable`
+4. Prepare pnpm with `corepack prepare pnpm@latest --activate`
+5. Use `pnpm install` to install dependencies
+
+### Network Issues with Corepack
+
+If you encounter network errors when Corepack tries to download pnpm (especially during git commits with Husky):
+
+```
+Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-8.15.4.tgz.
+Internal Error: Error when performing the request...
+```
+
+Try these solutions:
+
+1. **Install pnpm globally** as a fallback:
+   ```bash
+   npm install -g [email protected]
+   ```
+   This is the simplest solution and recommended for most users.
+
+2. **Configure npm registry** if you're behind a proxy or firewall:
+   ```bash
+   npm config set registry https://registry.npmjs.org/
+   ```
+
+3. **Disable Husky temporarily** if needed for commits:
+   ```bash
+   git commit --no-verify -m "Your commit message"
+   ```
+
+4. **Check network connectivity** to registry.npmjs.org
+
+For more information on pnpm, visit [the official pnpm documentation](https://pnpm.io/).
+
+For more information on Corepack, visit [the Node.js Corepack documentation](https://nodejs.org/api/corepack.html) and [Corepack Troubleshooting](https://github.com/nodejs/corepack#troubleshooting).

README.md

@@ -45,8 +45,10 @@ Frontend Tools Explorer is a curated collection of essential tools, libraries, a
 
 ### Prerequisites
 
-- Node.js (v18 or newer)
-- npm, pnpm, or Yarn
+- Node.js (v20.3.0 or newer)
+- 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).
 
 ### Installation
 
@@ -60,21 +62,22 @@ Frontend Tools Explorer is a curated collection of essential tools, libraries, a
 2. Install dependencies
 
    ```sh
-   npm install
-   # or
+   # Using Corepack (recommended)
+   corepack enable
+   corepack prepare pnpm@latest --activate
+   pnpm install
+   
+   # Alternative: If you have network issues with Corepack
+   npm install -g [email protected]
    pnpm install
-   # or
-   yarn install
    ```
 
+   > **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.
+
 3. Start the development server
 
    ```sh
-   npm run dev
-   # or
    pnpm dev
-   # or
-   yarn dev
    ```
 
 4. Open your browser and visit `http://localhost:4321`

package.json

@@ -2,6 +2,11 @@
   "name": "frontend-tools-explorer",
   "type": "module",
   "version": "0.0.1",
+  "engines": {
+    "node": ">=20.3.0",
+    "pnpm": ">=8.0.0"
+  },
+  "packageManager": "[email protected]",
   "scripts": {
     "dev": "astro dev",
     "build": "astro build",
@@ -11,7 +16,9 @@
     "format": "biome format . --write",
     "check": "biome check . --write",
     "prepare": "husky",
-    "lint-staged": "lint-staged"
+    "lint-staged": "lint-staged",
+    "preinstall": "node -e \"process.env.npm_config_user_agent && !process.env.npm_config_user_agent.includes('pnpm') && (console.error('Please use pnpm instead of npm or yarn'), process.exit(1))\"",
+    "install-pnpm-fallback": "npm install -g [email protected]"
   },
   "dependencies": {
     "@astrojs/vercel": "^8.2.0",
@@ -24,6 +31,7 @@
     "husky": "^9.1.7",
     "lint-staged": "^16.1.2",
     "postcss": "^8.5.6",
+    "semver": "^7.5.4",
     "tailwindcss": "^3.4.17"
   }
 }