Skip to main content
skill CX Codex

commerce-app-business-config — Claude Code skill for Adobe Commerce config

commerce-app-business-config adds typed business configuration fields to an Adobe Commerce app through businessConfig.schema. Merchants set them in Commerce Admin, the app reads values at runtime.

Apache-2.0 334 installs ★ 335 updated 2026-11-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add adobe/skills --skill commerce-app-business-config -a claude-code
Open on GitHub

What commerce-app-business-config does

The skill edits the businessConfig.schema array in an existing app.commerce.config.ts. Each entry defines one merchant-configurable setting rendered as a UI field in Commerce Admin: text, password, email, url, tel, boolean toggle, or a single/multiple select list.

Before writing anything, it verifies the project is actually initialized. It looks for app.commerce.config.ts plus a generated src/commerce-extensibility-1/ directory and installed @adobe/aio-commerce-lib-app. Missing config stops the skill and triggers commerce-app-init. Config present but no init files means running npx @adobe/aio-commerce-lib-app init first.

Validation happens per type before any write. Single-select list defaults must match an option value. Password defaults stay "" — a non-empty value gets rejected so secrets never land in config. An empty businessConfig.schema fails the build, so at least one field is required.

After that the skill registers the commerce/configuration/1 extension point in app.config.yaml and install.yaml, installs @adobe/aio-commerce-lib-config, and runs aio app build to confirm the config. Needs Node.js 22+, aio CLI, and @adobe/aio-commerce-lib-app.

What it helps with

  • add a merchant-configurable field to Commerce Admin
  • set the field type: text, password, email, url, tel, boolean or list
  • validate default values before build
  • register the commerce/configuration/1 extension point
  • verify config with aio app build

Example prompts for the agent

  • Add a password field for the API key to the app business config
  • Create a single-select region list with eu as default and EU/US options
  • Add a boolean debug_mode flag that defaults to false

How to install commerce-app-business-config

1Skills CLI (Vercel)

npx skills add adobe/skills --skill commerce-app-business-config -a claude-code

2Manually: put the files in place

~/.claude/skills/commerce-app-business-config/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/commerce-app-business-config/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about commerce-app-business-config

How do I install commerce-app-business-config in Claude Code?

Run npx skills add adobe/skills --skill commerce-app-business-config -a claude-code, then the skill lands in ~/.claude/skills/commerce-app-business-config/SKILL.md.

What does commerce-app-business-config do?

It adds and modifies fields in businessConfig.schema inside app.commerce.config.ts. Each field becomes a Commerce Admin setting, read by the app through @adobe/aio-commerce-lib-config.

What does the skill require to run?

Node.js 22+, aio CLI, and an initialized app with @adobe/aio-commerce-lib-app. If app.commerce.config.ts is missing, it invokes commerce-app-init first.

Source text

SKILL.md · Apache-2.0
---
name: commerce-app-business-config
description: >
  Manage custom business configuration in an Adobe Commerce app. Use when the
  user wants to add, modify, or remove merchant-configurable settings (config
  fields, admin config, store configuration) exposed through Commerce Admin.
  Creates typed config fields (text, password, email, url, tel, boolean, list)
  in businessConfig.schema. Requires a base app initialized with commerce-app-init.
license: Apache-2.0
compatibility: >
  Requires Node.js 22+, aio CLI, and @adobe/aio-commerce-lib-app installed.
  Requires a base app initialized with commerce-app-init.
metadata:
  author: adobe
---

# Configure Commerce App Business Config

Adds or modifies the `businessConfig.schema` array in an existing `app.commerce.config.ts`.
Each entry in the schema defines one merchant-configurable setting that Commerce Admin will render as a UI field.
Other extensibility domains (webhooks, events) 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.

## Step 1 — Understand intent

For each setting the user wants to expose, gather:

- **Name** — machine identifier for the field (used as the config key read by the app at runtime)
- **Type** — one of: `list`, `text`, `password`, `email`, `url`, `tel`, `boolean`
- **Label** (optional) — human-readable label shown in Admin
- **Description** (optional) — help text shown alongside the field in Admin
- **Default value** (optional, type-dependent — see constraints in Step 2)
- For `list` fields additionally: **`selectionMode`** (`"single"` or `"multiple"`) and **`options`** (each with a `label` and `value` string)

## Step 2 — Derive config values

