JavaScript module declarations (previously known as "module fragments") are a syntax for named, inline JS modules, which can be used for bundling multiple modules into a single JavaScript file.
Stage: 2
Champions:
JavaScript developers often write code in many small modules, and uptake of ECMAScript Modules (ESM, introduced in ES6/ES2015) is high as a source format. However, many small files--whether on the Web, servers, or other environments--has a high cost in terms of loading performance. For this reason, developers use tools called "bundlers" to emulate several ES modules in one (or a few) scripts or modules. Some examples are webpack, rollup, Parcel and esbuild.
The need for bundlers to entirely virtualize ES module semantics adds a lot of complexity to their implementation, and this cost increases over time, with new module features such as top-level await. It also has a cost in terms of runtime performance, as engines need to work through the virtualized code, and they cannot see the previous module structure. For example, modules would be a convenient point to divide up code for parallel bytecode generation, but this structure is not easily visible to JS engines today, if bundlers make everything one big script or module.
Some more general-purpose bundling format such as resource bundles has a significant benefit over a JS-only bundling system because developers need to combine more things than just JavaScript in practice. An implementation of fetch-level resources is expected to have some degree of overhead, which may be suitable for images, WebAssembly and CSS. However, JavaScript tends to have much higher "blowup" in the number of modules than other resources, so a special-purpose JS-only format could tie in more cheaply at the module level, rather than the network level.
This proposal adds a syntax to JavaScript to allow for several JavaScript modules in one file. This format can be used as output by bundlers, with low overhead on execution, so that bundlers don't have to emulate as much, and JS engines can see what's going on. It's also convenient to be typed directly by JavaScript developers, and it should be low overhead to fit into existing workflows.
// filename: app.js
module countModule {
let i = 0;
export function count() {
i++;
return i;
}
}
export module uppercaseModule {
export function uppercase(string) {
return string.toUpperCase();
}
}
import { count } from countModule;
import { uppercase } from uppercaseModule;
console.log(count()); // 1
console.log(uppercase("daniel")); // "DANIEL"This module, containing multiple module declarations, is referenced from an HTML file via a script tag:
<script type=module src="https://github.com/tc39/proposal-module-declarations/raw/main/app.js"></script>Module declarations, if exported, can also be used outside of the file where they are defined.
<script type=module>
import { uppercaseModule } from "./app.js";
import { uppercase } from uppercaseModule;
console.log(uppercase("yes")); // "YES"
</script>The countModule module, on the other hand, is not exported, and can not be used this way.
ModuleDeclaration is a new nonterminal which can exist at the top level of a module, like import and export statements, or of a script. Note that, as in the case of module expressions, there is no shared lexical scope between module declarations and the module that contains each other; they are simply side by side, like modules fetched from different URLs.
ModuleItem[Yield, Await, Return] :
...
<ins>ModuleDeclaration</ins>
ScriptItem[Yield, Await, Return] :
...
<ins>ModuleDeclaration</ins>
ModuleDeclaration : module [no LineTerminator here] Identifier { ModuleBody? }Module declarations may be nested inside of other module declarations.
If a module declaration is imported multiple times, the same module "instance" is returned, just like with modules declared in separate JS files. In other words, module declarations are singletons.
Note: The following is framed to give details for HTML/the Web platform, but other platforms which aim to be analogous to the Web where appropriate (e.g., Node.js) may wish to follow these designs as well.
import.meta.urlThe import.meta.url inside a module declaration is the module specifier of the surrounding module. For example,
// https://example.com/xyz.js
module mod { console.log(import.meta.url); }
import mod;The above code will log https://example.com/xyz.js.
Relative module specifiers within a module declaration are resolved just as if they were defined in the outer module. This behavior is the same as if they were calculated by new URL(moduleSpecifier, import.meta.url).
This behavior follows from the semantics proposed for module expressions.
Brave has expressed concerns about the possibility that bundling could be used to let servers remap URLs more easily, which cuts against privacy techniques for blocking tracking, etc. This proposal has significantly less expressivity than Web Bundles, making these issues not as big of a risk:
JS module bundles are restricted to just same-origin JS, so they are analogous in scope to what is currently done with popular bundlers like webpack and rollup, not adding more power. Although it is possible to rotate/scramble declaration identifiers, it is reasonable to treat the whole outer module containing several module declarations as a unit, with content blockers targeting either all or none of it.
Martin Thompson of Mozilla has articulated a preference for bundling schemes to be based on URLs which accurately identify the identity of the resource. As module declarations can not be loaded directly, but only through the outer module, and the outer module is fetched by its URL, the identity is clearly represented. (TODO: confirm this with MT)
Module declarations provide a very limited subset of the functionality of resource bundle loading behavior.
As a point-by-point comparison to how resource bundles and module declarations compare:
It's my (Dan Ehrenberg's) hypothesis at this point that, for best performance, module declarations should be nested inside resource bundles. This way, the expressiveness of resource bundles can be combined with the low per-asset overhead of module declarations: most of the "blow-up" in terms of the number of assets today is JS modules, so it makes sense to have a specialized solution for that case, which can be contained inside the JS engine. The plan from here will be to develop prototype implementations (both in browsers and build tools) to validate this hypothesis before shipping.
The module expressions proposal introduces the expressions form of inline modules. Being expressions, they are inherently dynamic: they can be imported with import() or new Worker(), but not with static import statements.
Module declarations lift this restriction: they can be imported statically if they appear at the top level of a module. This makes module declarations more useful for bundling than module expressions. See more context in this FAQ.
We are developing these two features as separate proposals because module declarations present additional complexity around static import statements that module expressions don't need, and module expressions have their own motivations independent from module declarations. Module declarations inherit different design decisions from module expressions, so the advancement of this proposal in its current shape depends on the evolution of module expressions.
The plan for this proposal is to present it for Stage 1 at a future TC39 meeting, and to prototype its use in conjunction with resource bundle loading for a high-performance, native bundling solution on the Web platform.