@hamuga/imap-react-native

Hamuga iMap SDK for React Native.

This package exposes:

• HamugaMap for map rendering with built-in search UI
• re-exports from @hamuga/imap-core for convenience

Shared ecosystem packages:

• @hamuga/imap-core
• @hamuga/imap-react-native

Prerequisites

Before integrating this SDK, make sure your app environment includes:

• React Native app project
• Node.js 18+
• React Native Safe Area Context installed
• Xcode + CocoaPods for iOS builds
• Android Studio + Android SDK for Android builds
• iOS deployment target 13.0 or higher

This repository is currently aligned with:

• React 18.2.0
• React Native 0.72.6

Architecture Compatibility

This package does not ship a custom native module or native view in the npm tarball. The public SDK surface is JavaScript on top of these peer native dependencies:

• @maplibre/maplibre-react-native
• react-native-safe-area-context
• react-native-svg

Because of that, this package can be used from both the old architecture (Paper) and the new architecture (Fabric/TurboModules) as long as those peer dependencies are compatible with the host app's React Native setup.

Installation

Install the package and its peer dependencies:

npm install @hamuga/imap-react-native @maplibre/maplibre-react-native react-native-safe-area-context react-native-svg

or

yarn add @hamuga/imap-react-native @maplibre/maplibre-react-native react-native-safe-area-context react-native-svg

This package expects these libraries to be installed in the host app so React Native autolinking can wire their native code correctly:

• @maplibre/maplibre-react-native
• react-native-safe-area-context
• react-native-svg

There is no additional autolinked native code from @hamuga/imap-react-native itself.

For iOS, install pods after dependency changes in the app:

cd ios && pod install

Native Dependencies

HamugaMap is built on top of:

• @maplibre/maplibre-react-native
• react-native-svg
• react-native-safe-area-context

If your app already uses these packages, keep the versions compatible with this SDK.

Usage

Map Component

import React, { useRef } from 'react';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import {
  HamugaMap,
  type HamugaMapRef,
} from '@hamuga/imap-react-native';

export function MyMapScreen() {
  const mapRef = useRef<HamugaMapRef>(null);

  const handleSearch = async () => {
    const results = await mapRef.current?.getPoi({ query: 'restaurant' });
    console.log(results);
  };

  return (
    <SafeAreaProvider>
      <HamugaMap
        ref={mapRef}
        apiKey="YOUR_HAMUGA_API_KEY"
        search
        center={[106.9163, 47.9191]}
        zoom={14}
      />
    </SafeAreaProvider>
  );
}

Global Initialization

If you prefer not to pass apiKey on every usage, initialize the SDK once:

import { HamugaApi } from '@hamuga/imap-react-native';

HamugaApi.initialize({
  apiKey: 'YOUR_HAMUGA_API_KEY',
});

Then:

<HamugaMap search />

Standalone Gateway Client

import { createHamugaSearchClient } from '@hamuga/imap-core';

const client = createHamugaSearchClient({
  apiKey: 'YOUR_HAMUGA_API_KEY',
});

async function search() {
  const suggestion = await client.getSuggest('central');
  const pois = await client.getPoi({ query: 'coffee' });
  const route = await client.planRoute({
    from: [106.9, 47.9],
    to: [106.91, 47.92],
    mode: 'WALK',
  });

  console.log({ suggestion, pois, route });
}

API Overview

HamugaMap props

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | apiKey | string | optional when HamugaApi.initialize() was called | Hamuga gateway API key | | center | [number, number] | [106.9163376, 47.919118] | [longitude, latitude] | | zoom | number | 14.5 | Initial zoom | | mapStyle | string \| object | https://cdn.hamuga.mn/mobile.json | Custom map style | | search | boolean | false | Enables the search panel | | searchWithinViewport | boolean | false | Restricts POI search to current viewport | | searchPlaceholder | string | Байршил хайх... | Search input placeholder | | gatewayBaseUrl | string | https://gateway.hamuga.mn | Custom gateway base URL | | showZoomControls | boolean | false | Shows zoom buttons | | showCompassControl | boolean | false | Shows compass button | | showMyLocationButton | boolean | true | Shows my-location button | | showScaleBar | boolean | false | Shows scale bar | | enableHapticFeedback | boolean | false | Enables haptics where supported |

HamugaMapRef

• suggest(query)
• getSuggest(query)
• searchPois(options)
• getPoi(options)
• planRoute(options)
• calculateRoute(options)

Search client

createHamugaSearchClient() returns the same gateway methods exposed through the map ref:

• suggest(query)
• getSuggest(query)
• searchPois(options)
• getPoi(options)
• planRoute(options)
• calculateRoute(options)

Use @hamuga/imap-core directly if you need gateway access without the React Native UI package.

Example App

The local example app lives under example/.

Typical workflow:

yarn install
yarn workspace hamuga-imap-example start

In another terminal:

yarn workspace hamuga-imap-example ios

or

yarn workspace hamuga-imap-example android

Publish Checklist

Before publishing a new version:

yarn verify
npm pack --dry-run

Publish to npm:

npm publish

License

Apache-2.0