How would one enable and use ES6 modules in the V8 javascript engine?

Question

I use an embedded V8 engine in my (Windows Desktop) C++ application. I understand that V8 has support for ES6 modules. How would I go about activating and using this feature in my application?

I would not expect anyone to have a complete worked example of how this works, but a high level answer pointing me (and future readers) in the right direction would entirely fulfil my hopes and aspirations for this question.

You tried some es6 features and they're not working? How are you embedding the V8 engine? — Anas, Aug 26 '18 at 04:51
I've not tried just enabling the features @Anas, it seems that, once enabled, there must be some configuration for me to complete before it actually works. How else would V8 know where to look on my filesystem for a file? If I use the following JS code, for example: `import {x} from "./y.js";` I don't think V8 would know where to look for `y.js`. — Boinst, Aug 26 '18 at 05:08
@Anas RE "how are you embedding", I think I'm embedding in a pretty standard way. Everything I do is consistent with [the "Embedder's Guide"](https://github.com/v8/v8/wiki/Embedder%27s-Guide). — Boinst, Aug 26 '18 at 05:10
I found it very helpful (given the lack of documentation) to discover that V8's implementation for modules hews awfully close to the literal text/language of the spec. https://www.ecma-international.org/ecma-262/#sec-source-text-module-records — Ron Burk, May 25 '20 at 02:40

snek · Accepted Answer · 2019-02-03T14:49:44.910

In leiu of actual examples from V8 (I was actually planning to write some at some point), I will write one here. For some examples of use in the wild I recommend Node.js's implementation, or my own, both using very similar layouts (having been written by the same people). There is also an implementation in D8, V8's CLI debugger.

Local<String> source_text = String::NewFromUtf8(
    isolate, "import 'some thing'; 1 + 1");

ScriptOrigin origin(String::NewFromUtf8("main.mjs"),      // specifier
                    Integer::New(isolate, 0),             // line offset
                    Integer::New(isolate, 0),             // column offset
                    False(isolate),                       // is cross origin
                    Local<Integer>(),                     // script id
                    Local<Value>(),                       // source map URL
                    False(isolate),                       // is opaque
                    False(isolate),                       // is WASM
                    True(isolate));                       // is ES6 module
Context::Scope context_scope(context);
ScriptCompiler::Source source(source_text, origin);
Local<Module> module;
if (!ScriptCompiler::CompileModule(isolate, &source).ToLocal(&module)) {
  // if you have a v8::TryCatch, you should check it here.
  return;
}

// You can resolve import requests ahead of time (useful for async)
for (int i = 0; i < module->GetModuleRequestsLength(); i++) {
  Local<String> specifier = module->GetModuleRequest(i); // "some thing"
}

// or you can resolve them sync in the InstantiateModule callback
module->InstantiateModule(context, [](Local<Context> context, // "main.mjs"
                                      Local<String> specifier, // "some thing"
                                      Local<Module> referrer) {
  return Local<Module>();
});

// setting this callback enables dynamic import
isolate->SetImportModuleDynamicallyCallback([](Local<Context> context,
                                               Local<ScriptOrModule> referrer,
                                               Local<String> specifier) {
  return MaybeLocal<Promise>();
});

// setting this callback enables import.meta
isolate->SetHostInitializeImportMetaObjectCallback([](Local<Context> context,
                                                      Local<Module> module,
                                                      Local<Object> meta) {
  // meta->Set(key, value); you could set import.meta.url here
});

Local<Value> result;
if (module->Evaluate(context).ToLocal(&result)) {
  String::Utf8Value utf8(isolate, result);
  printf("module eval result: %s\n", *utf8);
} else {
  // once again, if you have a v8::TryCatch, use it here.
}

How would you extend your example to support several modules that import from and export to each other? There would also be one main entry point module of course. — synchronizer, Dec 31 '19 at 15:49
@synchronizer you'd return the requested modules from InstantiateModule. — snek, Jan 01 '20 at 21:59
You don't simply load an array of files at the same time, or something along those lines? Do you mean that I need to figure out the dependencies myself? — synchronizer, Jan 01 '20 at 22:05
@synchronizer mapping specifiers to modules is left entirely to the host. You're responsible to decide how you resolve import requests, where the source is loaded from, etc. — snek, Jan 02 '20 at 02:30
@snek I'm not sure I understand why the script should be compiled as Module if the semantics should be different? — user64204, Jul 12 '20 at 14:45
@snek looking at v8 interface for module loading. It seems like any script that uses `import` is a module. I.e. it should execute once per isolate run-time. Now I'm trying to understand how the "compile once, run many times" paradigm works in a new module-based world. And it looks like, it just doesn't work at all. You cannot compile a sync function that uses a library anymore. The whole spec is unusable in an embedder's world... — user64204, Jul 15 '20 at 07:24
@user64204 the embedder explicitly chooses whether a given source text is a script or a module. See the ScriptCompiler::CompileModule() call in my example code? if I wanted to run a script I would use ScriptCompiler::Compile() instead. — snek, Jul 16 '20 at 13:02
@snek yup, but `import` cannot be used in a script. Which means either everything is a module (runs a single time, suited for long running process, like server), or you need to stick with `require()`, or use `import()` which is just an ugly async-only alias to require... — user64204, Jul 17 '20 at 15:14
Perhaps I'm blind, but could I ask for help on how to actually resolve an `import` request? You loop over all the specifiers in the ModuleRequests, but I can't figure out what I'm supposed to do next. How do I tell V8 that _this_ module should be linked to that specifier? — Cisco Ortega, Jul 26 '21 at 15:21

How would one enable and use ES6 modules in the V8 javascript engine?

1 Answers1