Life of an ESM in Node.js – and How It's Changing for the Better

Hi, thanks for having me today. Today this talk is about life of an ESM in Node. So this is a talk about fundamentals, and one of the most fundamental things in JavaScript is modules. Today we'll cover what happens when Node is asked to import a module, how the different stages of module loading differ in Node bundlers and browsers, and new Node transpiler or language features that are changing these stages. We'll also cover some common misunderstanding about how ESM works. It will be the most useful if you work on JavaScript framework or tooling or if you want to maximize your module loading performance or just when you need to debug some mysterious errors when you load the module. Even if you're using AI these days, the fundamentals can still be important because, well, AI can be trained on outdated data on the internet and they can be confused about the latest state of things unless you clarify it for them.

So a quick self-introduction. I'm Joy Yi. I work at Gallia and I've been sponsored by Bloomberg in many of my open source work. As mentioned before I'm a member of Node.tsc and a V8 committer. Recently I've been contributing to various module loading improvements in Node. You can find me on GitHub using this handle and you can also find the slides of this talk in my talks repository and the QR code here.

So before we start, let's do a quick quiz. Suppose we have this entry point ESM that have these four import statements. Individually they can all fail module loading, but when loaded together, which one will hit first? So option A is loading a module that throws a JavaScript error at the top level. B is a module that doesn't have a named export that this module is importing. C is a module that doesn't exist on disk. And D is a module that contains a syntax error. Which one do you think that we'll see first if we try to load this module? To save some time, let's jump to the correct answer for now. It's option C, the module that doesn't exist on disk that will hit first. We'll come back to this slide later after we explain different phases that an ESM goes through in Node, then it will become clear why this is the one that hits first.

So let's start with an import statement like this. For a little bit of complexity, let's talk about importing a package instead of just a path. So what will Node do when we run the file that imports a named export, called add here, from a specifier that's package? The first thing it's going to do is resolution. So this is a process of resolving the specifier package into a URL that identifies an actual file on disk. This is handled by the embedder of the JavaScript engine, in this case Node.

There are several differences in how resolution works in different environments. In Node, if the specifier is not a path, it looks into the Node modules folder recursively. It also tries to look at package.json. If there is one, it consults the import or export conditions in the package.json. If the specifier is a path, it must be an exact path because when Node loads ESM unlike for common.js, it does not probe the index.js, for example in directories, it also does not probe the .js extension if the specifier does not leave an extension. So these will all lead to resolution errors for ESM in Node.

When boundaries bundle code for Node, they mimic the module resolution in Node. They also consult Node modules and package.json recursively. They may pick up their own import and export conditions. That kind of varies depending on the boundaries you use. If the specifier is a path, unlike in Node, it is very typical for boundaries to actually do a common.js-like probing into directories or trying out different extensions because boundaries only need to pay for the lookup cost at build time, not at run time. This is why this is called faux ESM as opposed to real ESM in Node.

If the specifier is a path, unlike in Node, it is very typical for boundaries to actually do a common.js-like probing into directories or trying out different extensions because boundaries only need to pay for the lookup cost at build time, not at run time. This is why this is called faux ESM as opposed to real ESM in Node.

Now in browsers, they have no concept of Node modules or package.json. If you try to import a package name, it will simply fail to resolve because they only accept paths or URLs. So if the specifier is a path, it must be exact. Also browsers support import maps, but Node doesn't. Well, at least not yet. There is a work in progress, but discussions about whether import maps actually make sense for Node or whether Node should offer a different solution is kind of inconclusive right now.

So earlier we mentioned that only boundaries would probe different extensions when resolving an ESM specifier. Now here's a tip that may be useful if you work with TypeScript. Starting from 22, Node supports TypeScript via TypeScripting. With a suggestion from the TypeScripting team, Node only supports TypeEraser, so it does not allow transforms like converting ESM to CommonJS.

But for optimal performance and compatibility, the best practice is usually to use TypeScripting at development time. But if the code will be distributed in a running production environment where startup time is important, it's better to transpile it to JavaScript and run that instead in production. Then we have a problem because usually the transpilers transpile .ts files to .js files in a different folder. So for example here, the relative import in source slash main.ts is meant to resolve to source slash mod.ts. So when this gets transpiled into dist main.js, this relative import will no longer resolve because in the dist directory, we only have the transpiled mod.js, not mod.ts. So that was still in the source directory.

