capacitor-plugin-spm-support

Capacitor プラグインに SPM サポートを追加する

CAPBridgedPlugin Swift プロトコルを使用するように Objective-C ブリッジを置き換え、Package.swift マニフェストを追加して、既存の Capacitor プラグインに Swift Package Manager（SPM）サポートを追加します。

前提条件

要件	バージョン
Capacitor	6+
Swift	5.9+
Xcode	15+

プロジェクトは Capacitor のプラグイン（アプリプロジェクトではありません）である必要があります。プラグインには、ios/Plugin/ に Swift ソースファイルを含む既存の iOS 実装が必要です。

手順

ステップ 1：プラグイン情報を収集する

1. プラグインのルートにある package.json を読み取ります。次の情報を抽出します。
   • プラグインパッケージ名（例：@capawesome/capacitor-app-review）。
   • 既存の files 配列のエントリー。
   • 既存の scripts エントリー。
2. プラグインのルートにある .podspec ファイルを読み取ります。次の情報を抽出します。
   • Pod 名（Pod::Spec.new の引数。例：CapawesomeCapacitorAppReview）。これは SPM パッケージ名になります。
   • s.ios.deployment_target の iOS デプロイメントターゲット（例：'13.0'）。メジャーバージョン番号（例：13）を抽出します。これは SPM iOS バージョンになります。
   • すべての サードパーティ CocoaPods 依存関係 — Capacitor または CapacitorCordova ではない s.dependency または spec.dependency のエントリーをすべて記録します。各依存関係の名前とバージョン制約を記録します。
3. ios/Plugin/ にある プラグインの Swift ファイルを特定します。このファイルには、@objc(<PluginClassName>) を持つ CAPPlugin のサブクラスが含まれています。次の情報を抽出します。
   • プラグインのクラス名（例：AppReviewPlugin）。
   • Objective-C の .m ファイルにある CAP_PLUGIN マクロの最初の文字列引数から JavaScript 名を取得します（例：AppReview）。
   • .m ファイルの CAP_PLUGIN_METHOD マクロ呼び出しからすべての プラグインメソッドを取得し、各メソッドの名前と戻り値の型（例：CAPPluginReturnPromise）を記録します。
4. ios/Plugin/ にある Objective-C ブリッジファイルを特定します。
   • <PluginClassName>.h（ヘッダーファイル）
   • <PluginClassName>.m（CAP_PLUGIN マクロを含む実装ファイル）
5. package.json から Capacitor のピア依存関係のバージョン（peerDependencies["@capacitor/core"]）を読み取ります。メジャーバージョン（例：6）を特定します。これが Capacitor のメジャーバージョンです。

ステップ 2：SPM 用に CocoaPods の依存関係を解決する

ステップ 1 でサードパーティ CocoaPods の依存関係が見つからなかった場合は、このステップをスキップします。

サードパーティ CocoaPods の依存関係ごとに、SPM 互換のパッケージが必要です。依存関係の一覧をユーザーに提示し、SPM パッケージの URL を提供できるか、エージェントに SPM 対応の代替パッケージをウェブで検索させるかを尋ねます。

ユーザーが SPM パッケージの URL を提供する場合： それらを記録し、ステップ 3 に進みます。

ユーザーがウェブ検索を依頼する場合： CocoaPods の依存関係ごとに、次の手順を行います。

1. "<dependency_name>" Swift Package Manager をウェブで検索し、元の CocoaPods 依存関係も SPM をサポートしているか確認します。人気のあるライブラリ（Firebase、Alamofire など）の多くは、同じリポジトリから CocoaPods と SPM の両方で配布されています。
2. 元のライブラリが SPM をサポートしている場合は、その Git リポジトリの URL を使用します。podspec で指定されている同じバージョンを使用し、CocoaPods のバージョン制約を SPM に対応する形式に変換します（例：~> 5.0 は .upToNextMajor(from: "5.0.0") に、= 2.1.0 は .exact("2.1.0") になります）。
3. 元のライブラリが SPM をサポートしていない場合は、"<dependency_name>" SPM alternative を検索し、SPM で同等の機能を提供する代替パッケージを探します。podspec で使用されているバージョンと互換性のあるバージョンを使用します。
4. SPM 互換の代替パッケージが見つからない場合は、ユーザーに伝え、どのように進めるかを尋ねます。

