Environment Requirements

This page outlines the essential environment requirements and setup recommendations for contributing to the Network Pro™ Web Presence project.

 

Table of Contents

• Runtime Requirements
• Local Setup Script
• Manual Setup
• Post-Install Checks
• Version Enforcement

---

✅ Runtime Requirements

Ensure the following versions are installed on your system:

"engines": {
  "node": ">=22.0.0 <25",
  "npm": ">=11.0.0 <12"
}

These constraints are defined in package.json and automatically verified during setup.

Node Version Managers

To simplify environment setup and ensure consistency, we recommend using a Node version manager:

• nvm
• asdf
• Volta

This repository includes .nvmrc and .node-version files to streamline setup with these tools.

 

_{Back to top}

🧰 Local Setup Script

Run the following to bootstrap your local dev environment:

./scripts/bootstrap.local.sh

This script:

• Detects your OS (macOS/Linux)
• Installs Playwright dependencies (if required)
• Copies .env.template to .env if not already present
• Installs Node packages and validates the environment

 

_{Back to top}

📦 Manual Setup

If you prefer a manual setup:

git clone https://github.com/netwk-pro/netwk-pro.github.io.git
cd netwk-pro.github.io
cp .env.template .env
npm install

Then run:

npx playwright install

This installs required browser binaries for testing.

 

_{Back to top}

🧪 Post-Install Checks

After npm install, several validations run automatically:

• Node and npm version checks
• Friendly guidance if your setup is out of spec

 

_{Back to top}

💾 Version Enforcement

To ensure consistent environments across contributors and CI systems, this project enforces specific Node.js and npm versions via the "engines" field in package.json:

"engines": {
  "node": ">=22.0.0 <25",
  "npm": ">=11.0.0 <12"
}

Version compliance is gently enforced after installation (non-blocking during npm install) via a postinstall lifecycle hook:

npm run check:node

This script runs scripts/checkNode.js, which compares your current Node.js and npm versions against the required ranges. During the install phase, it will log warnings for out-of-range versions but allow installation to continue. In all other contexts (manual runs, CI workflows, etc.), it will fail with a descriptive error if the versions are out of spec.

Node Version Check (snippet from scripts/checkNode.js)

const semver = require('semver');
const { engines } = require('../package.json');

const requiredNode = engines.node;
const requiredNpm = engines.npm;
const isPostInstall = process.env.npm_lifecycle_event === 'postinstall';

let hasError = false;

if (!semver.satisfies(process.version, requiredNode)) {
  const msg = `Node.js ${process.version} does not satisfy required range: ${requiredNode}`;
  isPostInstall ? console.warn(`⚠️  ${msg}`) : console.error(`❌ ${msg}`);
  if (!isPostInstall) hasError = true;
}

const npmVersion = require('child_process')
  .execSync('npm -v')
  .toString()
  .trim();

if (!semver.satisfies(npmVersion, requiredNpm)) {
  const msg = `npm ${npmVersion} does not satisfy required range: ${requiredNpm}`;
  isPostInstall ? console.warn(`⚠️  ${msg}`) : console.error(`❌ ${msg}`);
  if (!isPostInstall) hasError = true;
}

if (!hasError) {
  console.log('✅ Node and npm versions are valid.');
} else {
  process.exit(1);
}

For full compatibility, .nvmrc and .node-version files are provided to work seamlessly with version managers like nvm, asdf, and Volta. This ensures consistent environments across local development, CI pipelines, and deployment targets.

To manually verify your environment:

node -v     # Should fall within engines.node
npm -v      # Should fall within engines.npm

 

_{Back to top}