capacitor-push-notifications

name capacitor-push-notifications description Guides the agent through setting up and using push notifications in Capacitor apps using Firebase Cloud Messaging via the @capacitor-firebase/messaging plugin. Covers Firebase project setup, plugin installation, platform-specific configuration (Android, iOS, Web), APNs certificate setup, requesting permissions, retrieving FCM tokens, listening for notifications, topic subscriptions, notification channels, and testing. Do not use for local notifications, non-Firebase push providers, migrating Capacitor apps or plugins, or non-Capacitor mobile frameworks. license MIT compatibility Requires Node.js, npm, and a Firebase project. Xcode on macOS and a paid Apple Developer Program membership are required for iOS; Android Studio for Android. metadata {"author":"capawesome-team","source":"https://github.com/capawesome-team/skills/tree/main/skills/capacitor-push-notifications"} Capacitor Push Notifications Set up and use push notifications in Capacitor apps using Firebase Cloud Messaging (FCM) via the @capacitor-firebase/messaging plugin. Prerequisites Capacitor 6, 7, or 8 app. Node.js and npm installed. A Firebase project . Create one at Firebase console if needed. For iOS : A paid Apple Developer Program membership and Xcode installed. For Android : Android Studio installed. @capacitor/push-notifications must not be installed — it conflicts with @capacitor-firebase/messaging . Agent Behavior Guide step-by-step. Walk the user through the process one step at a time. Never present multiple unrelated questions at once. Auto-detect before asking. Check the project for platforms ( android/ , ios/ ), build tools, framework, and package.json dependencies. Only ask the user when something cannot be detected. One decision at a time. When a step requires user input, ask that single question, wait for the answer, then continue. Present clear options. Provide concrete choices (e.g., "Do you want to configure topic subscriptions? (yes/no)") instead of open-ended questions. MCP Servers Two hosted MCP servers serve the current documentation, so both are always ahead of the guidance bundled with this skill: Capawesome MCP server — the Capawesome plugins, the Capawesome CLI, and Capawesome Cloud. Capacitor MCP server (unofficial) — Capacitor itself: the CLI, the capacitor.config file, the native Android and iOS projects, and the official plugin APIs. Both expose search_docs and get_doc_page , so pick the server by topic before calling either. If the MCP tools are available , call search_docs on the server that owns the topic and read the matching page with get_doc_page before applying the guidance below. Where the two disagree, follow the documentation. If they are not available , mention once that the servers can be added with the commands below, then continue with this skill. Never block on it. claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp" claude mcp add --transport http capacitor "https://capacitor-mcp.capawesome.io/mcp" Neither server needs an account or a token for documentation. See the capawesome-mcp and capacitor-mcp skills for full setup, including the Capawesome Cloud tools. Procedures Step 1: Analyze the Project Auto-detect the following by reading project files — do not ask the user for information that can be inferred: Platforms : Check which directories exist ( android/ , ios/ ). These are the platforms to configure. Build tool / framework : Check for vite.config.ts , angular.json , webpack.config.js , next.config.js , etc. Capacitor version : Read @capacitor/core version from package.json . Conflicting plugins : Check if @capacitor/push-notifications is in package.json . If found, warn the user it must be removed before proceeding: npm uninstall @capacitor/push-notifications Step 2: Set Up Firebase Check if Firebase is already configured in the project: Android : Check if android/app/google-services.json exists. iOS : Check if ios/App/App/GoogleService-Info.plist exists. If Firebase is not configured for a detected platform, read references/firebase-setup.md and guide the user through the Firebase setup for each missing platform. Step 3: Install the Plugin npm install @capacitor-firebase/messaging firebase npx cap sync Step 4: Configure Android Skip if android/ does not exist. Read references/android-setup.md and apply the Android-specific configuration. Step 5: Configure iOS Skip if ios/ does not exist. Read references/ios-setup.md and apply the iOS-specific configuration. This includes APNs key/certificate setup, AppDelegate.swift modifications, and enabling capabilities. Step 6: Configure Web (if applicable) If the project targets the web (detected via build tool config or user confirmation): Read references/web-setup.md and apply the Web-specific configuration. Step 7: Configure Capacitor Plugin Options Ask the user if they want to customize iOS foreground notification presentation. If yes, update capacitor.config.json or capacitor.config.ts : { "plugins" : { "FirebaseMessaging" : { "presentationOptions" : [ "alert" , "badge" , "sound" ] } } } Available options: badge , sound , alert , criticalAlert . Default is ["alert", "badge", "sound"] . Step 8: Add Push Notification Code Read references/implementation.md and add the push notification code to the project. Adapt imports and structure to match the user's framework. The implementation covers: Requesting permissions Retrieving the FCM token Listening for incoming notifications Handling notification taps Step 9: Configure Optional Features Ask the user which optional features to enable: Topic subscriptions — Subscribe/unsubscribe to FCM topics (Android/iOS only). Notification channels — Create custom Android notification channels (Android SDK 26+ only). Token refresh listener — Listen for FCM token changes. For each selected feature, read references/implementation.md and apply the relevant code. Step 10: Sync and Test Sync the project: npx cap sync Read references/testing.md and guide the user through sending a test notification via the Firebase Console. Error Handling @capacitor/push-notifications conflict : The @capacitor-firebase/messaging plugin cannot coexist with @capacitor/push-notifications . Uninstall the conflicting plugin: npm uninstall @capacitor/push-notifications && npx cap sync . iOS: No push notifications received : Verify APNs key/certificate is uploaded to Firebase Console. Verify Push Notifications and Background Modes capabilities are enabled. Verify AppDelegate.swift contains the required delegate methods. iOS: didRegisterForRemoteNotificationsWithDeviceToken not called : Ensure the Push Notifications capability is added in Xcode under Signing & Capabilities. Check that the app's bundle ID matches the one registered in Firebase and Apple Developer portal. Android: No push notifications received : Verify google-services.json is at android/app/google-services.json . Verify the Google services Gradle plugin is applied. Android: White square notification icon : The notification icon must be white pixels on a transparent background. Application icons with color will render as a white square. Add a dedicated push notification icon. Web: getToken() fails : Ensure the VAPID key is correct. Ensure firebase-messaging-sw.js exists at the root of the domain. Check that the browser supports the Push API. FCM token is null : Ensure requestPermissions() was called and returned granted before calling getToken() . On iOS, verify the device is not a simulator (simulators cannot receive push notifications). checkPermissions() returns denied : The user has permanently denied notification permissions. Guide them to re-enable via device settings (Settings > App > Notifications). Android 13+: No permission prompt : On Android 13 (API 33) and above, requestPermissions() must be called explicitly. Earlier Android versions grant notification permission by default. Related Skills capacitor-app-development — For general Capacitor development topics, troubleshooting, and best practices. capacitor-plugins — For general Capacitor plugin installation and configuration, including other Firebase plugins. capawesome-mcp — Connect an MCP client to the hosted Capawesome MCP server for always-current documentation and Capawesome Cloud management.