Skip to content

Clarify return types for Capacitor iOS plugins #471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
riderx wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Clarify return types for Capacitor iOS plugins #471

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f029997
docs: clarify return types for Capacitor iOS plugins
riderx Nov 11, 2025
576039e
Merge branch 'main' into better-plugin-doc
riderx Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/plugins/creating-plugins/ios-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,12 @@ This makes the `echo` method available to the Capacitor web runtime, indicating

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:
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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:

Copilot uses AI. Check for mistakes.

- `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.
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
- `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.

Copilot uses AI. Check for mistakes.
- `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.
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
- `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.

Copilot uses AI. Check for mistakes.

## Permissions

If your plugin has functionality on iOS that requires permissions from the end user, then you will need to implement the permissions pattern.
Expand Down
6 changes: 6 additions & 0 deletions versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,12 @@ This makes the `echo` method available to the Capacitor web runtime, indicating

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:
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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:

Copilot uses AI. Check for mistakes.

- `CAPPluginReturnNone`: fire-and-forget methods that return immediately through `nativeCallback` and do not keep a promise/callback open.
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
- `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.

Copilot uses AI. Check for mistakes.
- `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.
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
- `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.

Copilot uses AI. Check for mistakes.

## Permissions

If your plugin has functionality on iOS that requires permissions from the end user, then you will need to implement the permissions pattern.
Expand Down
Loading