On most Adobe Commerce (Magento 2) upgrades, the expensive part is the same: custom code that reached into core classes. Plugins on methods that changed signature. Preferences on classes that got refactored. Observers that assumed an event fired once. App Builder exists to cut that dependency. Your code runs on Adobe's infrastructure, outside the Commerce process, and talks to it through events, webhooks and APIs.
That's the promise. I want to find out whether it holds, starting from zero and in public, as part of learning the rest of the Adobe stack.
TL;DR
- Move an Adobe Commerce customisation to App Builder when it reacts to something and talks to another system, runs as back-office work on a schedule, has to survive upgrades untouched, or holds logic other systems need too.
- Keep it as a module when it changes money inside the request, renders storefront output on a hot path, is a five-line tweak, or needs data no API exposes.
- On Adobe Commerce as a Cloud Service the choice is made: it doesn't accept custom PHP modules.
How this series works
The foundations come first: Episodes 0 to 10. This episode covers when App Builder is the right tool at all. Episode 1 opens up a project and its key files. Episode 2 starts a real integration from Adobe's starter kit. Episode 3 maps an Adobe Commerce module's cron, config and tables to their App Builder equivalents. Episode 4 adds a real database, and Episode 5 sends the logs where your team already looks. Episodes 6 to 9 replace the classic Adobe Commerce extension points: an observer becomes an event, a plugin becomes a webhook, several APIs become one API Mesh endpoint, and an admin grid becomes an Admin UI SDK page. Episode 10 puts them together to port a small module. That's the ground you need before anything else makes sense.
Then it becomes a developer log. I learn the rest in short sessions with Claude Code and publish a post whenever a session teaches me something worth writing down. Each post has the same shape:
- The goal: one small thing I set out to do.
- What I asked Claude Code: the prompts that moved the work forward.
- Where the AI was wrong: the invented CLI flag, the outdated config, the confident answer that turned out to be wrong, and how I caught it.
- What actually worked: the code, marked by what was tested and what wasn't.
- Lessons: about App Builder, and about building with an AI assistant.
The code lives in a public repository, app-builder-learning-log, with a tag for each episode that has code, so you can check out exactly where I was and follow along. Each piece is marked by how far it's been tested: unit-tested, or verified on a real workspace.
Episode 0 has no code. It's the question to answer before writing any: when should an Adobe Commerce customisation leave the monolith at all?
What App Builder actually is
Adobe Developer App Builder is a platform for apps that run on Adobe I/O Runtime, a serverless environment based on Apache OpenWhisk. You write JavaScript actions. Optionally you add a React UI. Adobe hosts the compute, storage and CDN. For a Commerce developer, four building blocks matter, and each gets its own episode later:
- Adobe I/O Events: Commerce publishes an event, such as an order placed or a product saved, and your action receives it later. This is the out-of-process observer.
- Webhooks: Commerce calls your action at a specific point and waits for the answer, for example to validate a cart. This is the out-of-process plugin.
- API Mesh: one GraphQL endpoint that combines Commerce with other APIs.
- Admin UI SDK: menus and pages inside the Commerce admin, served by your app.
The shift is simple to state and easy to underestimate. Your code stops running inside Adobe Commerce's request. It either reacts after the fact, or Adobe Commerce pays a network hop to ask it a question.
If you're on Commerce as a Cloud Service, the choice is made
Adobe Commerce as a Cloud Service (ACCS), the SaaS edition, doesn't accept custom PHP modules. Extensibility there means App Builder, API Mesh, events and webhooks, full stop. If a SaaS move is anywhere on your roadmap, every module you write today on PaaS or on-premise is a module you'll rewrite later. That alone is a reason to build new integrations out of process now.
Move it out when
- It reacts to something and talks to another system. Order to ERP, product to PIM, customer to CRM, offers to a marketplace. This is App Builder's home ground. The integration no longer slows down checkout, and a failure in the other system doesn't throw an exception in front of a customer.
- It's back-office work on a schedule. Exports, reconciliations, clean-ups, "alert me when orders get stuck". App Builder has scheduled actions (episode 3), so
crontab.xmldoesn't have to be the answer. - It has to survive upgrades untouched. If the logic doesn't need Adobe Commerce's internals, keeping it out of the Adobe Commerce codebase means an upgrade can't break it.
- Other systems need the same logic. An action is reachable from Commerce, AEM, a mobile app or a partner, without going through Adobe Commerce.
Keep it as a module when
- It changes money inside the request. Price calculation, totals collectors, tax adjustments. Webhooks can influence some of these, but if every cart update would wait on a network call, keep it in process.
- It renders storefront output on a hot path. Template and layout changes, block output, anything on every page view. A network hop per render is the wrong trade.
- It's a five-line tweak. A small plugin that will never touch another system costs less as a module than as a deployed app with its own pipeline, credentials and monitoring.
- It needs data App Builder can't see. If the logic depends on joins across a dozen Adobe Commerce tables with no API that exposes them, moving it out means building that API first. Count that cost honestly.
Move the integration. Keep the transaction.
The three questions I ask
- Does Adobe Commerce need the answer before it can continue? No: it's an event. Yes, and the answer is a quick yes-or-no: maybe a webhook. Yes, and it touches money or rendering on every request: a module.
- Would an upgrade break it? If it plugs into core classes, moving it out removes the risk.
- Who else needs it? If the honest answer is "other systems too", it belongs outside.
What it costs you
App Builder isn't free in effort. You gain a second deployment pipeline, a second set of credentials, logs in another place, and network latency you now have to monitor. Your team needs JavaScript and serverless habits on top of PHP. For one integration that overhead is noticeable; for a platform with twenty integrations, it's the price of upgrades that stop hurting.
If I could move one thing first, it would be an order export to an ERP. On the projects I know, it runs inside Adobe Commerce as an observer with a cron job for retries. It adds time to every order placed, it breaks when an upgrade changes the order classes, and nothing in it needs Adobe Commerce's internals. It only needs the order data, which an event delivers anyway.
The plan
- Ep 1: what
aio app initputs on disk. - Ep 2: starting from a boilerplate.
- Ep 3: cron, config and custom tables, once your code leaves Adobe Commerce.
- Ep 4: Database Storage for a sync log you can query.
- Ep 5: forwarding action logs to New Relic.
- Ep 6: replacing an observer with a Commerce event.
- Ep 7: replacing a plugin with a webhook.
- Ep 8: one API Mesh endpoint, one Cache-Control.
- Ep 9: a page in the Commerce admin with the Admin UI SDK.
- Ep 10: porting a small Adobe Commerce module, end to end.
- Developer log: calling Commerce from an action, testing, CI/CD and retries. The order follows what I need next, and the log will say when it changes.
Done!
No code in this episode, on purpose. Episode 1 opens a real project: what aio app init actually creates, and the three files that decide how everything behaves.
