microsoft/power-platform-skills / plugins/mobile-apps/skills/create-mobile-app
create-mobile-app
VerifiedUse when the user wants to start a new Power Apps mobile app (Expo / React Native / TypeScript, targeting iOS and Android) from scratch.
references/template-preparation.md
View on GitHub# Template preparation
What `scripts/prepare-mobile-template.js --screens-first` does at Step 3.2 of the screens-first build order, and why.
The skill only runs the script; read this when the script fails, when you change it, or when a later step needs one of the boundaries below.
The script is the only owner of these mutations. It updates identity, removes
only recognized legacy example hooks/query-client files, copies shared helpers
only when missing, verifies that TypeScript inherits the host configuration, and
structurally verifies the root provider/theme/safe-area contract. It preserves
custom navigation, existing helper bytes, `offlineProfile`, provider props, and
the template's `@ts-ignore` generation boundaries. It must preserve
`app.json` byte-for-byte, including protected `powerappsNative` fields and
app-owned extras, plus `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`.
Do not replace runtime IDs with installed package versions.
`--screens-first` adds the two things only this build order needs: the
`POWER_APPS_WEB_PREVIEW` web-output override in the template's `customizeExpoConfig`
hook ([`screens-first.md`](screens-first.md) Step 3.5 explains why), and the data
layer's `src/hooks/data/core.ts`. The data-model-first order runs the script
without the flag, because an `src/hooks/data/` folder makes `screen-builder` and
`/edit-app` treat the app as a data-layer app.
Preparation also copies missing app-local guidance from `template/AGENTS.md`,
`template/CLAUDE.md`, and `template/.github/copilot-instructions.md`. Existing
customer guidance is preserved byte-for-byte; no symlinked destination is
followed. `copiedGuidanceFiles` and `preservedGuidanceFiles` describe the result,
and only actual copies appear in `writtenFiles`. Do not overwrite a preserved
file just to make the default skill routing appear.
**Generated ownership boundary:** Step 3.2 must not create, reset, delete, or
write anything under `src/generated/`. Only Power Apps schema/data-source
generation commands own that directory. A generated file required later is
created by its owning command, never by a placeholder barrel.
The script fails visibly for unsupported root-layout shapes or dangling legacy
imports. Do not fall back to a full-file rewrite or regex patch. After it
returns successfully, Step 3.3 initializes the app.
**Fix 1 — App identity in `app.config.js` and `package.json`**
Substitute the hardcoded template values with wizard answers from Step 2:
| Find | Replace with |
|---|---|
| `const APP_NAME = process.env.APP_DISPLAY_NAME || 'Power Apps Standalone App';` | `const APP_NAME = process.env.APP_DISPLAY_NAME || '<displayName>';` |
| `const APP_SLUG = process.env.APP_SLUG || 'powerapps-standalone-app';` | `const APP_SLUG = process.env.APP_SLUG || '<slug>';` |
| `"name": "powerapps-standalone-app"` | `"name": "<slug>"` |
Bundle ID and scheme are left as template defaults — they are fixed across all dev builds and patched by the wrap pipeline at release time.
**Fix 1b — Verify template-owned development lifecycle scripts**
Manual `npm run dev` remains the development entry point, and npm invokes `predev` before it. The template owns the command bodies for both lifecycle scripts and may change them as the native host evolves. The preparation script's fresh-template check (`verifyLifecycleScripts`) verifies only that both entries exist as non-empty strings; it does not compare, rewrite, or otherwise enforce their command bodies. A missing script fails preparation with `Expected package.json scripts.<name> to be a non-empty command.`
The template's `metro.config.js` delegates to `createPowerAppsMetroConfig` from `@microsoft/power-apps-native-host/config/metroConfig`; that factory installs sanitized Metro terminal and HTTP bundle-failure logging under `.powernative/metro-logs/`. Manual starts and `/debug-app` use the same log source without a process-owning wrapper.
**Fix 2 — Remove only an empty placeholder `power.config.json`**
The preparation script parses `power.config.json` and removes it only when
`environmentId` is empty or missing. A populated file is preserved and later
validated against the approved environment. Do not use an unconditional
delete.
**Fix 3 — Remove recognized legacy examples without touching generated code**
Newer snapshots do not ship the Contacts / Accounts / UserProfile example
hooks or the old app-owned query client. The preparation script removes only
those recognized files when present. It never traverses or mutates
`src/generated/`; generated models, services, schemas, and barrels remain
owned by Power Apps generation commands.
**Do NOT overwrite `app/(app)/home.tsx` here.** The current template ships a
safe-area-aware, semantic-token starter route. The screen-builder replaces it
only when the approved Screen Map assigns that route.
Keep `src/hooks/` itself — screen-builders write new hooks into it.
**Fix 3b — Scan for dangling imports referencing deleted files (back-compat only)**
The preparation script scans `app/` and non-generated `src/` files after
cleanup. Any remaining legacy example import is an explicit failure. Do not
replace whole screens or layouts to make the scan pass; use a supported fresh
template or repair the precise stale import before continuing.
**Fix 6 — Schema generation boundary**
`app/_layout.tsx` imports `schemaMap` from `src/generated/connectorSchemas.ts`, which
is generated by the template's `npm run generate-schemas` script. This builds the
runtime schema map; Power Apps CLI add/refresh/remove commands own source
registrations and generated models/services. Do not generate an empty schema map
during initial scaffold: the template's `@ts-ignore` boundary lets `tsc` validate
the scaffold without that artifact. Metro is stricter than `tsc` - it must resolve the
import to bundle at all - so Step 3.4 runs `npm run generate-schemas` right before Step 3.5 starts the web preview server
starts the web preview, and later steps rerun it after data sources change.
Do NOT hand-write a stub `connectorSchemas.ts` — the generated output has a specific shape that downstream code depends on; a placeholder will break `pa app push`.
**Why `tsc` already passes post-clone (current template, PR #30):** the template's `app/_layout.tsx` and `src/playerConfig.ts` carry `// @ts-ignore` comments above the `power.config.json` and `connectorSchemas` imports specifically so the project type-checks before `power.config.json` and `connectorSchemas.ts` exist. **Never strip these `@ts-ignore` lines** — Fix 8 below preserves them when patching `app/_layout.tsx` to thread the project's `tamaguiConfig` into `PowerAppsProvider`, and any future `Edit` to either file MUST keep them. Removing them resurfaces a `tsc` failure against missing generated files.
**Fix 7 — Seed shared code only when missing**
The preparation script creates the shared source directories and copies each
approved sample helper only when its destination does not exist. Existing
helpers are byte-for-byte preserved, so reruns cannot overwrite user or
builder changes.
**Fix 8 — Thread the project's `tamaguiConfig` and active theme into the host provider**
The template ships `PowerAppsProvider` with host-owned light and dark theme
defaults. Fix 8 ensures the project `tamaguiConfig` and color-scheme-driven
`defaultTheme` are present. It preserves explicit `theme` and `darkTheme`
overrides when an app already has them, but does not add redundant overrides
to a fresh template. Step 9.2 adds explicit themes only when applying generated
brand tokens. Do NOT add an outer `<TamaguiProvider>` — `PowerAppsProvider`
composes it internally and duplicating triggers "useTheme must be used within
a TamaguiProvider" warnings on hot reload.
The preparation script edits the existing root layout structurally. It adds
missing imports and provider props, then wraps `PowerAppsProvider` with
`SafeAreaProvider` only when needed. It does not replace the file and it does
not wrap `<Slot />` with `SafeAreaView`; each rendered route owns its content
edges to avoid double insets.
Key points:
- **Do NOT remove the two `// @ts-ignore` lines.** They keep `tsc` green pre-`pa app init`.
- **Do NOT add an outer `<TamaguiProvider>`** — `PowerAppsProvider` composes it internally.
- **`SafeAreaProvider` wraps the tree** so child screens can call `useSafeAreaInsets()` without a context error. Each route must use `SafeAreaView` or explicit insets for its own visible edges.
- `tamaguiConfig` is imported from `'../tamagui.config'` (the `default export` of `tamagui.config.ts` at project root).
- Import `app.json` and pass it through the `appConfig` prop. `PowerAppsProvider` reads `expo.extra.appInsightsConfig` and enforces its `enabled` opt-in; this explicit app-config boundary is required because the fixed Dev Player does not expose the loaded app's extras through `Constants.expoConfig`. Never print the connection string, copy it to `memory-bank.md`, or include it in a summary.
- `defaultTheme` flips between light/dark via `useColorScheme()`. `/design-system --add-dark-mode` later wires per-token dark variants.
**Fix 4 — Shared TypeScript configuration**
The current template extends
`@microsoft/power-apps-native-host/config/tsconfig`. That host configuration
owns the runtime package paths. Preserve the selected template's explicit
project-rooted aliases when present (including newer templates); do not replace
its entire `compilerOptions`. Older templates inherit the six shared-code aliases:
`@/components`, `@/hooks`, `@/utils`, `@/tokens`, `@/generated`, and
`@/native`. The preparation script verifies inheritance without deleting
template-local aliases. Expo Metro consumes the resulting
effective TypeScript paths, so no Babel alias plug-in is required.
`<Gradient>` (used by `components/index.tsx`) requires `expo-linear-gradient`. Verify it in the resolved release; do NOT install a missing native module to repair an older binary. Missing support blocks this capability and requires another verified release.
Do not run `npm install` inside Step 3.2 — in template-only mode dependencies must already be installed before the skill starts.
> **Install note (current template):** The template does not read `power.config.json` during `npm install`. `npm run generate-schemas` first runs at Step 3.4, because the web preview's bundle needs the schema map and the preview server starts right after.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |