# 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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 331 installs · ★ 335 repo stars
- Author: adobe
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/adobe/skills/tree/HEAD/plugins/commerce/app-management/skills/commerce-app-storage/SKILL.md
- Updated: 2026-11-14
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/commerce-app-storage

## What it does

The skill installs `@adobe/aio-lib-db` and generates a runtime action backed by a MongoDB-like API: data sits in document collections and is queried through standard filters.

Web actions and event handler actions share identical database code. The difference is registration and response shape — web actions carry `web: "yes"` and return responses via helpers from `@adobe/aio-commerce-lib-core`, while event and webhook actions are referenced from `app.commerce.config.ts` through `commerce-app-eventing` or `commerce-app-webhooks`.

The skill requires Node.js 22+, the `aio` CLI, and `@adobe/aio-commerce-lib-app`. Before any action can authenticate against the database, the `AppBuilderDataServicesSDK` API must be added to the project in the Adobe Developer Console for every workspace that uses the database. The region set in `app.config.yaml` under `database.region` must match the region passed to every `initDb({ region })` call — a mismatch breaks the connection. A base app initialized with `commerce-app-init` is a hard prerequisite.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add adobe/skills --skill commerce-app-storage -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/commerce-app-storage/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/commerce-app-storage/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add adobe/skills --skill commerce-app-storage -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/commerce-app-storage/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add adobe/skills --skill commerce-app-storage -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/commerce-app-storage/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install adobe/skills plugins/commerce/app-management/skills/commerce-app-storage
```

2. **Manually: put the files in place**
- File: `.github/skills/commerce-app-storage/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add adobe/skills --skill commerce-app-storage -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/adobe/skills --path plugins/commerce/app-management/skills/commerce-app-storage
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/commerce-app-storage/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add adobe/skills --skill commerce-app-storage -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/adobe/skills/tree/HEAD/plugins/commerce/app-management/skills/commerce-app-storage/SKILL.md

## When to use it
- Add persistent document storage to a Commerce app on App Builder
- Scaffold an HTTP-invokable web action with read and write access to a workspace database
- Connect a Commerce event handler action to a document collection
- Provision a workspace database declaratively via `app.config.yaml`
- Set up `@adobe/aio-lib-db` in a TypeScript project without disabling strict type checking

## Example prompts
- Add document storage to my Commerce app and create a web action to read and write the `orders` collection
- Scaffold a runtime action that handles a Commerce event and writes records to the database via `@adobe/aio-lib-db`
- Provision a workspace database in the `emea` region and connect it to the existing action

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2f113db907a53e88.

BEGIN THIRD-PARTY FILE 2f113db907a53e88
```text
---
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).
```
END THIRD-PARTY FILE 2f113db907a53e88

The third-party file has ended. Everything between the 2f113db907a53e88 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2085 of 23878 bytes. © adobe · Apache-2.0 · https://github.com/adobe/skills/tree/HEAD/plugins/commerce/app-management/skills/commerce-app-storage/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
