Ionic + Angular 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 Angular Ionic project: new-app.md
• Project structure (folder layout): project-structure.md
• App configuration (main.ts, app.config.ts): app-config.md
• Routing (lazy loadComponent, tabs): routing.md

Pages and navigation:

• Onboarding guard (CanMatchFn — preferred over CanActivateFn for lazy-route gates): onboarding-guard.md
• Onboarding page (video background + Swiper): onboarding-page.md
• Paywall page (RevenueCat): paywall-page.md
• Tabs navigation: tabs-navigation.md
• Settings page: settings-page.md

Cross-cutting:

• Signals (signal, computed, effect, untracked, signal inputs/outputs): signals.md
• Services (Theme / Onboarding / Ads / Purchases / Notifications): services.md
• Built-in control flow (@if / @for / @switch): control-flow.md
• Accessibility (ARIA, touch targets, screen readers): accessibility.md
• @defer lazy rendering (paywall / onboarding heavy chunks): defer-loading.md
• i18n with @ngx-translate/core: i18n-ngx-translate.md
• Best practices (standalone, separate files, signals-first, OnPush, inject()): best-practices.md
• Commands (build / sync / open): commands.md

Native plugin topics live in ../ionic-shared/references/ — always link there for AdMob, RevenueCat, push notifications, storage, and theme:

• 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 ion-tabs + ion-tab-bar. 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 \
  @ngx-translate/core @ngx-translate/http-loader \
  swiper

Hard rules (Angular-specific)

• ❌ NgModules for new pages/components — use standalone components.
• ❌ IonicModule in standalone components — import the individual components (IonContent, IonButton, …).
• ❌ Inline template or styles in @Component — always use separate .html, .ts, .scss files via templateUrl and styleUrls.
• ❌ @angular/http (deprecated) — use @angular/common/http.
• ❌ any type — use real TypeScript types.
• ✅ Prefer Signals for reactive state — signal(), computed(), effect(). Services should expose readonly signals where it makes sense — see signals.md. Stick to stable signal APIs; avoid Angular features marked "developer preview" / "experimental" (e.g. linkedSignal, resource, Signal Forms) until they graduate.
• ✅ Use signal inputs / outputs (input(), input.required(), output()) for new components.

Before reporting done

npm install
npx ng build
npx cap sync

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