In shim mode, only the above importmap-shim and module-shim tags will be parsed and executed by ES Module Shims.

Shim mode also provides some additional features that aren't yet natively supported such as external import maps with a "src" attribute and reading current import map state, which can be useful in certain applications.

Benchmarks

ES Module Shims is designed for production performance. A comprehensive benchmark suite tracks multiple loading scenarios for the project.

Benchmark summary:

• ES Module Shims Chrome Passthrough (for 94% of users) results in ~5ms extra initialization time over native for ES Module Shims fetching, execution and initialization, and on a slow connection the additional non-blocking bandwidth cost of its 14KB compressed download as expected.
• ES Module Shims Polyfilling (for the remaining 3% of users) is on average 1.4x - 1.5x slower than native module loading, and up to 1.8x slower on slow networks (most likely due to the browser preloader), both for cached and uncached loads, and this result scales linearly up to 10MB and 20k modules loaded executing on the fastest connection in just over 2 seconds in Firefox.
• Very large import maps (100s of entries) cost only a few extra milliseconds upfront for the additional loading cost.

Features

Browser Support

Works in all browsers with ES module dynamic import support.

Browser Compatibility on baseline ES modules support with ES Module Shims:

| ES Modules Features | Chrome (63+) | Firefox (67+) | Safari (11.1+) |
| ------------------------------------------------ | ------------------------------------ | ------------------------------------ | ------------------------------------ |
| modulepreload | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Import Maps | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Import Map Integrity | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Multiple Import Maps | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| JSON Modules | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| CSS Modules | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Wasm Modules | 89+ | 89+ | 15+ |
| Import Defer (syntax-stripping) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |

Browser compatibility without ES Module Shims:

| ES Modules Features | Chrome | Firefox | Safari |
| --------------------------------------------- | ------------------ | ------------------ | ------------------ |
| modulepreload | 66+ | 115+ | 17.5+ |
| Import Maps | 89+ | 108+ | 16.4+ |
| Import Map Integrity | 127+ | 138+ | 18+ |
| Multiple Import Maps | 135+ | :x: | 18.4+ |
| JSON Modules | 123+ | :x: | 17.2+ |
| CSS Modules | 123+ | :x: | :x: |
| Wasm Modules | Pending | :x: | :x: |
| Import Defer | Pending | :x: | :x: |
| import.meta.resolve | 105+ | 106+ | 16.4+ |
| Module Workers | ~68+ | ~113+ | 15+ |
| Top-Level Await | 89+ | 89+ | 15+ |

Import Maps

> Stability: WhatWG Standard, implemented in all browsers although only recently in Firefox and Safari

Import maps allow for importing _"bare specifiers"_ in JavaScript modules, which prior to import maps throw in all browsers with native modules support.

Using this polyfill we can write:

<script type="importmap-shim">
{
  "imports": {
    "test": "/test.js"
  },
  "scopes": {
    "/": {
      "test-dep": "/test-dep.js"
    }
  },
  "integrity": {
    "/test.js": "sha386-..."
  }
}
</script>
<script type="module-shim">
  import test from "test";
  console.log(test);
</script>

All modules are still loaded with the native browser module loader, but with their specifiers rewritten then executed as Blob URLs, so there is a relatively minimal overhead to using a polyfill approach like this.

External Import Maps

External import maps (using a "src" attribute) are not currently supported in any native implementation.

In polyfill mode, external import maps are therefore not supported.

In shim mode, external import maps are fully supported.

Multiple Import Maps

Multiple import maps have been recently implemented in Chromium in https://bugs.chromium.org/p/chromium/issues/detail?id=927119, including supporting dynamically loading import maps even after modules have been loaded.

In polyfill mode, multiple import maps are supported.

Support for dynamically injecting import maps with JavaScript via e.g.:

document.head.appendChild(Object.assign(document.createElement('script'), {
  type: 'importmap',
  innerHTML: JSON.stringify({ imports: { x: './y.js' } }),
}));

