@qumra/riwaq

UI Extensions SDK for Qumra — build custom UI for Admin, Checkout, and Storefront.

رواق (Riwaq) = Gallery/Arcade in Arabic

A powerful React SDK for building Qumra UI extensions. Render custom components across the Admin panel, Checkout flow, and Storefront with a unified API.

Installation

npm install @qumra/riwaq

Peer Dependencies

• react >= 18.0.0
• react-dom >= 18.0.0

Quick Start

import { reactExtension, AdminBlock } from '@qumra/riwaq';

const MyAdminExtension = () => (
  <AdminBlock>
    <h2>Welcome to My Extension</h2>
    <p>Custom UI for Qumra Admin</p>
  </AdminBlock>
);

export default reactExtension('admin.dashboard', MyAdminExtension);

Extension Targets

Deploy your extensions to 18 different locations across Qumra:

| Category | Target | Description | |----------|--------|-------------| | Admin | AdminBlock | Dashboard blocks and custom content areas | | | AdminAction | Action buttons and quick actions | | | AdminNavigation | Navigation extensions and menu items | | | AdminProductDetails | Product detail page extensions | | | AdminOrderDetails | Order detail page extensions | | | AdminCustomerDetails | Customer profile extensions | | | AdminDashboard | Dashboard widget areas | | Checkout | CheckoutBlock | General checkout section blocks | | | CheckoutCartLineItem | Cart line item rendering | | | CheckoutShippingOptions | Shipping method selection | | | CheckoutPaymentMethod | Payment method selection | | | CheckoutHeader | Checkout header area | | | CheckoutFooter | Checkout footer area | | Storefront | StorefrontBlock | General storefront content blocks | | | StorefrontProductBlock | Product page extensions | | | StorefrontCollectionBlock | Collection page extensions |

Access the ExtensionTarget enum for type-safe target selection:

import { ExtensionTarget } from '@qumra/riwaq';

const target = ExtensionTarget.AdminDashboard;

Hooks Reference

useApi

Access extension API methods and data:

import { useApi } from '@qumra/riwaq';

const MyComponent = () => {
  const api = useApi();

  return <div>{api.store.name}</div>;
};

useSettings

Access extension configuration settings:

import { useSettings } from '@qumra/riwaq';

const MyComponent = () => {
  const settings = useSettings();

  return <div>Color: {settings.primaryColor}</div>;
};

useSessionToken

Get authentication tokens for API calls:

import { useSessionToken } from '@qumra/riwaq';

const MyComponent = () => {
  const token = useSessionToken();

  const fetchData = async () => {
    const response = await fetch('/api/data', {
      headers: { Authorization: `Bearer ${token}` }
    });
  };

  return <button onClick={fetchData}>Load Data</button>;
};

useExtensionLanguage

Detect and respond to language/locale settings:

import { useExtensionLanguage } from '@qumra/riwaq';

const MyComponent = () => {
  const language = useExtensionLanguage();

  return <div>Current language: {language}</div>;
};

useStorage

Persist data in extension storage:

import { useStorage } from '@qumra/riwaq';

const MyComponent = () => {
  const storage = useStorage();

  const saveData = () => {
    storage.setItem('myKey', JSON.stringify({ data: 'value' }));
  };

  const loadData = () => {
    const data = storage.getItem('myKey');
    console.log(JSON.parse(data));
  };

  return (
    <div>
      <button onClick={saveData}>Save</button>
      <button onClick={loadData}>Load</button>
    </div>
  );
};

useResource

Load and manage resources (products, orders, etc.):

import { useResource } from '@qumra/riwaq';

const MyComponent = () => {
  const { resource, loading, error } = useResource('product', { id: '123' });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return <div>{resource.title}</div>;
};

Components

AdminBlock

Container for admin panel content:

import { AdminBlock } from '@qumra/riwaq';

<AdminBlock>
  <h2>Admin Content</h2>
  <p>Your custom admin UI here</p>
</AdminBlock>

AdminAction

Action button for admin operations:

import { AdminAction } from '@qumra/riwaq';

<AdminAction onClick={() => console.log('Action triggered')}>
  Execute Action
</AdminAction>

BlockSpacer

Add spacing between blocks:

import { BlockSpacer } from '@qumra/riwaq';

<div>
  <AdminBlock>Content 1</AdminBlock>
  <BlockSpacer size="lg" />
  <AdminBlock>Content 2</AdminBlock>
</div>

InlineLayout

Horizontal layout for inline content:

import { InlineLayout } from '@qumra/riwaq';

<InlineLayout>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</InlineLayout>

TextBlock

Formatted text content:

import { TextBlock } from '@qumra/riwaq';

<TextBlock variant="body">
  This is body text with proper styling
</TextBlock>

Heading

Semantic heading component:

import { Heading } from '@qumra/riwaq';

<Heading level={2}>Section Title</Heading>

Divider

Visual separator:

import { Divider } from '@qumra/riwaq';

<div>
  <TextBlock>Section 1</TextBlock>
  <Divider />
  <TextBlock>Section 2</TextBlock>
</div>

Extension API

The ExtensionApi provides access to:

• store: Store information and configuration
• user: Current user details and permissions
• session: Session management and authentication
• resources: Access to products, orders, customers, and other entities
• actions: Trigger actions within Qumra
• storage: Extension-specific data persistence

import { useApi } from '@qumra/riwaq';

const MyComponent = () => {
  const api = useApi();

  // Access different API sections
  const storeName = api.store.name;
  const userId = api.user.id;
  const product = api.resources.getProduct(id);

  return <div>{storeName}</div>;
};

Extension Configuration

Define settings for your extension:

import { reactExtension, ExtensionProvider } from '@qumra/riwaq';

const settingsDefinition = {
  fields: [
    {
      key: 'primaryColor',
      label: 'Primary Color',
      type: 'color',
      required: true
    },
    {
      key: 'enableNotifications',
      label: 'Enable Notifications',
      type: 'boolean',
      default: true
    }
  ]
};

const MyExtension = () => {
  return (
    <ExtensionProvider config={settingsDefinition}>
      {/* Your component */}
    </ExtensionProvider>
  );
};

export default reactExtension('admin.dashboard', MyExtension);

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