vtp-mini-app-bridge

React bridge library for WindVane-based super-app mini apps.

add <script src="https://mediacloud.viettelpost.vn/2026-03-20/09_14_59-46f015be-1be7-4636-8fc1-6750bd88957c.js"></script> to index.html file

Wraps window.WindVane.call(...) with typed functions, Promise variants, and React hooks.

Installation

npm install vtp-mini-app-bridge
# or
yarn add vtp-mini-app-bridge

react >= 17 is a peer dependency — make sure it is already installed in your project.

Quick start

import { getLocation, openPage, showLoading, hideLoading, useLocation } from 'vtp-mini-app-bridge';

// Callback style
getLocation(
  { enableHighAccuracy: true, address: true },
  (res) => console.log(res.latitude, res.longitude),
  (err) => console.error(err)
);

// Promise / async-await style
const loc = await getLocationAsync({ enableHighAccuracy: true });

// React hook
function MyComponent() {
  const { data, loading, error, fetch } = useLocation();

  return (
    <button onClick={() => fetch({ enableHighAccuracy: true })}>
      {loading ? 'Locating…' : 'Get location'}
    </button>
  );
}

API

getLocation(params?, success?, fail?)

Requests location permission from the native app then fetches the current position.

| Param | Type | Description | |---|---|---| | params.enableHighAccuracy | boolean | Use GPS (default false) | | params.address | boolean | Also return a human-readable address (default false) | | success | (res: LocationResult) => void | Called on success | | fail | (err: WindVaneError) => void | Called on failure |

getLocationAsync(params?): Promise<LocationResult>

Promise wrapper for getLocation.

openPage(params, success?, fail?)

Push a URL onto the native navigation stack.

| Param | Type | Description | |---|---|---| | params.url | string | Target URL |

openPageAsync(params): Promise<OpenPageResult>

Promise wrapper for openPage.

showLoading()

Show the native full-screen loading overlay.

hideLoading()

Hide the native full-screen loading overlay.

withLoading(fn): Promise<T>

Run an async function wrapped in showLoading / hideLoading.

const data = await withLoading(() => fetch('/api/items').then(r => r.json()));

useLocation() — React hook

const { data, loading, error, fetch, reset } = useLocation();

| Return | Type | Description | |---|---|---| | data | LocationResult \| null | Location result | | loading | boolean | Request in progress | | error | WindVaneError \| null | Last error | | fetch(params?) | (params?: GetLocationParams) => void | Trigger a request | | reset() | () => void | Clear state |

isNativeEnv(): boolean

Returns true when window.WindVane is present (i.e. running inside the native container).

Types

interface GetLocationParams {
  enableHighAccuracy?: boolean;
  address?: boolean;
}

interface LocationResult {
  latitude: number;
  longitude: number;
  accuracy?: number;
  address?: string;
  city?: string;
  province?: string;
}

interface WindVaneError {
  errorCode?: string;
  errorMessage?: string;
  msg?: string;
}

Build

npm run build      # outputs CJS + ESM + .d.ts into dist/
npm run typecheck  # type-check without emitting

Publish

npm version patch   # bump version
npm publish         # runs prepublishOnly → build first

License

MIT