V8 Reference
V8 Inspection Flags
Make the engine show its work — no source build required. Pass these to
node; Node forwards unrecognized --flags to its embedded V8.
Pattern: node <v8-flags> yourscript.js.
Many flags are debug-oriented but work in release Node. See the full list any time with
node --v8-options (hundreds of them).
Seeing the compiler pipeline
| Flag | Shows you |
|---|
| --print-bytecode | The Ignition bytecode generated for each function. |
| --print-bytecode-filter=NAME | Limit bytecode dumps to functions matching NAME. Essential — otherwise you drown in built-ins. |
| --print-ast | The Abstract Syntax Tree from the parser (the stage before bytecode). |
| --trace-opt | Logs when a function is selected for optimization (promoted to Maglev/TurboFan). |
| --trace-deopt | Logs deoptimizations — when optimized code bails back to bytecode (e.g. a type assumption broke). |
| --print-opt-code | Disassembly of the optimized machine code (verbose; filter it). |
| --trace-maps | Logs hidden-class (Map) creation and transitions — for the object-model lessons. |
| --trace-gc | One line per garbage-collection event (type, sizes, pause time). |
Forcing behavior with native syntax
Requires --allow-natives-syntax. Unlocks %-prefixed
intrinsics — V8's internal test hooks. These are not JavaScript; they only exist with the flag.
| Intrinsic | Effect |
|---|
| %OptimizeFunctionOnNextCall(fn) | Force fn to be optimized on its next call. |
| %GetOptimizationStatus(fn) | Returns a bitfield describing fn's compile state (optimized? interpreted? TurboFan? Maglev?). |
| %PrepareFunctionForOptimization(fn) | Often required before %OptimizeFunctionOnNextCall in newer V8 — sets up feedback. |
| %DebugPrint(obj) | Dumps an object's internal layout — its Map (hidden class), elements, properties. |
| %HaveSameMap(a, b) | True if two objects share a hidden class — the core test for "same shape". |
| %CollectGarbage(null) | Force a full GC. Handy when pairing with --trace-gc. |
Handy combinations
node --print-bytecode --print-bytecode-filter=add demo.js
node --allow-natives-syntax --trace-opt --trace-deopt demo.js
node --allow-natives-syntax demo.js # then call %DebugPrint(obj) inside
node --trace-gc --trace-gc-verbose demo.js
Later, with d8: once you build V8 from source you'll use
the d8 shell instead of node. The same flags apply
(d8 --print-bytecode file.js), plus d8-only goodies like --print-code
and a built-in REPL. Until then, Node is a perfectly good V8.