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:

// 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 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 for the full migration steps if converting an existing JavaScript project.