依存関係ごとに、解決した SPM パッケージの URL、バージョン要件、プロダクト名を記録します。これらは次のステップで Package.swift に追加します。

ステップ 3：Package.swift を作成する

プラグインのルートディレクトリに、次の内容で Package.swift を作成します。

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "<SPM_PACKAGE_NAME>",
    platforms: [.iOS(.v<SPM_IOS_VERSION>)],
    products: [
        .library(
            name: "<SPM_PACKAGE_NAME>",
            targets: ["<PLUGIN_CLASS_NAME>"])
    ],
    dependencies: [
        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", branch: "<CAPACITOR_MAJOR_VERSION>.0.0")
        // <ADDITIONAL_PACKAGE_DEPENDENCIES>
    ],
    targets: [
        .target(
            name: "<PLUGIN_CLASS_NAME>",
            dependencies: [
                .product(name: "Capacitor", package: "capacitor-swift-pm"),
                .product(name: "Cordova", package: "capacitor-swift-pm")
                // <ADDITIONAL_TARGET_DEPENDENCIES>
            ],
            path: "ios/Plugin"),
        .testTarget(
            name: "<PLUGIN_CLASS_NAME>Tests",
            dependencies: ["<PLUGIN_CLASS_NAME>"],
            path: "ios/PluginTests")
    ]
)

すべてのプレースホルダーを置き換えます。

• <SPM_IOS_VERSION> — ステップ 1 で確認した SPM の iOS バージョン（例：13）。
• <SPM_PACKAGE_NAME> — ステップ 1 で確認した Pod 名（例：CapawesomeCapacitorAppReview）。
• <PLUGIN_CLASS_NAME> — ステップ 1 で確認したプラグインクラス名（例：AppReviewPlugin）。
• <CAPACITOR_MAJOR_VERSION> — ステップ 1 で確認した Capacitor のメジャーバージョン（例：6）。
• <ADDITIONAL_PACKAGE_DEPENDENCIES> — ステップ 2 でサードパーティ依存関係を解決した場合は、それぞれに .package(url: "<repo_url>", <version_requirement>) エントリーを追加します。追加の依存関係がない場合は、コメント行を削除します。
• <ADDITIONAL_TARGET_DEPENDENCIES> — 上で追加した各パッケージ依存関係に対応する .product(name: "<ProductName>", package: "<package-name>") エントリーを追加します。追加の依存関係がない場合は、コメント行を削除します。

ステップ 4：Swift プラグインクラスを更新する

プラグインの Swift ファイル（例：ios/Plugin/<PluginClassName>.swift）を開きます。

1. クラス宣言に CAPBridgedPlugin プロトコルへの準拠を追加します。
2. 必須の 3 つのプロパティを、クラス本体の最初のプロパティとして既存のプロパティより前に追加します。

次の差分パターンを適用します。

 @objc(<PluginClassName>)
-public class <PluginClassName>: CAPPlugin {
+public class <PluginClassName>: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "<PluginClassName>"
+    public let jsName = "<JS_NAME>"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "<method1>", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "<method2>", returnType: CAPPluginReturnPromise)
+    ]

次の項目を置き換えます。

• <PluginClassName> — プラグインクラス名（例：AppReviewPlugin）。
• <JS_NAME> — .m ファイルの CAP_PLUGIN マクロにある JavaScript 名（例：AppReview）。
• pluginMethods 配列 — .m ファイルの CAP_PLUGIN_METHOD 呼び出しにあるメソッドをすべて列挙し、各メソッド名と戻り値の型を正確に維持します。

ステップ 5：Objective-C ブリッジファイルを削除する