is also provided using mutation observers. Note, only document.head appending of scripts, importmaps and preloads is supported - we do not observe body mutations to document.body for performance reasons.

The caveat for multiple import map support polyfill support in browsers that only support a single import map is per the usual "polyfill rule" for es-module-shims - only those top-level graphs with static import feailures can be polyfilled.

Therefore, imports that would otherwise be supported fine by the first map can't be polyfilled, for example:

<script type="importmap">
{
  "imports": {
    "a": "/a.js"
  }
}
</script>
<script type="importmap">
{
  "scopes": {
    "/": {
      "a": "/b.js"
    }
  }
}
</script>
<script type="module">
import 'a';
</script>

In the above, browsers with single import maps support will resolve /a.js and the polyfill will not apply, while browsers without any import maps support will be polyfilled to resolve /b.js.

Instead, following the usual advice, make sure to design the app to either have static failures or not on all polyfill environments to get well-defined polyfill behaviour:

<script type="importmap">
{
  "imports": {
    "a": "/a.js"
  }
}
</script>
<script type="importmap">
{
  "imports": {
    "b": "/b.js"
  }
}
</script>
<script type="module">
import 'a';
</script>
<script type="module">
import 'b';
</script>

The above will then correctly execute both a and b, with only the b importer being polyfilled.

Note that shimmed graphs will always support correct mappings - the above rules only apply to the initial polyfill engagement.

Reading current import map state

To make it easy to keep track of import map state, es-module-shims provides a importShim.getImportMap utility function, available only in shim mode.

const importMap = importShim.getImportMap();

// importMap will be an object in the same shape as the json in a importmap script

Setting current import map state

To make it easy to set the import map state, es-module-shims provides a importShim.addImportMap utility function, available only in shim mode.

// importMap will be an object in the same shape as the json in a importmap script
const importMap = { imports: {/*...*/}, scopes: {/*...*/} };

importShim.addImportMap(importMap);

Module Scripts

All module scripts except those with a noshim attribute are polyfilled. We support all of the the defer, integrity, referrerPolicy, fetchPriority and crossOrigin script attribute behaviours when polyfilling.

In addition to static module scripts, we also use mutation observers to automatically detect and apply dynamic polyfilling for scripts injected into the head of the page:

document.head.appendChild(Object.assign(document.createElement('script'), {
  innerHTML: `import 'maybe-polyfill-dep'; console.log('loaded');`,
}));

The same attributes as static scripts are also supported.

Shim Import

Dynamic import(...) within any modules loaded will be rewritten as importShim(...) automatically providing full support for all es-module-shims features through dynamic import.

To load code dynamically (say from the browser console), importShim can be called similarly:

importShim('/path/to/module.js').then(x => console.log(x));

import.meta.url

> Stability: Stable browser standard

import.meta.url provides the full URL of the current module within the context of the module execution.

modulepreload

> Stability: WhatWG Standard, Single Browser Implementer

Preloading of modules can be achieved by including a `` tag in the HTML or injecting it dynamically.

This tag also supports the "integrity", "crossorigin" and "referrerpolicy" attributes as supported on module scripts.

This tag just initiates a fetch request in the browser and thus works equally as a preload polyfill in both shimmed and unshimmed modes, with integrity validation support.

In browsers that don't support modulepreload, polyfilled preloading behaviour is provided using an early fetch() call with the same request options as the module script, resulting in network-level cache sharing.

Unlike the browser specification, the modulepreload polyfill does not request dependency modules by default, in order to avoid unnecessary
code analysis in the polyfill scenarios, _it is always recommended to preload deep imports so that this feature shouldn't be necessary._

Preload shim

When in shim mode, `` must be used to properly cache the preloaded modules.

CSP Support

By default ES Module Shims provides full support for CSP by using the asm.js ES Module Lexer build. This is absolutely identical in performance to the Wasm version in Firefox and Chrome (in Safari the asm.js version is actually faster than Wasm).