So some users have been solving dist by omitting the extension and then relying on a bundler to convert the module from ESM to CommonJS that probe extensions. So for example, for the extensionless mod here, they could count on bundlers to probe mod.ts during resolution at build time and then count on node CommonJS loader to probe mod.js at run time. But if they want to drop the dependency on the bundler and run it directly with node using type stripping, the extensionless imports doesn't work since node type stripping leaves ESM as ESM and ESM in node doesn't probe the extensions. It requires the exact path.

So if the main.ts file that imports mod without an extension runs in node, it fails in resolution error. The tip here is actually not about changing the node configuration, it's about changing the transpiler configuration. So since 5.7, TSC introduced a rewrite relative import extension option which rewrites the .ts specifiers in the source code to .js in generated code during transpilation. So like here, with this file that loads mod.ts, we're run by node. During development time, this will be source main.ts importing source mod.ts. After transpilation, any transpiler that supports this option will transpile it to this slash main.js importing from this mod.js in ESM. Both will resolve just fine in node, so if you're still relying on a bundler or custom loader to run TypeScript in node because of this issue specifically, the rewrite relative import extensions configuration may help you drop the dependency.

So here's another feature that makes module resolution more customizable. For node 22 and above, we have the module resolution hooks API that is now released candidate. This allows you to customize the resolution using the resolve hook. Like here, we can register a function that redirects all imports of db.js to db.mark.js. This is mostly useful for tooling or framework that needs to customize module resolution.

Now after resolution, we have the URL. So let's go to the next stage, which is fetching the source code identified by the resolve URL. This is more confusingly termed as loading in node APIs internals. In node, loading ESM sometimes specifically refers to the process of fetching the source code. And again, this is also handled by node, not by the engine.

So at this stage, if the source code cannot be fetched, for example if the file result is not readable due to lack of permissions, node can throw the file system error here. And different environments load the source code differently. For example, in node, it typically fetches the source infrared and synchronously to reduce the races with the required loading hash, loading cache. And also because in node, module loading is usually done from the local file system or memory before the application code runs.

In this case, synchronous loading is usually faster. While in browsers, this is usually off-thread and asynchronous or stringed because they typically load over the network. In the case of bundlers, this kind of varies. And also in node, because the only protocols supported are file, data, and node, and there are only opaque regions. So node relies on the file system permissions instead to check access. This is also usually the case for bundlers, bundling for node. But in browsers, the same origin policy applies to ESM. So if you're trying to load the module from a different origin in browsers, but you don't have the cross-origin resource string policy setup, then the loading will fail in the browser.

Now, similar to the result hook, node also provides a load hook that can be used to customize the source code of the modules being loaded. It's run synchronously in thread because it also needs to support require. Here, for example, you can implement a load hook that returns a pre-baked custom source code if a module's URL uses a custom protocol. And it can return source-true so that node will skip the default loading step and will then look it up on disk. This will allow the framework, for example, to virtualize the module loading or allow custom loaders to transpile and support modules in other languages on the fly.

So once we have the source code ready, the next stage is parsing. Now, parsing is mostly done by VA at this stage, but node also needs to do some driving here. So if the module loading being loaded is in ESM, VA will check its syntax and throws an error if the target module doesn't parse. After parsing, it builds an ASC, at least for the top-level code. So right before parsing, because node supports importing module types other than ESM, it may also first detect the module format to decide how to parse it. This detection can be based on extensions, the type field in PackJSON, or starting with 20, node also checks the syntax of the file if other signals are absent. Detection improves user experience, but it has a cost and it can be ambiguous. For maximum performance, it's always better to use extensions or the type field explicitly to avoid the detection cost. So bundlers usually have similar detection when they bundle the code to run on node, but in browsers, the type of the module is always indicated explicitly, either using the type attribute in the script tag or the type field passed to workers. And also in browsers, the transitive submodules loaded by an ESM will always be assumed to be ESM, so no detection is going to happen. So in node, parsing is infrared, it's not streamed because it needs to interoperate with customizations executed in single-threaded JavaScript. Browsers typically parse the file off-thread and streams the parsing. In the case of bundlers, they might do both. It kind of depends on the bundlers you're using. Now we have AST, the next stage is compilation. In the case of VA, it generates bytecode at the first compilation. So here we also have some differences in how browsers and node handle compilation.

