Expression evaluation
Evaluate controlled JavaScript expressions against application-provided values.
Node.js · Module
node:vm
The node:vm module compiles and runs JavaScript in V8 Virtual Machine contexts. It supports direct execution, reusable vm.Script objects, and low-level ECMAScript module execution.
How it works
The module compiles JavaScript into a vm.Script or executes source directly, then runs it in a V8 context whose global object is supplied by a contextified sandbox. Scripts can be compiled once and evaluated repeatedly in selected contexts, while module APIs provide lower-level ECMAScript-module execution.
Syntax
import vm from 'node:vm';
vm.createContext(sandbox);
const script = new vm.Script(code, options);
script.runInContext(contextifiedSandbox, options);Parameters
| Name | Type | Description |
|---|---|---|
code | string | JavaScript source code to compile or execute. |
sandbox | Object | Object used as the global object for a context after contextification. |
contextifiedSandbox | Object | Contextified object in which compiled code executes. |
options | Object | Options controlling compilation or execution, including metadata such as filename and timeout where supported. |
Returns
Depending on the API, execution returns the evaluated JavaScript value; vm.createContext returns a contextified sandbox, and vm.Script construction returns a compiled Script object.
Key points
- Use node:vm to compile and execute JavaScript in V8 VM contexts.
- vm.Script stores compiled JavaScript for later execution in chosen contexts.
- A VM context gives evaluated code a global object distinct from the surrounding application.
- vm.createContext prepares a sandbox object for use as a VM context.
- The low-level vm.Module workflow consists of creation or parsing, linking, and evaluation.
Common mistakes
- Do not treat a VM context as a security boundary for untrusted JavaScript.
- Code evaluated in a VM context cannot directly access the caller's lexical local variables.
Example: Compile and run code in a context
import vm from 'node:vm';
const sandbox = { value: 7 };
vm.createContext(sandbox);
const script = new vm.Script('value * 6');
const result = script.runInContext(sandbox);
console.log(result); // 42Creates a VM context from an object, compiles an expression once, and evaluates it against that context.
When to use it
Reusable script execution
Compile source once and execute it repeatedly in separate or reused contexts.
Controlled module execution
Implement low-level ECMAScript-module workflows inside VM contexts.
Interview questions
QWhat is the purpose of the node:vm module?
It provides APIs for compiling and running JavaScript within V8 Virtual Machine contexts. A context has its own global object, and a sandbox object can be contextified for use as that global.
Follow-up: How can compilation be separated from execution? Create a vm.Script once, then call runInContext with a contextified sandbox whenever evaluation is needed.
QWhy use vm.Script instead of evaluating source immediately?
vm.Script represents precompiled code and does not execute during construction. Its compiled code can later run in a selected context, which makes repeated evaluation possible without recompiling the source.
Follow-up: What changes when using vm.runInContext directly? The source is compiled and run in the supplied context as one operation rather than being retained as a Script object.
QCan node:vm safely sandbox untrusted code?
No. The documentation explicitly says the module is not a security mechanism and must not be used to run untrusted code. It is intended for controlled execution contexts, not isolation against hostile code.
Follow-up: What is a safer design for hostile input? Keep untrusted code out of the process or use a separately hardened isolation boundary rather than relying on node:vm.
Related
vm.Scriptvm.Modulevm.createContextvm.runInContextvm.runInNewContextvm.runInThisContextvm.isContext