nodejs-core_skill

Overview

This skill delivers deep Node.js internals expertise across V8, libuv, native addons, and the Node.js build system. It helps diagnose engine-level performance issues, develop and debug C++ addons safely, and resolve cross-platform compilation and runtime failures. The guidance focuses on practical commands, debugging workflows, and architecture-level explanations so you can fix root causes rather than symptoms.

How this skill works

I inspect runtime behavior at both JavaScript and native layers: V8 optimization and garbage collection patterns, libuv event loop phases and thread-pool interactions, and C++ addon lifecycle and memory management. For build and release issues I walk through gyp/ninja/make toolchains, linker diagnostics, and platform-specific quirks. Debugging and profiling workflows include specific commands for gdb/lldb, --prof and tracing flags, heap snapshots, and flame-graph generation.

When to use it

• Developing or debugging N-API or node-addon-api C++ addons
• Investigating GC, optimization, or deoptimization behavior in V8
• Diagnosing event loop stalls, thread-pool saturation, or async I/O regressions
• Fixing build, linkage, or cross-platform compilation failures
• Profiling CPU/memory hotspots that require native-level inspection and flame graphs
• Contributing patches to Node.js core or implementing low-level features

Best practices

• Start with high-signal, low-cost diagnostics: --trace-gc, --trace-opt, and simple heap snapshots before invasive changes
• Prefer N-API for new addons to maintain ABI stability; encapsulate native allocations and expose minimal, safe APIs
• Keep long-running or blocking work off the event loop; use UV_THREADPOOL_SIZE wisely and measure latency under load
• Instrument before optimizing: collect profiles, flame graphs, and representative workloads to avoid premature micro-optimizations
• Handle native memory explicitly: pair allocations with clear ownership, use external arrays when exposing buffers, and validate lifetime across async boundaries

Example use cases

• Track a sporadic memory leak by combining heap snapshots, native allocation tracing, and lldb allocations inspection
• Resolve a plugin crash by reproducing with sanitizers, building debug symbols, and stepping through V8 handles in gdb
• Fix high-latency I/O by analyzing libuv handles, identifying blocking operations in the thread pool, and switching to non-blocking APIs
• Port a native addon across Windows and Linux by adjusting gyp settings, resolving symbol exports, and testing with multiple Node.js releases
• Improve throughput by identifying deoptimization hotpaths with --trace-deopt and refactoring JS/C++ boundary calls to reduce hidden-class churn