{
    "slug": "js_import_maps",
    "term": "Import Maps",
    "category": "javascript",
    "difficulty": "intermediate",
    "short": "Import maps let browsers resolve bare module specifiers (import 'lodash') without a bundler — mapping module names to URLs in a JSON script tag.",
    "long": "Import maps (<script type='importmap'>) define a JSON mapping of bare specifiers to URLs. Without a bundler: import 'lodash' resolves to 'https://cdn.jsdelivr.net/npm/lodash@4.17.21/+esm'. This enables CDN-based ES module development without npm/bundler. Also supports scopes for version-specific imports in nested dependencies. Import maps must be declared before any module scripts. Fully supported in Chrome 89+, Firefox 108+, Safari 16.4+. Use esm.sh or skypack for CDN-hosted ES modules.",
    "aliases": [],
    "tags": [
        "javascript",
        "modules",
        "esm",
        "browser",
        "no-bundler"
    ],
    "misconception": "Import maps replace bundlers entirely for production — they're best for development or small projects. Production still benefits from bundling for performance.",
    "why_it_matters": "Import maps enable framework-free ES module development in browsers, removing the bundler requirement for simple apps and speeding up development iterations.",
    "common_mistakes": [
        "Declaring import map after module scripts — must come first.",
        "Using CommonJS CDN URLs — import maps need ES module (ESM) URLs.",
        "Expecting import maps to work in Node.js — they're a browser feature (Node has its own resolution)."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "js_modules",
        "js_top_level_await",
        "js_bundling_concepts"
    ],
    "prerequisites": [
        "js_modules"
    ],
    "refs": [
        "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap"
    ],
    "bad_code": "<!-- Before import maps: requires bundler for bare specifiers -->\n<script>\nimport lodash from 'lodash'; // Fails in browser\n</script>",
    "good_code": "<script type=\"importmap\">\n{\n  \"imports\": {\n    \"lodash\": \"https://cdn.jsdelivr.net/npm/lodash@4.17.21/+esm\",\n    \"react\": \"https://esm.sh/react@18\",\n    \"react-dom/client\": \"https://esm.sh/react-dom@18/client\"\n  }\n}\n</script>\n<script type=\"module\">\n  import _ from 'lodash'; // Works!\n</script>",
    "quick_fix": "Add <script type='importmap'> before module scripts. Use esm.sh or skypack for CDN ESM URLs. Declare all bare specifiers used in your modules.",
    "severity": "info",
    "effort": "low",
    "created": "2026-03-23",
    "updated": "2026-03-23",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/js_import_maps",
        "html_url": "https://codeclaritylab.com/glossary/js_import_maps",
        "json_url": "https://codeclaritylab.com/glossary/js_import_maps.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Import Maps](https://codeclaritylab.com/glossary/js_import_maps) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/js_import_maps"
            }
        }
    }
}