vm.createContext

History

vm.createContext(contextObject?, options?): Object

Attributes

contextObject:Object | vm.constants.DONT_CONTEXTIFY | undefined

Either vm.constants.DONT_CONTEXTIFY or an object that will be contextified. If undefined, an empty contextified object will be created for backwards compatibility.

options:Object

name?:string

Human-readable name of the newly created context. Default: 'VM Context i', where i is an ascending numerical index of the created context.

origin?:string

Origin corresponding to the newly created context for display purposes. The origin should be formatted like a URL, but with only the scheme, host, and port (if necessary), like the value of the url.origin property of a URL object. Most notably, this string should omit the trailing slash, as that denotes a path. Default: ''.

codeGeneration:Object

strings?:boolean

If set to false any calls to eval or function constructors (Function, GeneratorFunction, etc) will throw an EvalError. Default: true.

wasm?:boolean

If set to false any attempt to compile a WebAssembly module will throw a WebAssembly.CompileError. Default: true.

microtaskMode:string

If set to afterEvaluate, microtasks (tasks scheduled through Promises and async functions) will be run immediately after a script has run through script.runInContext(). They are included in the timeout and breakOnSigint scopes in that case.

importModuleDynamically:Function | vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER

Used to specify the how the modules should be loaded when import() is called in this context without a referrer script or module. This option is part of the experimental modules API. We do not recommend using it in a production environment. For detailed information, see Support of dynamic import() in compilation APIs.

Returns:Object

contextified object.

If the given contextObject is an object, the vm.createContext() method will prepare that object and return a reference to it so that it can be used in calls to vm.runInContext() or script.runInContext(). Inside such scripts, the global object will be wrapped by the contextObject, 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.

import { createContext, runInContext } from 'node:vm';

global.globalVar = 3;

const context = { globalVar: 1 };
createContext(context);

runInContext('globalVar *= 2;', context);

console.log(context);
// Prints: { globalVar: 2 }

console.log(global.globalVar);
// Prints: 3

JavaScript

const { createContext, runInContext } = require('node:vm');

global.globalVar = 3;

const context = { globalVar: 1 };
createContext(context);

runInContext('globalVar *= 2;', context);

console.log(context);
// Prints: { globalVar: 2 }

console.log(global.globalVar);
// Prints: 3

JavaScript

If contextObject is omitted (or passed explicitly as undefined), a new, empty contextified object will be returned.

When the global object in the newly created context is contextified, it has some quirks compared to ordinary global objects. For example, it cannot be frozen. To create a context without the contextifying quirks, pass vm.constants.DONT_CONTEXTIFY as the contextObject argument. See the documentation of vm.constants.DONT_CONTEXTIFY for details.

The vm.createContext() method is primarily useful for creating a single context that can be used to run multiple scripts. For instance, if emulating a web browser, the method can be used to create a single context representing a window's global object, then run all <script> tags together within that context.

The provided name and origin of the context are made visible through the Inspector API.