The CSP nonce to use for module scripts will be picked up from the first script on the page or via the <code class="ra0-md-code">nonce</code> init option.

A full example of such a CSP workflow is provided below:

<meta http-equiv="Content-Security-Policy" content="script-src 'self' 'nonce-n0nce'" />
<script async src="es-module-shims.js"></script>
<script type="importmap" nonce="n0nce">
{
  "imports": {
    "pkg": "/pkg.js"
  }
}
</script>
<script type="module" nonce="n0nce">
import pkg from 'pkg';
</script>

Trusted Types Support

ES Module Shims supports Trusted Types a browser security feature that prevents DOM-based XSS attacks. When your CSP includes require-trusted-types-for 'script', the library automatically creates a policy named es-module-shims to handle its internal script creation and source rewriting. Browsers without Trusted Types support fall back to standard behavior automatically.

To enable it, add es-module-shims to your CSP's trusted-types directive. If you see errors about "TrustedScript assignment," you're missing this directive.

<meta http-equiv="Content-Security-Policy" 
      content="require-trusted-types-for 'script'; trusted-types es-module-shims;">

Wasm Build

To use the Web Assembly / non-CSP build of ES Module Shims, this is available as a self-contained single file at es-module-shims/wasm or es-module-shims/dist/es-module-shims.wasm.js in the package folder.

Import Map Integrity

The "integrity" field for import maps is supported when possible, throwing an error in es-module-shims when the integrity does not match the expected value:

<script type="importmap">
{
  "imports": {
    "pkg": "/pkg.js"
  },
  "integrity": {
    "/pkg.js": "sha384-..."
  }
}
</script>
<script>
import "/pkg.js";
</script>

Note integrity can only be validated when in shim mode or when the polyfill is definitely engaging.

JSON Modules

> Stability: WhatWG Standard, Stable, Multiple Browser Implementers

JSON modules are now enabled by default in ES Module Shims with 85% browser support for native where the polyfill won't engage at all.

In shim mode, JSON modules are always supported.

JSON Modules are supported in Chrome and Safari when using them via an import assertion:

<script type="module">
import json from 'https://site.com/data.json' with { type: 'json' };
</script>

In addition JSON modules need to be served with a valid JSON content type.

CSS Modules

> Stability: WhatWG Standard, Single Browser Implementer

CSS imports are fully supported in both polyfill and shim mode with native passthrough applying in Chrome.

Use them by adding the type: 'css' import assertion when importing a CSS file:

<script type="module">
import sheet from 'https://site.com/sheet.css' with { type: 'css' };
</script>

In addition CSS files need to be served with a valid CSS content type.

Wasm Modules

> Stability: WebAssembly Standard, Unimplemented

Implements the WebAssembly ESM Integration spec, including support for source phase imports.

In shim mode, Wasm modules are always supported. In polyfill mode, Wasm modules require the polyfillEnable: ['wasm-module-sources'] (or 'wasm-module-instances' for instance imports) init option.

WebAssembly module exports are made available as module exports and WebAssembly module imports will be resolved using the browser module loader.

If only using Wasm modules in both the instance and source phase set polyfillEnable: ['wasm-modules'] init option to enable both modes.

When enabling the source phase feature either way, WebAssembly.Module is also polyfilled to extend from AbstractModuleSource per the source phase proposal.

WebAssembly modules require native top-level await support to be polyfilled, see the compatibility table above.

<script type="module">
import { fn } from './app.wasm';
</script>

And for the source phase:

<script type="module">
import source mod from './app.wasm';
const instance = await WebAssembly.instantiate(mod, { /* ...imports */ });
</script>

If using CSP, make sure to add 'unsafe-wasm-eval' to script-src which is needed when the shim or polyfill engages, note this policy is safer than normal eval due to the Wasm secure sandbox. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_webassembly_execution.

Import Defer

> Stability: Stage 3 Standard, Pending Shipping

Implements the Import Defer TC39 Proposal, including support for import defer * as mod from './mod.js'.

