This page outlines the essential environment requirements and setup
recommendations for contributing to the **Network Pro™ Web Presence** project.
### Table of Contents
- [Runtime Requirements](#runtime)
- [Local Setup Script](#local-setup)
- [Manual Setup](#manual-setup)
- [Post-Install Checks](#postinstall)
- [Version Enforcement](#version)
---
## ✅ Runtime Requirements
Ensure the following versions are installed on your system:
```json
"engines": {
"node": ">=22.0.0 <25",
"npm": ">=10.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](https://github.com/nvm-sh/nvm)
- [asdf](https://asdf-vm.com/)
- [Volta](https://volta.sh/)
This repository includes `.nvmrc` and `.node-version` files to streamline setup
with these tools.
[Back to top](#top)
## 🧰 Local Setup Script
Run the following to bootstrap your local dev environment:
```bash
./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](#top)
## 📦 Manual Setup
If you prefer a manual setup:
```bash
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:
```bash
npx playwright install
```
This installs required browser binaries for testing.
[Back to top](#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](#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`:
```json
"engines": {
"node": ">=22.0.0 <25",
"npm": ">=10.0.0 <12"
}
```
Version compliance is **gently enforced** after installation (non-blocking
during `npm install`) via a postinstall lifecycle hook:
```bash
npm run check:node
```
This script runs
[`scripts/checkNode.js`](https://github.com/netwk-pro/netwk-pro.github.io/blob/master/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`)_**
```javascript
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:
```bash
node -v # Should fall within engines.node
npm -v # Should fall within engines.npm
```
[Back to top](#top)