Vietmap GL SDK for React Native

Migrations

• v1.0.0 → v2.0.0
• v2.x → v3.0.0 — New Architecture support, required on Android, minimum iOS 15.1

A React Native library for building maps with the Vietmap GL Native SDK for iOS & Android.

Contact vietmap.vn to register a valid key.

Requirements

| | Minimum | | --- | --- | | React Native | 0.74 (tested against 0.76.x) | | React | 18.2.0 | | iOS deployment target | 15.1 | | Android minSdkVersion | 24 (compiles against 35) | | Android architecture | New Architecture required (newArchEnabled=true) | | iOS architecture | New or Legacy — both supported |

[!IMPORTANT] Since v3.0.0, Android only runs on the New Architecture. Your app must set newArchEnabled=true in android/gradle.properties. iOS works on both the New and the Legacy (Paper) architecture. If your app cannot enable the New Architecture on Android yet, stay on v2.x.

Starting with v3.0.0 the iOS deployment target is derived from React Native's own min_ios_version_supported, so it follows the React Native version your app uses.

Get started

The steps differ between a bare React Native project and an Expo project — follow the one matching your app.

Setup — bare React Native

1. Install the package

yarn add @vietmap/vietmap-gl-react-native
# or
npm i @vietmap/vietmap-gl-react-native

2. iOS — add the post install hook

Add $MLRN.post_install(installer) to the post_install block of your ios/Podfile:

post_install do |installer|
  # Other post install hooks...
+ $MLRN.post_install(installer)
end

Then install the pods:

cd ios
pod install

3. Android — enable the New Architecture

# android/gradle.properties
- newArchEnabled=false
+ newArchEnabled=true

This is required: the library does not support the legacy architecture on Android. No other setup is needed — the native dependencies are declared by the library itself.

4. Rebuild the app

The library contains native code, so a Metro reload is not enough:

yarn ios
yarn android

Setup — Expo

[!IMPORTANT] This package cannot be used with the Expo Go app, because it is not part of the Expo SDK. You need a development build.

1. Install the package

npx expo install @vietmap/vietmap-gl-react-native

2. Add the config plugin

Add the package to the plugins array of your app.json / app.config.{js,ts}:

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

The plugin only generates the post_install block in ios/Podfile; nothing is changed on Android and it takes no options.

3. Enable the New Architecture (required for Android)

On Expo SDK 52 and newer, set it in the same config file:

{
  "expo": {
    "newArchEnabled": true,
    "plugins": ["@vietmap/vietmap-gl-react-native"]
  }
}

On older SDKs, use expo-build-properties with android: { newArchEnabled: true }.

4. Rebuild the native project

npx expo prebuild --clean
npx expo run:ios
npx expo run:android

Rendering your first map

import React from "react";
import { MapView } from "@vietmap/vietmap-gl-react-native";

function App() {
  return <MapView style={{ flex: 1 }} mapStyle={YOUR_STYLE_URL} />;
}

mapStyle takes a style URL or a style JSON. Contact vietmap.vn to get a style URL with a valid API key.

New Architecture

Since v3.0.0 the library ships Fabric component views and codegen specs for both platforms. What is supported differs per platform:

| Platform | New Architecture | Legacy Architecture (Paper) | | --- | :--: | :--: | | iOS | ✅ | ✅ | | Android | ✅ | ❌ not supported |

Android — newArchEnabled=true is required:

# android/gradle.properties
- newArchEnabled=false
+ newArchEnabled=true

The Android view managers use the codegen ViewManagerDelegate interfaces and view commands always go through the generated Commands object, so the library does not work on Android with the legacy architecture.

iOS — either architecture works. The library follows whatever your app is set to via RCT_NEW_ARCH_ENABLED in ios/Podfile; when it is off, the Fabric sources are compiled out behind #ifdef RCT_NEW_ARCH_ENABLED and the legacy view managers are used, exactly as in v2.x.

After switching your app between architectures, delete ios/Pods and run pod install again so CocoaPods regenerates the codegen artifacts and the compiler flags.

To check which architecture is actually running, log this from JS:

console.log("Fabric:", global.nativeFabricUIManager != null);

Migrating from v2.x to v3.0.0

1. Enable the New Architecture on Android

# android/gradle.properties
- newArchEnabled=false
+ newArchEnabled=true

This is required — Android does not run on the legacy architecture in v3.0.0. Do a clean build afterwards (cd android && ./gradlew clean). No equivalent change is needed on iOS, which supports both architectures.

2. Raise the iOS deployment target to 15.1

# ios/Podfile
- platform :ios, '13.0'
+ platform :ios, '15.1'

3. Remove the DynamicLibrary subspec if you referenced it

# ios/Podfile
- pod 'vietmap-react-native/DynamicLibrary'
+ pod 'vietmap-react-native'

In most projects the pod is picked up automatically by use_native_modules! and no explicit pod line is needed at all.

4. Upgrade React Native to 0.74 or newer

v3.0.0 requires react-native >= 0.74.0 and react >= 18.2.0.

5. onPress on the native component was renamed to onMapPress

The public <MapView onPress={...}> prop is unchanged and needs no edit. This only matters if your code renders the native component directly instead of going through MapView.

See the CHANGELOG for the full list of changes.

Documentation

Installation

You must set your API key before using the library. This is required on Android and optional on iOS. You can set the API key in your app's entry file (e.g. App.js). We've created a demo project for Vietmap React-Native GL library, which contains sample code for the main functions of the library here.

If you're using the Expo project, follow the guide from this project.

Components

• MapView
• Light
• StyleSheet
• PointAnnotation
• MarkerView
• Callout
• Camera
• UserLocation
• Images

Sources

• VectorSource
• ShapeSource
• RasterSource

Layers

• BackgroundLayer

• CircleLayer

• FillExtrusionLayer

• FillLayer

• LineLayer

• RasterLayer

• SymbolLayer

• HeatmapLayer

Email us: [email protected]

Contact for support

Vietmap API document here

Have a bug to report? Open an issue. If possible, include a full log and information that shows the issue. Have a feature request? Open an issue. Tell us what the feature should do and why you want the feature.