{"id":38053801,"url":"https://github.com/bennypowers/mappa","last_synced_at":"2026-01-19T19:00:58.538Z","repository":{"id":332501157,"uuid":"1133698121","full_name":"bennypowers/mappa","owner":"bennypowers","description":"The high-performance import map generator for the modern web","archived":false,"fork":false,"pushed_at":"2026-01-16T12:12:09.000Z","size":1879,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T02:17:32.663Z","etag":null,"topics":["golang","import-maps"],"latest_commit_sha":null,"homepage":"https://bennypowers.dev/mappa","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bennypowers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-13T17:43:32.000Z","updated_at":"2026-01-16T12:12:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bennypowers/mappa","commit_stats":null,"previous_names":["bennypowers/mappa"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/bennypowers/mappa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bennypowers%2Fmappa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bennypowers%2Fmappa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bennypowers%2Fmappa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bennypowers%2Fmappa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bennypowers","download_url":"https://codeload.github.com/bennypowers/mappa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bennypowers%2Fmappa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28547004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T14:59:57.589Z","status":"ssl_error","status_checked_at":"2026-01-18T14:59:46.540Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","import-maps"],"created_at":"2026-01-16T20:20:33.652Z","updated_at":"2026-01-18T18:01:04.081Z","avatar_url":"https://github.com/bennypowers.png","language":"Go","funding_links":[],"categories":["Tools"],"sub_categories":["Building"],"readme":"# Mappa\n\nThe high-performance import map generator for the modern web, available as a CLI tool and Go library.\n\n![mappa - import map generator](./docs/images/mappa.png)\n\n\u003e *Mappa* (מַפָּה) is Hebrew for \"map\".\n\nModern web applications use ES modules with bare specifiers like `import { html } from 'lit'`. Browsers need [import maps][importmaps] to resolve these specifiers to actual URLs.\n\nMappa generates import maps from your `package.json` dependencies, pointing to your local `node_modules` paths or to a path of your choosing (like `/assets/packages/...`. It's designed to be fast, with parallel dependency resolution.\n\n## Features\n\n- **Local resolution**: Generate import maps pointing to your install node modules paths\n- **Custom URL templates**: Use any asset path with `{package}` and `{path}` variables\n- **Export maps**: Full support for package.json `exports` field including subpaths and wildcards\n- **Scopes**: Automatic scope generation for transitive dependencies\n- **Merge input maps**: Combine generated maps with manual overrides\n- **Parallel resolution**: Fast transitive dependency resolution\n\n## Installation\n\n### From Source\n\n```bash\ngo install bennypowers.dev/mappa@latest\n```\n\n\n## Quick Start\n\nGenerate an import map for your project:\n\n```bash\n# Local paths (default)\nmappa generate\n\n# Output as HTML script tag\nmappa generate --format html\n\n# Custom asset path\nmappa generate --template \"/assets/packages/{package}/{path}\"\n```\n\n## CLI Reference\n\n### `mappa generate`\n\nGenerate an import map from `package.json` dependencies.\n\n```\nFlags:\n  -f, --format string        Output format: json, html (default \"json\")\n      --include-package      Additional packages to include (repeatable)\n      --input-map string     Import map file to merge with generated output\n      --template string      URL template (default: /node_modules/{package}/{path})\n  -p, --package string       Package directory (default \".\")\n  -o, --output string        Output file (default: stdout)\n```\n\n**Examples:**\n\n```bash\n# Include devDependencies\nmappa generate --include-package fuse.js --include-package vitest\n\n# Merge with manual overrides\nmappa generate --input-map manual-imports.json\n\n# Custom asset path\nmappa generate --template \"/assets/packages/{package}/{path}\"\n```\n\n### `mappa trace`\n\nTrace HTML files to discover ES module imports and generate minimal import maps containing only the specifiers actually used.\n\n```\nFlags:\n  -f, --format string        Output format: json, html, specifiers (default \"json\")\n      --template string      URL template (default: /node_modules/{package}/{path})\n      --conditions string    Export condition priority (e.g., production,browser,import,default)\n      --glob string          Glob pattern to match HTML files (e.g., \"_site/**/*.html\")\n  -j, --jobs int             Number of parallel workers (default: number of CPUs)\n  -p, --package string       Package directory (default \".\")\n  -o, --output string        Output file (default: stdout)\n```\n\n**Examples:**\n\n```bash\n# Trace a single HTML file\nmappa trace index.html\n\n# Trace with custom template\nmappa trace index.html --template \"/assets/packages/{package}/{path}\"\n\n# Batch mode with glob pattern (outputs NDJSON)\nmappa trace --glob \"_site/**/*.html\" -j 8\n\n# Output raw traced specifiers for debugging\nmappa trace index.html --format specifiers\n```\n\n**How it works:**\n\n1. Parses HTML to find `\u003cscript type=\"module\"\u003e` tags\n2. Uses tree-sitter to extract all `import` statements from JS modules\n3. Follows transitive dependencies through local and node_modules files\n4. Generates an import map with only the bare specifiers actually imported\n\n**Static Analysis Limitations:**\n\nThe trace command uses static analysis to find imports. This means:\n\n- **Dynamic imports with variable specifiers cannot be detected.** For example:\n  ```javascript\n  // This WILL be traced\n  import '@rhds/icons/standard/web-icon.js';\n\n  // This will NOT be traced (specifier is computed at runtime)\n  const iconName = 'web-icon';\n  import(`@rhds/icons/standard/${iconName}.js`);\n  ```\n\n- To handle dynamic imports, mappa includes **trailing-slash import map keys** for all direct dependencies that have wildcard exports. For example, if your package.json lists `@rhds/icons` as a dependency and that package exports `./*`, the import map will include `\"@rhds/icons/\": \"/assets/packages/@rhds/icons/\"` to cover any dynamic imports.\n\n- The same applies to scopes: transitive dependencies with wildcard exports get trailing-slash keys so their dynamic imports work correctly.\n\n## URL Templates\n\nTemplates use `{variable}` syntax for dynamic URL generation:\n\n| Variable    | Description                | Example                    |\n| ----------- | -------------------------- | -------------------------- |\n| `{package}` | Full package name          | `@scope/name` or `name` |\n| `{name}`    | Package name without scope | `name`                     |\n| `{scope}`   | Scope without @ prefix     | `scope`                    |\n| `{path}`    | File path within package   | `index.js`                 |\n\n**Examples:**\n\n```bash\n# Default (node_modules)\n--template \"/node_modules/{package}/{path}\"\n\n# Custom assets directory\n--template \"/assets/packages/{package}/{path}\"\n\n# Scoped package handling\n--template \"/libs/{scope}/{name}/{path}\"\n```\n\n## Performance\n\nMappa is written in Go for speed. Benchmarked against [@jspm/generator][jspm] on a real-world project ([Red Hat Design System][rhds]):\n\n| Tool            | Time          |\n| --------------- | ------------- |\n| mappa           | 3.2ms ± 0.2ms |\n| @jspm/generator | 230ms ± 6ms   |\n\n**mappa is ~72x faster** for local import map generation.\n\n[jspm]: https://jspm.org/\n[rhds]: https://github.com/RedHat-UX/red-hat-design-system\n\n## Integration Examples\n\n### 11ty / Eleventy\n\n```typescript\nimport { execSync } from 'node:child_process';\n\nexport default function(eleventyConfig) {\n  const result = execSync('mappa generate --template \"/assets/packages/{package}/{path}\"', {\n    encoding: 'utf-8',\n  });\n\n  const importMap = JSON.parse(result);\n\n  // Set up passthrough copies for each package\n  for (const [, path] of Object.entries(importMap.imports)) {\n    const match = path.match(/^\\/assets\\/packages\\/(@[^/]+\\/[^/]+|[^/]+)/);\n    if (match) {\n      eleventyConfig.addPassthroughCopy({\n        [`node_modules/${match[1]}`]: `/assets/packages/${match[1]}`,\n      });\n    }\n  }\n\n  // Inject import map into HTML\n  eleventyConfig.addTransform('importmap', (content, outputPath) =\u003e {\n    if (!outputPath?.endsWith('.html')) return content;\n\n    const script = `\u003cscript type=\"importmap\"\u003e\\n${JSON.stringify(importMap, null, 2)}\\n\u003c/script\u003e`;\n    return content.replace('\u003c/head\u003e', `${script}\\n\u003c/head\u003e`);\n  });\n}\n```\n\n## License\n\nGPLv3\n\n[importmaps]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbennypowers%2Fmappa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbennypowers%2Fmappa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbennypowers%2Fmappa/lists"}