Home › Ionic / Capacitor › Ionic + Capacitor AGENTS.md

Ionic + Capacitor AGENTS.md

AGENTS.md for Ionic 8 apps with Capacitor (Angular, React, or Vue): native plugins, platform sync, and mobile UX rules.

AGENTS.mdIonic / Capacitor

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Ionic + Capacitor

## Commands
- Web dev: `ionic serve` (or `npm run dev`) · Build: `npm run build` · Native sync: `npx cap sync` · Open: `npx cap open ios|android`
- Live reload on device: `ionic cap run android -l --external` (ask before running on a device).
- Check `package.json` for Ionic and Capacitor majors; plugins must match the Capacitor major.

## Rules
- UI with Ionic components (`ion-page`, `ion-header`, `ion-content`, `ion-list`, `ion-item`) so platform styling, safe areas, and gestures work. Don't hand-roll headers or scroll containers.
- Navigation with the framework's Ionic router integration (`IonRouterOutlet`, `ion-tabs`); keep page lifecycle hooks (`ionViewWillEnter`) for refreshes that must run on back navigation.
- Native features through official `@capacitor/*` plugins (Camera, Filesystem, Preferences, Haptics, Push Notifications). Check `Capacitor.isNativePlatform()` and provide web fallbacks.
- Request permissions just in time (`Camera.requestPermissions()`), and add the usage descriptions to `Info.plist` / `AndroidManifest.xml`.
- Secrets/tokens in secure storage (a Keychain/Keystore plugin), not `Preferences` or `localStorage`.
- Run `npx cap sync` after adding plugins or changing web build output; commit native project changes deliberately.
- Performance: virtual scrolling for long lists, lazy-loaded routes, compressed images.
- Handle the hardware back button and keyboard (`@capacitor/keyboard`) on Android.

## Don't
Don't edit generated native files under `ios/App/App/public` or `android/app/src/main/assets/public`.

## Done
Web build, unit tests, and lint pass; `npx cap sync` runs cleanly.