feat: add Expo config plugin for SDK 56+

.github/workflows/ci.yml

@@ -60,3 +60,6 @@ jobs:
 
       - name: Build
         run: bun run build
+
+      - name: Test
+        run: bun run --filter react-native-nitro-maps test

.gitignore

@@ -9,6 +9,7 @@ dist/
 
 # Build outputs
 package/lib/
+package/plugin/build/
 package/nitrogen/
 
 # Expo

README.md

@@ -20,6 +20,43 @@ bun add react-native-nitro-maps react-native-nitro-modules
 
 > Requires React Native 0.78+ with the New Architecture enabled.
 
+### Expo config plugin
+
+For Expo apps (SDK 56+), add the config plugin to `app.json` or `app.config.js`:
+
+```js
+export default {
+  expo: {
+    plugins: [
+      [
+        'react-native-nitro-maps',
+        {
+          googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY,
+          locationPermission:
+            'Allow $(PRODUCT_NAME) to use your location for map features.',
+        },
+      ],
+    ],
+  },
+};
+```
+
+| Option | Platform | Description |
+| --- | --- | --- |
+| `googleMapsApiKey` | iOS + Android | Shared fallback when platform-specific keys are omitted. |
+| `iosGoogleMapsApiKey` | iOS | Injects `GoogleMapsIosApiKey` into Info.plist for `provider="google"`. |
+| `androidGoogleMapsApiKey` | Android | Injects `com.google.android.geo.API_KEY` meta-data. |
+| `locationPermission` | iOS + Android | String sets `NSLocationWhenInUseUsageDescription` and adds `ACCESS_FINE_LOCATION` + `ACCESS_COARSE_LOCATION`. Pass `false` or omit to skip. |
+| `locationAlwaysPermission` | iOS + Android | String sets `NSLocationAlwaysAndWhenInUseUsageDescription` and adds `ACCESS_BACKGROUND_LOCATION`. Pass `false` or omit to skip. |
+
+After `expo prebuild`, native projects have the required keys and permissions without manual edits.
+
+> **Google Maps API key:** Use either this plugin's `googleMapsApiKey` option or Expo's built-in `android.config.googleMaps.apiKey` — pick one source, not both.
+>
+> **EAS Secrets:** Store `GOOGLE_MAPS_API_KEY` as an EAS secret and reference it via `process.env.GOOGLE_MAPS_API_KEY` in `app.config.js`.
+
+See [docs/expo-setup.md](docs/expo-setup.md) for a full Expo SDK 56 setup walkthrough.
+
 ## Usage
 
 ```tsx

docs/expo-setup.md

@@ -0,0 +1,114 @@
+# Expo setup (SDK 56+)
+
+This guide covers configuring `react-native-nitro-maps` in an Expo app with the New Architecture enabled.
+
+## Prerequisites
+
+- Expo SDK 56+
+- React Native 0.78+ with New Architecture enabled (`newArchEnabled: true` in `app.json`)
+- `react-native-nitro-modules` installed alongside `react-native-nitro-maps`
+
+## Install
+
+```bash
+bun add react-native-nitro-maps react-native-nitro-modules
+```
+
+## Config plugin
+
+Add the plugin to `app.json` or `app.config.js`:
+
+```js
+/** @type {import('expo/config').ExpoConfig} */
+module.exports = {
+  expo: {
+    // ...your existing config
+    plugins: [
+      [
+        'react-native-nitro-maps',
+        {
+          googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY,
+          locationPermission:
+            'Allow $(PRODUCT_NAME) to use your location for map features.',
+        },
+      ],
+    ],
+  },
+};
+```
+
+### Plugin options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `googleMapsApiKey` | `string` | — | Android: injects `com.google.android.geo.API_KEY` meta-data. iOS: no-op (MapKit needs no key; reserved for future Google Maps iOS support in [#2](https://github.com/gmi-software/react-native-nitro-maps/issues/2)). |
+| `locationPermission` | `string \| false` | — | When set to a string: iOS `NSLocationWhenInUseUsageDescription` + Android `ACCESS_FINE_LOCATION` and `ACCESS_COARSE_LOCATION`. |
+| `locationAlwaysPermission` | `string \| false` | — | When set to a string: iOS `NSLocationAlwaysAndWhenInUseUsageDescription` + Android `ACCESS_BACKGROUND_LOCATION`. |
+
+Omitting `googleMapsApiKey` does not fail prebuild. Android maps will not render until a key is provided (via the plugin or manually). iOS MapKit works without a key.
+
+## Google Maps API key
+
+### Local development
+
+Create a `.env` file (see `example/.env.example`):
+
+```dotenv
+GOOGLE_MAPS_API_KEY=your-google-maps-api-key
+```
+
+Load it in `app.config.js` with `process.env.GOOGLE_MAPS_API_KEY` as shown above.
+
+### EAS Build
+
+Store the key as an EAS secret:
+
+```bash
+eas secret:create --name GOOGLE_MAPS_API_KEY --value your-google-maps-api-key
+```
+
+Reference it in `app.config.js` via `process.env.GOOGLE_MAPS_API_KEY`. EAS injects secrets into the build environment automatically.
+
+### Alternative: Expo built-in Google Maps config
+
+You can use Expo's native `android.config.googleMaps.apiKey` instead of the plugin's `googleMapsApiKey`. Pick one source — do not configure both.
+
+## Prebuild
+
+Generate native projects:
+
+```bash
+expo prebuild --clean
+```
+
+The plugin injects:
+
+- **Android:** `com.google.android.geo.API_KEY` meta-data (when `googleMapsApiKey` is set) and location permissions (when location options are set)
+- **iOS:** location usage description strings (when location options are set)
+
+## Run
+
+```bash
+expo run:android
+expo run:ios
+```
+
+## Example app
+
+The monorepo example at `example/` uses this plugin. From the repo root:
+
+```bash
+GOOGLE_MAPS_API_KEY=your-key bun example prebuild
+GOOGLE_MAPS_API_KEY=your-key bun example android
+```
+
+The example's `prebuild` script builds the plugin (`build:plugin`) before running `expo prebuild`, since the workspace symlink requires compiled plugin output.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| Blank map on Android | Ensure `googleMapsApiKey` is set and `expo prebuild` was run after adding the plugin. |
+| Location dot not showing | Set `locationPermission` in the plugin options and re-run prebuild. |
+| Plugin not found | Confirm `react-native-nitro-maps` is installed and listed in `plugins`. |
+| `Cannot find module './plugin/build/index'` | Run `bun run build:plugin` in the package (or `bun run build` from the repo root) before prebuild when using a workspace link. |

eslint.config.mjs

@@ -9,6 +9,7 @@ export default tseslint.config(
     ignores: [
       '**/node_modules/**',
       '**/lib/**',
+      '**/plugin/build/**',
       '**/nitrogen/**',
       '**/.expo/**',
       '**/android/**',
@@ -28,6 +29,9 @@ export default tseslint.config(
         ...globals.node,
       },
     },
+    rules: {
+      '@typescript-eslint/no-require-imports': 'off',
+    },
   },
   {
     files: ['**/*.{ts,tsx}'],

example/android/app/src/main/AndroidManifest.xml

@@ -1,4 +1,6 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools">
+  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
+  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" tools:replace="android:maxSdkVersion"/>
   <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
@@ -12,7 +14,6 @@
     </intent>
   </queries>
   <application android:name=".MainApplication" android:label="@string/app_name" android:icon="@mipmap/ic_launcher" android:roundIcon="@mipmap/ic_launcher_round" android:allowBackup="true" android:theme="@style/AppTheme" android:supportsRtl="true" android:enableOnBackInvokedCallback="false">
-    <meta-data android:name="com.google.android.geo.API_KEY" android:value="test-key"/>
     <meta-data android:name="expo.modules.updates.ENABLED" android:value="false"/>
     <meta-data android:name="expo.modules.updates.ENABLE_BSDIFF_PATCH_SUPPORT" android:value="true"/>
     <meta-data android:name="expo.modules.updates.EXPO_UPDATES_CHECK_ON_LAUNCH" android:value="ALWAYS"/>
@@ -23,6 +24,5 @@
         <category android:name="android.intent.category.LAUNCHER"/>
       </intent-filter>
     </activity>
-    <uses-library android:name="org.apache.http.legacy" android:required="false"/>
   </application>
 </manifest>

example/app.config.js

@@ -22,6 +22,8 @@ module.exports = {
         {
           iosGoogleMapsApiKey,
           androidGoogleMapsApiKey,
+          locationPermission:
+            'Allow $(PRODUCT_NAME) to use your location for map features.',
         },
       ],
     ],

example/ios/NitroMapsExample/Info.plist

@@ -44,6 +44,8 @@
       <key>NSAllowsLocalNetworking</key>
       <true/>
     </dict>
+    <key>NSLocationWhenInUseUsageDescription</key>
+    <string>Allow $(PRODUCT_NAME) to use your location for map features.</string>
     <key>RCTNewArchEnabled</key>
     <true/>
     <key>UILaunchStoryboardName</key>

package/android/README.md

@@ -56,6 +56,8 @@ For the example Expo app, set `GOOGLE_MAPS_ANDROID_API_KEY` or the shared `GOOGL
 <MapView provider="google" googleMapId="YOUR_MAP_ID" />
 ```
 
+Expo apps can use the built-in config plugin instead of manual manifest edits — see [docs/expo-setup.md](../../docs/expo-setup.md).
+
 ## Getting started
 
 1. Run `bun run nitrogen` from the repo root if you change the Nitro spec.

package/app.plugin.js

@@ -1,47 +1 @@
-const IOS_GOOGLE_MAPS_API_KEY = 'GoogleMapsIosApiKey';
-
-/**
- * @typedef {object} NitroMapsPluginProps
- * @property {string=} googleMapsApiKey Shared Google Maps API key for both platforms.
- * @property {string=} iosGoogleMapsApiKey Google Maps API key for iOS.
- * @property {string=} androidGoogleMapsApiKey Google Maps API key for Android.
- */
-
-/**
- * @param {import('expo/config').ExpoConfig} config
- * @param {NitroMapsPluginProps=} props
- * @returns {import('expo/config').ExpoConfig}
- */
-function withNitroMaps(config, props = {}) {
-  const iosGoogleMapsApiKey =
-    props.iosGoogleMapsApiKey ?? props.googleMapsApiKey;
-  const androidGoogleMapsApiKey =
-    props.androidGoogleMapsApiKey ?? props.googleMapsApiKey;
-
-  if (iosGoogleMapsApiKey != null) {
-    config.ios = {
-      ...config.ios,
-      infoPlist: {
-        ...config.ios?.infoPlist,
-        [IOS_GOOGLE_MAPS_API_KEY]: iosGoogleMapsApiKey,
-      },
-    };
-  }
-
-  if (androidGoogleMapsApiKey != null) {
-    config.android = {
-      ...config.android,
-      config: {
-        ...config.android?.config,
-        googleMaps: {
-          ...config.android?.config?.googleMaps,
-          apiKey: androidGoogleMapsApiKey,
-        },
-      },
-    };
-  }
-
-  return config;
-}
-
-module.exports = withNitroMaps;
+module.exports = require('./plugin/build/index').default;

package/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/plugin/src'],
+  testMatch: ['**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js'],
+};

package/package.json

@@ -18,6 +18,7 @@
     "app.plugin.js",
     "src",
     "lib",
+    "plugin/build",
     "nitrogen",
     "ios",
     "android",
@@ -29,11 +30,18 @@
     "!**/__mocks__"
   ],
   "scripts": {
-    "build": "bob build",
-    "typecheck": "tsc --noEmit",
+    "build": "bob build && bun run build:plugin",
+    "clean:plugin": "rm -rf plugin/build",
+    "build:plugin": "bun run clean:plugin && tsc --project tsconfig.plugin.json",
+    "prepack": "bun run build",
+    "test": "jest",
+    "typecheck": "tsc --noEmit && tsc --project tsconfig.plugin.json --noEmit",
     "typecheck:provider-types": "tsc --noEmit -p tsconfig.type-tests.json",
     "nitrogen": "nitrogen && bun ./scripts/patch-nitrogen-generated.mjs"
   },
+  "expo": {
+    "plugin": "./app.plugin.js"
+  },
   "keywords": [
     "react-native",
     "maps",
@@ -64,12 +72,16 @@
     "react-native-nitro-modules": ">=0.35.0"
   },
   "devDependencies": {
+    "@expo/config-plugins": "~56.0.0",
+    "@types/jest": "^29.5.14",
     "@types/react": "^19.2.15",
+    "jest": "^29.7.0",
     "nitrogen": "^0.35.9",
     "react": "19.2.3",
     "react-native": "0.85.3",
     "react-native-builder-bob": "^0.43.0",
     "react-native-nitro-modules": "^0.35.10",
+    "ts-jest": "^29.4.0",
     "typescript": "^5.8.3"
   },
   "react-native-builder-bob": {