The polyfill is simply just a defer syntax stripping, allowing environments that do support import defer to benefit from the performance benefits, while still supporting the syntax in older browsers.

TypeScript Type Stripping

TypeScript type stripping is supported like in Node.js.

To trigger TypeScript type stripping, make sure to either use shim mode, or to add the non-standard lang="ts" option to the top-level evaluator. This ensures that the polyfill processing will engage on this graph, while usually module graphs are not processed at all in browsers with full native support.

Modules will then be interpreted as TypeScript when one of the following applied:

• It is served with the application/typescript MIME type.
• It ends in .ts or .mts and is not served with a valid module script MIME type.
• Or, if it is an inline lang="ts" module script.

For example the following are all valid TypeScript usage patterns:

Shim mode - no lang=ts is necessary:

<script type="module-shim" src="app.ts">

Polyfill mode via lang=ts:

<script type="module" lang="ts" src="app.ts"></script>

Inline TypeScript with lang=ts:

<script type="module" lang="ts">
import './dep.ts';
const ts: boolean = true;
console.log('TypeScript!');
</script>

Indirect static import to a TypeScript module via lang="ts":

<script type="importmap">
{
  "imports": {
    "app": "/app.mts"
  }
}
</script>
<script type="module" lang="ts">
import 'app';
</script>

Loading TypeScript dynamically:

<script type="module" lang="ts">
importShim('./app.ts', { lang: 'ts' });
</script>

When processing a TypeScript module, the es-module-shims-typescript.js extension must be available as a sibling asset to es-module-shims.js. It will then be loaded on-demand to provide the type stripping processing.

Note that runtime TypeScript features such as enums are not supported, and type only imports should be used where possible, per the Node.js guidance for TypeScript.

Hot Reloading

Hot reloading is supported in both shim and polyfill modes, when explicitly enabled. To enable hot-reloading, enable the hotReload init option:

test.html

<script type="esms-options">
{
  "hotReload": true,
  "hotReloadInterval": 100
}
</script>
<script async src="es-module-shims.js"></script>
<script type="module" src="/app.js"></script>

In polyfill mode, all modules will be initialized twice when hot reloading to reinitiate with import.meta.hot. To avoid this, shim mode is recommended for hot reloading workflows whenever possible.

The hotReloadInterval option can also be configured which is the interval at which hot reload events are batched together as a single reload operation, with the default of 100.

When enabled, native passthrough will be automatically disabled, and all modules will be provided with the import.meta.hot API fully supporting Vite's <code class="ra0-md-code">import.meta.hot</code>, supporting the following methods except for the event handlers:

• hot.accept(cb): Accept a hot update.
• hot.accept(dep, cb): Accept a hot update of a dependency specifier string.
• hot.accept(deps, cb): Accept a hot update of a list of dependency specifier strings.
• hot.dispose(cb): Provide a dispose function for when this module is expected to be accepted by others.
• hot.data: Shared data object between hot reload instances.
• hot.invalidate(): Fully invalidate the current module, without accepting. Can be called within accept itself.

To trigger a hot reload, call the importShim.hotReload(url) API with the URL of the module that has changed. All of CSS, JSON, Wasm and TypeScript imports are supported in hot reloading.

This hot reload API can then be attached to a Web Socket, Server Side Events emitter or any other event source to provide a native hot reloading development environment.

Module Workers

ES Module Shims can be used in module workers in browsers that provide dynamic import in worker environments, which at the moment are Chrome(80+), Edge(80+), Firefox(~113+) and Safari(15+).

By default, when there is no DOM present, ES Module Shims will switch into shim mode. An example of ES Module Shims usage through shim mode in web workers is provided below:

/**
 *
 * @param {string} aURL a string representing the URL of the module script the worker will execute.
 * @returns {string} The string representing the URL of the script the worker will execute.
 */
