create-code-app

**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** - Cross-cutting concerns. **References:** - [prerequisites-reference.md](./references/prerequisites-reference.md) - Prerequisites and required permissions - [troubleshooting.md](./references/troubleshooting.md) - Common issues, npm scripts, resources # Create Power Apps Code App ## Workflow 1. Prerequisites → 2. Gather Requirements → 3. Plan → 4. Scaffold → 5. Initialize → 6. Build & Deploy (baseline) → 7. Add Data Sources → 8. Implement App → 9. Final Build & Deploy → 10. Summary --- ### Step 0: Check Memory Bank Check for `memory-bank.md` per [shared-instructions.md](../../shared/shared-instructions.md). Skip completed steps. ### Step 1: Validate Prerequisites Run prerequisite checks **first** -- no point gathering requirements if the environment isn't ready. See [prerequisites-reference.md](./references/prerequisites-reference.md) for details. Check Node.js and Git (runs natively in bash): ```bash node --version # Must be v22+ git --version # Optional but recommended ``` - **Missing Node.js**: Report "Install Node.js v22+ from https://nodejs.org/" and STOP. - **Node.js below v22**: Report "Node.js 22+ is required. Please upgrade or switch with `nvm use 22`." and STOP. - **Missing Git**: Report "Recommended but optional." Continue if approved. - **All present**: Report versions and proceed. ### Step 2: Gather Requirements **Skip questions the user already answered in their initial instruction.** **If the user has not described what they want to build** (i.e., `/create-code-app` was invoked with no arguments or a vague prompt), start with a single open-ended question before asking anything else: > "What would you like to build? Describe it in your own words — what it does, who uses it, and what problem it solves." Wait for their answer. Use it to frame all follow-up questions. Do NOT present a multiple-choice list of app types before the user has described their idea. Once you have their description: 1. Confirm the app name and clarify the purpose if needed 2. Ask about data -- focus on **what the app needs to do**, not specific technologies: - "What data does your app need to work with?" (e.g., company emails, project tasks, custom business records) - "Does your app need to search existing information, manage its own data, or both?" - Based on their answers, recommend the best approach: - **Store and manage custom business data** (tables, forms, CRUD) → Dataverse (`/add-dataverse`) - **Interact with specific services** (send emails, post messages, manage files) → the appropriate connector - **Search M365 data or get AI-powered answers** (emails, files, people, company knowledge) → Work IQ (`/add-workiq`) - If they mention existing Dataverse tables, SharePoint lists, or connectors by name, use those directly 3. Ask about UI requirements: key screens, layout, interactions, theme preference 4. Ask any clarifying questions now -- resolve all ambiguity before entering plan mode ### Step 3: Plan 1. Enter plan mode with `EnterPlanMode` 2. Design the full implementation approach: - Which `/add-*` skills to run for data sources - App architecture: components, pages, state management - Feature list with priority order 3. Present plan for approval, include `allowedPrompts` from [prerequisites-reference.md](./references/prerequisites-reference.md) 4. Exit plan mode with `ExitPlanMode` when approved ### Step 4: Scaffold Ask the user for a folder name. Default to `powerapps-{app-name-slugified}-{timestamp}` if they don't have a preference. **IMPORTANT: Use `npx degit` to download the template. Do NOT use `git clone`, do NOT manually create files, do NOT download from GitHub UI. `degit` downloads the template without git history.** ```bash npx degit microsoft/PowerAppsCodeApps/templates/vite {folder} --force cd {folder} npm install npm install --save-dev "@microsoft/power-apps-cli@^1.3.0" ``` **Notes:** - Use `--force` to overwrite if the directory already has files (e.g., `.claude` from a planning session) - If targeting an existing directory, use `.` as the folder name: `npx degit microsoft/PowerAppsCodeApps/templates/vite . --force` - If `npx degit` fails (network issues, npm not found), retry once, then ask the user to run manually - The template doesn't include the Power Apps CLI, so install it into the project as a dev dependency (not globally). Version 1.3.0 or later lets the connector skills find or create connections without asking for a connection ID. Verify: `package.json` exists, `node_modules/` created, and `@microsoft/power-apps-cli` is listed in `devDependencies`. Then resolve the CLI per [cli-binary.md](../../shared/cli-binary.md); it should resolve to `pa` with `PA_INLINE_CONNECTIONS=yes`. ### Step 5: Initialize > Resolve the CLI first (see [cli-binary.md](../../shared/cli-binary.md)): run as `$PA app init …` (`npx --no-install pa …`), never a bare `pa`. On `power-apps`-only projects, translate to `power-apps init …` (the `init` verb and its `-n`/`-e` flags are unchanged on both binaries). ```bash pa app init -n '{user-provided-app-name}' -e <environment-id> ``` **Finding the environment ID:** It's the GUID in the make.powerapps.com URL: `https://make.powerapps.com/environments/<env-id>/home`. If you don't pass `-e`, the CLI will prompt for it interactively. **Authentication:** On first run, a browser window opens for Microsoft sign-in. Complete the login and the command continues. No separate auth setup is needed. See [preferred-environment.md](../../shared/preferred-environment.md) for environment selection details. **`pa app init` failure:** - Non-zero exit: Report the exact output and STOP. Do not continue to Step 6. - "environmentId not found" or environment validation error: Verify the environment ID is correct and the user has maker permissions in that environment, then retry. - Example: _"The `pa app init` command failed: `[error text]`. Please check that environment ID `32a51012-...` is correct and that you have maker permissions in that environment."_ **Critical:** Read `power.config.json` after init and verify `environmentId` is set correctly. ### Step 6: Build & Deploy (baseline) > **Pre-approved**: This baseline deploy is part of the scaffold flow and does not require a separate confirmation prompt. Build and deploy the bare template to verify the pipeline works before adding data sources. ```bash npm run build ``` Verify `dist/` folder created with `index.html` and `assets/`. > Deploy via the resolved CLI: `$PA app push` on `pa`, or `power-apps push` on `power-apps`-only projects (see [cli-binary.md](../../shared/cli-binary.md)). ```bash pa app push ``` **Capture app URL** from output: `https://apps.powerapps.com/play/e/{env-id}/app/{app-id}` **Common deploy errors:** See [troubleshooting.md](./references/troubleshooting.md). **Create or update `memory-bank.md` in the project root now** -- don't wait until the end. Include: - Project path, app name, environment ID, app URL - Completed steps: scaffold, init, baseline deploy - Data sources planned (from Step 2) This ensures progress is saved even if the session ends unexpectedly. ### Step 7: Add Data Sources Invoke the `/add-*` skills identified in the plan (Step 3). Run each in sequence. **Pass context as arguments** so sub-skills skip redundant questions (project path, connector name, etc.): | App needs to... | Invoke | | ------------------------------------------ | ------------------ | | Store/manage custom business data | `/add-dataverse` | | Track work items, bugs, pipelines | `/add-azuredevops` | | Send or read Teams messages | `/add-teams` | | Read/write Excel spreadsheet data | `/add-excel` | | Upload, download, or manage files | `/add-onedrive` | | Work with SharePoint lists or docs | `/add-sharepoint` | | Send emails, read inbox, manage calendar | `/add-office365` | | Invoke a Copilot Studio agent | `/add-mcscopilot` | | Search M365 data or get AI-powered answers | `/add-workiq` | | Connect to another service | `/add-connector` | **Connections:** every connector except Dataverse needs a connection. With the CLI 1.3.0+ installed in Step 4, the connector skills find or create it themselves: they tell the user first that a connection may be created with the user's account, and ask before running `--use-sso` or `pa connection create`. See [connector-reference.md](../../shared/connector-reference.md#connections). Each `/add-*` skill runs `npm run build` to catch errors. Do NOT deploy yet. **If no data sources needed:** Skip to Step 8. ### Step 8: Implement App **This is the core step.** Build the actual app features described in the plan from Step 3. 1. **Review generated services**: Use `Grep` to find methods in generated service files (they can be very large -- see [connector-reference.md](../../shared/connector-reference.md#inspecting-large-generated-files)). Do NOT read entire generated files. 2. **Build components**: Create React components for each screen/feature in the plan 3. **Connect data**: Wire components to generated services (use `*Service.getAll()`, `*Service.create()`, etc.) 4. **Apply theme**: Use the user's theme preference (default: dark theme per development standards) 5. **Iterate with user**: Show progress, ask for feedback, adjust as needed **Key rules:** - Use generated services for all data access -- never use fetch/axios directly - Read [dataverse-reference.md](../add-dataverse/references/dataverse-reference.md) if working with Dataverse (picklist fields, virtual fields, lookups have critical gotchas) - Remove unused imports before building (TS6133 strict mode) - Don't edit files in `src/generated/` unless fixing known issues ### Step 9: Final Build & Deploy ```bash npm run build ``` Fix any TypeScript errors. Verify `dist/` contains the updated app. Ask the user: _"Ready to deploy to [environment name]? This will update the live app."_ Wait for explicit confirmation before proceeding. ```bash pa app push ``` ### Step 10: Summary Provide: - App name, environment, app URL, project location - What was built: features, data sources, components - Next steps: how to iterate (`npm run build && pa app push`), how to add more data sources - Suggest what else the app could do: - `/add-datasource` -- add another data source (describe what you need, and the plugin will recommend the best approach) - `/add-dataverse` -- store and manage custom business data - `/add-azuredevops` -- track work items, bugs, and pipelines - `/add-teams` -- send and read Teams messages - `/add-sharepoint` -- work with SharePoint lists or documents - `/add-office365` -- send emails, manage calendar - `/add-workiq` -- search M365 data or get AI-powered answers about company info - `/add-connector` -- connect to any other service - Manage at https://make.powerapps.com/environments/<environment-id>/home ### Update Memory Bank Update the memory bank (created in Step 6) with final state: - All completed steps (scaffold, data sources, implementation, deploy) - Features implemented and components created - Data sources connected - Suggested next steps --- ## Example Walkthroughs These walkthroughs show the full sequence from user request to final output — commands run, files changed, and the verbatim summary format the assistant should use. --- ### Example 1: Create a Task Tracker App with Dataverse **User request:** > "Build me a simple task tracker that stores tasks in Dataverse. I want to add tasks, mark them complete, and see a list." **Commands run (in order):** ```bash # Step 1: Prerequisites node --version # → v22.4.0 # Step 4: Scaffold npx degit microsoft/PowerAppsCodeApps/templates/vite powerapps-task-tracker-20260302 --force cd powerapps-task-tracker-20260302 npm install npm install --save-dev "@microsoft/power-apps-cli@^1.3.0" # Step 5: Initialize (browser login prompt on first run; CLI prompts for env ID if -e omitted) pa app init -n 'Task Tracker' -e <environment-id> # Step 6: Baseline deploy (pre-approved as part of scaffold flow) npm run build pa app push # → App URL: https://apps.powerapps.com/play/e/32a51012-.../app/<app-id> # Step 7: Add Dataverse (via /add-dataverse) pa app add data-source --connector dataverse --table cr123_task npm run build # verify connector — no deploy yet # Step 9: Final deploy (requires user confirmation) npm run build pa app push ``` **Files changed:** | File | Change | | --------------------------------------------- | ----------------------------------------------------- | | `package.json` | Updated — adds `@microsoft/power-apps-cli` to `devDependencies` | | `power.config.json` | Created by `pa app init` — contains `environmentId` | | `src/generated/models/Cr123_tasksModel.ts` | Generated by `pa app add data-source`, named after the table's entity set name (here `cr123_tasks`) | | `src/generated/services/Cr123_tasksService.ts` | Generated by `pa app add data-source` | | `src/components/TaskList.tsx` | Created — renders task list with status filter | | `src/components/AddTaskForm.tsx` | Created — form to add new tasks | | `src/App.tsx` | Updated — wires components to `Cr123_tasksService` | | `memory-bank.md` | Created in Step 6, updated at the end | **Final assistant summary (verbatim format):** ``` Task Tracker is live. App: Task Tracker Environment: <your-environment-name> (<environment-id>) URL: https://apps.powerapps.com/play/e/<environment-id>/app/<app-id> Project: ~/powerapps-task-tracker-20260302/ What was built: - Task list view with Active / Completed filter - Add task form (title, description, due date) - Mark complete / delete actions