@qumra/jisr

App Bridge for Qumra embedded apps — React hooks for communicating with the Qumra Admin.

جسر (Jisr) = Bridge in Arabic

@qumra/jisr provides a set of React hooks and utilities for seamless communication between embedded applications (running in iframes) and the Qumra Admin interface via postMessage. Perfect for building extensible admin apps that need to interact with the parent Qumra environment.

Features

• 🌉 iframe ↔ Admin Communication — Transparent two-way messaging
• 🎣 Custom React Hooks — useNavigate, useToast, useModal, useSaveBar, and more
• 📘 TypeScript Support — Fully typed exports for better DX
• 🔐 Authenticated Requests — Built-in hook for fetch with auth headers
• ⚡ Simple Setup — Wrap your app with QumraAppBridgeProvider

Installation

npm install @qumra/jisr react react-dom

Peer Dependencies

• react >= 18
• react-dom >= 18

Quick Start

1. Wrap Your App with the Provider

import { QumraAppBridgeProvider } from '@qumra/jisr';

function App() {
  return (
    <QumraAppBridgeProvider>
      <YourAppComponent />
    </QumraAppBridgeProvider>
  );
}

export default App;

2. Use Hooks in Your Components

import { useNavigate, useToast } from '@qumra/jisr';

function MyComponent() {
  const { navigate } = useNavigate();
  const { showToast } = useToast();

  const handleClick = () => {
    showToast('Hello from embedded app!', 'success');
    navigate('/dashboard');
  };

  return <button onClick={handleClick}>Navigate & Toast</button>;
}

Hooks Reference

useAppBridge

Access the core AppBridge instance directly for advanced use cases.

import { useAppBridge } from '@qumra/jisr';

function AdvancedComponent() {
  const bridge = useAppBridge();

  const handleCustomAction = () => {
    bridge.dispatch({ type: 'CUSTOM_ACTION', payload: { /* ... */ } });
  };

  return <button onClick={handleCustomAction}>Send Custom Action</button>;
}

useNavigate

Navigate within the Qumra Admin interface.

import { useNavigate } from '@qumra/jisr';

function NavigationComponent() {
  const { navigate } = useNavigate();

  return (
    <>
      <button onClick={() => navigate('/dashboard')}>Dashboard</button>
      <button onClick={() => navigate('/settings')}>Settings</button>
    </>
  );
}

useToast

Display toast notifications in the Qumra Admin UI.

import { useToast } from '@qumra/jisr';

function ToastComponent() {
  const { showToast, hideToast } = useToast();

  const handleSuccess = () => {
    showToast('Operation successful!', 'success');
  };

  const handleError = () => {
    showToast('Something went wrong.', 'error');
  };

  return (
    <>
      <button onClick={handleSuccess}>Show Success</button>
      <button onClick={handleError}>Show Error</button>
    </>
  );
}

useModal

Open and manage modal dialogs.

import { useModal } from '@qumra/jisr';

function ModalComponent() {
  const { openModal, closeModal } = useModal();

  const handleOpenModal = () => {
    openModal({
      title: 'Confirm Action',
      content: 'Are you sure you want to proceed?',
    });
  };

  return (
    <>
      <button onClick={handleOpenModal}>Open Modal</button>
      <button onClick={closeModal}>Close Modal</button>
    </>
  );
}

useSaveBar

Show/hide the save bar for form changes.

import { useSaveBar } from '@qumra/jisr';
import { useState } from 'react';

function FormComponent() {
  const { showSaveBar, hideSaveBar } = useSaveBar();
  const [isDirty, setIsDirty] = useState(false);

  const handleFieldChange = (e) => {
    setIsDirty(true);
    showSaveBar();
  };

  const handleSave = async () => {
    // Save logic
    hideSaveBar();
    setIsDirty(false);
  };

  return (
    <form>
      <input onChange={handleFieldChange} />
      {isDirty && <button onClick={handleSave}>Save</button>}
    </form>
  );
}

useTitleBar

Update the page title in the Qumra Admin.

import { useTitleBar } from '@qumra/jisr';
import { useEffect } from 'react';

function PageComponent() {
  const { updateTitleBar } = useTitleBar();

  useEffect(() => {
    updateTitleBar('My Page Title');
  }, [updateTitleBar]);

  return <div>Page content</div>;
}

useFullscreen

Enter and exit fullscreen mode.

import { useFullscreen } from '@qumra/jisr';

function FullscreenComponent() {
  const { enterFullscreen, exitFullscreen } = useFullscreen();

  return (
    <>
      <button onClick={enterFullscreen}>Go Fullscreen</button>
      <button onClick={exitFullscreen}>Exit Fullscreen</button>
    </>
  );
}

useAuthenticatedFetch

Make authenticated requests to the Qumra API with automatic auth headers.

import { useAuthenticatedFetch } from '@qumra/jisr';
import { useEffect, useState } from 'react';

function DataComponent() {
  const { fetch: authenticatedFetch } = useAuthenticatedFetch();
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    const loadData = async () => {
      setLoading(true);
      try {
        const response = await authenticatedFetch('/api/data');
        const json = await response.json();
        setData(json);
      } catch (error) {
        console.error('Fetch failed:', error);
      } finally {
        setLoading(false);
      }
    };

    loadData();
  }, [authenticatedFetch]);

  if (loading) return <div>Loading...</div>;
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

Action Creators

For advanced usage, dispatch actions directly via the AppBridge:

import {
  navigate,
  showToast,
  hideToast,
  openModal,
  closeModal,
  showSaveBar,
  hideSaveBar,
  updateTitleBar,
  startLoading,
  stopLoading,
  enterFullscreen,
  exitFullscreen,
} from '@qumra/jisr';

const bridge = useAppBridge();

// Navigate
bridge.dispatch(navigate('/path'));

// Toast notifications
bridge.dispatch(showToast('Message', 'success'));
bridge.dispatch(hideToast());

// Modals
bridge.dispatch(openModal({ title: 'Title', content: 'Content' }));
bridge.dispatch(closeModal());

// Save bar
bridge.dispatch(showSaveBar());
bridge.dispatch(hideSaveBar());

// Title bar
bridge.dispatch(updateTitleBar('New Title'));

// Loading state
bridge.dispatch(startLoading());
bridge.dispatch(stopLoading());

// Fullscreen
bridge.dispatch(enterFullscreen());
bridge.dispatch(exitFullscreen());

TypeScript

All types are exported from the main package:

import {
  AppBridge,
  AppBridgeConfig,
  AppBridgeAction,
  AppBridgeState,
  AppContext,
  ActionType,
  UseToastResult,
  UseModalResult,
  UseNavigateResult,
  UseSaveBarResult,
  UseTitleBarResult,
  UseFullscreenResult,
  UseAuthenticatedFetchResult,
} from '@qumra/jisr';

Example Type Usage

import { AppBridgeAction, ActionType } from '@qumra/jisr';

const myAction: AppBridgeAction = {
  type: ActionType.NAVIGATE,
  payload: { path: '/dashboard' },
};

Qumra Ecosystem

| Package | Description | |---------|-------------| | @qumra/app-sdk | Core SDK — sessions, security, errors | | @qumra/app-react-router | React Router 7 integration | | @qumra/app-session-storage-prisma | Prisma session storage | | @qumra/app-session-storage-mongodb | MongoDB session storage | | @qumra/jisr | App Bridge for iframe communication | | @qumra/manara | Design system & components | | @qumra/riwaq | UI Extensions SDK |

License

ISC © Qumra

Documentation

https://docs.qumra.cloud