capacitor-plugin-spm-support

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add SPM Support to a Capacitor Plugin

为Capacitor插件添加SPM支持

Add Swift Package Manager (SPM) support to an existing Capacitor plugin by replacing the Objective-C bridge with the

CAPBridgedPlugin

Swift protocol and adding a

Package.swift

manifest.

通过使用

CAPBridgedPlugin

Swift协议替换Objective-C桥接文件并添加

Package.swift

清单，为现有Capacitor插件添加Swift Package Manager (SPM) 支持。

Prerequisites

前提条件

Requirement	Version
Capacitor	6+
Swift	5.9+
Xcode	15+

The project must be a Capacitor plugin (not an app project). The plugin must have an existing iOS implementation with Swift source files in

ios/Plugin/

要求	版本
Capacitor	6+
Swift	5.9+
Xcode	15+

项目必须是Capacitor 插件（而非应用项目）。插件必须已有iOS实现，且Swift源文件位于

ios/Plugin/

目录下。

Procedures

操作步骤

Step 1: Gather Plugin Information

步骤1：收集插件信息

Read
```
package.json
```
in the plugin root. Extract:
- The plugin package name (e.g.,
```
@capawesome/capacitor-app-review
```
  ).
- The existing
```
files
```
  array entries.
- The existing
```
scripts
```
  entries.
Read the
```
.podspec
```
file in the plugin root. Extract:
- The pod name (the
```
Pod::Spec.new
```
  argument, e.g.,
```
CapawesomeCapacitorAppReview
```
  ). This becomes the SPM package name.
- The iOS deployment target from
```
s.ios.deployment_target
```
  (e.g.,
```
'13.0'
```
  ). Extract the major version number (e.g.,
```
13
```
  ). This becomes the SPM iOS version.
- All third-party CocoaPods dependencies — any
```
s.dependency
```
  or
```
spec.dependency
```
  entries that are not
```
Capacitor
```
  or
```
CapacitorCordova
```
  . Record each dependency name and version constraint.
Identify the plugin Swift file in
```
ios/Plugin/
```
. It contains a class extending
```
CAPPlugin
```
with
```
@objc(<PluginClassName>)
```
. Extract:
- The plugin class name (e.g.,
```
AppReviewPlugin
```
  ).
- The JavaScript name from the Objective-C
```
.m
```
  file's
```
CAP_PLUGIN
```
  macro first string argument (e.g.,
```
AppReview
```
  ).
- All plugin methods from
```
CAP_PLUGIN_METHOD
```
  macro calls in the
```
.m
```
  file, noting each method's name and return type (e.g.,
```
CAPPluginReturnPromise
```
  ).
Identify the Objective-C bridge files in
```
ios/Plugin/
```
:
- ```
<PluginClassName>.h
```
  (header file)
- ```
<PluginClassName>.m
```
  (implementation file with
```
CAP_PLUGIN
```
  macro)
Read the Capacitor peer dependency version from
```
package.json
```
(
```
peerDependencies["@capacitor/core"]
```
). Determine the major version (e.g.,
```
6
```
). This is the Capacitor major version.

读取插件根目录下的
```
package.json
```
，提取：
- 插件包名称（例如：
```
@capawesome/capacitor-app-review
```
  ）。
- 现有
```
files
```
  数组条目。
- 现有
```
scripts
```
  条目。
读取插件根目录下的
```
.podspec
```
文件，提取：
- Pod名称（
```
Pod::Spec.new
```
  的参数，例如：
```
CapawesomeCapacitorAppReview
```
  ），此名称将作为SPM包名称。
- 从
```
s.ios.deployment_target
```
  中提取的iOS部署目标（例如：
```
'13.0'
```
  ），取主版本号（例如：
```
13
```
  ）作为SPM iOS版本。
- 所有第三方CocoaPods依赖 —— 所有非
```
Capacitor
```
  或
```
CapacitorCordova
```
  的
```
s.dependency
```
  或
```
spec.dependency
```
  条目，记录每个依赖的名称和版本约束。
定位
```
ios/Plugin/
```
目录下的插件Swift文件，该文件包含一个继承自
```
CAPPlugin
```
且带有
```
@objc(<PluginClassName>)
```
的类，提取：
- 插件类名称（例如：
```
AppReviewPlugin
```
  ）。
- Objective-C
```
.m
```
  文件中
```
CAP_PLUGIN
```
  宏第一个字符串参数中的JavaScript名称（例如：
