Resilient Import Maps - Better Theme Development and Beyond

Summary

Shopify found that JavaScript modules and import maps failed in themes and App Blocks when modules loaded before a map, or when multiple maps collided. These restrictions reflected the requirement that module resolution remain stable, but real pages assembled by themes, apps, Shopify, and extensions could not reliably guarantee ordering or a single map. Working with web-platform contributors, Shopify proposed a reconciliation mechanism with one global import map, a resolved module set, and merging rules that preserve existing resolutions and drop conflicting or unsafe additions. The change reached the HTML specification and shipped in Chromium and WebKit; Chrome supports it from version 133 and Safari from 18.4. Shopify also uses es-modules-shim support for browsers without native support, while Firefox support is hoped for.

Context

Shopify’s migration of the Online Store Editor to JavaScript modules exposed failures when themes or App Blocks used import maps. Import maps required all modules to load afterward and allowed only one map, creating conflicts among Shopify, themes, apps, and user extensions and preventing broader adoption of their caching benefits.

Approach / What changed

Shopify and web-platform contributors defined a reconciliation mechanism using a global import map and a resolved module set. Each new map is merged while rules affecting already resolved modules or conflicting with existing rules are discarded. Shopify helped land the change in the HTML specification, implement it in Chromium and WebKit, and support older browsers with es-modules-shim.

Takeaways

• Import maps decouple bare module names from content-hashed URLs, allowing changed modules to receive new URLs without recursively changing importing code and triggering cache invalidation cascades.
• The reconciliation algorithm drops new rules that would change previously resolved modules and prevents later maps from overriding rules established by earlier maps.
• The feature ships in Chrome starting with version 133 and Safari starting with version 18.4; browsers without native support can use es-modules-shim version 2.4.0 or higher.

Related reading