# Node.js Version Requirements for TypeScript/JavaScript Profiling
## Minimum Required Version
**Node.js v12.0.0** (Released April 23, 2019)
The `--cpu-prof` flag was introduced in Node.js v12.0.0, which enables built-in CPU profiling without external dependencies.
## Supported Node.js Versions
### ✅ Currently Supported LTS Versions
| v20.x | Iron | Oct 2023 | Apr 2026 | ✅ Active LTS |
| v18.x | Hydrogen | Oct 2022 | Apr 2025 | ✅ Active LTS |
### ✅ Previous LTS Versions (End of Life but Supported)
| v16.x | Gallium | Oct 2021 | Sep 2023 | ✅ Works (EOL) |
| v14.x | Fermium | Oct 2020 | Apr 2023 | ✅ Works (EOL) |
| v12.x | Erbium | Oct 2019 | Apr 2022 | ✅ Works (EOL) |
### ✅ Current Non-LTS Versions
| v22.x | Apr 2024 | ✅ Works |
| v21.x | Oct 2023 | ✅ Works |
### ❌ Unsupported Versions
| v11.x and earlier | No `--cpu-prof` support |
| v10.x (Dubnium LTS) | Released before `--cpu-prof` was added |
## CPU Profiling Features by Version
### Node.js v12.0.0+
Introduced three new command-line flags:
- `--cpu-prof` - Start the V8 CPU profiler on start up
- `--cpu-prof-dir` - Directory where the CPU profiles will be saved (default: current working directory)
- `--cpu-prof-name` - File name of the CPU profile (default: `CPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile`)
### Profile Format
The CPU profiler generates profiles in V8's CPU profile format (JSON), which includes:
- Call frames with function names
- File names and line numbers
- Sample counts and timing information
- Call trees and execution paths
## Checking Your Node.js Version
```bash
node --version
```
Example output:
```
v20.11.0
```
To check if `--cpu-prof` is available:
```bash
Expected output (if supported):
```
--cpu-prof Start the V8 CPU profiler on start up, and write
--cpu-prof-dir directory where the CPU profiles generated by
--cpu-prof-name file name of the CPU profile generated by
```
## Testing CPU Profiling
### Quick Test
```bash
node --cpu-prof --cpu-prof-dir=/tmp -e "console.log('test')"
ls -la /tmp/*.cpuprofile
```
If successful, you should see a `.cpuprofile` file created in `/tmp`.
### With Our Profiler
```bash
# Profile a simple JavaScript file
cargo run -- typescript examples/test_node.js
# Profile with JSON export
cargo run -- typescript examples/test_node.js --json output.json
```
## Upgrading Node.js
### Using nvm (Node Version Manager)
```bash
# Install nvm (if not already installed)
# Install latest LTS
nvm install --lts
# Or install specific version
nvm install 20
nvm use 20
```
### Using Official Installers
- Download from [nodejs.org](https://nodejs.org/)
- LTS version recommended for production use
- Current version for latest features
### Using Package Managers
**macOS (Homebrew):**
```bash
brew install node@20
```
**Ubuntu/Debian:**
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```
**Windows (Chocolatey):**
```powershell
choco install nodejs-lts
```
## Alternative Profiling Methods (For Older Node.js Versions)
If you're stuck on Node.js v10 or v11, you can use these alternatives:
### 1. Inspector Protocol with Chrome DevTools
```bash
node --inspect your-script.js
```
Then open `chrome://inspect` in Chrome and click "inspect" on your Node.js process.
### 2. clinic.js
```bash
npm install -g clinic
clinic doctor -- node your-script.js
```
### 3. 0x Profiler
```bash
npm install -g 0x
0x your-script.js
```
### 4. V8 Profiler (Legacy)
```bash
node --prof your-script.js
node --prof-process isolate-*.log > processed.txt
```
Note: This generates a low-level V8 log that requires post-processing.
## Continuous Integration
When using this profiler in CI/CD pipelines, ensure your Node.js version is v12 or higher:
### GitHub Actions
```yaml
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '20' # or '18', '16', etc.
```
### GitLab CI
```yaml
image: node:20-alpine
test:
script:
- node --version
- cargo test
```
### Docker
```dockerfile
FROM rust:latest
# Install Node.js v20
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
&& apt-get install -y nodejs
# Verify installation
## Troubleshooting
### Error: "bad option: --cpu-prof"
This means your Node.js version is too old. Upgrade to v12 or later.
### Profile Not Generated
1. Check that your script runs successfully first
2. Ensure you have write permissions to the output directory
3. Try specifying an explicit directory with `--cpu-prof-dir`
4. Check Node.js stderr for error messages
### Empty or Minimal Profile Data
1. Ensure your script runs long enough to collect samples (at least 100ms)
2. CPU-bound operations produce better profiles than I/O-bound operations
3. Try a more CPU-intensive workload
## References
- [Node.js v12.0.0 Release Notes](https://nodejs.org/en/blog/release/v12.0.0/)
- [V8 CPU Profiler Documentation](https://v8.dev/docs/profile)
- [Node.js Command Line Options](https://nodejs.org/api/cli.html#--cpu-prof)
- [Node.js Release Schedule](https://github.com/nodejs/release#release-schedule)