Most major browsers have a way to cache the bytecode to disk. The next time the same module is loaded again without changes, if the browser is not updated, it will typically just reuse the bytecode read from disk. Like parsing compilation in browsers typically happens off-thread. Also most JavaScript engines built for browsers don't parse in their functions in the modules at first, like here. The top level constant assignment will be fully parsed and compiled when the module is loaded, but the function add won't be fully parsed or compiled until it's invoked for the first time.

So node also has started to support on-disk compilation cache since 2022. It's currently opt-in via the no compile cache environment variable or the module enable compile cache API or the use code cache option if you're building a node-syncable application. The bytecode is also only reused when the module is not changed and run in the same node version. And like parsing compilation in node happens in the main thread. Additionally node also only pre-parses inner functions and does not generate code for them until they are invoked, although this can also be made configurable in the future because node usually provides more low-level extensions than browsers.

After compilation, we got the bytecode of one module. What's next? We need to move on and handle its dependencies, if any. For example, here we have a module, main.js, that imports a package. That package in turn loads the node path built-in and another utils module. We need to iterate through these module requests. We need to resolve their specifiers to URLs, load the source code from the resolved URLs, parse and compile their code and repeat until the dependency graph is transitively loaded. At this stage, if any of the transitive dependencies can be resolved, loaded or parsed, node will throw an error because any module code in the graph before any module code in the graph is executed.

Like here, for instance, if the package utils.js doesn't exist, it fails to resolve, and node will error out and you won't execute any code even if you place it before the import statements. The first console log here won't be executed, because according to the language-specific specification, import statements are hoisted and executable code will run much later before the dependencies are loaded, regardless of source locations. And after we compile the entire graph transitively, the next stage is instantiation. This is when VA tries to match the import and exports, and look for mismatches. In the language specification, this stage has been renamed to linking. By node and VA terminology, this is still called instantiation, so we also call it instantiation for now. Here, for example, main.js imports a name, add, from package, and the package doesn't export code add. So, these two... that does have an export code add, so these references will be bound together. The package, in turn, imports n underscore add from another package, and also imports the default export from node path built-in. And these references will also be bound together by VA during instantiation. And at this stage, if a module imports a name from another module that doesn't export it, VA will throw an error.

And again, this happens before any code is executed. Like here, if main.js imports the name that does not get exported from the package, the console.log statement before the imports statement would not run. So earlier, we talked about using module-registered hooks to customize resolution and loading, but how about customizing the stages from parsing to instantiation? These stages are more special in ESM, and cannot share primitives with CommonJS via the same module-registered hooks API. We have the VM modules API. It's been used by a few testing frameworks for lightweight isolation. This was the reason why ESM support in Jest is still experimental, because they rely on this API that has been experimental since 2017. It turns out that this API has some design issues that lead to bugs and caveats when used in the real world. So to deal with these issues, we're revamping this API with a new design that tries to avoid issues in memory management.

And also in aborting and error reporting, this is still an early draft. Just listening here to give you an idea of what it looks like. So if you're building frameworks or tools using the experimental VM modules API, please check out this issue and help us figure out a design that's suitable for stabilization. So we last stopped at instantiation. If the graph is instantiated correctly, we can finally enter evaluation or execution. At this stage, the dependencies are executed before the dependent modules. So if the dependencies throw an error at the top level, the dependent modules won't be executed. And if the dependency here throws errors in JS, then the console.log statement in main will not get executed, even if it's placed before the import. Remember import statements are hoisted before the executable code in the importing module. And at this stage, Node only gets to kick off the evaluation of the root module, because VA controls the evaluation of the transitive submodules.

Like here, Node can do something before the entire module graph is run, but it cannot do anything between running the code in the package and running the code in the dependent module. Like here, it cannot insert anything before console.log call in main, because the inner evaluation is completely controlled by VA. This is why there is no pre-module ESN evaluate hook. Another limitation of ESN is that while ESN namespaces can reflect mutations from within the exporter, it cannot be mutated from the importer. The mutability is mandated by the language and controlled by the JavaScript engine, not by the JavaScript engine embedder. So for example here, we have a module that mutates the count variable. If we attempt to update the count to 5 from the main module, the mutation is a no-op, because the namespace is immutable according to the language. But if we invoke the ink method, which mutates the count from within that module, this will be reflected in the module namespace object.

