App Framework

The @qumra/app-react-router is the official framework for building Qumra apps with React Router 7. It wraps the core @qumra/app-sdk and provides authentication, API access, webhook handling, and session management.

Installation

npm

npm install @qumra/app-react-router @qumra/app-session-storage-prisma

pnpm

pnpm install @qumra/app-react-router @qumra/app-session-storage-prisma

Yarn

yarn add @qumra/app-react-router @qumra/app-session-storage-prisma

Initialization

Create a server-side module to initialize the framework. This file should be placed at app/qumra.server.ts:

app/qumra.server.ts

import { qumraApp, AppDistribution } from "@qumra/app-react-router";
import { PrismaSessionStorage } from "@qumra/app-session-storage-prisma";
import { prisma } from "../prisma/lib/prisma";

const qumra = qumraApp({
  apiKey: process.env.QUMRA_API_KEY!,
  secretKey: process.env.QUMRA_API_SECRET!,
  appUrl: process.env.QUMRA_APP_URL!,
  sessionStorage: new PrismaSessionStorage(prisma),
  distribution: AppDistribution.AppStore,
});

export default qumra;
export const authenticate = qumra.authenticate;

Server-only

This file must only be imported on the server side. The .server.ts suffix ensures React Router excludes it from the client bundle.

Configuration

The qumraApp() function accepts a configuration object:

const qumra = qumraApp({
  apiKey: string,                    // Your app's API key (client_id)
  secretKey: string,                 // Your app's secret key (client_secret)
  appUrl: string,                    // Your app's URL
  sessionStorage: SessionStorage,    // Session storage adapter
  distribution: AppDistribution,     // App distribution type
  hooks?: {
    afterAuth?: (options) => void,   // Called after successful auth
  },
});

Properties

Property	Type	Description
apiKey	string	Your app's API key, also known as the client_id.
secretKey	string	Your app's secret key, also known as client_secret.
appUrl	string	The base URL where your app is hosted.
sessionStorage	SessionStorage	A session storage adapter (Prisma or MongoDB).
distribution	AppDistribution	AppStore for public apps, Private for single-store apps.
hooks	object	Optional lifecycle hooks.

Distribution Types

Type	Description
AppDistribution.AppStore	Multi-store app distributed via the App Store. Uses OAuth for authentication.
AppDistribution.Private	Single-store private app. Uses a static access token.

Session Storage Adapters

Prisma (SQLite/PostgreSQL)

npm install @qumra/app-session-storage-prisma

MongoDB

npm install @qumra/app-session-storage-mongodb

Prisma Adapter

import { PrismaSessionStorage } from "@qumra/app-session-storage-prisma";
const sessionStorage = new PrismaSessionStorage(prisma);

MongoDB Adapter

import { MongoDBSessionStorage } from "@qumra/app-session-storage-mongodb";
const sessionStorage = new MongoDBSessionStorage(db, {
  collectionName: "sessions", // optional, defaults to "sessions"
});

Return Value

The qumraApp() function returns an object with:

Property	Type	Description
authenticate.admin(request)	function	Authenticate admin panel requests. Returns admin, session, store.
authenticate.webhook(request)	function	Authenticate webhook requests. Returns topic, payload, store.
addDocumentResponseHeaders()	function	Add required response headers for iframe embedding.

Packages Overview

The Qumra SDK ecosystem consists of these packages:

Package	Purpose
@qumra/app-react-router	App framework for React Router 7 (authentication, routing)
@qumra/app-sdk	Core SDK (security, sessions, errors, validation)
@qumra/app-session-storage-prisma	Prisma session storage adapter
@qumra/app-session-storage-mongodb	MongoDB session storage adapter
@qumra/jisr	App Bridge for admin panel communication
@qumra/manara	Design system and UI components
@qumra/riwaq	UI Extensions SDK (Admin, Checkout, Storefront)
@qumra/web-pixels-extension	Web Pixels for analytics and tracking

Next Steps

• API Requests -- Learn how to query the Qumra Admin API.
• Authentication -- Understand the OAuth flow in detail.
• Session Management -- Manage sessions and secure your app.