es-module-shims 2.2.0 → 2.3.1

package/README.md

@@ -9,10 +9,11 @@ For the remaining ~4% of users, the highly performant (see [benchmarks](#benchma
 The following modules features are polyfilled:
 
 * [Import Maps](#import-maps) polyfill.
-* [JSON](#json-modules) and [CSS modules](#css-modules) with import assertions when enabled.
-* [Wasm modules](#wasm-modules) with support for Source Phase Imports when enabled.
-* [Import defer](#import-defer) via syntax stripping to allow usage in modern browsers with a polyfill fallback when enabled.
+* [JSON](#json-modules) and [CSS modules](#css-modules) polyfill with import assertions.
+* [Wasm modules](#wasm-modules) with support for Source Phase Imports, when enabled.
+* [Import defer](#import-defer) via syntax stripping to allow usage in modern browsers with a polyfill fallback, when enabled.
 * [TypeScript](#typescript-type-stripping) type stripping.
+* [Hot Reloading](#hot-reloading) with a Vite-style `import.meta.hot` API.
 
 When running in shim mode, module rewriting is applied for all users and custom [resolve](#resolve-hook) and [fetch](#fetch-hook) hooks can be implemented allowing for custom resolution and streaming in-browser transform workflows.
 
@@ -29,7 +30,7 @@ Because we are still using the native module loader the edge cases work out comp
 Include ES Module Shims with a `async` attribute on the script, then include an import map and module scripts normally:
 
 ```html
-<script async src="https://ga.jspm.io/npm:es-module-shims@2.2.0/dist/es-module-shims.js"></script>
+<script async src="https://ga.jspm.io/npm:es-module-shims@2.3.1/dist/es-module-shims.js"></script>
 
 <!-- https://generator.jspm.io/#U2NhYGBkDM0rySzJSU1hKEpNTC5xMLTQM9Az0C1K1jMAAKFS5w0gAA -->
 <script type="importmap">
@@ -222,7 +223,7 @@ ES Module Shims is designed for production performance. A [comprehensive benchma
 
 Benchmark summary:
 
-* [ES Module Shims Chrome Passthrough](bench/README.md#chrome-passthrough-performance) (for [94% of users](https://caniuse.com/import-maps)) 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 10KB compressed download as expected.
+* [ES Module Shims Chrome Passthrough](bench/README.md#chrome-passthrough-performance) (for [94% of users](https://caniuse.com/import-maps)) 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 13KB compressed download as expected.
 * [ES Module Shims Polyfilling](bench/README.md#native-v-polyfill-performance) (for the remaining [3% of users](https://caniuse.com/import-maps)) 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](bench/README.md#large-import-maps-performance) (100s of entries) cost only a few extra milliseconds upfront for the additional loading cost.
 
@@ -617,6 +618,39 @@ When processing a TypeScript module, the `es-module-shims-typescript.js` extensi
 
 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
+```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](#native-passthrough) will be automatically disabled, and all modules will be provided with the `import.meta.hot` API fully supporting [Vite's `import.meta.hot`](https://vite.dev/guide/api-hmr), 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+).
@@ -656,6 +690,7 @@ Provide a `esmsInitOptions` on the global scope before `es-module-shims` is load
 * [enforceIntegrity](#enforce-integrity)
 * [fetch](#fetch-hook)
 * [mapOverrides](#overriding-import-map-entries)
+* [nativePassthrough](#native-passthrough)
 * [modulepreload](#modulepreload)
 * [noLoadEventRetriggers](#no-load-event-retriggers)
 * [globalLoadEventRetrigger](#global-load-event-retrigger)
@@ -687,6 +722,9 @@ window.esmsInitOptions = {
   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
@@ -700,7 +738,7 @@ window.esmsInitOptions = {
   // Hook import.meta construction
   meta: (meta, url) => void // default is noop
   // Hook top-level imports
-  onimport: (url, options, parentUrl) => void // default is noop
+  onimport: (url, options, parentUrl, source) => void // default is noop
 }
 </script>
 <script async src="es-module-shims.js"></script>
@@ -904,6 +942,17 @@ document.body.appendChild(Object.assign(document.createElement('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](#hot-reloading).
+
 ### Hooks
 
 #### Polyfill hook
@@ -949,8 +998,11 @@ The import hook is supported for both shim and polyfill modes and provides an as
 ```js
 <script>
   window.esmsInitOptions = {
-    onimport: function (url, options, parentUrl) {
-      console.log(`Top-level import for ${url}`);
+    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>