Initialize your app

Before initializing your App Builder application for App Management, ensure you have completed the prerequisites and have the required services configured.

Prerequisites

Complete the following steps before initializing your app:

Create a project in the Adobe Developer Console

Create a new project or use an existing one in the Adobe Developer Console.
Add required services

Add the following services to your project:
- I/O Management API. Required for App Builder runtime actions.
- I/O Events. Required only if your app uses events.
- I/O Events for Adobe Commerce. Required only if your app uses events.
- Adobe Commerce as a Cloud Service. Required only for Adobe Commerce as a Cloud Service instances.
Only add the services your app needs. This keeps your credentials scoped to the minimum required permissions.
Set up App Builder

Ensure you have the Adobe I/O CLI installed and configured.

Initialize

Run the following command to set up your App Builder project:

data-variant=info

data-slots=text

Unlike the commands in CLI commands below, the init command runs before the library is installed. At this point, each package manager needs to use its fetch-and-run runner (npx, yarn dlx, pnpm dlx, bun x) rather than its exec-style equivalent, which only runs locally installed binaries. For the same reason, this command references the library by its full registry name (@adobe/aio-commerce-lib-app), whereas later commands invoke the locally installed binary using the short name (aio-commerce-lib-app).

              data-slots=heading, code

              data-repeat=4

              data-languages=BASH, BASH, BASH, BASH

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

              yarn
            
              # For Yarn classic (v1), install first
yarn add @adobe/aio-commerce-lib-app
yarn exec aio-commerce-lib-app init

# For Yarn Berry (v2+), pull directly from remote via `dlx`
yarn dlx @adobe/aio-commerce-lib-app init

              pnpm
            
              pnpm dlx @adobe/aio-commerce-lib-app init

              bun
            
              bun x @adobe/aio-commerce-lib-app init

The initialization process:

Creates app.commerce.config with a template (prompts you to choose format and features if the file doesn't exist)
Installs required dependencies (@adobe/aio-commerce-lib-app, @adobe/aio-commerce-sdk, and @adobe/aio-commerce-lib-config when business configuration is enabled)
Generates all required artifacts (commerce/configuration/1 resources are only generated when businessConfig is defined)
Updates app.config.yaml and install.yaml with the appropriate extension references. Creates these files if they do not exist.
Adds a postinstall hook to package.json

Working with TypeScript

As of version 1.10.0 of @adobe/aio-commerce-lib-app, the init command supports TypeScript scaffolding. Using TypeScript in an App Management project requires the project's TypeScript build setup: a webpack-config.cjs file, a root tsconfig.json, and the typescript development dependency. Scaffolding a new project with a TypeScript config sets this up for you out of the box.

If you're adding TypeScript to an existing project, re-run init. It's idempotent: it only adds files and dependencies that don't already exist, so your existing setup and code are preserved.

See Migrating an Existing Project to TypeScript if you already have these files or need to configure the TypeScript setup yourself.

Initialize the configuration library in runtime actions

When your app defines businessConfig, each App Builder runtime action that calls getConfiguration, getConfigurationByKey, or setConfiguration must run initialize before any of those three methods.

If your schema includes dynamicList fields, you must await initialize and pass runtime action params. See Initialize configuration and Configure action inputs for dynamic lists.

See Retrieve configuration at runtime for an example.

CLI commands

The library provides the following CLI commands. Replace npx with your package manager of preference, using the equivalents below:

For Yarn: yarn exec
For PNPM: pnpm exec
For Bun: bun x

Command

Description

npx aio-commerce-lib-app generate all

Generate all artifacts (manifest, schema, and runtime actions). If your schema contains password fields, configure an encryption key. An encryption key is generated when no encryption key is found. See Password field encryption for more information.

npx aio-commerce-lib-app generate manifest

Generate only the app manifest file

npx aio-commerce-lib-app generate actions

Generate only runtime actions

npx aio-commerce-lib-app generate schema

Generate only the configuration schema

Update the library

When a new version of the library is available, update your project to get the latest features and fixes:

              data-slots=heading, code

              data-repeat=4

              data-languages=BASH, BASH, BASH, BASH

              npm
            
              npm install @adobe/aio-commerce-lib-app@latest @adobe/aio-commerce-sdk@latest

              yarn
            
              yarn add @adobe/aio-commerce-lib-app@latest @adobe/aio-commerce-sdk@latest

              pnpm
            
              pnpm add @adobe/aio-commerce-lib-app@latest @adobe/aio-commerce-sdk@latest

              bun
            
              bun add @adobe/aio-commerce-lib-app@latest @adobe/aio-commerce-sdk@latest

If you use a business configuration, also run the following command:

              data-slots=heading, code

              data-repeat=4

              data-languages=BASH, BASH, BASH, BASH

              npm
            
              npm install @adobe/aio-commerce-lib-config@latest

              yarn
            
              yarn add @adobe/aio-commerce-lib-config@latest

              pnpm
            
              pnpm add @adobe/aio-commerce-lib-config@latest

              bun
            
              bun add @adobe/aio-commerce-lib-config@latest

The postinstall hook refreshes generated artifacts when you install or update the library. Separately, aio app build runs pre-app-build, which regenerates runtime action sources from your current app.commerce.config.