Also, in this case, the embedder cannot control the namespace mutability. If you want to do some customization of the namespace, it has to be done through modifying the source code in the load hook. We also have some new language features that change how evaluations are done. For example, since 2004, Node supports the Stage 3 source-based import proposal that allows users to customize Wazen evaluation in ESN using the WebAssembly API. Another upcoming Stage 3 feature is deferred evaluation. This is currently being integrated in Node behind a V8 flag. So if you have a module like HeavyJS here, that has a lot of initializations to run, or it just has a huge dependency graph containing a lot of libraries that you do not use, if their exports will only really be needed when the function is called, you can use the defer keyword to defer the evaluation of the less-used modules so that they are only evaluated on demand when the property is accessed. With this you can reduce the code startup time and keep the memory usage low.

So that was a walkthrough of importing ESN in Node. Back to the initial quiz, I think it will be clear now what's happening here. In a snippet, we will first hit the resolution error because that's the first step. If we fix resolution, Node will start trying to load the code and parse the dependencies and the module with syntax error will fail next. After that, if we fix that, we go to instantiation, we run into the error from the mismatched export. Finally we will hit the error from the dependency of the module because evaluation happens at the last stage. So one last thing, we talked about how ESN comes to life in Node, but what keeps it alive? When will it go away? In this case, most of the complexity comes from this idempotency requirement in the language specification. When the module request is the same, the module being returned by the embedder must be the same. For example, here if we have a stateful module that exports something that mutates its inner state and in another module we kind of load it and kind of release it. After some garbage collection, the state should have gone away. But actually, according to the spec, sometime later, even if the original variable seems to go away, when it comes back, being loaded again, it still needs to maintain the original state. So as you can imagine, to achieve this, Node needs to maintain various internal caches. And these internal references can make tools and frameworks kind of point to leaks when they implement, for example, hot reloading ESN in Node. So to address this problem, there's a module clear cache API currently being worked on.

These won't clear all the caches for now, but you will allow frameworks to mutate the only cache that was previously unclearable and can make offloading to ESN easier to use in the future. Okay, so that's it. I hope this is helpful. Thank you for joining me.

The one that I've highlighted so far is, what is the biggest ESM misconception that you see with senior engineers that you talk with? I think the biggest misconception would be the way that ESM is loaded is different from CommonJS, especially for people coming from older Node CommonJS background. Because for CommonJS, you load the module one by one, and then right after loading the source code, you execute it. So if the first one fails to execute, it blocks the subsequent execution. But in ESN, it tries to load the entire graph, parse it, compile it, and then it takes off the execution of the graph. So it's like, there's two faces. So if any module doesn't resolve, doesn't parse or something, it does not execute. That's like the biggest misconception for people looking at ESN versus CommonJS. Right, okay, so the loading of the whole graph all at once, yeah.

And what about circular dependencies? So someone was asking how the module system deals with circular dependencies. So for loading, the circular dependency is handled by a cache. So when you try to load the first module and then in turn loads other modules, the loader will come back to visit the cache, and you'll pick it up from the cache. If for example, one of the loading hits an error, you'll temporarily stash something in the cache. If it errors, you'll just pop it out. So that's how loading is done. For evaluation, when you have a circular dependency, according to the language specification, you'll kind of have some sort of placeholder. So you cannot actually access it during evaluation when you are still in the cycle. If you do that, you'll hit tdz, like typical, if you do let or cons before it's initialized, you'll hit a tdz. So it's the same tdz in circular dependencies in evaluation in ESN. Okay, nice.

About the future of this, I have one here that's about the flag in TypeScript. Do you know if that's going to become default or anything? I guess that's more of a TypeScript question. Yeah, that's a question for the TypeScript. There's also another one about how maybe historically the loading has been a little bit less performant. So historically it's been less performant. Is there anything that's being done to make that startup cost a little bit less, or is there any work that still needs to be done there? So one of the things that I talked about earlier, like making loading synchronous, is actually helping out performance. Because if your application code is not actually going to be run before module loading, you have a huge chunk of time just being spent on module loading. And actually, in that chunk of time, it's faster to run things synchronously because asynchronous and asynchronous in Node actually has a lot of overhead because it needs to do a lot of things, especially when you have threading, coordination, that kind of thing. So that's one thing. And the other thing is compile cache that I talked about earlier that just eliminates the loading overhead because you're just desizing things. You're not actually parsing anymore. Right, okay. So yeah, nice. Unfortunately, we're out of time. I would love to ask more questions here. But of course, Joy, maybe come up to her in one of the sessions afterwards. Thanks again, Joy.