commerce-app-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Initialize a new Commerce App

初始化新的Commerce应用

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.

搭建一个空白的Adobe Commerce应用：创建包含元数据的

app.commerce.config.ts

，然后运行

init

命令安装依赖并生成所有必需的项目文件。扩展领域（事件、Webhook、业务配置）需通过领域技能单独添加。

Step 1 — Create the config

步骤1 — 创建配置文件

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
    version: "1.0.0", // Major.Minor.Patch only, no pre-release identifiers
  },
});

See assets/app.commerce.config.ts for the full annotated template.

如果项目根目录中已存在

app.commerce.config.ts

，请勿覆盖它——直接跳至步骤2（此技能可安全地在已有配置的应用上重新调用）。否则，根据用户的需求推导以下字段的值，确认后将文件写入项目根目录：

// 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
  },
});

查看assets/app.commerce.config.ts获取完整的带注释模板。

Step 2 — Initialize the project

步骤2 — 初始化项目

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

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

始终要运行init命令——它会查找现有配置，验证其有效性，并处理项目设置：

npx @adobe/aio-commerce-lib-app init

由于

app.commerce.config.ts

已存在，init命令会跳过交互式提示。重复运行是安全的：当配置存在时，它会安装依赖并（重新）生成项目文件——

app-management

包会被重新生成，而

src/commerce-extensibility-1/actions/

下的用户包会被保留（见下方项目结构）。

对于TypeScript Commerce配置，init命令还会创建缺失的

webpack-config.cjs

和根目录下的

tsconfig.json

文件，安装兼容的

typescript

、

ts-loader

和

@tsconfig/bases

开发依赖，并将

typecheck:actions

添加到项目的组合

typecheck

脚本中。生成的Runtime操作仍为JavaScript。一旦搭建完成，用户编写的Runtime操作（通过下方的领域技能添加）和自定义安装脚本（

commerce-app-storage

）可以用

.ts

编写——如果要转换现有JavaScript项目，请查看aio-commerce-lib-app使用指南获取完整迁移步骤。

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.

初始化完成后，项目的

src/

目录下有两种类型的文件夹：

src/commerce-extensibility-1/actions/
— 用于Webhook和事件的自定义Runtime操作。在
```
src/commerce-extensibility-1/ext.config.yaml
```
中，在用户定义的包名下注册它们（除
```
app-management
```
之外的任意名称，该名称为框架保留）。这些文件在
```
aio app build
```
时会保留——生成器仅重新生成
```
app-management
```
包。
src/commerce-extensibility-1/.generated/
— 由
```
aio app build
```
自动生成。请将其视为只读文件；此处的任何手动编辑都会被覆盖。
src/commerce-configuration-1/
— 由
```
aio app build
```
管理。请将其视为只读文件。
根目录下的
tsconfig.json
— 检查TypeScript Commerce配置和生成的Runtime操作，同时排除Admin UI的
```
web-src
```
，后者有自己的TypeScript配置。

Step 3 — Verify the config

步骤3 — 验证配置

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.

构建项目以确认所有内容均有效：

aio app build

如果配置无效，构建会失败并显示详细的验证错误，指出有问题的字段。

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

id
验证错误：
```
metadata.id
```
仅接受字母数字字符和连字符——不允许使用点、下划线或空格。
version
验证错误：仅接受数字语义化版本（如
```
1.0.0
```
）。不支持预发布标识符（如
```
1.0.0-beta
```
）。

defineConfig
未找到：确保已安装

@adobe/aio-commerce-lib-app

，并从

@adobe/aio-commerce-lib-app/config

导入。

Quality Bar

质量标准

```
aio app build
```
completes without errors

```
aio app build
```
无错误完成

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

aio app build

通过后：

引导开发者控制台 — 对于任何与App Builder设置相关的后续主题（控制台项目/工作区、API订阅、部署、运行、工作区连接），调用技能
```
appbuilder-project-init
```
（来自
```
adobe/skills
```
）。告知它：
- 跳过
```
aio app init
```
  步骤——Commerce脚手架已存在
- 在工作区引导过程中订阅
```
AdobeIOManagementAPISDK
```
  （I/O管理API）——这是运行时IMS凭据同步所必需的
- 工作区创建完成后，询问用户其Commerce后端是ACCS（Adobe Commerce云服务）还是PaaS。如果是ACCS，还必须订阅
```
ACCS-REST-API
```
  ：运行
```
aio console open
```
  在浏览器中打开工作区，然后通过开发者控制台UI手动添加。在用户确认已添加之前，请勿继续。
如果未安装
```
appbuilder-project-init
```
，请要求用户先安装它：
sh
```
npx skills add adobe/skills --skill appbuilder-project-init -y
```
使用领域技能扩展 — 工作区连接完成后：
- ```
commerce-app-eventing
```
  — 管理Commerce和外部事件源
- ```
commerce-app-webhooks
```
  — 管理Webhook拦截
- ```
commerce-app-business-config
```
  — 管理自定义业务配置
- ```
commerce-app-admin-ui
```
  — 使用自定义列、批量操作、订单视图按钮或菜单项扩展Commerce Admin UI
- ```
commerce-app-storage
```
  — 为Runtime操作提供持久化、可查询的数据库存储

References

参考资料

assets/app.commerce.config.ts — Minimal config template

assets/app.commerce.config.ts — 最小配置模板