Extension Platform Overview

Extensions let apps inject custom UI directly into the SeloraX merchant dashboard. Instead of only running inside a full-page iframe, your app can render blocks, action buttons, widgets, and navigation links across key surfaces — orders, products, customers, dashboard, POS, checkout, and more.

There are two rendering modes:

• JSON mode — You define a declarative UI tree as JSON. The dashboard interprets and renders it natively using built-in components. No iframe, no JavaScript, no hosting required.
• Sandbox mode — Your JavaScript runs inside an isolated iframe. You get full control over rendering, can use the @selorax/ui SDK to communicate with the dashboard, and can make API calls, open resource pickers, and more.

Both modes are deployed and managed through the same system. You can mix JSON and sandbox extensions within a single app.

Extension Targets

Every extension declares a target — the exact location where it appears. There are 34 targets: 25 for the admin dashboard and 9 for the customer-facing storefront.

Orders

Products

Customers

Dashboard

Navigation and Settings

POS

Checkout

Fulfillment

Storefront (Customer-Facing)

These targets render on the customer-facing store, not the admin dashboard. They use the Storefront Extensions system with a dedicated renderer, public API endpoint, and cart integration.

Extension Lifecycle

1.  Define extensions in selorax.config.json
         |
2.  Build sandbox bundles (esbuild)
         |
3.  Deploy via CLI: selorax deploy
         |
4.  Platform stores extension definitions in app metadata
         |
5.  Auto-register for all active installations
         |
6.  Dashboard fetches extensions by target when page loads
         |
7.  JSON extensions → rendered natively
    Sandbox extensions → loaded in isolated iframe
         |
8.  Merchant can enable/disable, reorder, and configure
    via Settings > Apps > Extension Config

Step by Step

1. Define — You declare extensions in selorax.config.json. Each extension specifies an extension_id, target, mode, and either a ui tree (JSON mode) or an entry file (sandbox mode).

2. Build — For sandbox extensions, the CLI bundles your JavaScript with esbuild into a single IIFE file. JSON extensions require no build step.

3. Deploy — selorax deploy sends all extensions to the platform in a single atomic operation. The platform validates every extension (component types, action types, tree depth) before committing. If any extension fails validation, the entire deploy is rejected.

4. Store — Extensions are stored in the app's metadata.extensions array. Each deploy creates a version snapshot (up to 25 versions retained), enabling rollback.

5. Register — The platform automatically enables extensions for all stores that have your app installed. New installations also inherit the current extension set.

6. Render — When a merchant views an order detail page, for example, the dashboard fetches all extensions targeting order.detail.block and order.detail.action for that store, then renders them in sort order.

7. Configure — Merchants can toggle extensions on/off, reorder them, and fill in settings fields that you define in the extension's settings_schema.

Architecture

                                SeloraX Dashboard
                          +---------------------------+
                          |                           |
                          |   Order Detail Page       |
                          |   +---------+---------+   |
                          |   | Native  | Sandbox |   |
                          |   | JSON    | iframe  |   |
                          |   | render  | (app JS)|   |
                          |   +---------+---------+   |
                          |        |          |        |
                          +--------|----------|--------+
                                   |          |
        GET /extensions/page       |   postMessage protocol
        (fetch JSON UI trees)      |   (selorax:api_request,
                                   |    selorax:navigate, etc.)
                                   |          |
                          +---------------------------+
                          |     SeloraX API           |
                          |     (Express.js)          |
                          |                           |
                          |  - Extension definitions  |
                          |  - API proxy (scoped)     |
                          |  - Sandbox token gen      |
                          |  - Action proxy           |
                          +---------------------------+
                                   |
                          +---------------------------+
                          |    App Backend (yours)    |
                          |    Receives call_backend  |
                          |    actions with signed    |
                          |    session JWT            |
                          +---------------------------+

JSON Mode Flow

The dashboard fetches extension definitions from the API. Each JSON extension includes a ui tree — a nested structure of { type, props, children } nodes. The dashboard's ExtensionRenderer maps each node to a real React component and renders it inline. No iframe is involved.

Actions within the JSON tree (button clicks, link taps) are handled by the dashboard according to their type: navigate, open_link, set_state, call_backend, open_modal, open_drawer, close_modal, close_drawer, or selorax_api.

Sandbox Mode Flow

The dashboard creates an iframe and loads the extension's sandbox_url. A signed JWT (5-minute TTL) authenticates the iframe session. The @selorax/ui SDK handles the postMessage protocol automatically — your code calls selorax.api.get('/products') and the SDK routes the request through the dashboard's API proxy, which enforces scopes and rate limits.

Registering Extensions

Extensions can be registered through two paths:

CLI Deploy (Recommended)

npm install -g @selorax/cli
selorax auth:login --client-id sx_app_... --client-secret sx_secret_... --store-id 22
selorax deploy

The CLI reads selorax.config.json, builds sandbox bundles, uploads them, and sends the full extension set to POST /api/apps/extensions/app/deploy. This is an atomic operation — all extensions are replaced at once.

API (Programmatic)

Your app can manage extensions directly via the REST API:

# Create a single extension
curl -X POST "https://api.selorax.io/api/apps/extensions/app" \
  -H "X-Client-Id: sx_app_..." \
  -H "X-Client-Secret: sx_secret_..." \
  -H "X-Store-Id: 22" \
  -H "Content-Type: application/json" \
  -d '{
    "extension_id": "order-fraud-check",
    "target": "order.detail.block",
    "title": "Fraud Risk Score",
    "mode": "json",
    "ui": {
      "type": "Card",
      "props": { "title": "Fraud Check" },
      "children": [
        { "type": "Text", "props": { "content": "Risk score: Low" } }
      ]
    }
  }'

Extension API Reference

All extension endpoints live under /api/apps/extensions. App-facing endpoints use client credentials (X-Client-Id + X-Client-Secret + X-Store-Id). Store-facing endpoints use Bearer token authentication.

App Management Endpoints

Dashboard Endpoints (used internally)

Version Management

Every deploy creates a version snapshot. You can list versions and rollback:

selorax versions       # List version history
selorax rollback -v 3  # Rollback to version 3

The platform retains the last 25 versions. Rollback re-registers the restored extension set for all active installations.

Packages

What's Next

• JSON Extensions — Declarative UI trees, all 74 components, actions, state, and template expressions
• Sandbox Extensions — JavaScript in isolated iframes, the selorax global, App Bridge API
• CLI Reference — All CLI commands, configuration file format, dev mode
• Metafields — Attach custom data to orders, products, customers, and stores
• Merchant Settings — Let merchants configure your extensions