Apply the following per-type validation rules before writing. Surface any issues to the user before proceeding.

| Field                   | Constraint                                                                                      |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| `name`                  | Required, non-empty string                                                                      |
| `type`                  | Required; one of `list`, `text`, `password`, `email`, `url`, `tel`, `boolean`                   |
| `label`                 | Optional string                                                                                 |
| `description`           | Optional string                                                                                 |
| `list.selectionMode`    | Required for list fields: `"single"` or `"multiple"`                                            |
| `list.options`          | Required for list fields; each option needs both `label` and `value` strings                    |
| `list/single` default   | Required; must match one of the option `value` strings (non-empty)                              |
| `list/multiple` default | Optional array of strings (defaults to `[]`); each element must match an option value           |
| `text` default          | Optional string (defaults to `""`)                                                              |
| `password` default      | Must be `""` — any non-empty default is rejected to prevent secrets in config                   |
| `email` default         | Optional; `""` or a fully valid email address                                                   |
| `url` default           | Optional; `""` or a fully valid absolute URL                                                    |
| `tel` default           | Optional; `""` or matches `/^\+?[0-9\s\-()]+$/` (digits, spaces, hyphens, parens, optional `+`) |
| `boolean` default       | Optional boolean (defaults to `false`)                                                          |

`businessConfig.schema` must contain at least one field — an empty array is rejected at build time.

## Step 3 — Update `app.commerce.config.ts`

Add (or merge into) the top-level `businessConfig.schema` array, preserving all other domains. If the config already has a `businessConfig` key, append to `businessConfig.schema` rather than replacing it.

Minimal examples:

```ts
businessConfig: {
  schema: [
    // Password (masked input — API keys, secrets)
    { name: "api_key", type: "password", label: "API Key", default: "" },

    // Single-select list
    {
      name: "region", type: "list", selectionMode: "single",
      label: "Region",
      options: [{ label: "EU", value: "eu" }, { label: "US", value: "us" }],
      default: "eu",   // required; must match an option value
    },

    // Boolean toggle
    { name: "debug_mode", type: "boolean", label: "Enable Debug Mode", default: false },

    // Dynamic list — options resolved at runtime via a factory that receives the action's params.
    // Required `default` factory for single-select; optional for multiple (falls back to []).
    {
      name: "paymentMethod", type: "dynamicList", selectionMode: "single",
      label: "Default Payment Method",
      options: async (params) => {
        const methods = await fetchPaymentMethods(params.SOME_API_KEY);
        return methods.map((m) => ({ label: m.title, value: m.code }));
      },
      default: (resolvedOptions) => resolvedOptions[0].value,
    },
  ],
}
```

See [assets/business-config.ts](assets/business-config.ts) for the full reference showing all field types.

## Step 4 — Register the extension point

Run init so that `commerce/configuration/1` is added to `app.config.yaml` and `install.yaml`, and the required `@adobe/aio-commerce-lib-config` dependency is installed. This is idempotent — safe to run even if the extension is already registered.

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

## Step 5 — Validate

Build the project to confirm the updated config is valid:

```sh
aio app build
```

A build failure with a validation error points directly to the offending field.

## Reading config in runtime actions

Use `@adobe/aio-commerce-lib-config` to read the values merchants set in Commerce Admin.
The library must be initialized with the generated schema on every action invocation before any config call.

### Basic pattern

```typescript
import {
  initialize,
  getConfigurationByKey,
  getConfiguration,
  byCodeAndLevel,
} from "@adobe/aio-commerce-lib-config";
// Schema is generated by `aio app build` into .generated/configuration-schema.json
// under the commerce-configuration-1 extension; adjust the relative path for your action.
import schema from "../../.generated/configuration-schema.json" with { type: "json" };

export async function main(params) {
  await initialize({ schema });

  // Required to decrypt `password` fields — see "Password fields" below
  const options = { encryptionKey: params.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY };

  // Read a single field — config is null if the key has never been set
  const { config } = await getConfigurationByKey(
    "api_key", // the `name` from your schema
    byCodeAndLevel("global", "global"), // scope
    options,
  );
  const apiKey = config?.value ?? "";

  // Read all fields for a scope
  const { config: allConfig } = await getConfiguration(
    byCodeAndLevel("global", "global"),
    options,
  );
  // allConfig is an array of { name, value, origin } entries

  return { statusCode: 200, body: { success: true } };
}
```

