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.

Mollescent

You tried some es6 features and they're not working? How are you embedding the V8 engine? – Kilogram

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. – Mollescent

@Kilogram 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". – Mollescent

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. ecma-international.org/ecma-262/#sec-source-text-module-records – Tarahtaran

Answer 1

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.
}

Shockheaded

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. – Edgaredgard

@Edgaredgard you'd return the requested modules from InstantiateModule. – Shockheaded

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? – Edgaredgard

@Edgaredgard 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. – Shockheaded

@Shockheaded I'm not sure I understand why the script should be compiled as Module if the semantics should be different? – Mulkey

@Mulkey I don't understand what you're asking. – Shockheaded

@Shockheaded 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... – Mulkey

@Mulkey 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. – Shockheaded

@Shockheaded 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... – Mulkey

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? – Renfred