@kwicai/app-bridge

The Child SDK for the Bridge architecture. This package enables a micro-frontend (Child) to communicate securely with its container (Host) via postMessage.

It supports both Web (iFrames) and React Native (WebView) environments automatically.

Installation

npm install @kwicai/app-bridge

Usage (React)

The easiest way to use the SDK is via the provided React Context.

1. Wrap your App

Wrap your application root (or the part that needs bridge access) with BridgeProvider. This handles the initial handshake automatically.

import { BridgeProvider } from '@kwicai/app-bridge'

function App() {
  return (
    <BridgeProvider>
      <YourAppContent />
    </BridgeProvider>
  )
}

2. Use the Hook

Use useBridge() to access the bridge instance and state.

import { useBridge } from '@kwicai/app-bridge'
import { useEffect } from 'react'

function UserProfile() {
  const { bridge, isReady, authToken } = useBridge()

  // Example: Request navigation in the Host app
  const goHome = () => bridge.navigate('/')

  return (
    <div>
      <p>Connection: {isReady ? 'Active' : 'Connecting...'}</p>
      <button onClick={goHome}>Exit to Host Home</button>
    </div>
  )
}

Usage (Vanilla JS)

If you are not using React, or need to use the bridge outside of components:

import { bridge } from '@kwicai/app-bridge'

async function init() {
  try {
    const token = await bridge.handshake()
    console.log('Bridge ready, token:', token)
  } catch (err) {
    console.error('Handshake failed', err)
  }
}

init()

API Reference

Core

• handshake(): Promise - Initiates connection with Host. Returns auth token.
• getAuthToken(): string | null - Returns current token if set.

Navigation & UI

• navigate(path: string): Request Host to change its route (and effectively the URL bar).
• showModal(config): Open a modal in the Host app.

  bridge.showModal({ id: 'my-modal', title: 'Edit Profile', content: { ... } })

• setOverlay(active: boolean): Request Host to show/hide a full-screen overlay (e.g., for loading).
• setFullscreen(active: boolean): Request Host to enter/exit fullscreen mode for the child view.

Features

• requestMedia(config): Request user to pick media (Image/Video) from Host's native picker.

  const media = await bridge.requestMedia({ type: 'image' })
  if (media) console.log(media[0].url)

Events

Listen to events coming from the Host:

// Route changes in Host
bridge.onNavigation((path) => {
  console.log('Host navigated to:', path)
})

// Modal actions (e.g. user clicked "Confirm" in Host modal)
bridge.onModalAction((id, action, payload) => {
  if (id === 'my-modal' && action === 'CONFIRM') {
    saveData()
  }
})