function getWorkerScriptURL(aURL) {
  // baseURL, esModuleShimsURL are considered to be known in advance
  // esModuleShimsURL - must point to the non-CSP build of ES Module Shims,
  // namely the `es-module-shim.wasm.js` output: es-module-shims/dist/es-module-shims.wasm.js

  return URL.createObjectURL(new Blob(
    [
      `importScripts('${new URL(esModuleShimsURL, baseURL).href}');
      importShim.addImportMap(${JSON.stringify(importShim.getImportMap())});
      importShim('${new URL(aURL, baseURL).href}').catch(e => setTimeout(() => { throw e; }))`
    ],
    { type: 'application/javascript' }))
}

const worker = new Worker(getWorkerScriptURL('myEsModule.js'));

> Web workers must use the non-CSP build of ES Module Shims via es-module-shim.wasm.js from the dist/ folder, since the CSP build currently assumes a DOM.

Init Options

Provide a esmsInitOptions on the global scope before es-module-shims is loaded to configure various aspects of the module loading process:

• polyfillEnable
• polyfillDisable
• enforceIntegrity
• fetch
• mapOverrides
• nativePassthrough
• modulepreload
• noLoadEventRetriggers
• nonce
• onerror
• onpolyfill
• resolve
• source
• shimMode
• skip
• version

<script>
window.esmsInitOptions = {
  // Enable Shim Mode
  shimMode: true, // default false
  // Enable newer modules features
  polyfillEnable: ['wasm-module-sources'], // default empty
  // Disable features that are unused
  polyfillDisable: ['css-modules'], // default empty
  // Custom CSP nonce
  nonce: 'n0nce', // default is automatic detection
  // Don't retrigger load events on module scripts (DOMContentLoaded, domready, window 'onload')
  noLoadEventRetriggers: true, // default false
  // Skip source analysis of certain URLs for full native passthrough
  skip: /^https://cdn.com/, // defaults to null
  // Secure mode to not support loading modules without integrity
  // (integrity is always verified even when disabled though)
  enforceIntegrity: true, // default false
  // Permit overrides to import maps
  mapOverrides: true, // default false
  // Whether es-module-shims will defer to the native module loader whenever it can
  // Automatically disabled in hot reloading workflows
  nativePassthrough: false, // default true

  // -- Hooks --
  // Module load error
  onerror: (e) => { /*...*/ }, // default noop
  // Called when polyfill mode first engages
  onpolyfill: () => {}, // default logs to the console
  // Hook all module resolutions
  resolve: (id, parentUrl, resolve) => resolve(id, parentUrl), // default is spec resolution
  // Hook module source loading
  source: (url, options, parentUrl, defaultSourceHook) => ({ type: 'js', source: 'export var p = 5' }),
  // Hook source fetch function
  fetch: (url, options) => fetch(url, options), // default is native
  // Hook import.meta construction
  meta: (meta, url) => void // default is noop
  // Hook top-level imports
  onimport: (url, options, parentUrl, source) => void // default is noop
  // Ensure only the exact provided version of es-module-shims registered
  version: '2.4.0' // default is empty
}
</script>
<script async src="es-module-shims.js"></script>

`` can also be used:

<script type="esms-options">
{
  "shimMode": true,
  "polyfillEnable": ["wasm-module-sources"],
  "nonce": "n0nce",
  "onpolyfill": "polyfill"
}
</script>

This can be convenient when using a CSP policy. Function strings correspond to global function names.

Shim Mode Option

Shim Mode can be overridden using the shimMode option:

<script type="esms-options">
{
  "shimMode": true
}
</script>

For example, if lazy loading `` scripts alongside static native module scripts, shim mode would not be enabled at initialization time.

DOM load events are fired for all "module-shim" scripts both for success and failure just like for native module scripts.

Polyfill Enable Option

The polyfillEnable option allows enabling polyfill features which are newer and would otherwise result in unnecessary polyfilling in modern browsers that haven't yet updated.

This options supports "wasm-modules", "wasm-module-sources", "wasm-module-instances" and "import-defer".

In adddition, the "all" option will enable all features.

