Customize

The installation field in your app.commerce.config file allows you to customize the installation experience with messages and custom scripts.

Installation messages

Define messages that display to users before and after the installation process:

import { defineConfig } from "@adobe/aio-commerce-lib-app/config"

export default defineConfig({
  metadata: {
    // ...
  },
  installation: {
    messages: {
      preInstallation: "This app requires configuration A & B to be completed before clicking Install.",
      postInstallation: "Configure your email settings to complete the setup.",
    },
  },
});

Installation experience

Before installation begins, App Management displays the application's business use cases, including configured events and custom installation steps. If installation.messages.preInstallation is defined, it appears under Pre Installation Instructions.

After the administrator selects Install, the dialog displays installation progress for individual items. Keep the page open until installation finishes: closing or refreshing it might prevent installation from completing correctly.

When installation succeeds, the dialog displays Successfully Installed and marks completed items with a check mark.

Use pre-installation instructions to explain prerequisites administrators must complete before selecting Install. Use postInstallation for any remaining setup required after installation.

Custom installation steps

The customInstallationSteps field allows you to define custom scripts that run during the application installation process. These scripts are loaded and executed in the order they are defined.

import { defineConfig } from "@adobe/aio-commerce-lib-app/config"

export default defineConfig({
  metadata: {
    // ...
  },
  installation: {
    messages: {
      preInstallation: "Please ensure all prerequisites are met before installation.",
    },
    customInstallationSteps: [
      {
        script: "./scripts/configure-webhooks.js",
        name: "Configure Webhooks",
        description: "Set up webhook endpoints for order notifications",
      },
      {
        script: "./scripts/initialize-database.ts",
        name: "Initialize Database",
        description: "Create required database tables and indexes",
      },
    ],
  },
});

Step properties

data-variant=info

data-slots=text

Keep the name stable after a step has run. A new name introduces a new migration; changing a completed step's script does not run it again. See Custom installation steps as migrations for upgrade and cleanup behavior.

Working with TypeScript

You can write custom installation step scripts as .ts files instead of .js once your project has the TypeScript build setup in place. See Working with TypeScript for details.

Writing installation scripts

Your custom installation scripts must export a default value using defineCustomInstallationStep. It accepts either a plain handler function (install only) or an object with install and optional uninstall handlers.

The context passed to each handler exposes:

Plain function form

import { defineCustomInstallationStep } from "@adobe/aio-commerce-lib-app/management";

export default defineCustomInstallationStep(async (config, context) => {
  const { logger, params } = context;

  logger.info("Installation step started");

  // Your installation logic here

  logger.info("Installation step completed");

  return {
    status: "success",
    message: "Custom installation step completed",
    timestamp: new Date().toISOString(),
  };
});

Object form with install and uninstall

Use the object form when your step needs to clean up resources it created when the app is uninstalled:

import { defineCustomInstallationStep } from "@adobe/aio-commerce-lib-app/management";

export default defineCustomInstallationStep({
  install: async (config, context) => {
    context.logger.info(`Registering ${config.metadata.displayName}...`);
    return { status: "success" };
  },
  uninstall: async (config, context) => {
    context.logger.info(`Removing ${config.metadata.displayName}...`);
  },
});

data-variant=info

data-slots=text

Script with error handling

import { defineCustomInstallationStep } from "@adobe/aio-commerce-lib-app/management";

export default defineCustomInstallationStep(async (config, context) => {
  const { logger } = context;

  logger.info("Initializing database...");

  try {
    if (!config.businessConfig?.schema) {
      throw new Error("Business configuration schema is required");
    }

    logger.info(`Setting up database for ${config.metadata.displayName}`);

    // Database initialization logic
    await initializeDatabase();

    logger.info("Database initialized successfully");

    return {
      status: "success",
      message: "Database tables and indexes created",
    };
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    logger.error(`Database initialization failed: ${errorMessage}`);
    throw error;
  }
});

Script requirements

• Scripts must use export default to export either a handler function or an object with install/uninstall handlers.
• Scripts are executed sequentially in the order defined, for both installation and uninstallation (uninstall does not reverse the order).
• If any script throws an error, the installation fails and subsequent scripts are not executed.
• On retry of a failed installation, upgrade, or uninstallation, custom steps recorded as successful are skipped. A failed or interrupted handler can run again, including after a timeout.
• Make handlers safe to run repeatedly (idempotent): check for resources created by partial execution, and allow cleanup to succeed when resources are already removed. Test retries after failures and interruptions.
• Scripts have access to the complete app configuration.

After you modify custom installation scripts, you must manually run the npx aio-commerce-lib-app generate actions command before building and deploying. This ensures the installation action picks up your changes. For all other app.commerce.config updates, build and deploy alone is sufficient, as artifacts are regenerated during pre-app-build.