appbuilder-project-init

name appbuilder-project-init description Initialize an Adobe App Builder project end-to-end and prepare the machine to build one. Creates the Console project and workspace, subscribes APIs (including those needing a product profile), maps intent to the right template, runs non-interactive `aio app init`, and guides post-init customization. Use whenever the user mentions creating an App Builder app, scaffolding a project, `aio app init`, an Experience Cloud extension, adding actions or web assets, or creating a Console project/workspace — even without saying "App Builder". Also for SPA templates, AEM extensions, API Mesh, Asset Compute workers, and MCP servers. Also covers first-time machine/CLI setup (Node 20, aio CLI install, `aio login`, IMS org, stage vs prod) and debugging setup/init failures — `ERR_REQUIRE_ESM`, empty `aio console org list`, `451 accept developer terms`, template not found, init hangs, or Node/npm and post-init build errors. metadata {"category":"project-initialization"} license Apache-2.0 compatibility Requires aio CLI (Adobe I/O CLI) — install or refresh with `npm install -g @adobe/aio-cli` so the bundled plugins (`aio-cli-plugin-console`, `aio-cli-plugin-app`, etc.) are current. Node.js 18+ (Node 24 supported on Stage runtimes). Bash shell. allowed-tools Bash(aio:*) Bash(npm:*) Bash(node:*) Read Write App Builder Project Initialization Maps user intent to the right Adobe App Builder template and runs non-interactive aio app init . Default: @adobe/generator-app-excshell (SPA + actions). For headless/bare projects, use init-bare . When a Developer Console project / workspace / API subscription does not yet exist, this skill walks the agent through creating them non-interactively by calling aio console … directly — see the Bootstrap section and references/bootstrap.md . The latest @adobe/aio-cli bundle exposes non-interactive aio console project create / workspace create / api list / workspace api add (with --license-config for services that require a product profile), and non-interactive aio app init --org/--project/--template-options . Together they remove every blocking "open the Developer Console UI and click" step from the agentic setup path. Just install the latest CLI ( npm install -g @adobe/aio-cli ) and use them. Machine setup (first time) Do this once per machine before initializing a project — plus a login per environment. If the CLI is already installed and you're logged in, skip to Bootstrap below. 1. Node 20 App Builder needs Node 20 (npm ships with it). Check what's active: node -v → expect v20.x . Have nvm? nvm install 20 && nvm use 20 && nvm alias default 20 so new shells keep it. If several Node versions are installed, the active one must be 20. No Node / no nvm? Install nvm, then Node 20: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # reopen the shell, then: nvm install 20 && nvm use 20 && nvm alias default 20 (Alternatives: brew install node@20 , or the official installer at nodejs.org.) Older Adobe docs say Node 18 — use 20 . A global aio belongs to whichever Node was active when you ran npm i -g ; if you switch Node versions the old aio won't be on PATH. Symptom of a mismatch: aio dies with SyntaxError: Unexpected token '??=' (a pre-20 Node parsing the Node-20 aio ) — fix with nvm use 20 and reinstall aio there. 2. Install the aio CLI + log in npm install -g @adobe/aio-cli # on Node 20 aio login # opens a browser; `aio login -f` forces a fresh prompt aio where # confirm the correct IMS org/context aio console org list # list orgs and their IDs (then `aio console org select <id>` if needed) Tokens are stored by the CLI automatically; a normal aio login lasts hours/days — one login per session, not per command. Confirm the correct IMS org — wrong-org is the most common setup mistake. 3. Stage vs prod The default environment is prod . To target stage , set the env var and re-authenticate: export AIO_CLI_ENV=stage aio logout && aio login Unset the variable (or open a new shell) to return to prod. The stage CLI talks to the stage Console ( developer-stage ). Logging in without a browser (CI / no human) Import creds: in the Developer Console open the workspace → Download all → console.json , then aio app init <app> --import path/to/console.json (fills .env / .aio — treat console.json as a secret, gitignore it). CI / pipeline: add an OAuth Server-to-Server credential to the workspace; aio and Runtime authenticate from the client id/secret with no human. Don't script SSO/MFA headlessly. Bootstrap the Developer Console (project, workspace, APIs) If the user is starting from zero — no Developer Console project yet, or an existing project that is missing a workspace or API subscription — bootstrap that state before aio app init . Otherwise aio app init / aio app use / aio app deploy have nothing to wire the local app to. The full bootstrap is just aio commands; call them directly , not through a wrapper script. They are already non-interactive in the recent plugin releases, and per-step calls let you react to "already exists" or "needs a product profile" responses without baking those decisions into bash. Preflight Make sure the CLI is current — that's what brings in the non-interactive Console + app init commands: npm install -g @adobe/aio-cli aio --version Don't try to assert specific plugin versions; just take the latest. If a console or app subcommand below is rejected as "command not found" or "unknown flag" after this, the CLI install genuinely failed (PATH issue, permissions, registry mirror) — fix the install rather than working around it. Confirm an org is selected (or pass --orgId on every command below): aio console org list --json # if needed, then: aio console org select <orgId> Decision rule User state Next action "Create a project + workspace + add APIs from scratch" Run the bootstrap chain (project → workspace → APIs), then aio app init . Project exists, workspace missing Skip project-create. Run aio console workspace create , then optionally aio console workspace api add . Project + workspace exist, only need to add an API Run aio console api list to discover service codes, then aio console workspace api add . Everything already wired Skip bootstrap. Go straight to Initialize via Script . Always check what already exists with aio console project list --json and aio console workspace api list --projectName <p> --workspaceName <w> --json before creating — these commands fail loudly on "already exists" and there is no built-in idempotency. The bootstrap chain (raw commands) Step 1 — create the Console project: aio console project create -n my-project --json # optional: -t "Title" -d "Description" -o <orgId> Step 2 — create a workspace inside it ( Stage is the conventional first non-Production workspace; pick a more descriptive name in long-lived shared projects): aio console workspace create \ --projectName my-project \ --name Stage \ --json # optional: --orgId <orgId> --title "Stage workspace" Step 3 — discover and subscribe the APIs the app needs: aio console api list --json # see all service codes available to the org # entries flagged for whether they need a product profile # Free-tier service: aio console workspace api add \ --projectName my-project \ --workspaceName Stage \ --service-code AdobeIOManagementAPISDK \ --json # Service that requires a product profile: aio console workspace api add \ --projectName my-project \ --workspaceName Stage \ --service-code AdobeAnalyticsSDK \ --license-config AdobeAnalyticsSDK=AnalyticsProductionProfile \ --json --service-code accepts a comma-separated list to subscribe several free-tier services in one call. --license-config is repeatable when several profile-bound services are added together. Recover from per-step failures Failure What to do project create fails with "already exists" Read aio console project list --json , reuse the existing project's name, and continue at step 2. workspace create fails with "already exists" List workspaces with aio console workspace list --projectName <p> --json and continue at step 3. workspace api add returns "product profile required" The service code requires --license-config . Ask the user (or the org admin) for the profile name and retry with --license-config CODE=PROFILE . Any step returns an org-selection error Pass --orgId <id> explicitly, or aio console org select <id> once before retrying. Wire the local app to the bootstrapped state Two equivalent ways to point a fresh aio app init at the project/workspace you just created: Pass them as flags to init itself (cleanest): skills/appbuilder-project-init/scripts/init.sh init \ "@adobe/generator-app-excshell" ./my-project \ --org <orgId> --project my-project The wrapper passes --org / --project / --template-options straight through to aio app init , on top of the existing -y --no-login --no-install flags. Run aio app use after init (works on any plugin version): cd ./my-project aio app use --no-input # adopts the currently selected project/workspace, no prompts Either route ends with the local .aio and .env pointing at the workspace you just bootstrapped, so aio app deploy publishes to the right namespace. Fast Path (for clear requests) When the user's intent maps unambiguously to a single template — for example, they name a template directly or describe an app that clearly matches exactly one entry below — skip straight to Initialize via Script below. Use the matched template and any project name the user provided (or a sensible default). Examples of fast-path triggers: "Create an App Builder app using @adobe/generator-app-excshell " → use that template, run init "Set up an Asset Compute worker" → maps unambiguously to @adobe/generator-app-asset-compute , run init "Create a new App Builder app" (no specifics) → defaults to @adobe/generator-app-excshell , run init "Initialize a bare project" → use init-bare , run init If there is any ambiguity — multiple templates could fit, or the user's constraints are unclear — use the full template decision table and workflow below. Template Decision Table Pick the template that matches the user's intent. When unclear, default to @adobe/generator-app-excshell . User wants Template SPA with actions + React UI @adobe/generator-app-excshell AEM Content Fragment Console extension @adobe/aem-cf-admin-ui-ext-tpl AEM React SPA (WKND-based) @adobe/generator-app-aem-react Adobe API Mesh (GraphQL) @adobe/generator-app-api-mesh Asset Compute custom worker @adobe/generator-app-asset-compute Remote server on App Builder @adobe/generator-app-remote-mcp-server-generic Bare / from-scratch project (no pre-scaffolded actions or UI) init.sh init-bare For a headless/backend-only request, prefer init-bare when possible. If the user still needs a template that generates UI files, plan a post-init cleanup so the final project has no web-src frontend directory or web manifest wiring. Initialize via Script The aio app * wrappers go through a single script: scripts/init.sh . (Console bootstrap commands are called directly — see the Bootstrap section above for the rationale.) Note: The path to this skill's scripts may be skills/ , .augment/skills/ , or .github/skills/ depending on your platform and repository layout. Adjust the prefix in the commands below accordingly. With a template: skills/appbuilder-project-init/scripts/init.sh init "@adobe/generator-app-excshell" ./my-project With a template, fully wired to a specific Console org/project (no post-init aio app use needed): skills/appbuilder-project-init/scripts/init.sh init \ "@adobe/generator-app-excshell" ./my-project \ --org <orgId> --project my-project --org , --project , --template-options (base64-encoded JSON), and --no-config-validation are passed straight through to aio app init . Use the latest @adobe/aio-cli so they're all recognised; --no-config-validation is the escape hatch for the rare case where a partial scaffold shouldn't yet have to pass schema validation. Bare project (no template): skills/appbuilder-project-init/scripts/init.sh init-bare ./my-project Use init-bare only when the user explicitly wants to configure everything from scratch. In that case, "bare" means the generated project should stay minimal: app.config.yaml exists with an empty or minimal application.runtimeManifest package.json exists with only the basic project dependencies No pre-scaffolded src/ , web-src/ , or actions/ directories Why this matters: if the user asked for a bare project, pre-generated actions or web assets contradict that intent and remove the clean starting point they requested. The script outputs JSON with success , path , and output fields. Check success before proceeding. Full Workflow (for ambiguous or complex requests) Step 1 — Gather intent Ask the user (or infer from conversation context): Question Examples What type of app? SPA shell, headless API, AEM extension, Asset Compute worker, API Mesh, remote server Needs a UI? Yes (React Spectrum in ExC Shell), No (actions only) Extension point? dx/excshell/1, aem/cf-console-admin/1, dx/asset-compute/worker/1, or N/A Additional actions? Names and purposes of custom actions beyond the default Console state? Existing project + workspace? Or do we need to create them and subscribe APIs first? APIs needed? e.g. Adobe I/O Management, Analytics, Target — including any that require a product profile If the user simply says "create an App Builder app" with no specifics, default to @adobe/generator-app-excshell . If the Console state is "from scratch" or unknown, run the Bootstrap the Developer Console flow before continuing to template selection. See references/bootstrap.md for the full agentic bootstrap playbook. Step 2 — Select template Consult the Template Decision Table above and references/templates.md to map the user's intent to a template. Step 3 — Initialize, customize, validate Follow the Initialize via Script , Post-init customization , and Validate sections below. Post-init Customization Consult references/templates.md for template-specific post-init guidance. Common tasks: Install dependencies — Run npm install in the project directory. The init script uses --no-install to keep initialization fast, but dependencies are required before building or testing. For API Mesh projects, verify mesh.json is at the project root — After aio app init with @adobe/generator-app-api-mesh , confirm ./mesh.json exists before treating the scaffold as ready. If the file only exists at node_modules/@adobe/generator-app-api-mesh/templates/mesh.json , copy it into place with cp node_modules/@adobe/generator-app-api-mesh/templates/mesh.json ./mesh.json . The file under node_modules/ is the generator's template source, not the project's active API Mesh configuration. Then customize the root mesh.json with the user's real source handlers; for multi-backend scenarios, configure at least two handlers. Clean up bare-project scaffolding if needed — After init-bare , inspect the generated project. If the initializer created actions/ , src/ , or web-src/ , remove those directories before continuing. A bare project should not keep auto-generated action code or web assets. Headless cleanup after template init — If the user wants a headless project with no frontend , delete any generated UI directory after aio app init : rm -rf web-src/ or the template-specific path such as rm -rf src/<extension>/web-src/ . Then remove matching web-src config from app.config.yaml or ext.config.yaml if present, especially web: web-src and operations.view / impl: index.html entries. This avoids unnecessary frontend build artifacts and stale manifest wiring in a backend-only project. Add actions — If the user later wants custom actions, run cd ./my-project && skills/appbuilder-project-init/scripts/init.sh add-action "my-action" . Add web assets — Only if the user later decides the bare project needs a UI, run skills/appbuilder-project-init/scripts/init.sh add-web-assets . Edit ext.config.yaml directly — Customize action definitions: Set runtime: nodejs:22 for production. Stage workspaces also accept runtime: nodejs:24 . Add inputs: for environment variables the action needs Set annotations.require-adobe-auth: true if the action needs IMS tokens Set web: 'yes' or web: 'raw' depending on HTTP access needs Edit app.config.yaml — For multi-extension projects, add $include entries. Apply action boilerplate — Use the appbuilder-action-scaffolder skill's boilerplate pattern for production-ready action code with logging, input validation, and error handling. Validate Verify the project structure by checking these items directly: app.config.yaml ** exists** and contains valid YAML All $include paths resolve to real files