2001105254-netizen/RacePulsePH / .agents/skills/capacitor-android-architect
capacitor-android-architect
VerifiedConvert React Native or React applications into production-ready Capacitor Android apps with optimal performance and native integration. Use when the user asks to convert React Native to Capacitor, migrate a mobile app to Capacitor, wrap a React or React Native Web project into an Android APK/AAB, replace React Native modules with Capacitor plugins, or optimize a Capacitor Android build.
Capacitor Android Architect
Convert React Native or React codebases into store-ready Capacitor Android applications using Vite bundling, native Capacitor bridges, and Android WebView optimization. In this repository, maintain the existing Capacitor v8 Android shell (capacitor.config.ts, android/, npm run android:sync).
Load with: antislop, antislop-layoutmobile. Related: racepulse-responsive-ui, racepulse-release-engineering, racepulse-delivery-performance. Rules upheld: C-1, C-2, C-4, C-5, R-02, R-03, R-26, R-33, R-35, R-36. Details: migration workflow and Android hardening.
Architectural Reality Check
Clarify the build path with the user before migrating files:
- Direct React Native Android build: React Native already compiles to native Android Views (
android.view.*) without Capacitor. If the user only needs an Android APK or App Bundle (.aab) from an existing React Native project, advise runningnpx expo run:androidorcd android && ./gradlew bundleReleasedirectly. - Path A (React Native Web Adapter): Alias
react-nativetoreact-native-webin Vite to keep existing<View>,<Text>, andStyleSheetprimitives intact for the fastest migration into a Capacitor Android wrapper. - Path B (Pure Web / UI Refactor): Replace React Native primitives with semantic HTML/CSS (
@ionic/reactor Tailwind CSS), swapreact-native-*modules for@capacitor/*plugins, and follow.impeccable.mdplusracepulse-responsive-uifor lightweight bundles with zero adapter overhead.
Workflow Checklist
| Step | Action | Reason | Evidence |
|---|---|---|---|
| 1. Audit dependencies | Inspect package.json for react-native-*, @react-native-*, and C++/JSI TurboModules | Separates convertible UI/device packages from native SDKs needing custom Kotlin plugins | Audit table covering UI, Device APIs, and Native SDKs (workflow) |
| 2. Configure Vite | Bundle index.html, JS, and CSS into dist/ (alias react-native-web only on Path A) | Capacitor packages compiled static web assets into the Android WebView container | npm run build exits 0 and emits dist/index.html |
| 3. Initialize Capacitor | Install @capacitor/core, @capacitor/android, @capacitor/cli and maintain root capacitor.config.ts | Sets appId, webDir, Android signing options, and plugin defaults | capacitor.config.ts and android/ present; allowMixedContent disabled |
| 4. Replace native modules | Map react-native-* libraries to @capacitor/* plugins and run npx cap sync android | Registers native Kotlin/Java bridge classes and avoids runtime PluginNotImplemented errors | All native calls use @capacitor/*; npx cap sync android exits 0 |
| 5. Harden Android ergonomics | Handle @capacitor/app backButton, viewport-fit=cover, env(safe-area-inset-*), and touch/overscroll CSS | Prevents accidental exits on back press, gesture-bar overlap, and web pull-to-refresh bounce | Inspect index.html, CSS safe-area rules, and back-button listener (hardening) |
| 6. Optimize Android build | Confirm android:hardwareAccelerated, lazy-load heavy plugins/routes, and configure R8/ProGuard for release | Minimizes startup WebView JS parse cost and shrinks release APK/AAB size | Inspect android/app/src/main/AndroidManifest.xml and android/app/build.gradle |
Critical Gotchas
- Never commit a live-reload
server.urlincapacitor.config.ts; guard it behindprocess.env.NODE_ENV === 'development'so production installs do not show a white screen. - Avoid Base64 for large photos or videos across the bridge; use
CameraResultType.UriwithCapacitor.convertFileSrc(uri)to prevent Android OOM crashes (hardening). - Always run
npx cap sync android(ornpm run android:sync) after installing or updating Capacitor plugins so Gradle includes the native plugin code.
RacePulsePH Stack Mapping
- Web and Capacitor scripts live in
package.json(npm run build,npm run android:sync,npm run android:open) with@capacitor/core,@capacitor/android, and@capacitor/cli. - Bundler and Capacitor configs live in
vite.config.ts,capacitor.config.ts, andindex.html. - Native Android shell files live in
android/variables.gradle,android/app/build.gradle,android/app/src/main/AndroidManifest.xml, andandroid/app/src/main/java/com/racepulseph/app/MainActivity.java. - Existing safe-area inset styling lives in
src/access-ui.css,src/components/BottomNav.tsx, andsrc/components/RunningLoader.css.
Not Covered
- Desktop and mobile console layout audits belong to
iso-ui-layout-auditorandracepulse-responsive-ui. - Firebase Hosting, Cloud Functions deployments, and Windows Timing Station builds belong to
racepulse-release-engineeringandracepulse-delivery-performance.
Verify
- Edit source, config, CSS, and Gradle/Manifest files directly without patching built artifacts (
R-33). - Run
npm run lint,npm run build, andnpm run android:sync(ornpx cap sync android) and confirm exit code0. - For APK/AAB releases, verify
cd android && ./gradlew bundleRelease(.\gradlew.bat bundleReleaseon Windows) exits0and deliver theAGENTS.mdPASS/FAIL report.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |