/nodejs-core

name: nodejs-core
description: Contributes to and debugs Node.js core, including nodejs/node commit and PR tone, contribution workflows, native crashes, V8 performance, node-gyp builds, N-API bindings, and libuv issues. Use when drafting or reviewing a Node.js core commit or pull request, working in nodejs/node, or diagnosing C++ addons, binding.gyp failures, segfaults, native leaks, V8 deoptimizations, and event-loop internals.
metadata:
  tags: nodejs, nodejs-core, contributing, commit-message, pull-request, v8, libuv, cpp, native-addons, performance, debugging, internals

When to use

Use this skill when you need deep Node.js internals expertise, including:

• C++ addon development
• V8 engine debugging
• libuv event loop issues
• Build system problems
• Compilation failures
• Performance optimization at the engine level
• Understanding Node.js core architecture
• Writing or reviewing `nodejs/node` commits and pull request descriptions

How to use

Read individual rule files for detailed explanations and code examples:

V8 Engine

• [rules/v8-garbage-collection.md](rules/v8-garbage-collection.md) - Scavenger, Mark-Sweep, Mark-Compact, generational GC
• [rules/v8-hidden-classes.md](rules/v8-hidden-classes.md) - Hidden classes, inline caching, optimization
• [rules/v8-jit-compilation.md](rules/v8-jit-compilation.md) - TurboFan, optimization/deoptimization patterns

libuv

• [rules/libuv-event-loop.md](rules/libuv-event-loop.md) - Event loop phases, timers, I/O, idle, check, close
• [rules/libuv-thread-pool.md](rules/libuv-thread-pool.md) - Thread pool size, blocking operations, UV_THREADPOOL_SIZE
• [rules/libuv-async-io.md](rules/libuv-async-io.md) - Async I/O patterns, handles, requests

Native Addons

• [rules/napi.md](rules/napi.md) - N-API development, ABI stability, async workers
• [rules/node-addon-api.md](rules/node-addon-api.md) - C++ wrapper patterns, best practices
• [rules/native-memory.md](rules/native-memory.md) - Buffer handling, external memory, prevent leaks

Core Modules Internals

• [rules/streams-internals.md](rules/streams-internals.md) - How Node.js streams work at C++ level
• [rules/net-internals.md](rules/net-internals.md) - TCP/UDP implementation, socket handling
• [rules/fs-internals.md](rules/fs-internals.md) - libuv fs operations, sync vs async
• [rules/crypto-internals.md](rules/crypto-internals.md) - OpenSSL integration, performance considerations
• [rules/child-process-internals.md](rules/child-process-internals.md) - IPC, spawn, fork implementation
• [rules/worker-threads-internals.md](rules/worker-threads-internals.md) - SharedArrayBuffer, Atomics, MessageChannel

JavaScript Internals

• [rules/primordials.md](rules/primordials.md) - **Using primordials to prevent prototype pollution (required for `lib/internal/`)**

Build & Contributing

• [rules/build-and-test-workflow.md](rules/build-and-test-workflow.md) - **The edit-build-lint-test cycle (start here)**
• [rules/pre-commit-lint.md](rules/pre-commit-lint.md) - **Mandatory lint, format, and `core-validate-commit` gate for every commit so CI passes first time**
• [rules/configure.md](rules/configure.md) - `./configure` flags for debug builds, ASan, Ninja, etc.
• [rules/build-system.md](rules/build-system.md) - gyp, ninja, make, cross-platform compilation
• [rules/cli-options.md](rules/cli-options.md) - Adding CLI options and gating experimental modules
• [rules/contributing.md](rules/contributing.md) - How to contribute to Node.js core, the process
• [rules/commit-and-pr-guideline.md](rules/commit-and-pr-guideline.md) - Commit message and PR description style, trailers, DCO sign-off, and validation
• [rules/reviewing-prs.md](rules/reviewing-prs.md) - Reviewing PRs for correctness, clarity, and contribution quality

Documentation

• [rules/documentation.md](rules/documentation.md) - **Updating doc/api/*.md files: structure, link ordering, error docs, code example constraints**

Debugging & Profiling

• [rules/debugging-native.md](rules/debugging-native.md) - gdb, lldb, debugging C++ addons
• [rules/profiling-v8.md](rules/profiling-v8.md) - --prof, --trace-opt, --trace-deopt, flame graphs
• [rules/memory-debugging.md](rules/memory-debugging.md) - Heap snapshots, memory leak detection

Instructions

Node.js contribution writing

When drafting a `nodejs/node` commit or pull request, read [rules/commit-and-pr-guideline.md](rules/commit-and-pr-guideline.md). Use terse subsystem-prefixed titles and plain, matter-of-fact prose. Lead with concrete behavior, explain the reason for the change, and omit hype, canned headings, file-by-file narration, and unsupported claims. Include the contributor's DCO sign-off, and never add `PR-URL:` or `Reviewed-By:` — those are added when the change lands. Validate the result with `npx core-validate-commit --no-validate-metadata <sha>` in the `nodejs/node` checkout.

MANDATORY: Rebuild before testing

Node.js embeds `lib/` JavaScript files into the binary at compile time via `js2c`. **After ANY change to `src/` or `lib/`, you MUST rebuild before running tests.** Without a rebuild, tests run against stale code and results are meaningless.

edit src/ or lib/  →  make -j$(nproc)  →  make lint  →  then test

Never skip the rebuild step. Never run `./node test/...` after editing without building first.

Before starting work, **ask the user** about their build configuration (Make vs Ninja, debug vs release, what configure flags they use). Do not assume a specific setup. Most of the time, `./configure` has already been run and only `make -j$(nproc)` is needed to rebuild.

MANDATORY: Lint and format before every commit

Node.js runs a `Linters` CI workflow on every non-draft pull request, and on Unix `make test` runs **no** linters. Run `make lint` before each `git commit` — plus `make format-cpp` for C++ changes — so the lint jobs pass on the first CI run instead of costing a force-push and another full cycle.