commerce-app-storage — скилл для Claude Code
Скилл commerce-app-storage для Claude Code, Cursor, Codex и других платформ — встраивает App Builder Database Storage в существующее Adobe Commerce-приложение и создаёт runtime action для чтения и записи документов.
Apache-2.0 331 установок ★ 335 обновлён 2026-11-14
npx skills add adobe/skills --skill commerce-app-storage -a claude-codeЧто делает commerce-app-storage
Скилл добавляет библиотеку @adobe/aio-lib-db и разворачивает runtime action с MongoDB-подобным API: данные хранятся в коллекциях документов, запросы строятся через привычные фильтры.
Два типа action отличаются только регистрацией и форматом ответа. Web action помечается web: "yes" и возвращает HTTP-ответ через хелперы из @adobe/aio-commerce-lib-core. Action для событий и вебхуков подключается через commerce-app-eventing или commerce-app-webhooks в файле app.commerce.config.ts. Код доступа к базе в обоих случаях одинаковый.
Для работы нужны Node.js 22+, aio CLI и @adobe/aio-commerce-lib-app. База данных должна быть подготовлена: API AppBuilderDataServicesSDK добавлен в проект в Adobe Developer Console в каждом воркспейсе, который использует БД. Регион в манифесте app.config.yaml и в каждом вызове initDb({ region }) обязаны совпадать — несоответствие ломает подключение. Скилл требует базового приложения, инициализированного через commerce-app-init.
Какие задачи решает
- Добавить персистентное хранилище документов в Commerce-приложение на App Builder
- Создать web action с HTTP-доступом к базе данных рабочего пространства
- Подключить обработчик Commerce-события к коллекции документов
- Провизировать базу данных декларативно через
app.config.yaml - Настроить
@adobe/aio-lib-dbв TypeScript-проекте без потери строгой проверки типов
Примеры запросов агенту
- Добавь хранилище документов в моё Commerce-приложение и создай web action для чтения и записи коллекции
orders - Создай runtime action для обработки Commerce-события с записью данных в базу через
@adobe/aio-lib-db - Провизируй воркспейс-базу данных в регионе
emeaи подключи её к существующему action
Как установить commerce-app-storage
1Через Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-storage -a claude-code2Вручную: положить файлы
~/.claude/skills/commerce-app-storage/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/commerce-app-storage/
1Через Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-storage -a codex2Вручную: положить файлы
.agents/skills/commerce-app-storage/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-storage -a cursor2Вручную: положить файлы
.cursor/skills/commerce-app-storage/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install adobe/skills plugins/commerce/app-management/skills/commerce-app-storage2Вручную: положить файлы
.github/skills/commerce-app-storage/SKILL.md1Через Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-storage -a gemini-cli2Командой платформы
gemini skills install https://github.com/adobe/skills --path plugins/commerce/app-management/skills/commerce-app-storageВручную: положить файлы
.devin/skills/commerce-app-storage/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-storage -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о commerce-app-storage
Как установить commerce-app-storage в Claude Code?
Выполните команду npx skills add adobe/skills --skill commerce-app-storage -a claude-code. После этого скилл будет доступен по пути ~/.claude/skills/commerce-app-storage/SKILL.md.
Что делает скилл commerce-app-storage?
Встраивает App Builder Database Storage (@adobe/aio-lib-db) в существующее Adobe Commerce-приложение и создаёт runtime action с MongoDB-подобным API для чтения и записи документов — как для HTTP-вызываемого web action, так и для обработчика событий.
Какие зависимости нужны для работы скилла?
Node.js 22+, aio CLI, пакет @adobe/aio-commerce-lib-app и база App Builder с добавленным API AppBuilderDataServicesSDK в Adobe Developer Console. Базовое приложение должно быть инициализировано через commerce-app-init.
Исходный текст
SKILL.md · Apache-2.0
---
name: commerce-app-storage
description: >
Integrate App Builder Database Storage (@adobe/aio-lib-db) into an Adobe
Commerce app and scaffold a runtime action that reads and writes documents.
Use when the user wants persistent, queryable storage backing a Commerce app —
either from a web action (HTTP-invokable) or from an event/webhook handler.
Requires a base app initialized with commerce-app-init.
license: Apache-2.0
compatibility: >
Requires Node.js 22+, aio CLI, @adobe/aio-commerce-lib-app, and a provisioned
workspace database with the App Builder Data Services API added to the project
in the Adobe Developer Console. Requires a base app initialized with commerce-app-init.
metadata:
author: adobe
sdk-package: "@adobe/aio-commerce-lib-app"
version: "0.0.3"
---
# Add Database Storage to a Commerce App
Integrates App Builder Database Storage into an existing Commerce app and scaffolds a runtime action that uses `@adobe/aio-lib-db` to read and write documents. The library is MongoDB-like: data lives in collections of documents, queried with familiar filters.
The db-access code is identical regardless of action type — what differs is how the action is registered and what its handler returns:
- **Web action** — HTTP-invokable (`web: "yes"`); returns a response built with the `responses` helpers from `@adobe/aio-commerce-lib-core`.
- **Event/webhook action** — invoked by a Commerce event or webhook; referenced from `app.commerce.config.ts` via `commerce-app-eventing` (`runtimeActions`) or `commerce-app-webhooks` (`runtimeAction`).
## 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 and custom installation scripts 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 them in JavaScript.
- The **App Builder Data Services** API (API code `AppBuilderDataServicesSDK`) must be **added to the project in the Adobe Developer Console** — in every workspace that uses the database (no special license beyond App Builder). Without it, runtime actions cannot authenticate to the database service.
## Step 1 — Provision the workspace database
There is a strict one-to-one relationship between an AIO project workspace and a workspace database. The recommended way to provision it is **declaratively** in `app.config.yaml` — the database is provisioned (if not already present) on `aio app deploy`:
```yaml
application:
runtimeManifest:
database:
auto-provision: true
region: emea # amer | apac | emea | aus — the single source of truth for the region
```
**Extension-only apps need a workaround.** Due to a bug in the `aio app` CLI plugin (not `aio-lib-db`), `aio app deploy` only runs declarative auto-provision when the `application` runtime manifest has at least one package with a runtime action. Apps built purely with `extensions` (the recommended layout per the submission guidelines) have no `application` actions, so deploy silently skips provisioning. Make the `application` block "real enough" for provisioning to run by adding an empty packages map and a `post-app-build` hook that creates the directory the provisioning step expects:
```yaml
application:
hooks:
post-app-build: "mkdir -p dist/application/actions" # provisioning expects this dir to exist
runtimeManifest:
packages: {} # empty map — required by the config schema so the application block validates with no actions
database:
auto-provision: true
region: emea # single source of truth — see the region callout below
```
For **local development**, declarative auto-provisioning does **not** run during `aio app run` / `aio app dev`. Provision once up front with the CLI fallback (self-service, no special permissions). The `aio app db …` commands are only available once the [storage CLI plugin](https://github.com/adobe/aio-cli-plugin-app-storage) is installed:
```sh
aio plugins install @adobe/aio-cli-plugin-app-storage
aio app db provision --region <amer|apac|emea|aus>
```
> **Region is a single source of truth.** The `region` in the manifest `database` block must match the `region` passed to every `initDb({ region })` call (or `AIO_DB_REGION`) — in every action **and** in the install step (Step 6). A mismatch fails the connection. Changing region is destructive: `aio app db delete`, update `database.region` in the manifest, then re-provision.
## Step 2 — Install the library
```sh
npm install @adobe/aio-lib-db
```
For existing apps, inspect the dependency, lockfile and installed package before installing; preserve ranges and pins.
For TypeScript or checked JavaScript, check actual declaration resolution, not just the version (package types first appeared in 1.1.0):
- **Types resolve:** prefer package declarations, otherwise reuse compatible application declarations. Report conflicts without silently changing application declarations.
- **No types resolve:** recommend a typed release, but require approval before dependency or lockfile changes. To keep the installed version, add this comment immediately above each DB import reporting TS7016, including copied asset imports:
```ts
// @ts-expect-error -- Installed aio-lib-db has no resolvable TypeScript declarations.
import { init as initDb } from "@adobe/aio-lib-db";
```
The fallback leaves DB APIs untyped. Keep strict checking; do not add ambient DB bridges, downgrade dependencies, or suppress unrelated errors. Compilation does not prove runtime compatibility.
## Step 3 — Understand intent
Gather from the user:
- **Action type**: web action or event/webhook action (see the two shapes above).
- **Collection name** and the **operations** needed (insert / find / update / delete).
- **Region**: must match the manifest `database.region` (see the region callout in Step 1). Pass it to `init()` or set `AIO_DB_REGION`.
## Step 4 — Register the action
Add the action to a user-defined package in `src/commerce-extensibility-1/ext.config.yaml` (any name except `app-management`, which is reserved).
> **`include-ims-credentials: true` is required on every DB action.** Without it, `aio-lib-db` has no IMS token to authenticate with and the connection fails at runtime (and the app installation fails if the action runs during install). Do not omit this annotation.
>
> Do not manually wire OAuth Server-to-Server credentials with `AIO_COMMERCE_AUTH_IMS_*` inputs.
> That legacy fallback is deprecated and planned for removal in a future major release.
```yaml
# src/commerce-extensibility-1/ext.config.yaml
runtimeManifest:
packages:
app-management:
# ... auto-generated — do not edit
my-app: # any name except "app-management"
actions:
store-record:
function: actions/store-record/index.js # relative to src/commerce-extensibility-1/
runtime: nodejs:26
web: "yes" # "yes" for a web action; "no" for an event/webhook action
annotations:
include-ims-credentials: true # REQUIRED for aio-lib-db auth
```
| Field | Constraint |
| ------------------------- | --------------------------------------------------------------------------------- |
| Package name | Lowercase alphanumeric + hyphens; never `app-management` (reserved) |
| `function` | Path relative to `src/commerce-extensibility-1/` — not `src/...` or root-relative |
| `include-ims-credentials` | Must be `true` — without it `init()` has no IMS token and the connection fails |
| `web` | `"yes"` for HTTP-invokable web actions; `"no"` for event/webhook handlers |
| Collection name | Non-empty string; created on first write if it doesn't exist |
| Region | Must match the manifest `database.region` (`amer` \| `apac` \| `emea` \| `aus`) |
## Step 5 — Implement the handler
Every handler follows the same lifecycle: resolve IMS auth → mint token → `init` → `connect` → use a collection → **always `close` in `finally`**.
```ts
// Web action — src/commerce-extensibility-1/actions/store-record/index.ts
import { buildErrorResponse, ok } from "@adobe/aio-commerce-lib-core/responses";
import {
getImsAuthProvider,
resolveImsAuthParams,
} from "@adobe/aio-commerce-lib-auth";
import { init as initDb } from "@adobe/aio-lib-db";
export async function main(params: Record<string, unknown>) {
let client;
try {
// Resolve credentials injected by include-ims-credentials, then mint a raw token string.
const authProvider = getImsAuthProvider(resolveImsAuthParams(params));
const token = await authProvider.getAccessToken();
const db = await initDb({ token, region: "emea" }); // must match the manifest database.region
client = await db.connect();
const records = client.collection("records");
const result = await records.insertOne({
...(params.document as object),
createdAt: new Date().toISOString(),
});
return ok({ body: { result } });
} catch (error: any) {
return buildErrorResponse(error.statusCode || 500, {
body: { message: error.message },
});
} finally {
if (client) await client.close(); // always close — avoids connection leaks
}
}
```
Event and webhook actions both register with `web: "no"`, but their payloads have different shapes — do not treat them as the same:
- **Event handler** (wired via `commerce-app-eventing`): the extracted fields arrive in `params.data.value`. `params.data` also carries `_metadata` (Commerce instance metadata) and `source` (the merchant/environment ID pair from the Commerce eventing configuration) — neither is handler input.
- **Webhook handler** (wired via `commerce-app-webhooks`): there is no `data` wrapper — the Commerce operation payload arrives directly on `params` (e.g. `params.order`), and the response must use the operation helpers from `@adobe/aio-commerce-lib-webhooks/responses` (see `commerce-app-webhooks`), not the plain `ok`/`buildErrorResponse` shape used above.
```ts
// Event handler — src/commerce-extensibility-1/actions/store-order/index.ts
export async function main(params: Record<string, unknown>) {
const data = params.data as Record<string, unknown>;
const value = data.value as Record<string, unknown>;
let client;
try {
const authProvider = getImsAuthProvider(resolveImsAuthParams(params));
const token = await authProvider.getAccessToken();
const db = await initDb({ token, region: "emea" });
client = await db.connect();
await client
.collection("orders")
.insertOne({ orderId: value.order_id, receivedAt: new Date() });
return ok({ body: { processed: true } });
} finally {
if (client) await client.close();
}
}
```
```ts
// Webhook handler — src/commerce-extensibility-1/actions/log-order/index.ts
import {
ok,
successOperation,
} from "@adobe/aio-commerce-lib-webhooks/responses";
export async function main(params: Record<string, unknown>) {
const order = params.order as Record<string, unknown>; // Commerce operation payload, directly on params
let client;
try {
const authProvider = getImsAuthProvider(resolveImsAuthParams(params));
const token = await authProvider.getAccessToken();
const db = await initDb({ token, region: "emea" });
client = await db.connect();
await client
.collection("orders")
.insertOne({ orderId: order.entity_id, receivedAt: new Date() });
return ok(successOperation());
} finally {
if (client) await client.close();
}
}
```
See [assets/db-action.ts](assets/db-action.ts) for the full annotated reference covering all CRUD operations and cursor iteration.
## Step 6 — Set up collections and indexes on install
For an App Management app, create collections and indexes with a **custom installation step** — a script that runs once when the app is installed from the Commerce Admin, and can be reversed on uninstall. Prefer this over creating them ad-hoc on the first request.
Author the step with `defineCustomInstallationStep` (an `install` handler plus an optional `uninstall`). Inside it, resolve the IMS auth params from **`context.params`** — _not_ `config` — then follow the same init → connect → `close` lifecycle as Step 5, and call `createIndex` **on the collection object**:
```ts
// ./scripts/setup-database.ts — referenced from config as ./scripts/setup-database.ts
import { defineCustomInstallationStep } from "@adobe/aio-commerce-lib-app/management";
import {
getImsAuthProvider,
resolveImsAuthParams,
} from "@adobe/aio-commerce-lib-auth";
import { init as initDb } from "@adobe/aio-lib-db";
export default defineCustomInstallationStep({
install: async (config, context) => {
let client;
try {
// context.params carries the injected IMS credentials — NOT config.
const authProvider = getImsAuthProvider(
resolveImsAuthParams(context.params),
);
const token = await authProvider.getAccessToken();
const db = await initDb({ token, region: "emea" }); // must match the manifest database.region
client = await db.connect();
const orders = client.collection("held_orders"); // get the collection object first
await orders.createIndex({ order_id: 1 }, { unique: true }); // createIndex on the collection, not a name string
return { status: "success" };
} finally {
if (client) await client.close(); // always close — avoids connection leaks
}
},
uninstall: async (config, context) => {
// Tear down your database state here.
// Leave empty to preserve data across reinstalls.
},
});
```
> **Author the install script as an ES module with `export default` — never `module.exports`.** The installation action loads each step via `import * as step from "<script>"` and reads `step.default`, so the script must default-export the `defineCustomInstallationStep(...)` result. CommonJS breaks this: `module.exports.default` surfaces as `step.default.default` and validation fails. The `script` path must end in `.js` or `.ts` — author it directly in TypeScript, no separate compile step needed.
Register the step in `app.commerce.config.ts` under `installation.customInstallationSteps`. The `script` path points directly at your `.ts` file:
```ts
// app.commerce.config.ts
installation: {
customInstallationSteps: [
{
script: "./scripts/setup-database.ts",
name: "Set up held-orders collection",
description: "Creates the held_orders collection and a unique index on order_id",
},
],
},
```
| Field | Constraint |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `script` | Path relative to the project root; must be an ES module (`export default`) ending in `.js` or `.ts` |
| `name` | Non-empty string, ≤ 255 characters; **unique** across all installation steps |
| `description` | Non-empty string, ≤ 255 characters |
See [assets/setup-database.ts](assets/setup-database.ts) for the full annotated install/uninstall reference.
## Step 7 — Regenerate the `installation` action
If this custom installation step is the first install-requiring domain in the config (the others are `webhooks`, `eventing.commerce`, `eventing.external`, `adminUi`), re-run:
```sh
npx @adobe/aio-commerce-lib-app init
```
This is what adds the `installation` action to `ext.config.yaml`'s `app-management` package — `aio app build`/`aio app deploy` only read the existing file, they never regenerate it. Skip this and the script never runs, even though it's registered in code and the DB action is deployed. Safe to re-run even when the action already exists.
## Step 8 — Validate
Run the project's strict typecheck, including the storage runtime action. If adding a custom installation step, verify its root `installation.customInstallationSteps` registration produces a generated import of the configured script and that the actual compiler file list includes it. Preserve existing compiler includes and exclusions; do not add `scripts/**/*.ts` to compensate for missing registration.
```sh
aio app build
```
A build failure points directly to the offending config field. To exercise the action against the real database, deploy and invoke it (`aio app deploy`). If this step needed Step 7, also check that `ext.config.yaml` now has `actions.installation` under `app-management`.
## Best practices
- **Always close connections** in a `finally` block — leaked connections exhaust resources.
- **Match the region** — the manifest `database.region` is the single source of truth; every `init()` call and the install step must use it (see the region callout in Step 1). A mismatch fails the connection silently from the caller's view.
- **Use projections** (`.project({ field: 1 })`) and **indexes** (`createIndex`) for frequently queried fields; index fields must total ≤ 2048 bytes. For public responses, prefer inclusion projections.
Filters select documents; projections select fields. Inclusion returns selected fields and `_id` by default; `_id: 0` is the only exclusion allowed alongside included fields. Otherwise, do not mix inclusion and exclusion.
```ts
const cursor = client
.collection("records")
.find({ status: "active" })
.project({ _id: 0, title: 1, status: 1 });
```
- **Iterate large result sets with cursors** (`for await (const doc of collection.find(...))`) instead of `toArray()` to bound memory.
- **Don't hardcode the region or secrets** — prefer `AIO_DB_REGION` and the injected IMS token over inline values.
- **Prefer the most specific Adobe I/O library** in runtime actions over the `@adobe/aio-sdk` umbrella — e.g. `@adobe/aio-commerce-lib-auth` for IMS auth and `@adobe/aio-lib-core-logging` for the logger — to keep action bundles small.
- **Set up collections and indexes during installation** with a custom installation step (`defineCustomInstallationStep`, see Step 6) rather than ad-hoc on the first request — it runs once when the app is installed from the Commerce Admin and is reversible on uninstall. A generic App Builder `post-app-deploy` hook is only an alternative when the app is not installed through App Management.
## Common Issues
- **Connection fails despite a valid token**: the action is missing `include-ims-credentials: true`, or the **App Builder Data Services** API has not been added to the project in the Adobe Developer Console (see Prerequisites).
- **DB not provisioned after `aio app deploy` (extension-only app)**: a bug in the `aio app` CLI plugin (not `aio-lib-db`) skips declarative auto-provision when the `application` runtime manifest has no runtime action. Apply the extension-only workaround from Step 1 — add `packages: {}` and a `post-app-build: "mkdir -p dist/application/actions"` hook under `application` — or provision once with the CLI fallback for local dev.
- **Connection fails after a region change**: the library region doesn't match the manifest `database.region`. Moving regions is destructive — `aio app db delete`, update `database.region` in the manifest, then re-provision (`aio app deploy`, or the CLI fallback for local dev).
- **Querying by `_id` from a string returns nothing**: convert it first — `new ObjectId(idString)` from `bson`. A raw string never matches the stored `ObjectId`.
- **`DbError` vs unexpected error**: errors thrown by the service have `name === "DbError"`; branch on it to separate database failures from application bugs.
- **`findOne` throws instead of returning `null` on no match**: unlike MongoDB, a miss is not a successful `null` result — it throws a `DbError` with a message containing `"Document not found"`. `name === "DbError"` alone isn't enough to detect this, since every `DbError` (including a genuine connection failure) has that name; check `error.message` too:
```ts
function isDocumentNotFoundError(error: unknown) {
const e = error as { name?: string; message?: string };
return e.name === "DbError" && e.message?.includes("Document not found");
}
let existing;
try {
existing = await records.findOne({ order_id: orderId });
} catch (error) {
if (!isDocumentNotFoundError(error)) {
throw error;
}
}
```
See [assets/db-action.ts](assets/db-action.ts) for the full reference.
- **Auth fails inside an installation step**: resolve the injected IMS auth params from `context.params` with `resolveImsAuthParams(context.params)` — not from `config`, which holds no credentials. Ensure the action is annotated with `include-ims-credentials: true`; manually wired `AIO_COMMERCE_AUTH_IMS_*` credentials are deprecated.
- **Installation step fails to load (`must export a default function or object`)**: the script was authored as CommonJS. Author it as an ES module with `export default`; `module.exports` (or `module.exports.default`) surfaces through the framework's `import * as` loader as `.default.default` and fails validation.
- **`createIndex` errors or has no effect**: it must be called on a collection object (`client.collection("name").createIndex({ field: 1 })`), not with a collection-name string. Get the collection first, then call `createIndex` on it.
- **Custom installation step registered and deployed but never runs**: `init` wasn't re-run after registering the first install-requiring domain (Step 7) — no `installation` action, no install endpoint.
## Quality Bar
- `aio app build` completes without errors
- Every user-authored DB action declares `include-ims-credentials: true` in its annotations
- The action closes the client in a `finally` block and initializes the library in the region declared in the manifest `database` block
- `installation` action present in `ext.config.yaml` when this custom installation step requires it
## Chaining
- **Wire the action to an event** — invoke `commerce-app-eventing` and reference this action in an event's `runtimeActions`.
- **Wire the action to a webhook** — invoke `commerce-app-webhooks` and reference this action via `runtimeAction`.
- **Trigger the action from Admin UI** — invoke `commerce-app-admin-ui` to add a mass action, order view button, or grid column that invokes this runtime action.
## References
- [assets/db-action.ts](assets/db-action.ts) — Full annotated handler: init/connect, CRUD, cursor iteration, and the close lifecycle
- [assets/setup-database.ts](assets/setup-database.ts) — Full annotated custom installation step: install creates a collection and a unique index, uninstall drops it, with the `context.params` and `createIndex`-on-collection patterns
© adobe · Apache-2.0 · adobe/skills