<script type="esms-options">
{
  "polyfillEnable": ["all"]
}
</script>

The reason the polyfillEnable option is needed is because ES Module Shims implements a performance optimization where if a browser supports modern modules features to an expected baseline of import maps support, it will skip all polyfill source analysis resulting in full native passthrough performance.

Polyfill Disable Option

Conversely to polyfillEnable it can be beneficial to dissable unused features where excluding those features from the baseline allows avoiding unnecessary feature detections or unnecessary analysis of module graphs.

This option effectively lowers the baseline support allowing wider passthrough cases.

The supported options currently are just css-modules and json-modules.

For example:

<script type="esms-options">
{
  "polyfillDisable": ["css-modules", "json-modules"]
}
</script>

will disable the CSS and JSON feature detections, and lower the baseline passthrough modules support from Chrome 123, Firefox 138 and Safari 17.2 down to Chrome 64, Safari 11.1 and Firefox 67.

Enforce Integrity

While integrity is always verified and validated when available, when enabled, enforceIntegrity will ensure that all modules must have integrity defined when loaded through ES Module Shims either on a `, a preload tag in shim mode, or the "integrity"` field in the import map. Modules without integrity will throw at fetch time.

For example in the following, only the listed app.js, dep.js and another.js modules will be able to execute with the provided integrity:

<script type="importmap">
{
  "integrity": {
    "/another.js": "sha384-..."
  }
}
</script>
<script type="esms-options">{ "enforceIntegrity": true }</script>
<link rel="modulepreload-shim" href="/app.js" integrity="sha384-..." />
<link rel="modulepreload-shim" href="/dep.js" integrity="sha384-..." />
<script type="module-shim">
  import '/app.js';
  import '/another.js';
</script>

Strong execution guarantees are only possible in shim mode since in polyfill mode it is not possible to stop the native loader from executing code without an integrity.

Future versions of this option may provide support for origin-specific allow lists.

Nonce

The nonce option allows setting a CSP nonce to be used with all script injections for full CSP compatibility supported by the CSP build of ES Module Shims.

Alternatively, add a blob: URL policy with the CSP build to get CSP compatibility.

<script type="esms-options">
{
  "nonce": "n0nce"
}
</script>

No Load Event Retriggers

Because of the extra processing done by ES Module Shims it is possible for static module scripts to execute after the DOMContentLoaded, readystatechange or window load events they expect, which can cause missed attachment.

In addition, script elements will also have their load events refired when polyfilled.

In order to ensure libraries that rely on these event still behave correctly, ES Module Shims will always double trigger these events that would normally have executed before the document ready state transition to completion, once all the static module scripts in the page have been completely executed through ES module shims.

In such a case, this double event firing can be disabled with the noLoadEventRetriggers option:

<script type="esms-options">
{
  // do not re-trigger DOM events (onreadystatechange, DOMContentLoaded, window 'onload')
  "noLoadEventRetriggers": true
}
</script>
<script async src="es-module-shims.js"></script>

Skip

When loading modules that you know will only use baseline modules features, it is possible to set a rule to explicitly opt-out modules from being polyfilled to always load and be referenced through the native loader only. This enables instance sharing with the native loader and also improves performance because those modules then do not need to be processed or transformed at all, so that only local application code is handled and not library code.

The skip option supports a string regular expression or array of exact module URLs to check:

<script type="esms-options">
{
  "skip": "^https?://(cdn.skypack.dev|jspm.dev)/"
}
</script>
<script async src="es-module-shims.js"></script>

When passing an array, relative URLs or paths ending in / can be provided:

<script type="esms-options">
{
  "skip": ["./app.js", "https://jspm.dev/"]
}
</script>
<script async src="es-module-shims.js"></script>

Version

When there is a risk of multiple versions of ES Module Shims on the same page, deconflicting is managed by logic that will opt-out of initializing ES Module Shims if it has already been initialized. In addition, ES Module Shims itself is frozen and locked from further mutations.

