commerce-app-init

---
name: commerce-app-init
description: >
  Scaffold a new Adobe Commerce app using the aio-commerce-sdk. Creates the base
  project structure and app.commerce.config file with metadata. Use when the user
  wants to create a new Commerce app from scratch or initialize a bare Commerce
  app project. After scaffolding, chains to appbuilder-project-init for Developer
  Console setup (project, workspace, API subscriptions) when the user wants to deploy.
  Does not configure extensibility domains — use commerce-app-eventing,
  commerce-app-webhooks, commerce-app-business-config, commerce-app-admin-ui,
  or commerce-app-storage for that.
license: Apache-2.0
compatibility: >
  Requires Node.js 22+, aio CLI, and @adobe/aio-commerce-lib-app.
  For Developer Console setup (project/workspace creation, API subscriptions, workspace wiring, deploy, or run),
  also requires appbuilder-project-init from adobe/skills:
  npx skills add adobe/skills --skill appbuilder-project-init -y
metadata:
  author: adobe
---

# Initialize a new Commerce App

Scaffolds a bare Adobe Commerce app: creates `app.commerce.config.ts` with metadata,
then runs `init` to install dependencies and generate all required project files.
Extensibility domains (events, webhooks, business config) are added separately via domain skills.

## Step 1 — Create the config

If `app.commerce.config.ts` already exists in the project root, do **not** overwrite it — skip straight to Step 2 (this skill is safe to re-invoke on an app that already has a config). Otherwise, derive values for the following fields from the user's intent, confirm, and write the file to the project root:

```ts
// app.commerce.config.ts
import { defineConfig } from "@adobe/aio-commerce-lib-app/config";

export default defineConfig({
  metadata: {
    id: "my-commerce-app", // alphanumeric + hyphens only, max 100 chars
    displayName: "My Commerce App", // shown in App Management UI, max 50 chars
    description: "...", // max 255 chars
    upgradeMode: "manual", // optional; currently defaults to "manual" while upgrade execution stabilizes (will default to "auto" once ready); "auto" (experimental) runs upgrades after deploy and waits for completion, "manual" returns plans without executing them
    version: "1.0.0", // Major.Minor.Patch only, no pre-release identifiers
  },
});
```

See [assets/app.commerce.config.ts](assets/app.commerce.config.ts) for the full annotated template.

## Step 2 — Initialize the project

Always run init — it finds the existing config, validates it, and handles project setup:

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

Since `app.commerce.config.ts` already exists, init skips the interactive prompts. Re-running is safe: when a config is present it installs dependencies and (re)generates the project files — the `app-management` package is regenerated, while user packages under `src/commerce-extensibility-1/actions/` are preserved (see Project structure below).

For a TypeScript Commerce config, init also creates missing `webpack-config.cjs` and root `tsconfig.json` files, installs compatible `typescript`, `ts-loader`, `@tsconfig/bases`, and `@types/node` development dependencies, and adds `typecheck:actions` to the project's composed `typecheck` script. Generated Runtime actions remain JavaScript. Once this scaffolding is in place, user-authored runtime actions (added via the domain skills below) and custom installation scripts (`commerce-app-storage`) can be written in `.ts` — see the [aio-commerce-lib-app usage guide](https://github.com/adobe/aio-commerce-sdk/blob/main/packages/aio-commerce-lib-app/docs/usage.md#setup) for the full migration steps if converting an existing JavaScript project.

### Project structure

After init, the project has two types of directories under `src/`:

- **`src/commerce-extensibility-1/actions/`** — custom runtime actions for webhooks and events. Register them in `src/commerce-extensibility-1/ext.config.yaml` under a user-defined package name (any name except `app-management`, which is reserved by the framework). These survive `aio app build` — the generator only regenerates the `app-management` package.
- **`src/commerce-extensibility-1/.generated/`** — auto-generated by `aio app build`. Treat as read-only; any manual edits here will be overwritten.
- **`src/commerce-configuration-1/`** — managed by `aio app build`. Treat as read-only.
- **Root `tsconfig.json`** — checks the TypeScript Commerce config and generated Runtime actions while excluding Admin UI `web-src`, which has its own TypeScript configuration.

## Step 3 — Verify the config

Build the project to confirm everything is valid:

```sh
aio app build
```

If the config is invalid, the build fails with a detailed validation error pointing to the offending field.

## Common Issues

- **`id` validation error**: `metadata.id` accepts alphanumeric characters and hyphens only — no dots, underscores, or spaces. It cannot change during an upgrade; uninstall and reinstall the app to use a different ID.
- **`version` validation error**: Only numeric semver is accepted (`1.0.0`). Pre-release identifiers (`1.0.0-beta`) are not supported.
- **`defineConfig` not found**: Ensure `@adobe/aio-commerce-lib-app` is installed and imported from `@adobe/aio-commerce-lib-app/config`.

## Quality Bar

- `aio app build` completes without errors

## Chaining

After `aio app build` passes:

1. **Bootstrap the Developer Console** — for any follow-up topic related to App Builder setup (Console project/workspace, API subscriptions, deploy, run, workspace wiring), invoke skill `appbuilder-project-init` (from `adobe/skills`). Tell it:
   - Skip the `aio app init` steps — the Commerce scaffold already exists
   - Subscribe `AdobeIOManagementAPISDK` (I/O Management API) as part of the workspace bootstrap — required for IMS credential syncing at runtime
   - Once the workspace is created, ask the user whether their Commerce backend is **ACCS** (Adobe Commerce as Cloud Service) or **PaaS**. If ACCS, `ACCS-REST-API` must also be subscribed: run `aio console open` to open the workspace in the browser, then add it manually through the Developer Console UI. **Do not proceed until the user confirms it has been added.**

   If `appbuilder-project-init` is not installed, ask the user to install it first:

   ```sh
   npx skills add adobe/skills --skill appbuilder-project-init -y
   ```

2. **Extend with domain skills** — once the workspace is wired:
   - `commerce-app-eventing` — manage Commerce and external event sources
   - `commerce-app-webhooks` — manage webhook interception
   - `commerce-app-business-config` — manage custom business configuration
   - `commerce-app-admin-ui` — extend the Commerce Admin UI with custom columns, mass actions, order view buttons, or menu entries
   - `commerce-app-storage` — back runtime actions with persistent, queryable DB storage

## References

- [assets/app.commerce.config.ts](assets/app.commerce.config.ts) — Minimal config template

From adobe/skills at 940b879, shown as plain text under its license: Apache-2.0 (permissive). The license text is in plugins/commerce/app-management/skills/commerce-app-init/SKILL.md.

• SKILL.md7.1 KB · 858d79a13631
• assets/
• app.commerce.config.ts671 B · 5a7e0b9efb46
• evals/
• evals.json3.2 KB · 9df895c1e95a

3 files, 11 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.