Commerce App Admin UI

Configure Commerce App Admin UI

Adds or modifies the adminUi block in an existing app.commerce.config.ts. The Admin UI extension point (commerce/backend-ui/2) lets a Commerce app extend the Commerce Admin with custom grid columns, mass actions, order view buttons, a menu entry, and custom ACL resources. Other extensibility domains (webhooks, events, business config) are added separately via their own skills.

Prerequisites

• Verify the app is scaffolded and initialized, not merely that the config exists. Require both:
  • app.commerce.config.ts present in the project root, and
  • the project initialized — signalled by the generated src/commerce-extensibility-1/ directory and installed node_modules (the @adobe/aio-commerce-lib-app dependency).
• If app.commerce.config.ts is missing, stop and invoke commerce-app-init first (it writes the config, then runs init).
• If the config is present but the project is not initialized (no src/commerce-extensibility-1/ or node_modules), run npx @adobe/aio-commerce-lib-app init before continuing. Init is idempotent — it finds the existing config, skips the interactive prompts, installs dependencies, and generates the project files.
• Actions can be authored in TypeScript only once the project has the TypeScript build setup (webpack-config.cjs + root tsconfig.json) that init scaffolds for a TypeScript Commerce config — see commerce-app-init. Otherwise, author actions in JavaScript.

Extension points at a glance

view renders an iframe into the app's web UI (web-src) at the entry's path; worker invokes a runtime action server-side. Custom ACL resources have no variant and no handler: they are standalone permissions Commerce renders in the User Roles tree, and the app checks them itself (see custom-acl). Grid columns are always worker; the menu is always an iframe.

Step 1 — Understand intent

For each thing the user wants to add, gather:

• Which extension point — grid columns, mass actions, order view buttons, menu, or custom ACL resources
• Which entity — order, product, or customer (grid columns and mass actions; view buttons are order-only; menu and custom ACL resources have no entity)
• For mass actions and view buttons, the variant — worker (runtime action) or view (iframe into web-src)
• The fields for that extension point (column definitions, button labels, menu parent, etc.) — see the reference file in the table above for the full field set

Step 2 — Declare in app.commerce.config.ts

Add (or merge into) the top-level adminUi block, preserving all other domains. If adminUi already exists, merge into it rather than replacing — keep existing entities, the menu, and existing array entries.

These fields are shared across the extension points:

Minimal example covering each feature (use only the parts you need):

import { MENU_SALES } from "@adobe/aio-commerce-sdk/admin-ui/menu";

// inside defineConfig({ ... }):
adminUi: {
  order: {
    // Custom column on the order grid (worker only)
    gridColumns: {
      label: "Fulfillment data",
      description: "Fulfillment status from the warehouse system.",
      runtimeAction: "my-app/order-grid", // <package>/<action> — declare in Step 4
      columns: [
        { id: "fulfillment_status", label: "Fulfillment", type: "string", align: "left" },
      ],
    },
    // Bulk action on selected orders (worker variant shown)
    massActions: [
      { type: "worker", id: "archive-orders", label: "Archive",
        runtimeAction: "my-app/archive-orders", selectionLimit: 500 },
    ],
    // Button on the order view page (worker variant shown)
    viewButtons: [
      { type: "worker", id: "sync-inventory", label: "Sync inventory",
        runtimeAction: "my-app/sync-inventory" },
    ],
  },
  // Custom Admin menu entry (iframe into the app)
  menu: {
    id: "my_app_dashboard", // letters, digits, / : _ only
    label: "My Dashboard",
    description: "Custom dashboard for my app.",
    parentMenu: MENU_SALES,
  },
  // Custom ACL resources — standalone permissions the app checks itself (no handler)
  acl: [
    { id: "reports", label: "Reports", children: [
      { id: "export", label: "Export" },
    ]},
    { id: "approve_refunds", label: "Approve Refunds" },
  ],
}

For the view variants (iframe) and the complete field set and constraints of each extension point, read the matching reference file under References before writing.

Step 3 — Register the extension point

Run init so that commerce/backend-ui/2 is added to app.config.yaml and install.yaml, and the src/commerce-backend-ui-2/ extension folder is generated. This is idempotent — safe to run even if the extension is already registered.

npx @adobe/aio-commerce-lib-app init

