Skip to content
mountly

installRuntime

import { installRuntime } from "mountly";

Writes an <script type="importmap"> to <head> mapping react, react/jsx-runtime, react-dom, and react-dom/client to the URLs you pass. Pair with peer-built widgets so the host ships one copy of React for many widgets.

It does not create mappings for mountly/* subpaths. If your browser host imports subpaths directly, map them yourself in your import map.

Signature

Section titled “Signature”
function installRuntime(urls: RuntimeUrls): void;


interface RuntimeUrls {
  react: string;
  reactDom: string;
  reactDomClient: string;
  reactJsxRuntime?: string; // derived from react if omitted
}

Use it

Section titled “Use it”

In an inline module script in <head>, before any other module imports:

<head>
  <script type="module">
    import { installRuntime } from "https://cdn.jsdelivr.net/npm/mountly@0.1/dist/index.js";
    installRuntime({
      react: "https://esm.sh/react@18",
      reactDom: "https://esm.sh/react-dom@18",
      reactDomClient: "https://esm.sh/react-dom@18/client",
    });
  </script>
  <!-- … rest of head … -->
</head>

After this runs, any subsequent import "mountly" (or any peer-built widget importing react) resolves through the import map.

What it produces

Section titled “What it produces”

A single <script type="importmap" data-mountly-runtime> element prepended to <head>:

{
  "imports": {
    "react": "https://esm.sh/react@18",
    "react/jsx-runtime": "https://esm.sh/react@18/jsx-runtime",
    "react-dom": "https://esm.sh/react-dom@18",
    "react-dom/client": "https://esm.sh/react-dom@18/client"
  }
}

react/jsx-runtime is derived from react by appending /jsx-runtime if you don’t pass reactJsxRuntime.

Rules

Section titled “Rules”

1. Call before any module imports

Section titled “1. Call before any module imports”

If installRuntime runs after another module has started loading, the runtime warns:

[mountly] installRuntime called after module loading may have started.
Call it from an inline <script> in <head>, before any module imports.

The browser commits to an import map at the moment the first module begins resolving. Later mutation is a no-op.

2. First call wins

Section titled “2. First call wins”

Calling installRuntime twice with different URLs warns:

[mountly] installRuntime called twice with different URLs; first call wins.

The second call is otherwise ignored. Changing runtime URLs at runtime means re-architecting more than this helper supports.

3. The mark attribute

Section titled “3. The mark attribute”

The injected element has data-mountly-runtime so you can detect it from external tooling:

const map = document.querySelector("script[data-mountly-runtime]");

When to skip it

Section titled “When to skip it”
  • You’re using self-contained widget builds (dist/index.js). They embed React and don’t need an import map.
  • You’re inside a bundler (Vite, Next, Astro). The bundler resolves react directly; an import map would be redundant or conflicting.
  • You manage your own import map already. mountly’s helper is a convenience, not a requirement.

Manifest-driven hosts: bootstrapMountly

Section titled “Manifest-driven hosts: bootstrapMountly”

installRuntime is the low-level primitive. If a manifest describes your host, prefer bootstrapMountly from mountly/runtime. It fetches the manifest, calls installPlatformRuntime for you, and defines the <mountly-feature> elements in the order that avoids the bare-specifier race:

<script type="module">
  import { bootstrapMountly } from "/path/to/mountly/dist/runtime.js";
  await bootstrapMountly("/manifest.json");
</script>

installPlatformRuntime(urls) is the same as installRuntime but also accepts an imports map for mountly/* subpaths and vertical specifiers. appendImports(map) adds new import-map keys after boot (used by setVertical for runtime-added remotes). See Manifest & host shells.

Section titled “Related”