Ionic + React App Guidelines

This is a SKILL file, NOT a project. Never run npm install here. When creating a new project, ask for the project path or scaffold in a separate directory (e.g. ~/Projects/<app>).

When to consult these references

Project setup:

• Create a new React Ionic project: new-app.md
• Project structure: project-structure.md
• App configuration (main.tsx, App.tsx, i18n/index.ts): app-config.md
• Routing (IonReactRouter, tab routes): routing.md

Pages and navigation:

• Onboarding guard (component wrapper): onboarding-guard.md
• Onboarding page (video background + Swiper): onboarding-page.md
• Paywall page (RevenueCat): paywall-page.md
• Tabs layout (with banner ad lifecycle): tabs-navigation.md
• Settings page: settings-page.md

Cross-cutting:

• Hooks (Theme / Onboarding / Ads / Purchases / Notifications): hooks.md
• i18n with react-i18next: i18n-react-i18next.md
• Best practices (functional + IonPage): best-practices.md
• Commands (build / sync / open): commands.md

Native plugin topics live in ../ionic-shared/references/:

• admob.md
• revenuecat.md
• push-notifications.md
• storage.md
• theming.md
• localization-content.md

Required pages (always create)

• Onboarding — swipe-based, fullscreen background video + gradient overlay.
• Paywall — RevenueCat (weekly / yearly), shown immediately after onboarding.
• Settings — language, theme, notifications, remove ads, reset onboarding.

Required navigation

Use IonTabs + IonTabBar. Never build a custom tab bar or pull in a third-party tab library.

Required libraries

npm install \
  @capacitor/preferences @capacitor/push-notifications \
  @capacitor/splash-screen @capacitor/status-bar \
  @revenuecat/purchases-capacitor @capacitor-community/admob \
  react-i18next i18next i18next-http-backend \
  swiper

Hard rules (React-specific)

• ❌ Class components — use functional components with hooks.
• ❌ Direct DOM manipulation — use refs / state.
• ❌ Importing from @ionic/angular or @ionic/vue — only @ionic/react.
• ❌ any type.
• ✅ Wrap every page in <IonPage> so Ionic's transitions and lifecycle work.

Before reporting done

npm install
npm run build
npx cap sync

The build must complete without errors. cap sync is required after every web build before testing on native.