The build derives the extension's ext.config.yaml from your adminUi config: each worker runtimeAction becomes a workerProcess operation, and when you declare a menu or any view-type entry, a view operation plus an explicit web: web-src key are written. Those hooks, operations, and web sections are managed by the library — do not hand-edit them.

When a view operation is present, init/generate also scaffolds the web frontend automatically (skipped if web-src/index.html already exists). It generates src/commerce-backend-ui-2/web-src/ — index.html, src/app.jsx, src/pages/main-page.jsx, src/components/welcome.jsx (.tsx plus an independent tsconfig.json when the app config is TypeScript) — adds the #web/* import alias to package.json, and declares and installs pinned versions of react, react-dom, @react-spectrum/s2, and @adobe/aio-commerce-lib-admin-ui (React and Spectrum S2 are optional peer dependencies of the admin-ui library), plus some devDependencies for proper TypeScript and Babel support/config. A separate required-file phase runs on every generation to ensure a set of web source support files is present without replacing existing versions. The current set includes web-src/.babelrc, which selects React's automatic JSX transform for each environment so development builds retain JSX diagnostics while production builds do not emit jsxDEV calls. If BABEL_ENV is set, keep it synchronized with NODE_ENV, because Babel gives BABEL_ENV precedence when selecting the configuration environment. TypeScript scaffolds also add typecheck:web-src to the project’s composed typecheck script. Do not hand-pick different versions of these dependencies; the scaffold fails if incompatible versions are already installed.

If the scaffold is skipped because web-src already exists, check its package.json for classic React Spectrum (@adobe/react-spectrum or @react-spectrum/<component> without s2) instead of @react-spectrum/s2. The two are compatible, but S2 is the version Adobe recommends moving to and the one this scaffold targets — suggest upgrading. This skill only configures the Admin UI extension, it doesn't drive the upgrade itself, so point the user to the commerce-app-migrate skill for the actual migration:

npx skills add adobe/skills --skill commerce-app-migrate

Do not install it or perform the upgrade yourself unless the user asks.

Step 4 — Implement the handlers

What you implement depends on the variant. Examples below are in TypeScript; if the project uses JavaScript, omit type imports and annotations.

Worker variants (grid columns, worker mass actions, worker view buttons)

Each worker runtimeAction needs an action you declare and implement, inside the Admin UI extension folder src/commerce-backend-ui-2/.

1. Put the handler source under src/commerce-backend-ui-2/actions/.
2. Declare it in src/commerce-backend-ui-2/ext.config.yaml under your own package in runtimeManifest (any package name). The build manages hooks and operations in this file but preserves the packages you add under runtimeManifest, so your action survives rebuilds:

# src/commerce-backend-ui-2/ext.config.yaml
runtimeManifest:
  packages:
    my-app: # must match the <package> in runtimeAction
      actions:
        order-grid:
          function: actions/order-grid/index.js # relative to src/commerce-backend-ui-2/
          web: "yes"
          runtime: nodejs:24
          annotations:
            require-adobe-auth: true # Commerce calls the action with an IMS token — validate it
            final: true

The <package>/<action> in runtimeAction maps directly: my-app/order-grid → package my-app, action order-grid. Commerce invokes these worker actions with an Adobe IMS token, so they need require-adobe-auth: true (and final: true to lock the bound inputs).

Implement the handler with the wire-contract builders from the @adobe/aio-commerce-sdk/admin-ui/* entrypoints. The builders differ per extension point — the reference file gives the exact request shape and response builders. Grid columns example:

// src/commerce-backend-ui-2/actions/order-grid/index.ts
import {
  parseGridRequest,
  okGridResponse,
  errorGridResponse,
} from "@adobe/aio-commerce-sdk/admin-ui/grid-columns";
import type { RuntimeActionParams } from "@adobe/aio-commerce-sdk/core/params";

export async function main(params: RuntimeActionParams) {
  const { gridType, ids } = parseGridRequest(params);
  try {
    const rows = await fetchRows(gridType, ids);
    // row keys must match the column ids declared in config
    return okGridResponse(rows, { fulfillment_status: "unknown" });
  } catch (error) {
    return errorGridResponse(
      500,
      error instanceof Error ? error.message : String(error),
    );
  }
}