Codakey
Play
← Back to nodejs/node

How to Deploy & Use nodejs/node

# Node.js Runtime Build and Deployment Guide

This guide covers building the Node.js JavaScript runtime from source, configuring build options, and deploying the compiled binary.

## Prerequisites

### Required Tools

- **Python**: Version 3.11 or newer (required for the build system)
- **C++ Compiler**: 
 - GCC 10.x or newer (Linux)
 - Clang 12.x or newer (macOS/Linux)
 - MSVC 2019 or newer (Windows)
- **Make**: GNU Make 3.81+ or Ninja build system
- **Git**: For cloning the repository

### Platform-Specific Dependencies

**Linux (Debian/Ubuntu):**
```bash
sudo apt-get install python3 g++ make python3-pip

Linux (RHEL/CentOS/Fedora):

sudo dnf install python3 gcc-c++ make

macOS:

# Install Xcode Command Line Tools
xcode-select --install

Windows:

  • Visual Studio 2019 or newer with "Desktop development with C++" workload
  • Python 3.11+ from python.org or Microsoft Store
  • Git for Windows

Installation

1. Clone the Repository

git clone https://github.com/nodejs/node.git
cd node

For a specific version:

git checkout v22.x  # Current branch
# or
git checkout v20.x  # LTS branch

2. Install Python Dependencies (if needed)

pip3 install setuptools

Configuration

Configure Build Options

Run the configure script to set up build parameters:

./configure --prefix=/usr/local

Common configuration flags:

# Debug build
./configure --debug

# Release build with specific prefix
./configure --prefix=/opt/node --enable-static

# Minimal build (no bundled dependencies)
./configure --without-npm --without-corepack

# Configure with Ninja instead of Make
./configure --ninja

Environment Variables

Set these before running configure or make:

VariableDescription
CCC compiler path (e.g., gcc or clang)
CXXC++ compiler path (e.g., g++ or clang++)
PYTHONPython executable path
DESTDIRDestination for make install (useful for packaging)

Example:

export CC=clang
export CXX=clang++
./configure --prefix=/usr/local

Build & Run

Building the Runtime

Compile Node.js using Make:

make -j$(nproc)

Or with Ninja (if configured):

ninja -C out/Release

This generates the node executable in the out/Release/ directory (or out/Debug/ for debug builds).

Running the Built Binary

Test the compiled runtime:

./node --version
./node -e "console.log('Hello from Node.js')"

Running Tests

Validate the build:

make test          # Run all tests
make test-only     # Run tests without building
make jslint        # Run JavaScript linting
make cpplint       # Run C++ linting

Development Mode

For active development with faster rebuilds:

# Incremental build
make -j$(nproc) node

# Run specific test
./node ./test/parallel/test-http.js

Deployment

System Installation

Install the built binary system-wide:

sudo make install

This installs:

  • node binary to $prefix/bin/
  • npm and npx (if not excluded)
  • Corepack (if enabled)
  • Man pages to $prefix/share/man/

Creating Distribution Packages

Build a distributable tarball:

make binary
# Creates: node-vXX.X.X-linux-x64.tar.xz

Docker Deployment

Build a minimal Docker image with your compiled Node.js:

FROM ubuntu:22.04
COPY out/Release/node /usr/local/bin/node
ENTRYPOINT ["node"]

Build and run:

docker build -t custom-node .
docker run --rm custom-node --version

Verification

Verify binary signatures before deployment (for official releases):

curl -fsO "https://nodejs.org/dist/v22.0.0/SHASUMS256.txt.asc"
gpgv --keyring=/path/to/nodejs-keyring.kbx SHASUMS256.txt.asc
shasum -a 256 --check SHASUMS256.txt --ignore-missing

Troubleshooting

Build Failures

Error: Python not found

  • Ensure Python 3.11+ is installed and in PATH
  • Set explicitly: PYTHON=/usr/bin/python3 ./configure

Error: C++ compiler too old

  • GCC 10+ or Clang 12+ required
  • Check version: gcc --version

Error: WebAssembly module compilation failed

  • Related to llhttp WASM parser (seen in deps/undici)
  • Set UNDICI_NO_WASM_SIMD=1 to disable SIMD if on Power9 or problematic architecture

Error: No rule to make target

  • Run ./configure first before make
  • Clean and reconfigure: make distclean && ./configure

Runtime Issues

Module not found errors

  • Ensure NODE_PATH includes your global modules if using custom prefix
  • For local builds: ./node -e "require('./lib/repl')"

HTTP Parser errors

  • The HTTP parser uses WASM (see deps/undici/src/lib/dispatcher/client-h1.js)
  • If WASM fails to load, Node.js falls back to native implementation

Platform-Specific Issues

macOS: clang: error: invalid version number

  • Update Xcode Command Line Tools: softwareupdate --install --all

Windows: MSB8020 build tools error

  • Ensure "Desktop development with C++" workload is installed in Visual Studio
  • Run from "Developer Command Prompt for VS"

Linux: undefined reference to std::filesystem

  • Add linker flag: ./configure LDFLAGS="-lstdc++fs"

Getting Help

  • Check BUILDING.md in the repository for platform-specific details
  • Review GitHub Issues for similar errors
  • Join the Node.js Slack or Discord for real-time help
← Project overviewView alternatives to nodejs/node →