Clarify return types for Capacitor iOS plugins#471
Clarify return types for Capacitor iOS plugins#471riderx wants to merge 2 commits intoionic-team:mainfrom
Conversation
|
@riderx is attempting to deploy a commit to the Ionic Team on Vercel. A member of the Team first needs to authorize it. |
There was a problem hiding this comment.
Pull request overview
Adds clarification to the iOS plugin creation guide about Capacitor plugin method returnType values and how they affect the JS↔native bridge.
Changes:
- Documented the three iOS
returnTypevalues (CAPPluginReturnNone,CAPPluginReturnPromise,CAPPluginReturnCallback) in the iOS plugin guide. - Added this clarification to both the current docs and the versioned v7 docs.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/plugins/creating-plugins/ios-guide.md | Adds a new section explaining iOS plugin returnType behaviors. |
| versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md | Mirrors the new returnType explanation in the v7 snapshot. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| - `CAPPluginReturnNone`: Use for fire-and-forget calls that neither resolve nor reject a JavaScript promise. The generated JS uses `nativeCallback` immediately and expects no further data. | ||
| - `CAPPluginReturnPromise`: The default. The generated JS returns a `Promise` that you must resolve or reject once per call. | ||
| - `CAPPluginReturnCallback`: Use when you want to push multiple updates back to the web side. Capacitor automatically appends a `_callback` argument to your method, and the generated JS keeps the callback alive until you explicitly finish. |
There was a problem hiding this comment.
The CAPPluginReturnCallback description says Capacitor appends a _callback argument to the Swift method. In Capacitor’s native APIs, streaming/multiple responses are handled by keeping the CAPPluginCall alive (e.g., call.keepAlive = true) and releasing it when finished (see docs/main/reference/core-apis/saving-calls.md). Suggest updating this explanation to match the documented keepAlive/saveCall pattern instead of implying the Swift method signature gains a _callback parameter.
| - `CAPPluginReturnCallback`: Use when you want to push multiple updates back to the web side. Capacitor automatically appends a `_callback` argument to your method, and the generated JS keeps the callback alive until you explicitly finish. | |
| - `CAPPluginReturnCallback`: Use when you want to push multiple updates back to the web side (for example, streaming or progress updates). The generated JS uses a callback-style API and keeps the callback alive while your native plugin keeps the associated `CAPPluginCall` alive (for example by setting `call.keepAlive = true` or using the “saving calls” API) and explicitly finishes it when no more updates will be sent. |
|
|
||
| To add more methods to your plugin, create them in the `.swift` plugin class with the `@objc` before the `func` keyword and add a new `CAPPluginMethod` entry in the `pluginMethods` array. | ||
|
|
||
| Capacitor defines three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift`, and each one changes how the generated JavaScript wrapper calls into native code: |
There was a problem hiding this comment.
The docs repo does not contain ios/Capacitor/Capacitor/JSExport.swift, so referencing it as a plain path is not actionable for readers. Prefer linking to the upstream file on GitHub (or remove the file-path reference entirely) to avoid broken/ambiguous references.
| Capacitor defines three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift`, and each one changes how the generated JavaScript wrapper calls into native code: | |
| Capacitor defines three `returnType` values in [`JSExport.swift`](https://github.com/ionic-team/capacitor/blob/main/ios/Capacitor/Capacitor/JSExport.swift), and each one changes how the generated JavaScript wrapper calls into native code: |
|
|
||
| Capacitor defines three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift`, and each one changes how the generated JavaScript wrapper calls into native code: | ||
|
|
||
| - `CAPPluginReturnNone`: fire-and-forget methods that return immediately through `nativeCallback` and do not keep a promise/callback open. |
There was a problem hiding this comment.
CAPPluginReturnNone is described here as returning via nativeCallback and not keeping a promise open, but Capacitor plugin calls are still promise-based (the void-return case is Promise<void> in /plugins/method-types). Consider rephrasing to avoid implying there is no promise completion, and avoid referencing internal implementation details like nativeCallback.
| - `CAPPluginReturnNone`: fire-and-forget methods that return immediately through `nativeCallback` and do not keep a promise/callback open. | |
| - `CAPPluginReturnNone`: methods that don't return a value to JavaScript and complete immediately (mapped to `Promise<void>`), without keeping a long‑lived callback open. |
|
|
||
| - `CAPPluginReturnNone`: fire-and-forget methods that return immediately through `nativeCallback` and do not keep a promise/callback open. | ||
| - `CAPPluginReturnPromise`: the standard promise-based bridge where you resolve or reject once per invocation. | ||
| - `CAPPluginReturnCallback`: for streaming data. Capacitor adds a `_callback` parameter to your Swift method and keeps the JavaScript callback alive until you finish. |
There was a problem hiding this comment.
The CAPPluginReturnCallback bullet says Capacitor adds a _callback parameter to the Swift method. Streaming callbacks are typically implemented by keeping the CAPPluginCall alive (call.keepAlive = true) and releasing it when done (see docs/main/reference/core-apis/saving-calls.md). Please adjust this text to match the documented native API behavior rather than describing a modified Swift method signature.
| - `CAPPluginReturnCallback`: for streaming data. Capacitor adds a `_callback` parameter to your Swift method and keeps the JavaScript callback alive until you finish. | |
| - `CAPPluginReturnCallback`: for streaming or repeated data. Use the associated `CAPPluginCall` (for example, with `call.keepAlive = true` and the saving-calls pattern) to keep the JavaScript callback alive until you are done and release the call. |
|
|
||
| To add more methods to your plugin, create them in the `.swift` plugin class with the `@objc` before the `func` keyword and add a new `CAPPluginMethod` entry in the `pluginMethods` array. | ||
|
|
||
| Capacitor currently exposes three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift` that control how the generated JavaScript proxies interact with native code: |
There was a problem hiding this comment.
The docs repo does not contain ios/Capacitor/Capacitor/JSExport.swift, so referencing it as a plain path is not actionable for readers. Prefer linking to the upstream file on GitHub (or remove the file-path reference entirely) to avoid broken/ambiguous references.
| Capacitor currently exposes three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift` that control how the generated JavaScript proxies interact with native code: | |
| Capacitor currently exposes three `returnType` values in [`JSExport.swift`](https://github.com/ionic-team/capacitor/blob/main/ios/Capacitor/Capacitor/JSExport.swift) that control how the generated JavaScript proxies interact with native code: |
|
|
||
| Capacitor currently exposes three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift` that control how the generated JavaScript proxies interact with native code: | ||
|
|
||
| - `CAPPluginReturnNone`: Use for fire-and-forget calls that neither resolve nor reject a JavaScript promise. The generated JS uses `nativeCallback` immediately and expects no further data. |
There was a problem hiding this comment.
CAPPluginReturnNone is described here as not resolving/rejecting a JavaScript promise, but Capacitor method calls are still promise-based (see /plugins/method-types where the void-return case is Promise<void>). This should be reworded to reflect that the promise resolves with no value (and can still reject on error), rather than implying there is no promise completion.
| - `CAPPluginReturnNone`: Use for fire-and-forget calls that neither resolve nor reject a JavaScript promise. The generated JS uses `nativeCallback` immediately and expects no further data. | |
| - `CAPPluginReturnNone`: Use for calls that don't return a value. The generated JS still returns a `Promise<void>` that resolves with no value (and can reject on error), and it uses `nativeCallback` immediately without expecting further data. |
1 participant
Enhance documentation by clarifying the return types for Capacitor iOS plugins, detailing how each return type affects the interaction between JavaScript and native code.