Ionic Shared (Capacitor) Guidelines

Cross-framework guidance for Ionic Capacitor apps. The framework skills (ionic-angular, ionic-react, ionic-vue) link here for native plugin and content topics so the same code is not repeated three times.

When to consult these references

• Capacitor config / native platforms: capacitor-config.md
• Environments & API keys (env vars per framework, what's safe to ship): environments-and-keys.md
• Persistent storage (@capacitor/preferences): storage.md
• Theme switching (Light / Dark / System): theming.md
• AdMob banner ads: admob.md
• RevenueCat purchases / paywall logic: revenuecat.md
• Push notifications: push-notifications.md
• Translation strings (TR / EN): localization-content.md
• App Store / Play Store submission notes: app-store-notes.md
• Pre-release testing checklist: testing-checklist.md

Hard rules (apply to all frameworks)

• ✅ Use the latest stable versions of Ionic Framework, Capacitor, and the framework (Angular / React / Vue). When scaffolding a new project, do not pin to older majors — let npm install <pkg> resolve the latest. Verify against npm view <pkg> version if uncertain. Do not write specific version numbers into SKILL.md examples — they go stale.
• ✅ Read API keys and ad unit IDs from environment variables, never hardcoded in source. The mobile bundle is not a secret container — only publishable keys (RevenueCat SDK key, AdMob unit ID, Firebase web config, Sentry DSN) belong in the app. Secret keys (Stripe sk_…, OpenAI / Anthropic, RevenueCat REST secret) MUST live behind a backend. See environments-and-keys.md.
• ✅ Tie isTesting flags to the build mode, not a hardcoded true. Shipping initializeForTesting: true or isTesting: true to production can get an AdMob account banned.
• ❌ NEVER use localStorage directly — use @capacitor/preferences.
• ❌ NEVER use @ionic/storage — use @capacitor/preferences.
• ❌ NEVER use cordova-plugin-* — use the Capacitor equivalent.
• ❌ NEVER use ngx-admob-free or other deprecated ad libraries — use @capacitor-community/admob.
• ❌ NEVER call Capacitor plugin methods synchronously — always await.
• ✅ ALWAYS guard native-only code with Capacitor.isNativePlatform().
• ✅ ALWAYS run npx cap sync after installing or updating any Capacitor plugin.

Required shared libraries

npm install \
  @capacitor/app \
  @capacitor/preferences \
  @capacitor/push-notifications \
  @capacitor/splash-screen \
  @capacitor/status-bar \
  @revenuecat/purchases-capacitor \
  @capacitor-community/admob \
  swiper

@capacitor/app is needed by ionic-deep-links (and any skill that listens to appUrlOpen / appStateChange), so it's part of the shared baseline.

These are installed in addition to the framework-specific i18n library (see each framework's SKILL.md).