To better support cooporative multi-version cases, as of version 2.4.0, we support a version option, which when set will skip initialization if the current version of ES Module Shims does not match this exact expected version.

This way, any other old versions after version 2.4.0 running on the page can effectively be turned off, ensuring only the defined version of the polyfill initiates the polyfill.

Revoke Blob URLs

When polyfilling the missing features es-module-shims would create in-memory blobs using URL.createObjectURL() for each processed module.
In most cases, memory footprint of these blobs is negligible so there is no need to call URL.revokeObjectURL()
for them, and we don't do that by default.

That said, in some scenarios, e.g. when evaluating some continuously changing modules without a page reload, like in a web-based code editor,
you might want to reduce the growth of memory usage by revoking those blob URLs after they were already imported.

You can do that by enabling the revokeBlobURLs init option:

<script type="esms-options">
{
  "revokeBlobURLs": true
}
</script>
<script type="module" src="es-module-shims.js"></script>

NOTE: revoking object URLs is not entirely free, while we are trying to be smart about it and make sure it doesn't
cause janks, we recommend enabling this option only if you have done the measurements and identified that you really need it.

Overriding import map entries

When dynamically injecting import maps, an error will be thrown in both polyfill and shim modes if the new import map would override existing entries with a different value.

It is possible to disable this behavior in shim mode by setting the mapOverrides option:

<script type="esms-options">
{
  "shimMode": true,
  "mapOverrides": true
}
</script>
<script type="importmap-shim">
{
  "imports": {
    "x": "/x.js"
  }
}
</script>
<script>
// No error will be thrown here
document.body.appendChild(Object.assign(document.createElement('script'), {
  type: 'importmap',
  innerHTML: JSON.stringify({ imports: { x: './y.js' } }),
}));
</script>

This can be useful for HMR workflows.

Native Passthrough

By default, ES Module Shims will always use the native passthrough of calling the native import() mechanism to load module graphs, when it has analyzed that that module graph is fully supported in the current environment. This way, the native module registry is fully shared between polyfilled and non-polyfilled graphs,
and we lean into the native support as much as popssible.

In Shim mode, ES Module Shims never uses native pass through regardless of this option - it only applies to polyfill mode.

This option is enabled by default, so by turning it off it is possible to ensure that ES Module Shims is rewriting and processing all sources itself.

Native passthrough is automatically disabled when using hot reloading.

Hooks

Polyfill hook

The polyfill hook is called when running in polyfill mode and the polyfill is kicking in instead of passing through to the native loader.

This can be a useful way to verify that the native passthrough is working correctly in latest browsers for performance, while also allowing eg the ability to analyze or get metrics reports of how many users are getting the polyfill actively applying to their browser application loads.

<script>
window.polyfilling = () => console.log('The polyfill is actively applying');
</script>
<script type="esms-options">
{
  "onpolyfill": "polyfilling"
}
</script>

The default hook will log a message to the console with console.info noting that polyfill mode is enabled and that the native error can be ignored.

Overriding this hook with an empty function will disable the default polyfill log output.

In the above, running in latest Chromium browsers, nothing will be logged, while running in an older browser that does not support newer features like import maps the console log will be output.

> As this hook does not affect execution, it is recommended for use in polyfill mode.

Error hook

You can provide a function to handle errors during the module loading process by providing an onerror option:

<script>
  window.esmsInitOptions = {
    onerror: error => console.log(error) // defaults to `((e) => { throw e; })`
  }
</script>
<script async src="es-module-shims.js"></script>

> As this hook does not affect execution, it is recommended for use in polyfill mode.

Import Hook

The import hook is supported for both shim and polyfill modes and provides an async hook which can ensure any necessary work is done before a top-level module import or dynamic import() starts further processing.

<script>
  window.esmsInitOptions = {
    onimport: function (url, options, parentUrl, source) {
      if (source !== undefined)
        console.log(`Top-level inline script with source: ${source}`);
      else
        console.log(`Top-level URL import (static or dynamic) for ${url}`);
    }
  }
