Comprehensive Guide to the Node.js VM Module (node:vm)

1. Introduction

The node:vm module provides APIs for compiling and running JavaScript code inside isolated V8 contexts. Each context has its own globalThis, allowing code to run independently from the main application environment. This makes vm ideal for dynamic evaluation, plugin systems, template engines, and REPL implementations.

2. Accessing the Module

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

3. Core Concepts: Contexts & Isolation

Node.js executes JavaScript inside a V8 Context. The vm module allows you to create additional contexts, each with its own global scope. Code executed inside a context only sees the variables and objects explicitly provided to it.

4. Creating a Context

const context = { foo: 'hello', console };
vm.createContext(context);

Now context becomes the global object for any code executed inside it.

5. Running Code in Different Ways

5.1 vm.runInContext()

Runs code inside an existing context.

vm.runInContext('foo += " world!"; console.log(foo)', context);
console.log(context.foo); // "hello world!"

5.2 vm.runInNewContext()

Creates a new context (or uses a provided sandbox) and runs code inside it.

const result = vm.runInNewContext('a + b', { a: 10, b: 20 });
console.log(result); // 30

5.3 vm.runInThisContext()

Runs code in the current global context — with full access to Node.js internals. Use with extreme caution.

vm.runInThisContext('process.exit(1)');

5.4 vm.Script — Precompiled Code

Compile once, run many times for better performance.

const script = new vm.Script('count += 1; name = "kitty"');

const context = { count: 0 };
vm.createContext(context);

for (let i = 0; i < 1000; i++) {
  script.runInContext(context);
}

console.log(context.count); // 1000

6. Useful Options

{
  filename: 'my-script.vm',
  lineOffset: 0,
  columnOffset: 0,
  timeout: 1000,
  breakOnSigint: true,
  microtaskMode: 'afterEvaluate'
}

7. Module Support (Experimental)

Requires --experimental-vm-modules.

const module = new vm.SourceTextModule('export default 42');
await module.link(() => {});
await module.evaluate();
console.log(module.namespace.default); // 42

8. Dynamic import() Support

Supported via importModuleDynamically callback or USE_MAIN_CONTEXT_DEFAULT_LOADER.

9. Security Warning

vm is NOT a secure sandbox. Never run untrusted code with it.

Reasons:

• May access Node.js internals if exposed
• Can freeze the event loop
• Prototype manipulation can escape sandbox
• No true isolation

Never do this:

vm.runInNewContext(userCode, { require, process });

Safer Alternatives

• Use vm.constants.DONT_CONTEXTIFY
• Freeze or strictly limit the sandbox
• Use timeout
• For real isolation: child_process, Worker Threads, containers

10. Practical Examples

10.1 Simple Sandbox

const sandbox = {
  result: null,
  console: { log: (msg) => console.log('User:', msg) }
};
vm.createContext(sandbox);

vm.runInContext('result = 2 + 3 * 4', sandbox);
console.log(sandbox.result); // 14

10.2 Template Engine

function render(template, data) {
  const code = `with(data) { return \`${template}\`; }`;
  const fn = new vm.Script(code).runInNewContext({ data });
  return fn;
}

console.log(render('Hello {{name}}!', { name: 'Ali' }));

10.3 Measuring Memory

vm.measureMemory({ mode: 'detailed', execution: 'eager' })
  .then(info => console.log(info));

11. Best Practices

• Always use createContext() + runInContext().
• Never expose require, process, or global.
• Use timeout for potentially unsafe code.
• Use vm.Script for repeated execution.
• Use microtaskMode: 'afterEvaluate' for async code.

Conclusion

The node:vm module is a powerful tool for dynamic JavaScript execution, plugin systems, template engines, and isolated logic testing. However, it must never be used as a security sandbox. With careful sandbox design and proper limitations, vm enables flexible and controlled execution of dynamic code inside Node.js applications.