/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:

// 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:

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:

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)