UI Extensions (@qumra/riwaq)

UI Extensions allow your app to inject custom UI into the Qumra Admin panel, Checkout, and Storefront. Instead of building an entire embedded app, you can add targeted blocks to specific locations.

Installation

npm

npm install @qumra/riwaq

pnpm

pnpm install @qumra/riwaq

Yarn

yarn add @qumra/riwaq

Quick Example

extensions/my-extension/src/index.tsx

import { reactExtension, ExtensionTarget, useApi } from "@qumra/riwaq";
import { AdminBlock, TextBlock } from "@qumra/riwaq";

export default reactExtension(
  ExtensionTarget.AdminProductDetails,
  (api) => (
    <AdminBlock title="Product Insights">
      <TextBlock>Store: {api.store.domain}</TextBlock>
      <TextBlock>Product ID: {api.resource?.id}</TextBlock>
    </AdminBlock>
  )
);

How Extensions Work

1. You create an extension using the CLI: qumra app extension
2. The extension targets a specific location (Admin, Checkout, or Storefront)
3. During development, the CLI watches and auto-syncs your extension code
4. The extension renders as a React component in the target location

Creating an Extension

qumra app extension

The CLI prompts you for:

• Extension name -- URL-friendly identifier
• Extension type -- Web Pixel or Function

This creates a directory under extensions/ with the following structure:

extensions/my-extension/
├── src/
│   └── index.ts          # Extension entry point
├── dist/
│   └── index.js          # Built output (auto-generated)
├── manifest.json          # Extension metadata
└── package.json

manifest.json

extensions/my-extension/manifest.json

{
  "_id": "extension_id_from_backend",
  "name": "my-extension",
  "type": "web_pixel"
}

Extension Targets

Extensions can render in 18 different locations across three areas:

Admin Targets

Target	Description
AdminBlock	Generic block in the admin panel.
AdminAction	Action button/panel in the admin.
AdminNavigation	Custom navigation item.
AdminProductDetails	Block on the product details page.
AdminOrderDetails	Block on the order details page.
AdminCustomerDetails	Block on the customer details page.
AdminDashboard	Block on the admin dashboard.

Checkout Targets

Target	Description
CheckoutBlock	Generic block in checkout.
CheckoutCartLineItem	After cart line items.
CheckoutShippingOptions	After shipping options.
CheckoutPaymentMethod	After payment methods.
CheckoutHeader	Checkout header area.
CheckoutFooter	Checkout footer area.

Storefront Targets

Target	Description
StorefrontBlock	Generic storefront block.
StorefrontProductBlock	Block on the product page.
StorefrontCollectionBlock	Block on the collection page.

Next Steps

• Hooks & API -- Access store context, settings, storage, and resources.
• Components -- Built-in components for extension UI.
• Settings -- Define configurable settings for your extension.