App Builder · Ep 1: what aio app init puts on disk

Step 1 of 7

A fresh App Builder project has more files than a typical Adobe Commerce (Magento 2) module, and it isn't obvious which ones you're meant to touch. Most of them are scaffolding. Three files decide almost everything: app.config.yaml, .env and .aio. Learn those, and the rest of the folder reads like any Node project. About 20 minutes of reading, with your terminal open if you like.

You’ll need

  • Node.js LTS and the Adobe I/O CLI (npm install -g @adobe/aio-cli)
  • Any App Builder project, or the one you'll create in episode 2

Look at the whole tree once

A project with actions and a web UI looks roughly like this after aio app init:

my-app/
├── .aio                  # which org, project and workspace this folder deploys to
├── .env                  # Runtime credentials and your secrets
├── app.config.yaml       # the manifest: actions, web UI, triggers, rules, extensions
├── package.json          # dependencies, including @adobe/aio-sdk
├── actions/              # serverless functions, one folder each
│   ├── utils.js
│   └── generic/index.js
├── web-src/              # optional React single-page app
├── test/                 # Jest unit tests for actions
├── e2e/                  # end-to-end tests against deployed actions
└── .github/workflows/    # CI templates that test and deploy

For an Adobe Commerce developer: app.config.yaml is your module.xml, di.xml and crontab.xml rolled into one. actions/ is where the PHP classes would have been.

FileWhat it decidesIn git?
app.config.yamlThe manifest: actions, web UI, triggers, rules, extensionsYes
.envRuntime namespace and auth key, plus every secret your actions readNo. Commit .env.dist with empty values
.aioWhich org, project and workspace this folder is bound toNo (episode 2)

Read app.config.yaml first

This file is the manifest. Adobe's reference for all three files is App Builder Configuration Files. It lists every action, how it's exposed, what inputs it receives, and later, which triggers and rules run it on a schedule.

application:
  actions: actions
  web: web-src
  runtimeManifest:
    packages:
      order-sync:
        license: Apache-2.0
        actions:
          export-order:
            function: actions/export-order/index.js
            runtime: nodejs:20
            web: 'yes'
            inputs:
              LOG_LEVEL: info
              ERP_API_URL: $ERP_API_URL
              ERP_API_KEY: $ERP_API_KEY
            annotations:
              require-adobe-auth: true
              final: true
            limits:
              timeout: 60000
              memory: 256

The parts worth memorising:

  • web: 'yes' gives the action a public HTTPS URL. Leave it out for actions that only run from events or schedules.
  • inputs are passed to the action as params. A value starting with $ is read from .env at deploy time.
  • require-adobe-auth: true means callers need a valid Adobe token and the x-gw-ims-org-id header. aio app deploy enforces it by putting Adobe's validator in front of your action; the annotation on its own changes nothing at runtime, so an action created with aio rt action create and the same annotation stays public. Use it on anything that isn't deliberately public. I've tested this by hand, not through a real deploy yet; details in the note below.
  • final: true stops a caller from overriding your inputs with request parameters. Without it, ?ERP_API_URL= on the request would win. I tried it on Stage: Runtime answered 400 before my code ran.
  • limits sets the timeout in milliseconds and the memory in MB for this one action.

Treat .env as a secret, always

.env holds the Runtime namespace and auth key for the workspace, plus every secret your actions read through $VARIABLES. It's in .gitignore for a reason. Commit a .env.dist with the variable names and empty values instead, so a teammate knows what to fill in.

# .env.dist
ERP_API_URL=
ERP_API_KEY=
COMMERCE_BASE_URL=

Tip: In CI, inject these as pipeline secrets. A leaked Runtime auth key lets anyone deploy into your workspace.

Know what .aio does

.aio binds this folder to one organisation, project and workspace in Adobe Developer Console. You rarely edit it by hand. You switch workspace with the CLI, which rewrites both .aio and .env:

aio app use ~/Downloads/my-project-Stage.json
aio where
aio rt property get --namespace

aio where prints the org, project and workspace the CLI has selected globally, and aio app use changes that selection for every project on your machine, not only this folder. The deploy itself goes to the namespace in this folder's .env (AIO_runtime_namespace), which is what aio rt property get --namespace prints. Check that one before every deploy to production. It takes a second, and deploying Stage code into Production is the kind of mistake you only want to make once.

Read one action

Every action exports a main function that receives params and returns a response. The generated utils.js gives you helpers for checking required parameters and building error responses.

const { Core } = require('@adobe/aio-sdk')
const { errorResponse, checkMissingRequestInputs } = require('../utils')

async function main (params) {
  const logger = Core.Logger('export-order', { level: params.LOG_LEVEL || 'info' })
  const missing = checkMissingRequestInputs(params, ['ERP_API_URL'], [])
  if (missing) return errorResponse(400, missing, logger)

  logger.info('export-order called')
  return { statusCode: 200, body: { ok: true } }
}
exports.main = main

One folder per action, with its own index.js, keeps actions small and testable on their own.

Spot the extension layout

The Admin UI SDK adds menus and pages inside the Commerce admin, served by your app (episode 9). Apps that extend another Adobe product, such as the Commerce admin through the Admin UI SDK, use extension points. The actions and UI then live under src/<extension>/, each with its own ext.config.yaml, and app.config.yaml includes them:

extensions:
  commerce/backend-ui/1:
    $include: src/commerce-backend-ui-1/ext.config.yaml

Same ideas, different folders. If a starter kit looks unfamiliar, look for ext.config.yaml first.

Check the rest quickly

  • package.json: dependencies, plus scripts the CI templates call. @adobe/aio-sdk bundles the libraries you'll use most: logging, State, Files and events.
  • test/ and e2e/: Jest unit tests run locally with aio app test. Keep them, because CI runs them before deploy.
  • .github/workflows/: templates that run tests on pull requests, deploy to Stage when you merge to main, and deploy to Production on a release. Fill in the secrets they expect, or delete them deliberately.

Tested on: a real Stage workspace. There I've seen aio app use write .aio and the credentials in .env, a $VARIABLE input reach the deployed action, a web: 'yes' action answer on its public URL, and Runtime refuse a request that tried to set a final input: it answered 400 before my code ran. require-adobe-auth I've tested only by building by hand the sequence aio app deploy creates, with Adobe's validator in front of the action: no token, a made-up token, or a valid token without the org header all got 401, and a valid token with the header got through.

Not tested: require-adobe-auth through a real deploy, and the CI templates.

Done!

You can now read any App Builder project. Episode 2 starts one properly, from a boilerplate.

> code for this episodeGitHub · ep1-project-anatomy →

Written by Vishwas Bhatnagar

Technical Architect. Adobe Commerce, marketplaces and AI-assisted engineering.

More about me →

More