Getting started

This page tells you how to clone, build, and run node from this repository. The authoritative reference is BUILDING.md; this is a fast, opinionated path that covers the cases most contributors actually hit.

Prerequisites

Pulled from BUILDING.md "Prerequisites":

• Python 3.x available as python3 (the build system is GYP-based and Python-driven).
• A C/C++ toolchain:
  • Linux: GCC ≥ 12.2 or Clang ≥ 8 with libstdc++ ≥ 12.
  • macOS: Xcode Command Line Tools (xcode-select --install).
  • Windows: Visual Studio with the "Desktop development with C++" workload (use vcbuild.bat from a Developer PowerShell).
• GNU Make (or Ninja, see below). On Windows, vcbuild.bat drives MSBuild.
• ccache is recommended for fast incremental rebuilds.
• For ICU "full" builds, an internet connection (downloads ICU data the first time) or a pre-staged tarball.

The supported-platform matrix and toolchain versions live in BUILDING.md § "Platform list" and § "Supported toolchains" — they change every major. If your platform is not Tier 1 or Tier 2, expect bumps.

Get the source

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

The repository is large (≈ 47 000 commits). A shallow clone is fine for most contributing work but git log, git blame, and the lore-style scripts under tools/ need full history.

Build

The default unix build is just:

./configure
make -j"$(getconf _NPROCESSORS_ONLN)"

That writes out/Release/node. You typically symlink it into your PATH:

ln -s "$(pwd)/out/Release/node" ~/bin/node

Useful ./configure flags (full list: ./configure --help):

Flag	Purpose
--debug	Build out/Debug/node with assertions and symbols (slow but invaluable)
--ninja	Generate Ninja files instead of Makefiles
--shared	Build libnode.so for embedders
--without-intl	Strip ICU
--with-intl=full-icu	Bundle full Unicode data
--openssl-no-asm	Disable assembly in OpenSSL (when cross compiling)
--openssl-is-fips	Build against a FIPS-validated OpenSSL
--enable-asan	Build with AddressSanitizer (make with the resulting out/)
--node-builtin-modules-path=$(pwd)	Load lib/*.js from disk at runtime instead of from the binary's embedded blob (great for editing JS without rebuilding)

After the first ./configure you usually only need make — it re-runs configure when node.gyp, common.gypi, or configure.py change.

Speeding up rebuilds

• --ninja is materially faster than Make for large rebuilds.
• ccache avoids recompiling unchanged C/C++ translation units.
• For pure-JS work, use --node-builtin-modules-path so editing lib/** does not require relinking the binary. See BUILDING.md § "Loading JS files from disk instead of embedding".
• make -j saturates CPU; pair with make V=1 only when debugging build commands.

Run the test suite

The test driver is tools/test.py, fronted by Make targets:

make test            # full suite (slow)
make test-only       # just the parallel/sequential JS tests
make test-ci         # what CI runs
make jstest          # JS unit tests with the active build
make cctest          # C++ unit tests in test/cctest/
python3 tools/test.py test/parallel/test-fs-readfile.js   # one file
python3 tools/test.py --mode=release parallel sequential  # subset

See How to contribute › Testing for the test categories under test/ and how to write new tests.

Lint and format

make lint            # everything
make lint-md         # markdown only (used heavily by docs PRs)
make lint-cpp        # cpplint over src/
make lint-js         # ESLint over lib/, test/, doc/, tools/
make format-cpp      # clang-format the C++ tree

ESLint is configured in eslint.config.mjs plus per-tree eslint.config_partial.mjs files. There are project-specific rules in tools/eslint-rules/ (see Patterns and conventions).

Build documentation

make doc          # generates HTML+JSON in out/doc/api/

The doc tooling is in tools/doc/. Markdown sources are in doc/api/. Lint with make lint-md-build and make lint-md.

Run a debug build under a debugger

./configure --debug
make -j$(nproc)
gdb --args ./out/Debug/node app.js          # Linux
lldb -- ./out/Debug/node app.js             # macOS

Inside node, use --inspect, --inspect-brk, or the inspector-aware tools (node inspect, Chrome DevTools, VS Code) to debug the JS side. The C++ side typically uses gdb/lldb on the debug build.

A reasonable contributor loop

1. Fork; create a topic branch.
2. make -j ccache=on and run targeted tests with tools/test.py.
3. make lint before pushing.
4. Open the PR. Add the right subsystem: prefix to the commit subject (see CONTRIBUTING.md and Patterns and conventions).
5. Wait for nodejs-github-bot and reviewers; rerun CI as needed.

The full review/landing playbook is in doc/contributing/collaborator-guide.md, summarised in How to contribute › Development workflow.