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.

capacitor-push-notifications