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.
| File | What it decides | In git? |
|---|---|---|
app.config.yaml | The manifest: actions, web UI, triggers, rules, extensions | Yes |
.env | Runtime namespace and auth key, plus every secret your actions read | No. Commit .env.dist with empty values |
.aio | Which org, project and workspace this folder is bound to | No (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.inputsare passed to the action asparams. A value starting with$is read from.envat deploy time.require-adobe-auth: truemeans callers need a valid Adobe token and thex-gw-ims-org-idheader.aio app deployenforces it by putting Adobe's validator in front of your action; the annotation on its own changes nothing at runtime, so an action created withaio rt action createand 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: truestops 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.limitssets 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-sdkbundles the libraries you'll use most: logging, State, Files and events.test/ande2e/: Jest unit tests run locally withaio 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 tomain, 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.
