インポートマップとモジュール解決

なぜブラウザはreactを解決できないのか

ESモジュールの import 文で相対パス（./a.js）や絶対URL（https://example.com/a.js）を書けば、ブラウザは指定子をそのままURLとして扱い解決できます。ところが import React from "react" のような**裸の指定子（bare specifier）**は、そもそもURLとして不正です。スキームもドット始まりの相対パスも持たない文字列を、ブラウザは単独では取得先に変換できません。

Node.jsではこの変換を node_modules 探索と package.json の exports フィールドが担いますが、ブラウザにファイルシステム探索の概念はありません。import mapは、この裸の指定子を実URLへ変換するための宣言的な解決表をHTML側に持ち込む仕組みです。バンドラが担っていた「依存名→実ファイル」の対応づけを、ビルドではなくブラウザの解決アルゴリズムに肩代わりさせます。ESMの読み込みが construction・instantiation・evaluation の3フェーズで進む点は ESモジュールの解決・リンク・評価フェーズ が扱う内容で、import mapが介入するのは最初のフェーズ、指定子解決の入口です。

import mapの基本構造

import map は <script type="importmap"> に埋め込むJSONで、imports キーの下に「指定子→URL」の対応を列挙します。

<script type="importmap">
{
  "imports": {
    "react": "https://esm.sh/react@18",
    "react-dom/client": "https://esm.sh/react-dom@18/client",
    "app/": "./src/app/"
  }
}
</script>
<script type="module">
  import React from "react";
  import { createRoot } from "react-dom/client";
  import { Header } from "app/components/header.js";
</script>

これだけで、ビルドツールなしに import React from "react" がCDN上のファイルへ解決されます。バンドラが不要になるわけではなく、開発時の即時反映や依存の差し替え、小規模プロジェクトでのビルドレス開発の選択肢が増えるのが実利です。

解決アルゴリズム：最長一致で決まる

複数のマッピングが同じ指定子の前方部分にマッチしうる場合、ブラウザは最も長く一致するキーを採用します。これが最長一致（longest prefix match）です。

{
  "imports": {
    "lodash/": "https://esm.sh/lodash@4/",
    "lodash/debounce": "https://esm.sh/lodash-es@4/debounce.js"
  }
}

import debounce from "lodash/debounce" は、lodash/（プレフィックス）と lodash/debounce（完全一致）の両方に前方一致しますが、より長く具体的な lodash/debounce が優先されます。一方 import pick from "lodash/pick" は完全一致のエントリがないため、lodash/ プレフィックスにフォールバックして解決されます。登録順ではなく一致の長さが優先順位を決める点が、CSSの詳細度に近い性質だと理解すると整理しやすくなります。

スコープ付きマッピング：パス階層で解決を切り替える

scopes キーを使うと、特定のパス配下でだけ有効な指定子マッピングを定義できます。これは同じ指定子名でも読み込み元によって違うバージョンを解決したいときに使います。

{
  "imports": {
    "lib": "https://esm.sh/lib@2"
  },
  "scopes": {
    "/legacy/": {
      "lib": "https://esm.sh/lib@1"
    }
  }
}

/legacy/ 配下から読み込まれたモジュールが import x from "lib" すると lib@1 に、それ以外からの同じ指定子は lib@2 に解決されます。スコープの適用範囲は、インポート元モジュールのURLがスコープキーのパスに前方一致するかどうかで判定されます。スコープも複数マッチしうるため、まずスコープキー同士の最長一致で対象スコープを絞り、その中のマッピングをトップレベルの imports より優先して適用します。トップレベルの imports はいわば「既定のスコープ」として最後にフォールバックされる位置づけです。

import mapのタイミング制約

import map はブラウザの解決に介入するため、いつ読み込まれるかに制約があります。ただしこの制約は当初の仕様より緩和されており、実装差にも注意が必要です。

• 初期の仕様およびそれを反映した実装（例: 2023年頃までのChromium）では、import mapは最初のモジュールスクリプトが評価される前に確定していなければならず、1ドキュメントにつき1つしか書けませんでした。
• その後の仕様改定（Chromium 133、Firefox・WebKit追随）で、この制約は緩和されました。1つのドキュメントに複数の <script type="importmap"> を書ける上、モジュールの評価が始まった後からでも動的に追加できます。すでに解決済みの指定子には影響しませんが、未解決の指定子には新しいマッピングが反映されます。
• 複数のimport mapで同じ指定子キーが重複した場合、エラーにはならず、先に登録されたマッピングが優先され、後から来た重複エントリは無視されます（import map自体は無効化されません）。すでに解決済みのモジュールに対する再定義も同様に無視されます。
• 外部ファイル参照（<script type="importmap" src="...">）にも対応していますが、非同期取得である以上、後続のモジュール実行を暗黙に遅らせる形で足並みを揃える必要があります。

バンドラなし開発とCDN移行の実利

import map が実務で効くのは、依存の実体をHTML側の1箇所に集約できる点です。CDNのメジャーバージョンを上げるときはimport mapの値を書き換えるだけで済み、アプリコード中の import "react" は一切変更不要です。開発中は素の <script type="module"> を python -m http.server のような単純な静的サーバーで動かし、本番だけバンドル・圧縮する、といった段階的な使い分けも可能です。スクリプトの取得・実行タイミングそのものは レンダリングブロックとパース阻害（defer/async/moduleの差） が扱う type=module の既定挙動（defer相当）と組み合わさるため、import mapを使っても評価順の直感は変わりません。

CDN経由でサードパーティスクリプトを読み込む以上、配信経路の改ざん検出も合わせて検討する価値があります。integrity 属性によるハッシュ照合は Subresource Integrityとリソース改ざん検出 が扱う領域で、import mapのマッピング先URLに対しても同様にCORSと crossorigin の制約が関わります。クロスオリジンの解決先を使う場合の応答共有の前提は CORS（オリジン間リソース共有） の仕組みと地続きです。

まとめ