add

npx mapcn-rn add <component...> [--overwrite] [--yes] [--renderer maplibre|mapbox]
npx mapcn-rn add --all

What it does

1. Reads mapcn.json. If the project has none, add runs init first, then continues with the components you asked for.
2. Fetches the registry manifest and resolves every requested component's transitive registryDependencies, topologically sorted -- already-satisfied dependencies are skipped, and the resolved set is printed before anything is written.
3. For each file:
   • New file: written directly.
   • Unmodified since install: upgraded silently if the registry version differs.
   • Locally modified (or an untracked file already at that path): never overwritten. The new version is written to a <name>.new.tsx sidecar instead, and the CLI prints a diff command to review it -- unless --overwrite is passed, in which case the original is snapshotted to .mapcn-backup/<timestamp>/ first, then replaced.
4. Installs any newly-required npm dependencies with the detected package manager.
5. Writes the components' declared Expo config plugins and native permissions into app.json — see Permissions.
6. Regenerates components/ui/mapcn/index.ts, the barrel that re-exports everything installed.
7. Updates mapcn.json with the installed component versions and file hashes.

Where files land

Components are installed into components/ui/mapcn/, alongside a generated index.ts, so the whole library sits in one folder next to (not mixed into) your own components/ui files:

src/
  components/ui/mapcn/
    index.ts              generated barrel -- rewritten on every add
    map.tsx
    map-marker.tsx
    ...
  lib/mapcn/              shared utilities
  hooks/
    use-location-tracking.ts

Import anything you have installed from a single path:

import { Map, MapMarker, MapClusterLayer, useLocationTracking } from "@/components/ui/mapcn";

The barrel is generated, so edits to index.ts are overwritten on the next add. Everything else in the folder is yours to change. Renderer-internal adapters (map-renderer.tsx) are deliberately left out of the barrel, since their exports differ per renderer — import those directly when you need raw renderer access.

Install everything

npx mapcn-rn add --all

--all installs every component available for the renderer recorded in mapcn.json. Combined with the auto-init above, this is the one-command path from an empty Expo project to every map primitive installed and doctor-clean:

npx mapcn-rn add --all --yes

With --yes and no existing config, setup is fully non-interactive and defaults to MapLibre with CARTO, which needs no API key. Pass --renderer / --provider to choose something else without prompts.

Flags

Example

npx mapcn-rn add cluster choropleth legend location-puck

Installing cluster automatically resolves and installs its map and core dependencies too, if not already present.

Related

init · list & diff · Configuration