```
AppReview
```
  ）。
- ```
.m
```
  文件中
```
CAP_PLUGIN_METHOD
```
  宏调用的所有插件方法，记录每个方法的名称和返回类型（例如：
```
CAPPluginReturnPromise
```
  ）。
定位
```
ios/Plugin/
```
目录下的Objective-C桥接文件：
- ```
<PluginClassName>.h
```
  （头文件）
- ```
<PluginClassName>.m
```
  （包含
```
CAP_PLUGIN
```
  宏的实现文件）
从
```
package.json
```
中读取Capacitor对等依赖版本（
```
peerDependencies["@capacitor/core"]
```
），确定主版本（例如：
```
6
```
），此为Capacitor主版本。

Step 2: Resolve CocoaPods Dependencies for SPM

步骤2：为SPM解析CocoaPods依赖

Skip this step if no third-party CocoaPods dependencies were found in Step 1.

For each third-party CocoaPods dependency, an equivalent SPM-compatible package is needed. Present the list of dependencies to the user and ask whether they can provide the SPM package URLs themselves, or whether the agent should search the web for SPM equivalents.

If the user provides SPM package URLs: Record them and proceed to Step 3.

If the user requests a web search: For each CocoaPods dependency:

Search the web for
```
"<dependency_name>" Swift Package Manager
```
to determine whether the original CocoaPods dependency also supports SPM. Many popular libraries (e.g., Firebase, Alamofire) distribute via both CocoaPods and SPM from the same repository.
If the original library supports SPM, use its Git repository URL. Use the same version as specified in the podspec — convert the CocoaPods version constraint to the SPM equivalent (e.g.,
```
~> 5.0
```
becomes
```
.upToNextMajor(from: "5.0.0")
```
,
```
= 2.1.0
```
becomes
```
.exact("2.1.0")
```
).
If the original library does not support SPM, search for
```
"<dependency_name>" SPM alternative
```
to find a replacement package that provides equivalent functionality via SPM. Use a version that is compatible with the version used in the podspec.
If no SPM-compatible alternative exists, inform the user and ask how to proceed.

Record the resolved SPM package URL, version requirement, and product name(s) for each dependency. These will be added to

Package.swift

in the next step.

如果步骤1中未找到第三方CocoaPods依赖，可跳过此步骤。

对于每个第三方CocoaPods依赖，需要找到对应的SPM兼容包。将依赖列表展示给用户，询问他们是否能自行提供SPM包URL，或是需要助手在网上搜索等效的SPM包。

如果用户提供SPM包URL： 记录URL并进入步骤3。

如果用户要求进行网络搜索： 对于每个CocoaPods依赖：

在网上搜索
```
"<dependency_name>" Swift Package Manager
```
，判断原CocoaPods依赖是否也支持SPM。许多热门库（例如Firebase、Alamofire）会通过同一仓库同时发布CocoaPods和SPM版本。
如果原库支持SPM，使用其Git仓库URL。使用与podspec中指定的相同版本 —— 将CocoaPods版本约束转换为SPM等效格式（例如：
```
~> 5.0
```
转换为
```
.upToNextMajor(from: "5.0.0")
```
，
```
= 2.1.0
```
转换为
```
.exact("2.1.0")
```
）。
如果原库不支持SPM，搜索
```
"<dependency_name>" SPM alternative
```
以找到提供等效功能的SPM替代包，使用与podspec中版本兼容的版本。
如果找不到SPM兼容的替代包，告知用户并询问后续处理方式。

记录每个依赖已解析的SPM包URL、版本要求和产品名称，这些将在下一步添加到

Package.swift

中。

Step 3: Create

Package.swift

步骤3：创建

Package.swift

Create

Package.swift

in the plugin root directory with the following content:

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")
    ]
)

Replace all placeholders:

```
<SPM_IOS_VERSION>
```
— the SPM iOS version from Step 1 (e.g.,
```
13
```
).

<SPM_PACKAGE_NAME>

