script.runInNewContext() Method in Node.js

Introduction

Node.js gives developers powerful tools to run JavaScript code safely and independently using the vm module. One such tool is the script.runInNewContext() method, which allows code execution inside a newly created context (sandbox). This method is useful when you want complete isolation between your main program and the code being executed.

What is script.runInNewContext()?

The script.runInNewContext() method runs a compiled script inside a brand-new context. Unlike runInThisContext() or runInContext(), this method creates a fresh context every time it’s called, making it ideal for securely executing untrusted or external code.

Syntax

script.runInNewContext([sandbox][, options])

- sandbox (optional): An object that acts as the global scope for the script.
- options (optional): Configuration like filename, timeout, lineOffset, etc.

Example

const vm = require('vm');

// Define script
const code = 'message = "Hello from sandbox";';

// Compile script
const script = new vm.Script(code);

// Run in new context
const result = script.runInNewContext({}, { timeout: 1000 });

console.log(result); // undefined, but 'message' is in sandbox

In this example, the script runs inside a newly created sandbox. The variable message exists only in that sandbox and does not affect the main environment.

Accessing Values from Sandbox

You can pass an object to act as the sandbox and retrieve updated values after the script runs:

const context = { a: 5, b: 10 };
const script2 = new vm.Script('result = a + b;');

script2.runInNewContext(context);

console.log(context.result); // 15

The context object acts as the sandbox’s global scope, allowing two-way communication with the script.

Why Use runInNewContext()?

This method is helpful when:

• You need to safely run code without risking your main environment.
• You want each execution to be completely independent and fresh.
• You’re executing code dynamically (e.g., in REPL tools, compilers, or interpreters).

Options Parameter

The optional options object can contain:

• filename: For debugging and stack traces.
• timeout: To prevent infinite loops or long-running code.
• lineOffset and columnOffset: Adjustments for error messages.

Security Tips

While runInNewContext() isolates the code, always validate or sanitize input when dealing with external code to avoid logic-based vulnerabilities or resource overuse.

Conclusion

The script.runInNewContext() method in Node.js offers a safe and flexible way to run JavaScript code in a clean, sandboxed environment. It’s perfect for cases where complete isolation and control are required, making it a valuable tool for any developer working with dynamic or external scripts.