capacitor-plugin-starter-template

A starter template for building a Capacitor plugin, with a small set of working example native capabilities you can keep, replace, or delete:

• saveCredentials — store credentials in the native keychain
• getFCMToken / clearFCMToken — retrieve / forget a push token (FCM)
• signInWithGoogle / signInWithApple — native social sign-in
• appUpdateRequired listener + resetPatchAlertShownToday — App Store version check

It targets web (stubs), iOS (implemented), and Android (stubbed unimplemented).

Architecture note: the iOS side is a thin bridge — its methods post NotificationCenter notifications that the host app's AppDelegate handles (Firebase, Keychain, Google/Apple sign-in, version check) and then calls back into the plugin to resolve the JS promise. This keeps Firebase/GoogleSignIn dependencies in the app, not the plugin. See iOS host-app wiring below.

Install

npm install capacitor-plugin-starter-template
npx cap sync

Usage

import { StarterPlugin } from 'capacitor-plugin-starter-template';

const { fcmToken, deviceId } = await StarterPlugin.getFCMToken();

await StarterPlugin.saveCredentials({ username, password });

const google = await StarterPlugin.signInWithGoogle();
const apple = await StarterPlugin.signInWithApple();

await StarterPlugin.addListener('appUpdateRequired', (event) => {
  // event.kind === 'blocking' | 'patch'
  console.log('Update available:', event.appStoreVersion, event.appStoreUrl);
});

iOS host-app wiring (required)

Because the plugin is a bridge, the iOS app must implement the native work in its AppDelegate. After npx cap add ios, Capacitor generates a default AppDelegate without this wiring — copy it from example/AppDelegate.swift.

That file shows how to:

• configure Firebase and forward the FCM token via plugin.setFCMToken(_:)
• store credentials and report back with plugin.saveCredentialsResult(_:)
• run native Google / Apple sign-in and resolve via plugin.googleSignInResult(...) / plugin.appleSignInResult(...)
• poll the App Store and emit updates via plugin.notifyAppUpdateRequired(...)

The plugin posts these notifications (observe them in the AppDelegate):

| Notification name | Triggered by | | --- | --- | | StarterPluginSaveCredentials | saveCredentials() | | StarterPluginSignInWithGoogle | signInWithGoogle() | | StarterPluginSignInWithApple | signInWithApple() | | StarterPluginResetPatchAlertShownToday | resetPatchAlertShownToday() |

App-side prerequisites: Firebase (FirebaseCore, FirebaseMessaging) and GoogleSignIn packages; Push Notifications, Background Modes → Remote notifications, and Sign in with Apple capabilities; a GoogleService-Info.plist; and FirebaseAppDelegateProxyEnabled = NO in Info.plist. Replace the TODO placeholders (App Store id, shared-web-credentials domain) in the example.

Android

The example capabilities are iOS-only, so the Android methods return unimplemented. Implement them in android/src/main/java/com/example/starterplugin/ (the plugin class is StarterPluginPlugin, with shared logic in StarterPlugin).

Renaming the plugin

If you fork this template, replace the StarterPlugin identity throughout:

• npm name in package.json
• JS export + registered name in src/index.ts (StarterPlugin)
• iOS: ios/Sources/StarterPluginPlugin/, jsName/identifier, Package.swift, StarterPlugin.podspec
• Android: package com.example.starterplugin, @CapacitorPlugin(name = "..."), namespace in android/build.gradle

Develop

npm install
npm run build      # tsc + rollup
npm run verify     # build web + native (needs Xcode / Android SDK)
npm run docgen     # regenerate the API docs from JSDoc

License

MIT