index

Usage

import * as mod from "node:vm";

The node:vm module enables compiling and running code within V8 Virtual Machine contexts.

The node:vm module is not a security mechanism. Do not use it to run untrusted code.

JavaScript code can be compiled and run immediately or compiled, saved, and run later.

A common use case is to run the code in a different V8 Context. This means invoked code has a different global object than the invoking code.

One can provide the context by contextifying an object. The invoked code treats any property in the context like a global variable. Any changes to global variables caused by the invoked code are reflected in the context object.

const vm = require('node:vm');

const x = 1;

const context = { x: 2 };
vm.createContext(context); // Contextify the object.

const code = 'x += 40; var y = 17;';
// `x` and `y` are global variables in the context.
// Initially, x has the value 2 because that is the value of context.x.
vm.runInContext(code, context);

console.log(context.x); // 42
console.log(context.y); // 17

console.log(x); // 1; y is not defined.

Classes

Module

This feature is only available with the --experimental-vm-modules command flag enabled.

Script

Instances of the vm.Script class contain precompiled scripts that can be executed in specific contexts.

SourceTextModule

This feature is only available with the --experimental-vm-modules command flag enabled.

SyntheticModule

This feature is only available with the --experimental-vm-modules command flag enabled.

Functions

compileFunction

Compiles the given code into the provided context (if no context is supplied, the current context is used), and returns it wrapped inside a function with the given params.

createContext

If given a contextObject, the vm.createContext() method will prepare that object so that it can be used in calls to runInContext or script.runInContext(). Inside such scripts, the contextObject will be the global object, retaining all of its existing properties but also having the built-in objects and functions any standard global object has. Outside of scripts run by the vm module, global variables will remain unchanged.

isContext

Returns true if the given object object has been contextified using createContext.

measureMemory

Measure the memory known to V8 and used by all contexts known to the current V8 isolate, or the main context.

runInContext

The vm.runInContext() method compiles code, runs it within the context of the contextifiedObject, then returns the result. Running code does not have access to the local scope. The contextifiedObject object must have been previously contextified using the createContext method.

runInNewContext

The vm.runInNewContext() first contextifies the given contextObject (or creates a new contextObject if passed as undefined), compiles the code, runs it within the created context, then returns the result. Running code does not have access to the local scope.

runInThisContext

vm.runInThisContext() compiles code, runs it within the context of the current global and returns the result. Running code does not have access to local scope, but does have access to the current global object.