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

Hi. Thanks for having me today. Today's 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 would 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.

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 VA 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 will see first if we try to load this module? Okay, so 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 would Node do when we run a file that imports a named export called add here from the 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. So if the module can't be resolved, for example if it doesn't exist on disk, Node throws an error. This is why we see that in the previous snippet importing a non-existent file will fail first because resolution is the first step.

And 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 CommonJS, 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 export conditions. That kind of varies depending on the boundaries you use. If the specifier is a path, unlike Node, it's very typical for boundaries to actually do a CommonJS-like probing into directories or trying out different extensions because boundaries only need to pay for the lookup calls 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.

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. So starting from 22, Node supports TypeScript via type stripping. With a suggestion from the TypeScript team, Node only supports type erasure, so it does not allow transforms like converting ESM to CommonJS.

But for optimal performance and compatibility, the best practice is usually to use type stripping at development time. But if the code will be distributed or running in a 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 transfilers transfile .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. Some users have been solving this by omitting the extension and then relying on a bounder to convert the module from ESM to CommonJS that probe extensions. For extensionless mod, they count on bounders to probe mod.ts during resolution at build time and Node CommonJS loader to probe mod.js at run time. However, for direct running with Node using type stripping, extensionless imports don't work as type stripping leaves ESM as ESM and ESM in Node requires the exact path, leading to a resolution error.

The tip involves changing the transpiler configuration. Since 5.7, TSC introduced a rewrite relative import extension option, rewriting .ts specifiers to .js during transpilation. This ensures smooth resolution in Node after transpilation, resolving imports correctly. Another feature for Node 22 and above is the moduleResolutionHooks API, allowing customization of resolution using the resolve hook. This customization permits redirects like mapping db.js imports to dbMock.js, beneficial for tooling or frameworks requiring tailored module resolution.

After resolution, the process moves to fetching the source code identified by the resolve URL. This step, termed loading in Node APIs internals, involves fetching the source code, handled by Node. In Node, loading ESM refers to fetching the source code, and if issues like file permission restrictions arise, Node may throw file system errors. Environments load source code differently, with Node favoring synchronous loading for speed and efficiency, while browsers usually opt for off-thread asynchronous loading, especially over networks. Bundlers exhibit variability in their approaches to loading source code.

We have the moduleResolutionHooks API that is now a release 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 dbMock.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 somewhat 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 the different environments load the source code differently. For example, in Node, you typically fetch the source infrared and synchronously to reduce the races with the required loading cache. 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 they 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 set up, 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 circuit true so that Node will skip the default loading step and wouldn't 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 because Node also needs to do some driving here. So if the module loading being loaded is an ESM, VA will check its syntax and throw 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 typefield in Pack.json 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 can be ambiguous. For maximum performance, it's better to use extensions or the typefield explicitly to avoid detection costs. Browsers explicitly indicate the module type, while in Node, parsing is infrared for JavaScript customizations. Browsers parse off-thread and string files, while bundlers may vary in their approach.

After parsing, the next stage is compilation. Browsers cache bytecode for performance, while Node also supports on-disk compilation cache. JavaScript engines for browsers delay parsing functions until invocation. In contrast, Node pre-parses functions and delays code generation until invocation. Compilation in Node occurs in the main thread.

Handling dependencies follows compilation. Modules need to resolve specifiers to URLs, load source code, parse, and compile code transitively. Node throws an error if any dependency cannot be resolved or parsed before execution. Instantiation involves V8 matching imports and exports to detect mismatches.

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. Node also has started to support on-disk compilation cache since 22, although it's currently updated via the no-compile-cache variable or the module enable-compile-cache API, or the use-code-cache option if you're building a no-sync-code 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. Currently Node also only pre-parses in their 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.

So after compilation, we've 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, like the first console log here won't be executed because according to language 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 V8 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 V8 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 does not have an export called add. So these references will be bound together, and package in turn imports n underscore add from another package, and it also imports the default export from node path built-in. And these references will also be bound together by V8 during instantiation. And at this stage, if a module imports a name from another module that doesn't export it, V8 will throw an error. And this is why we call it instantiation, because if it's a module that doesn't export it, V8 will throw an error. And again, this happens before any code is executed. Like here, if main.js importing the name that does not get exported from a package, the console.log statement before the imports statement would not run. So earlier we talked about using module.register.hooks in coding, 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.register.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 module 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. Like here, throws errors njs throws, 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 sum modules. 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 eval 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 five 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 the module, this will be reflected in the module namespace object. And also in this case, the embedder cannot control the namespace mutability. So 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 changes how evaluations is done.

For example, since 24, Node supports the stage 3 source-based import proposal that allows users to customize a Wazen evaluation in ESM 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 initialization to run, or if it just has a huge dependency graph containing a lot of libraries that you do not use, or 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 ESM in Node. Now back to the initial quiz, I think it will be clear now what's happening here. In the 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. Then we'll 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 ESM 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, if we have a stateful module that exports something that mutates its inner state, and in another module, we can load it and release it, and 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. These internal references can make tools and frameworks point to leaks when they implement, for example, hot reloading ESM in Node. To address this problem, there's a module clear cache API currently being worked on. This won't clear all the caches for now, but it will allow frameworks to mutate the only cache that was previously unclearable and can make offloading to ESM easier to use in the future.

Okay, so that's it. I hope this is helpful. Thank you for joining me. So 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 like the way that ESM is loaded is different from CommonJS, especially for people coming from older, like no CommonJS background. Because for CommonJS, you load the module one by one, and right after loading the source code, you execute it. So if the first one fails to execute, it blocks the subsequent execution. But in ESM, it tries to load the entire graph, parse it, compile it, and then it can solve the execution of the graph. So it's like there's two phases. 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 ESM 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 system, 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 kind of like temporary stash something in the cache. If it errors, it will 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 kind of like 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 TDC, like typical, like if you do like let or cons before it's initialized, you'll hit a TDC. So it's the same TDC in circular dependencies in evaluation in ESM.

Okay, nice. And about the kind of like future of this, I have one here that's about the flag in TypeScript. Do you know if that's going to become like a default or anything? I guess that's more of a TypeScript question. Yeah, that's a question for the TypeScript. Yeah. 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 like kind of 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 I talked about earlier, like making loading synchronous is actually helping our performance because if your application code is not actually going to be run before module loading, you have like 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 its synchronicity, you know, actually has a lot of overhead, because it needs to do a lot of things, especially when you have like threading coordination, that kind of thing. So that's one of the things. And the other thing is like 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 afterward. Thanks again, Joy.