capacitor-push-notifications

Q: How do I install capacitor-push-notifications?

Run npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-push-notifications in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/capacitor-push-notifications/ (personal) or .claude/skills/capacitor-push-notifications/ (project).

by cap-goMobile

Sets up and debugs remote push in Capacitor apps with @capacitor/push-notifications (FCM on Android, APNs on iOS), or Capgo alternatives @capgo/capacitor-firebase-messaging and @capgo/capacitor-notifications. Covers APNs keys, Push Notifications capability, AppDelegate didRegisterForRemoteNotificationsWithDeviceToken forwarding (stays in AppDelegate under the Capacitor 8.5 UIScene lifecycle), Android 13+ POSTNOTIFICATIONS permission, notification channels and icons, firebaseMessagingVersion, foreground presentationOptions (Capacitor 9 removes iOS alert; use banner/list), and tap routing. Use when registration never fires, iOS returns an APNs token instead of an FCM token, errors like "no valid aps-environment entitlement string found" appear, or notifications do not show. Do not use for local-only notifications or deep link URL handling (capacitor-deep-linking), UIScene migration (capacitor-uiscene-migration), or log capture (ios-android-logs).

Installs: 1.1K
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-push-notifications

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads capacitor-push-notifications automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Push Notifications in Capacitor

When to Use

TRIGGER when:

Adding remote push (FCM / APNs) to a Capacitor app
registration / registrationError never fire, or the token works on one platform only
iOS token is a 64-hex APNs token but the backend expects an FCM token
Notifications arrive in background but not in foreground (or vice versa)
Android 13+ shows no prompt and nothing is delivered
Upgrading to Capacitor 8.5 (UIScene) or 9 (alert presentation option removed)

Do not use:

Opening the app from https:// / myapp:// links: capacitor-deep-linking
Moving AppDelegate code to SceneDelegate: capacitor-uiscene-migration
Device log capture: ios-android-logs
Choosing other native plugins: capacitor-plugins

Choose the plugin first (ask the user if unclear)

Need	Plugin
Official plugin; APNs token on iOS, FCM token on Android	`@capacitor/push-notifications`
FCM token on both platforms, topics, Firebase-first backend	`@capgo/capacitor-firebase-messaging`
Capgo-managed delivery (dashboard campaigns, badges, silent live-update checks, no own push server)	`@capgo/capacitor-notifications`
Local notifications only, rich layouts	`@capgo/capacitor-rich-notifications` or `@capacitor/local-notifications`

The rest of this file covers @capacitor/push-notifications. For Capgo plugins follow https://capgo.app/docs/plugins/firebase-messaging/ or https://capgo.app/docs/plugins/notifications/getting-started/.

Workflow

