/commerce-app-admin-ui

name: commerce-app-admin-ui
description: >
  Add or modify Adobe Commerce Admin UI extensions on the
  commerce/backend-ui/2 extension point: custom grid columns, mass actions,
  order view buttons, a custom Admin menu entry, and custom ACL resources. Use
  whenever the user wants to extend the Commerce Admin — add a column to the
  order, product, or customer grid, add a bulk/mass action to a grid, add a
  button to the order view page, add a custom menu item or page, or declare
  custom permissions the app checks itself — even when they don't name the
  extension point.
license: Apache-2.0
compatibility: >
  Requires Node.js 22+, aio CLI, @adobe/aio-commerce-lib-app, and
  @adobe/aio-commerce-sdk (for Admin UI runtime action handlers).
  View variants use @adobe/aio-commerce-lib-admin-ui/web (installed
  automatically by the web-src scaffold).
  Requires a base app initialized with commerce-app-init.
metadata:
  author: adobe

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

| Extension point | Entities | Variants | Server handler | Reference | | ------------------ | ----------------------------- | ------------- | -------------- | ------------------------------------------------------ | | Grid columns | order, product, customer | worker only | yes | [grid-columns](references/grid-columns.md) | | Mass actions | order, product, customer | view / worker | worker only | [mass-actions](references/mass-actions.md) | | Order view buttons | order only | view / worker | worker only | [order-view-buttons](references/order-view-buttons.md) | | Menu | single entry (`adminUi.menu`) | view (iframe) | no | [menu](references/menu.md) | | Custom ACL | list (`adminUi.acl`) | none | no | [custom-acl](references/custom-acl.md) |

`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](references/custom-acl.md)). 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:

| Field | Constraint | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `runtimeAction` | `<package>/<action>`; must resolve to a handler action you declare (Step 4) | | `confirm` | Optional `{ title?, message? }` — confirmation dialog before the action runs | | `notifications` | Optional `{ success?, error? }` — toast text Commerce shows on completion | | `sandboxPermissions` | Optional array (view/iframe entries); non-empty, no duplicates; each one of `allow-downloads`, `allow-modals`, `allow-popups` |

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 o