Stability: 1 - Experimental

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

    The vm.Module class provides a low-level interface for using ECMAScript modules in VM contexts. It is the counterpart of the vm.Script class that closely mirrors [Module Record][]s as defined in the ECMAScript specification.

    Unlike vm.Script however, every vm.Module object is bound to a context from its creation. Operations on vm.Module objects are intrinsically asynchronous, in contrast with the synchronous nature of vm.Script objects. The use of ‘async’ functions can help with manipulating vm.Module objects.

    Using a vm.Module object requires three distinct steps: creation/parsing, linking, and evaluation. These three steps are illustrated in the following example.

    This implementation lies at a lower level than the [ECMAScript Module loader][]. There is also no way to interact with the Loader yet, though support is planned.

    1. const vm = require('vm');
    3. const contextifiedObject = vm.createContext({
    4.   secret: 42,
    5.   print: console.log,
    6. });
    8. (async () => {
    9.   // Step 1
    10.   //
    11.   // Create a Module by constructing a new `vm.SourceTextModule` object. This
    12.   // parses the provided source text, throwing a `SyntaxError` if anything goes
    13.   // wrong. By default, a Module is created in the top context. But here, we
    14.   // specify `contextifiedObject` as the context this Module belongs to.
    15.   //
    16.   // Here, we attempt to obtain the default export from the module "foo", and
    17.   // put it into local binding "secret".
    19.   const bar = new vm.SourceTextModule(`
    20.     import s from 'foo';
    21.     s;
    22.     print(s);
    23.   `, { context: contextifiedObject });
    25.   // Step 2
    26.   //
    27.   // "Link" the imported dependencies of this Module to it.
    28.   //
    29.   // The provided linking callback (the "linker") accepts two arguments: the
    30.   // parent module (`bar` in this case) and the string that is the specifier of
    31.   // the imported module. The callback is expected to return a Module that
    32.   // corresponds to the provided specifier, with certain requirements documented
    33.   // in `module.link()`.
    34.   //
    35.   // If linking has not started for the returned Module, the same linker
    36.   // callback will be called on the returned Module.
    37.   //
    38.   // Even top-level Modules without dependencies must be explicitly linked. The
    39.   // callback provided would never be called, however.
    40.   //
    41.   // The link() method returns a Promise that will be resolved when all the
    42.   // Promises returned by the linker resolve.
    43.   //
    44.   // Note: This is a contrived example in that the linker function creates a new
    45.   // "foo" module every time it is called. In a full-fledged module system, a
    46.   // cache would probably be used to avoid duplicated modules.
    48.   async function linker(specifier, referencingModule) {
    49.     if (specifier === 'foo') {
    50.       return new vm.SourceTextModule(`
    51.         // The "secret" variable refers to the global variable we added to
    52.         // "contextifiedObject" when creating the context.
    53.         export default secret;
    54.       `, { context: referencingModule.context });
    56.       // Using `contextifiedObject` instead of `referencingModule.context`
    57.       // here would work as well.
    58.     }
    59.     throw new Error(`Unable to resolve dependency: ${specifier}`);
    60.   }
    61.   await bar.link(linker);
    63.   // Step 3
    64.   //
    65.   // Evaluate the Module. The evaluate() method returns a promise which will
    66.   // resolve after the module has finished evaluating.
    68.   // Prints 42.
    69.   await bar.evaluate();
    70. })();