commerce-app-init

# 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