Installation

Requirements

mapcn-rn is built and tested for Expo projects. Bare React Native may work, but the CLI reports it as unverified.

Both supported renderers contain native code. Expo Go is not supported. Use an Expo development build, run prebuild after changing the renderer or Expo plugin, and rebuild the native client.

Initialize the project

Run the command from your Expo project root:

npx mapcn-rn init

This is the only command you need to get started. The interactive setup detects your package manager, src layout, aliases, and whether you use Uniwind, NativeWind, or neither. It then:

1. asks for a renderer and compatible basemap provider;
2. asks which components to install — Minimal (map, marker, popup, controls), Everything, or a grouped checkbox list;
3. writes schema-version-2 mapcn.json;
4. installs the renderer package;
5. adds its Expo config plugin and the components' native permissions when app.json is available;
6. adds a required public token placeholder to .env.example;
7. installs the selected components and their transitive dependencies.

For a non-interactive setup, provide the choices explicitly:

npx mapcn-rn init --renderer maplibre --provider maptiler --all --yes

Valid pairs are MapLibre with carto, maptiler, or custom, and Mapbox with mapbox. With --yes and no explicit pair, init defaults to MapLibre with CARTO, which needs no API key.

Provider setup

MapTiler's public key is read when a named MapTiler style is resolved. Mapbox needs a public runtime token and a downloads token available to the native build. Treat MAPBOX_DOWNLOADS_TOKEN as a build secret; do not expose it with an EXPO_PUBLIC_ prefix.

The two renderer packages cannot coexist in one Expo app. The doctor command treats that combination as an error.

Native configuration

If the CLI can read app.json, it adds the selected renderer plugin to expo.plugins. With a dynamic Expo config, add the plugin yourself:

{
  "expo": {
    "plugins": ["@maplibre/maplibre-react-native"]
  }
}

Use @rnmapbox/maps instead when the selected renderer is Mapbox.

The base map component requests no location permissions. Components that use location—location, location-puck, and controls' locate behavior—require foreground permissions. init and add write these into app.json when they install such a component, without overwriting a usage description you already wrote. With a dynamic Expo config, add them yourself:

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSLocationWhenInUseUsageDescription": "Show your location on the map."
      }
    },
    "android": {
      "permissions": ["ACCESS_FINE_LOCATION", "ACCESS_COARSE_LOCATION"]
    }
  }
}

Build the native client

After initialization or any renderer switch:

npx expo prebuild --clean

Then rebuild your development client for iOS or Android. A JavaScript-only reload cannot add or change the native renderer.

Add components

If you chose Minimal at init, install the rest by registry name at any time. Transitive registry dependencies, npm dependencies, and native permissions are resolved automatically.

npx mapcn-rn add cluster heatmap route

Or install everything the renderer supports:

npx mapcn-rn add --all

Run npx mapcn-rn list to see every component and which are already installed.

Everything lands in components/ui/mapcn/ with a generated index.ts, so your own components/ui files stay untouched and the whole library imports from one path:

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

See add for the full layout.

Verify the setup

npx mapcn-rn doctor

doctor checks the project type, package manager, mapcn.json, renderer package, conflicting renderer packages, Expo plugin, Mapbox downloads token, provider token, location permissions when applicable, and installed component state. Use --verbose to include passing checks or --json for machine-readable output.