Inspect: package.json versions (@capacitor/core, @capacitor/push-notifications), capacitor.config.* plugins.PushNotifications, ios/App/App/AppDelegate.swift, ios/App/App/*.entitlements, android/app/google-services.json, android/variables.gradle, AndroidManifest.xml.
Install: npm install @capacitor/push-notifications && npx cap sync.
iOS: capability + APNs key + AppDelegate forwarding. Details: references/ios-setup.md.
Android: google-services.json, channel, icon, permission. Details: references/android-setup.md.
JS: listeners first, then permission, then register() (below).
Backend: send a test message. Payload shapes: references/sending.md.
Verify with the checklist below on physical devices.

Only load a reference when its topic is in play.

JS registration (order matters)

import { PushNotifications } from '@capacitor/push-notifications';

export async function initPush() {
  // 1. Listeners before register(), or the first token is missed
  await PushNotifications.addListener('registration', ({ value }) => sendTokenToServer(value));
  await PushNotifications.addListener('registrationError', (err) => console.error('push reg', err.error));
  await PushNotifications.addListener('pushNotificationReceived', (n) => {
    // foreground only (and Android data-only while app is alive)
  });
  await PushNotifications.addListener('pushNotificationActionPerformed', ({ notification, actionId }) => {
    routeFromNotification(notification.data); // tap handling
  });

  // 2. Permission (required on iOS and Android 13+ / targetSdk 33+)
  let perm = await PushNotifications.checkPermissions();
  if (perm.receive === 'prompt' || perm.receive === 'prompt-with-rationale') {
    perm = await PushNotifications.requestPermissions();
  }
  if (perm.receive !== 'granted') return; // explain + link to settings, do not loop prompts

  // 3. Register
  await PushNotifications.register();
}

Traps:

Call initPush() at bootstrap so pushNotificationActionPerformed from a cold-start tap is captured.
Tokens rotate. Send every registration value to the server and upsert by user + device.
On iOS the plugin reports the raw APNs token unless AppDelegate swaps in the FCM token (see ios-setup). Sending an APNs token to FCM fails with messaging/invalid-registration-token.
Ask permission after a user action that explains the value; iOS shows the system prompt only once.

Foreground presentation

// capacitor.config.ts
plugins: {
  PushNotifications: {
    presentationOptions: ['badge', 'sound', 'banner', 'list'],
  },
},

banner + list replace the deprecated iOS alert. Capacitor 9 removes alert on iOS; replace it when upgrading. badge is iOS only.
Empty array = nothing shown in foreground; handle pushNotificationReceived yourself.

Capacitor version notes

Version	Change
7	`firebaseMessagingVersion` default 24.1.0
8	`firebaseMessagingVersion` default 25.0.1
8.5	UIScene lifecycle. Remote-notification callbacks (`didRegisterForRemoteNotificationsWithDeviceToken`, `didFailToRegister...`) stay in AppDelegate and keep working. Do not move them to SceneDelegate. Tap routing that used AppDelegate `application(_:open:)` must move (see `capacitor-deep-linking`).
9	iOS `alert` presentation option removed; iOS 16 min; `@main` replaces `@UIApplicationMain`; google-services Gradle plugin 4.5.0

Verification

iOS: codesign -d --entitlements :- path/to/App.app | grep aps-environment shows development (debug) or production (TestFlight/App Store).
Android: adb shell dumpsys package com.example.app | grep POST_NOTIFICATIONS shows granted=true after accepting the prompt.
App logs a registration token on a real device (iOS Simulator on Apple silicon can receive pushes via xcrun simctl push, but test real APNs on device).
Send a test from Firebase Console (Messaging -> "Send test message") or your backend to that token.
Check all three states: foreground (presentation + pushNotificationReceived), background (system tray), killed (tap -> pushNotificationActionPerformed routes correctly).
iOS simulator smoke test without a server:

cat > /tmp/push.apns <<'EOF'
{ "Simulator Target Bundle": "com.example.app", "aps": { "alert": { "title": "Test", "body": "Hello" } }, "route": "/inbox" }
EOF
xcrun simctl push booted com.example.app /tmp/push.apns

(aps.alert in the APNs payload is the message content and is unaffected by the presentationOptions change.)

Error Handling

Error / symptom	Cause	Fix
`no valid "aps-environment" entitlement string found for application`	Push Notifications capability missing or profile not regenerated	Add capability in Xcode, re-sign, rebuild
`registration` never fires on iOS, no error	AppDelegate does not post `.capacitorDidRegisterForRemoteNotifications`	Add forwarding methods to AppDelegate
`Default FirebaseApp is not initialized in this process` (Android)	`google-services.json` missing/empty, so google-services plugin was not applied (`google-services.json not found, google-services plugin not applied. Push Notifications won't work`)	Put file in `android/app/`, rebuild
`messaging/registration-token-not-registered`	Token stale (app reinstalled / data cleared)	Delete token server-side; rely on next `registration`
`messaging/invalid-registration-token` / `BadDeviceToken`	APNs token sent to FCM, or sandbox token sent to production APNs	Use FCM token on iOS (ios-setup) or match APNs environment
`messaging/third-party-auth-error`	APNs key not uploaded to Firebase, wrong Key ID / Team ID	Upload .p8 under Firebase Project Settings -> Cloud Messaging
Android 13+: nothing shown, no prompt	`requestPermissions()` never called	Call it; manifest permission is added by the plugin
Android shows white square icon	No monochrome notification icon	Set `default_notification_icon` meta-data
Android notification silent / wrong importance	Channel created with low importance (importance is immutable after creation)	Create a new channel id; delete the old one
Data-only message ignored when app killed (Android)	Plugin only delivers while app process lives	Native `FirebaseMessagingService` (android-setup)
iOS silent / background push not delivered to JS	Plugin does not support iOS silent push	Native handling, or `@capgo/capacitor-notifications` silent update checks
Duplicate class errors with Firebase after Capacitor 9	Old `core-ktx` / Kotlin stdlib pins	See `capacitor-app-upgrade-v8-to-v9`

Resources

Plugin API: https://capacitorjs.com/docs/apis/push-notifications
Firebase guide: https://capacitorjs.com/docs/guides/push-notifications-firebase
Updating to 9.0: https://capacitorjs.com/docs/updating/9-0
Capgo Firebase Messaging: https://capgo.app/docs/plugins/firebase-messaging/
Capgo Notifications: https://capgo.app/docs/plugins/notifications/

FAQ

What does the capacitor-push-notifications skill do?

How do I install capacitor-push-notifications?

Run npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-push-notifications in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/capacitor-push-notifications/ (personal) or .claude/skills/capacitor-push-notifications/ (project).

Which AI agents can use capacitor-push-notifications?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is capacitor-push-notifications safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains capacitor-push-notifications?

It is published by cap-go in cap-go/capgo-skills. It has 1,100 recorded installs.

More from cap-go/capgo-skills

View all →

capacitor-best-practices

cap-go/capgo-skills

Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via @next). Use for a Capacitor codebase review, capacitor.config.ts audit, new project setup, aligning @capacitor/core/cli/ios/android and plugin majors, plugin patterns (availability checks, checkPermissions/requestPermissions, error code handling, web fallbacks), or release prep; or on " " plugin is not implemented on ios, Could not find the web assets directory, platform has not been added yet, a dev server.url shipped to production, lost edits in android/app/src/main/assets/public, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).

Code Quality & Workflow2.7K installs

ionic-design

cap-go/capgo-skills

Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).

Frontend & Design1.6K installs

capacitor-plugins

cap-go/capgo-skills

Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/ packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/ index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG- codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).

Frontend & Design1.6K installs

debugging-capacitor

cap-go/capgo-skills

Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, "X" plugin is not implemented on ios/android, net::ERRCLEARTEXTNOTPERMITTED, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, npx cap run --url (Capacitor 9) vs -l --host (8), xcrun simctl openurlprivacypush, xcrun devicectl device process launchopenURL, xctrace. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).

Code Quality & Workflow1.3K installs

capacitor-testing

cap-go/capgo-skills

Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (vi.mock('@capacitor/core'), registerPlugin), Playwright for the web build, Appium E2E with NATIVEAPP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, CAPPluginCall patterns, xcodebuild test on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with xcrun simctl, xcrun devicectl, adb, Xcode MCP device tools, and live reload via npx cap run --url (Capacitor 9) or -l --host --port (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor

Testing & QA1.3K installs

safe-area-handling

cap-go/capgo-skills

Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers viewport-fit=cover + env(safe-area-inset-), the Capacitor 8 SystemBars core plugin (insetsHandling, injected --safe-area-inset- CSS variables for Android WebView < 140, removal of android.adjustMarginsForEdgeToEdge), Android 15/16 enforced edge-to-edge (overlaysWebView and backgroundColor of @capacitor/status-bar no longer work at targetSdk 36), iOS contentInset, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, env() returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).

Mobile1.3K installs

Popular mobile skills

View category →

design-mobile-apps

designed-by-ai/skills

Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML.

Mobile1.1M installs

ios-design

uizze.sh

Design and review iOS UI/UX for iPhone apps in SwiftUI, UIKit, or React Native. Use for mobile app design, screen redesigns, navigation flows, typography, forms, keyboard and safe-area layout, and accessibility checks. Apply Apple Human Interface Guidelines and consult real product references through the optional Uizze connection.

Mobile416.5K installs

vercel-react-native-skills

vercel-labs/agent-skills

React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.

OfficialMobile256.7K installs

animate-expo

emilkowalski/skills

Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use animate.

Mobile140.1K installs

xcode-project-setup

firebase/agent-skills

Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).

OfficialMobile131.2K installs

firebase-remote-config-basics

firebase/agent-skills

Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON templates, managing version history/feature flags, setting in-app defaults, fetchAndActivate(), real-time listeners, or SDK setup. Don't use for Firebase Hosting, Auth, Firestore, Data Connect, Crashlytics, or App Hosting.

OfficialMobile121.7K installs

capacitor-push-notifications

Install

Install

Describe the task

Review the result

SKILL.md

Push Notifications in Capacitor

When to Use

Choose the plugin first (ask the user if unclear)

Workflow

JS registration (order matters)

Foreground presentation

Capacitor version notes

Verification

Error Handling

Resources

FAQ

More from cap-go/capgo-skills

Popular mobile skills