# Mappa The high-performance import map generator for the modern web, available as a CLI tool and Go library. **[Try the web demo](https://bennypowers.github.io/mappa/)** - Generate import maps directly in your browser. ![mappa - import map generator](./docs/images/mappa.png) > *Mappa* (מַפָּה) is Hebrew for "map". Modern 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. Mappa 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. ## Features - **Local resolution**: Generate import maps pointing to your install node modules paths - **Custom URL templates**: Use any asset path with `{package}` and `{path}` variables - **Export maps**: Full support for package.json `exports` field including subpaths and wildcards - **Scopes**: Automatic scope generation for transitive dependencies - **Merge input maps**: Combine generated maps with manual overrides - **Parallel resolution**: Fast transitive dependency resolution ## Installation ### npm ```bash npm install @pwrs/mappa ``` Provides both a CLI (`npx mappa generate`) and a JavaScript API: ```typescript import { resolve } from '@pwrs/mappa'; const importMap = await resolve('.', { template: '/assets/packages/{package}/{path}', }); ``` ### Gentoo Linux Enable the `bennypowers` overlay, then install: ```bash eselect repository enable bennypowers emaint sync -r bennypowers emerge dev-util/mappa ``` ### From Source ```bash go install bennypowers.dev/mappa@latest ``` The `trace` command uses tree-sitter, so building from source requires a C toolchain and `CGO_ENABLED=1` (the default when a compiler is present). ## Quick Start Generate an import map for your project: ```bash # Local paths (default) mappa generate # Output as HTML script tag mappa generate --format html # Custom asset path mappa generate --template "/assets/packages/{package}/{path}" ``` ## CLI Reference ### `mappa generate` Generate an import map from `package.json` dependencies. ``` Flags: -f, --format string Output format: json, html (default "json") --include-package Additional packages to include (repeatable) --exclude Packages to exclude, including transitively (repeatable) --input-map string Import map file to merge with generated output --template string URL template (default: /node_modules/{package}/{path}) --conditions strings Export condition priority (e.g. production,browser,import,default) -O, --optimize int Optimization level: 0=none, 1=simplify+dedup (default 1) --strict Exit non-zero on validation warnings or unresolved declared deps --path-base string Rebase workspace paths relative to this directory --package-deps string Limit dependency resolution to this package's dependencies --cpuprofile string Write a CPU profile to this file -p, --package string Package directory (default ".") -o, --output string Output file (default: stdout) ``` Warnings about declared dependencies that could not be resolved are written to stderr. Use `--strict` to turn them into a non-zero exit. **Examples:** ```bash # Include devDependencies mappa generate --include-package fuse.js --include-package vitest # Merge with manual overrides mappa generate --input-map manual-imports.json # Custom asset path mappa generate --template "/assets/packages/{package}/{path}" ``` ### `mappa trace` Trace HTML files to discover ES module imports and generate minimal import maps containing only the specifiers actually used. ``` Flags: -f, --format string Output format: json, html, specifiers (default "json") --template string URL template (default: /node_modules/{package}/{path}) --conditions string Export condition priority (e.g., production,browser,import,default) --glob string Glob pattern to match HTML files (e.g., "_site/**/*.html") -j, --jobs int Number of parallel workers (default: number of CPUs) -p, --package string Package directory (default ".") -o, --output string Output file (default: stdout) ``` **Examples:** ```bash # Trace a single HTML file mappa trace index.html # Trace with custom template mappa trace index.html --template "/assets/packages/{package}/{path}" # Batch mode with glob pattern (outputs NDJSON) mappa trace --glob "_site/**/*.html" -j 8 # Write batch NDJSON to a file mappa trace --glob "_site/**/*.html" -o trace.ndjson # Output raw traced specifiers for debugging mappa trace index.html --format specifiers ``` In batch mode (more than one file), each NDJSON line is a result envelope: ```json {"file":"pages/index.html","imports":{"lit":"/node_modules/lit/index.js"},"scopes":{...},"warnings":["..."]} ``` Results are sorted by file name and `--format` only accepts `json`. A file-level failure sets the process exit code to 1 while still emitting a line for every file. A failed file still carries `"imports": {}`, never `null`. `--format specifiers` prints a JSON array of the discovered specifiers, and prints `[]` when a file contains none. **How it works:** 1. Parses HTML to find ``; return content.replace('', `${script}\n`); }); } ``` ## License GPLv3 [importmaps]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap