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.

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

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

   Copy

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 — Minimal config template