commerce-app-init

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

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.

3installs

Sourceadobe/skills

Added on2026-08-14

NPX Install

npx skill4agent add adobe/skills commerce-app-init

SKILL.md Content

View Translation Comparison →

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

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

, and

@tsconfig/bases

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:

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

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
```
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