— the pod name from Step 1 (e.g.,

CapawesomeCapacitorAppReview

```
<PLUGIN_CLASS_NAME>
```
— the plugin class name from Step 1 (e.g.,
```
AppReviewPlugin
```
).
```
<CAPACITOR_MAJOR_VERSION>
```
— the Capacitor major version from Step 1 (e.g.,
```
6
```
).
```
<ADDITIONAL_PACKAGE_DEPENDENCIES>
```
— if third-party dependencies were resolved in Step 2, add a
```
.package(url: "<repo_url>", <version_requirement>)
```
entry for each. Remove the comment line if no extra dependencies exist.
```
<ADDITIONAL_TARGET_DEPENDENCIES>
```
— for each package dependency added above, add a corresponding
```
.product(name: "<ProductName>", package: "<package-name>")
```
entry. Remove the comment line if no extra dependencies exist.

在插件根目录下创建

Package.swift

，内容如下：

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>")
```
条目。如果没有额外依赖，删除此注释行。

Step 4: Update the Swift Plugin Class

步骤4：更新Swift插件类

Open the plugin Swift file (e.g.,

ios/Plugin/<PluginClassName>.swift

Add
```
CAPBridgedPlugin
```
protocol conformance to the class declaration.
Add the three required properties as the first properties in the class body, before any existing properties.

Apply this diff pattern:

diff

 @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)
+    ]

Replace:

```
<PluginClassName>
```
— the plugin class name (e.g.,
```
AppReviewPlugin
```
).
```
<JS_NAME>
```
— the JavaScript name from the
```
.m
```
file's
```
CAP_PLUGIN
```
macro (e.g.,
```
AppReview
```
).
The
```
pluginMethods
```
array — list all methods from the
```
.m
```
file's
```
CAP_PLUGIN_METHOD
```
calls, preserving each method's name and return type exactly.

打开插件Swift文件（例如：

ios/Plugin/<PluginClassName>.swift

）。

为类声明添加
```
CAPBridgedPlugin
```
协议一致性。
在类体的最前面添加三个必需的属性，位于所有现有属性之前。

应用如下差异模式：

diff

 @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
```
调用的所有方法，严格保留每个方法的名称和返回类型。

Step 5: Delete Objective-C Bridge Files

步骤5：删除Objective-C桥接文件

Delete the following files from

ios/Plugin/

```
<PluginClassName>.h
```
```
<PluginClassName>.m
```

These are no longer needed because the plugin registration is now handled by the

CAPBridgedPlugin

protocol in Swift.

从

ios/Plugin/

目录中删除以下文件：

```
<PluginClassName>.h
```
```
<PluginClassName>.m
```

这些文件不再需要，因为现在插件注册由Swift中的

CAPBridgedPlugin

协议处理。

Step 6: Clean Up the Xcode Project File

步骤6：清理Xcode项目文件

Open

ios/Plugin.xcodeproj/project.pbxproj

and remove all references to the deleted Objective-C files. Specifically, remove lines referencing:

<PluginClassName>.h

— file references, build phase entries (

PBXBuildFile

PBXFileReference

PBXGroup

children,

PBXHeadersBuildPhase

)

<PluginClassName>.m

— file references, build phase entries (

PBXBuildFile

PBXFileReference

PBXGroup

children,

PBXSourcesBuildPhase

)

Search for both filenames in the

.pbxproj

file and remove every line that references them.

打开

ios/Plugin.xcodeproj/project.pbxproj

，移除所有已删除Objective-C文件的引用。具体来说，移除引用以下内容的行：

<PluginClassName>.h

—— 文件引用、构建阶段条目（

PBXBuildFile

、

PBXFileReference

、

PBXGroup

子项、

PBXHeadersBuildPhase

）

<PluginClassName>.m

—— 文件引用、构建阶段条目（

PBXBuildFile

、

PBXFileReference

、

PBXGroup

子项、

PBXSourcesBuildPhase

）

在

.pbxproj

文件中搜索这两个文件名，移除所有引用它们的行。

Step 7: Update

.gitignore

步骤7：更新

.gitignore

Open

.gitignore

in the plugin root. Add the following entries if not already present:

diff

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

Place these entries in the iOS section of the

.gitignore

file, after any existing iOS-related entries (e.g.,

Pods

Podfile.lock

打开插件根目录下的

.gitignore

，如果以下条目尚未存在，添加它们：

diff

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

将这些条目放在

.gitignore

的iOS部分，位于所有现有iOS相关条目之后（例如

Pods

、

Podfile.lock

）。

Step 8: Update

package.json

步骤8：更新

package.json

Apply two changes to

package.json

Add
```
"Package.swift"
```
to the
```
files
```
array:

diff

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

Add the
```
ios:spm:install
```
script to the
```
scripts
```
object:

diff

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

If the

ios:pod:install

script does not exist, add the

ios:spm:install

script after the last existing script entry.

对

package.json

进行两处修改：

将
```
"Package.swift"
```
添加到
```
files
```
数组：

diff

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

在
```
scripts
```
对象中添加
```
ios:spm:install
```
脚本：

diff

     "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

脚本添加到最后一个现有脚本条目之后。

Step 9: Verify

步骤9：验证

Run
```
npm install
```
in the plugin root to ensure
```
package.json
```
is valid.
Verify the iOS build still succeeds by building the plugin's example or test app.

在插件根目录运行
```
npm install
```
，确保
```
package.json
```
有效。
通过构建插件的示例或测试应用，验证iOS构建是否仍能成功。

Error Handling

错误处理

If the
```
.pbxproj
```
file becomes corrupted after removing ObjC references, restore it from version control and carefully re-edit, ensuring only complete lines are removed.
If the Swift build fails with
```
CAPBridgedPlugin
```
not found, verify that
```
@capacitor/core
```
is version 6+ and that
```
capacitor-swift-pm
```
branch matches the Capacitor major version.
If SPM resolution fails (
```
swift package resolve
```
), verify the
```
Package.swift
```
target paths match the actual directory structure (
```
ios/Plugin
```
for sources,
```
ios/PluginTests
```
for tests).
If the plugin has no test target directory (
```
ios/PluginTests
```
), remove the
```
.testTarget
```
block from
```
Package.swift
```
.
If the plugin has additional Swift source files beyond the main plugin file, no extra changes are needed — SPM automatically includes all
```
.swift
```
files in the target path.
If the
```
.m
```
file uses
```
CAPPluginReturnNone
```
instead of
```
CAPPluginReturnPromise
```
for some methods, preserve the original return type in the
```
pluginMethods
```
array.
If a CocoaPods dependency has no SPM equivalent and no alternative can be found, the plugin cannot fully support SPM. Inform the user and suggest they either vendor the dependency source or wait for upstream SPM support.

如果移除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
```
文件中某些方法使用
```
CAPPluginReturnNone
```
而非
```
CAPPluginReturnPromise
```
，在
```
pluginMethods
```
数组中保留原始返回类型。
如果某个CocoaPods依赖没有SPM等效包且找不到替代方案，该插件无法完全支持SPM。告知用户并建议他们要么将依赖源码嵌入项目，要么等待上游支持SPM。

capacitor-plugin-spm-support

Original

Translation

Add SPM Support to a Capacitor Plugin

为Capacitor插件添加SPM支持

Prerequisites

前提条件

Procedures

操作步骤

Step 1: Gather Plugin Information

步骤1：收集插件信息

Step 2: Resolve CocoaPods Dependencies for SPM

步骤2：为SPM解析CocoaPods依赖

Step 3: Create
`Package.swift`

步骤3：创建
`Package.swift`

Step 4: Update the Swift Plugin Class

步骤4：更新Swift插件类

Step 5: Delete Objective-C Bridge Files

步骤5：删除Objective-C桥接文件

Step 6: Clean Up the Xcode Project File

步骤6：清理Xcode项目文件

Step 7: Update
`.gitignore`

步骤7：更新
`.gitignore`

Step 8: Update
`package.json`

步骤8：更新
`package.json`

Step 9: Verify

步骤9：验证

Error Handling

错误处理

capacitor-plugin-spm-support

Original

Translation

Add SPM Support to a Capacitor Plugin

为Capacitor插件添加SPM支持

Prerequisites

前提条件

Procedures

操作步骤

Step 1: Gather Plugin Information

步骤1：收集插件信息

Step 2: Resolve CocoaPods Dependencies for SPM

步骤2：为SPM解析CocoaPods依赖

Step 3: Create Package.swift

步骤3：创建Package.swift

Step 4: Update the Swift Plugin Class

步骤4：更新Swift插件类

Step 5: Delete Objective-C Bridge Files

步骤5：删除Objective-C桥接文件

Step 6: Clean Up the Xcode Project File

步骤6：清理Xcode项目文件

Step 7: Update .gitignore

步骤7：更新.gitignore

Step 8: Update package.json

步骤8：更新package.json

Step 9: Verify

步骤9：验证

Error Handling

错误处理

Step 3: Create
`Package.swift`

步骤3：创建
`Package.swift`

Step 7: Update
`.gitignore`

步骤7：更新
`.gitignore`

Step 8: Update
`package.json`

步骤8：更新
`package.json`