</script>

> It is usually recommended to use shim mode with module customization hooks. When the resolve hook is enabled in polyfill mode (or any other hooks), native passthrough will be disabled and modules may be executed twice if they correctly execute without the hook.

Resolve Hook

The resolve hook is supported for both shim and polyfill modes and allows full customization of the resolver, while still having access to the original resolve function.

<script>
  window.esmsInitOptions = {
    shimMode: true,
    resolve: function (id, parentUrl, defaultResolve) {
      if (id === 'custom' && parentUrl.startsWith('https://custom.com/'))
        return 'https://custom.com/custom.js';

      // Default resolve will handle the typical URL and import map resolution
      return defaultResolve(id, parentUrl);
    }
  }
</script>

> It is usually recommended to use shim mode with module customization hooks. When the resolve hook is enabled in polyfill mode (or any other hooks), native passthrough will be disabled and modules may be executed twice if they correctly execute without the hook.

Source Hook

The source hook used to obtain the module source for a given URL, allowing for the implementation
of virtual module sources.

Note that only valid fetch scheme URLs are supported - http: / https: / data: / blob: / file:.
https: or file: is therefore recommended for virtual module paths.

For example:

<script>
const virtualFs = {
  'index.js': `import './src/dep.js';`,
  'src/dep.js': 'console.log("virtual source execution!")'
};
esmsInitOptions = {
  source (url, fetchOpts, parent, defaultSourceHook) {
    // Only virtualize sources under the URL file:///virtual-pkg/ (i.e. via
    // `import 'file:///virtual-pkg/index.js'`.
    if (!url.startsWith('file:///virtual-pkg/')) return defaultSourceHook(url, fetchOpts, parent);

    // Strip the query string prefix for hot reloading workflow support
    const versionQueryParam = url.match(/?v=d+$/);
    if (versionQueryParam) url = url.slice(0, -versionQueryParam[0].length);

    // Lookup the virtual source from the virtual filesystem and return if found
    const virtualSource = virtualFs[url.slice('file:///virtual-pkg/'.length)];
    if (!virtualSource) throw new Error(`Virtual module ${url} not found, imported from ${parent}`);
    return {
      type: 'js',
      source: virtualSource
    };
  }
};
</script>

For support in hot reloading workflows, note that the ?v={Number} version query
string suffix will be passed so needs to be checked and removed if applicable.

For JS, CSS, JSON and TypeScript, it provides the source text string.
For WebAssembly, it provides the compiled WebAssembly.Module record.

The default implementation uses globalThis.fetch to obtain the response and then
the 'content-type' MIME type header to infer the module type, per HTML semantics.

URL may be returned differently from the request URL because responseURL
is allowed to be distinct from requestURL in the module system even thoough
requestURL is used as the registry key only.

Meta Hook

The meta hook allows customizing the import.meta object in each module scope.

The function takes as arguments the import.meta object itself (with import.meta.url an import.meta.resolve already present), and the URL of the module as its second argument.

Example:

<script>
  window.esmsInitOptions = {
    shimMode: true,
    meta: function (metaObj, url) {
      metaObj.custom = `custom value for ${url}`;
    }
  }
</script>

Where within the module the following would be supported:

import assert from 'assert';
assert.ok(import.meta.custom.startsWith('custom value'));

> It is usually recommended to use shim mode with module customization hooks. When the resolve hook is enabled in polyfill mode (or any other hooks), native passthrough will be disabled and modules may be executed twice if they correctly execute without the hook.

Fetch Hook

The fetch hook is supported for shim mode only.

The ES Module Shims fetch hook can be used to implement transform plugins.

For example TypeScript support:

```js

window.esmsInitOptions = {
shimMode: true,
fetch: async function (url, options) {
const res = await fetch(url, options);
if (!res.ok)
return res;
if (res.url.endsWith('.ts')) {
const source = await res.body();
const transformed = tsCompile(source);
return new Response(new Blob([transf