ios/Plugin/ から次のファイルを削除します。

• <PluginClassName>.h
• <PluginClassName>.m

Swift の CAPBridgedPlugin プロトコルがプラグインの登録を処理するため、これらのファイルは不要になりました。

ステップ 6：Xcode プロジェクトファイルを整理する

ios/Plugin.xcodeproj/project.pbxproj を開き、削除した Objective-C ファイルへの参照をすべて削除します。具体的には、次のファイルを参照する行を削除します。

• <PluginClassName>.h — ファイル参照、ビルドフェーズのエントリー（PBXBuildFile、PBXFileReference、PBXGroup の children、PBXHeadersBuildPhase）
• <PluginClassName>.m — ファイル参照、ビルドフェーズのエントリー（PBXBuildFile、PBXFileReference、PBXGroup の children、PBXSourcesBuildPhase）

.pbxproj ファイル内で両方のファイル名を検索し、それらを参照する行をすべて削除します。

ステップ 7：.gitignore を更新する

プラグインのルートにある .gitignore を開き、次のエントリーがまだなければ追加します。

 # iOS files
+Package.resolved
+/.build
+/Packages
+.swiftpm/configuration/registries.json
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.netrc

これらのエントリーは、.gitignore ファイルの iOS セクションで、既存の iOS 関連エントリー（例：Pods、Podfile.lock）の後に配置します。

ステップ 8：package.json を更新する

package.json に次の 2 つの変更を加えます。

1. files 配列に "Package.swift" を追加します。

     "ios/Plugin/",
-    "<PodName>.podspec"
+    "<PodName>.podspec",
+    "Package.swift"
   ],

2. scripts オブジェクトに ios:spm:install スクリプトを追加します。

     "ios:pod:install": "cd ios && pod install --repo-update && cd ..",
+    "ios:spm:install": "cd ios && swift package resolve && cd ..",

ios:pod:install スクリプトがない場合は、既存の最後のスクリプトエントリーの後に ios:spm:install スクリプトを追加します。

ステップ 9：確認する

1. プラグインのルートで npm install を実行し、package.json が有効であることを確認します。
2. プラグインのサンプルアプリまたはテストアプリをビルドし、iOS のビルドが引き続き成功することを確認します。

エラー処理

• ObjC の参照を削除した後に .pbxproj ファイルが破損した場合は、バージョン管理から復元し、完全な行だけが削除されるよう注意して再編集してください。
• Swift のビルドで CAPBridgedPlugin が見つからないというエラーが発生した場合は、@capacitor/core がバージョン 6 以降であること、および capacitor-swift-pm のブランチが Capacitor のメジャーバージョンと一致していることを確認してください。
• SPM の解決に失敗した場合（swift package resolve）、Package.swift のターゲットパスが実際のディレクトリ構造（ソースは ios/Plugin、テストは ios/PluginTests）と一致していることを確認してください。
• プラグインにテストターゲット用ディレクトリ（ios/PluginTests）がない場合は、Package.swift から .testTarget ブロックを削除してください。
• プラグインにメインのプラグインファイル以外の Swift ソースファイルがある場合、追加の変更は不要です。SPM はターゲットパス内のすべての .swift ファイルを自動的に含めます。
• .m ファイルの一部のメソッドで CAPPluginReturnPromise ではなく CAPPluginReturnNone が使われている場合は、pluginMethods 配列に元の戻り値の型を維持してください。
• CocoaPods の依存関係に SPM の同等のものがなく、代替手段も見つからない場合、そのプラグインは SPM を完全にはサポートできません。ユーザーにその旨を伝え、依存関係のソースをベンダーとして取り込むか、上流で SPM がサポートされるまで待つことを提案してください。

関連スキル

• capacitor-plugin-development — スキャフォールディング、ネイティブ実装、公開を含め、Capacitor プラグインをゼロから作成する場合に使用します。
• capacitor-plugin-upgrades — Capacitor プラグインを新しいメジャーバージョンにアップグレードする場合に使用します。