### Scope selectors

| Selector                                  | When to use                                        |
| ----------------------------------------- | -------------------------------------------------- |
| `byCodeAndLevel("global", "global")`      | App-wide settings — applies to all stores          |
| `byCodeAndLevel(storeCode, "store_view")` | Per store view (most specific)                     |
| `byCode(storeCode)`                       | Resolves using the default level for the scope     |
| `byScopeId(scopeId)`                      | When you have the scope's numeric ID from Commerce |

Values inherit from parent scopes — a field not set on `store_view` falls back to `store`, `website`, then `global`.

### Password fields

`aio app build` generates `AIO_COMMERCE_CONFIG_ENCRYPTION_KEY` automatically into `.env` the first time it encounters a password field (and validates it on subsequent builds). No manual setup needed.

The library does not read the key from the environment. Pass it as the `encryptionKey` option on every `getConfigurationByKey`, `getConfiguration`, and `setConfiguration` call, as in the example above. A call that reads or writes a non-empty `password` value without it throws `Encryption key has not been given`.

The key reaches `params` only if the action declares it as an input. Add it to the `inputs` of **every** action that makes these calls in `ext.config.yaml` — declaring it on one action does not make it available to the others:

```yaml
inputs:
  AIO_COMMERCE_CONFIG_ENCRYPTION_KEY: $AIO_COMMERCE_CONFIG_ENCRYPTION_KEY
```

With the option and the input in place, password values are returned as plaintext.

## Common Issues

- **`list/single` default missing**: Single-select list fields require a `default` — it can't be omitted. It must exactly match one of the option `value` strings.
- **`Encryption key has not been given`**: A config call touched a stored `password` value without the `encryptionKey` option, or the action does not declare the `AIO_COMMERCE_CONFIG_ENCRYPTION_KEY` input, so `params.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY` is `undefined`.
- **`defineConfig` not found**: Ensure `@adobe/aio-commerce-lib-app` is installed and `defineConfig` is imported from `@adobe/aio-commerce-lib-app/config`.

## Quality Bar

- `aio app build` completes without errors

## Chaining

After `aio app build` passes:

- **Add webhook interceptors** — invoke `commerce-app-webhooks` to intercept Commerce operations before or after they execute
- **Add event subscriptions** — invoke `commerce-app-eventing` to subscribe to Commerce or external events
- **Extend the Admin UI** — invoke `commerce-app-admin-ui` to add custom columns, mass actions, order view buttons, or menu entries in Commerce Admin

## References

- [assets/business-config.ts](assets/business-config.ts) — Reference config showing all field types with inline constraint comments

© adobe · Apache-2.0 · adobe/skills

Similar skills

All skills for Backend and APIs →

From the same set108

The whole set →
diff diff — a skill for Claude Code that reconciles built web pages against design prototypes. Executes dual Playwright probes to spot visual regressions and misplaced DOM content. CX Codex +1 343installs commerce-app-init The commerce-app-init skill sets up the base structure and metadata for an Adobe Commerce app. Use it to start a project from scratch or initialize a bare app. CX Codex +1 342installs commerce-app-admin-ui commerce-app-admin-ui — a Claude Code skill for extending the Adobe Commerce Admin UI. It activates for requests to add grid columns, bulk actions, page buttons, menu entries, forms, or app-checked permissions. CX Codex +1 340installs deploy Turns styled, page-based HTML prototypes into Edge Delivery Services blocks and pages, then deploys them through DA. CX Codex +1 340installs link-rot-scanner link-rot-scanner is a Claude Code skill that finds and validates internal and external links on AEM Edge Delivery Services sites. Run it before launch or after content migration. CX Codex +1 334installs commerce-app-eventing commerce-app-eventing configures Commerce and external event subscriptions, extraction rules, and runtime action handlers in Adobe Commerce apps. CX Codex +1 332installs commerce-app-storage commerce-app-storage — a skill for Claude Code, Cursor, Codex and other platforms that wires App Builder Database Storage into an existing Adobe Commerce app and scaffolds a runtime action for reading and writing documents. CX Codex +1 331installs commerce-app-webhooks The commerce-app-webhooks skill adds webhook interceptors to an Adobe Commerce app. Validate input data, append information, or modify operation behavior before or after execution. CX Codex +1 330installs

Project sponsors

Companies that keep this analytics open