or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bridge-integration.mdconfiguration.mdindex.mdmethod-calls.mdnotifications.mdplugin-development.md
tile.json

tessl/npm-capacitor--ios

iOS native runtime implementation for Capacitor that bridges JavaScript and native iOS APIs.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@capacitor/ios@7.4.x

To install, run

npx @tessl/cli install tessl/npm-capacitor--ios@7.4.0

index.mddocs/

Capacitor iOS

Capacitor iOS provides the native iOS runtime implementation for Capacitor applications, enabling web developers to build native iOS apps using JavaScript, HTML, and CSS. This package contains Swift and Objective-C implementations that bridge web applications with native iOS APIs and device capabilities.

Package Information

  • Package Name: @capacitor/ios
  • Package Type: npm
  • Language: Swift/Objective-C
  • Platform: iOS 14.0+
  • Installation: npm install @capacitor/ios
  • Pod Integration: Distributed as CocoaPods specs (Capacitor.podspec, CapacitorCordova.podspec)

Core Imports

Swift:

import Capacitor

Objective-C:

@import Capacitor;

Basic Usage

import UIKit
import Capacitor

class ViewController: CAPBridgeViewController {
    override func instanceDescriptor() -> InstanceDescriptor {
        let descriptor = InstanceDescriptor()
        descriptor.appLocation = Bundle.main.url(forResource: "public", withExtension: nil)!
        return descriptor
    }
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Capacitor bridge is automatically initialized
    }
}

Architecture

Capacitor iOS is built around several key components:

  • Bridge Architecture: CAPBridgeViewController and CapacitorBridge manage JavaScript-to-native communication
  • Plugin System: CAPPlugin base class and CAPBridgedPlugin protocol for extending functionality
  • Configuration Management: InstanceDescriptor and InstanceConfiguration for runtime configuration
  • Type Safety: JSTypes system providing type-safe JavaScript-to-Swift data conversion
  • Notification Routing: NotificationRouter for handling push and local notifications
  • Cordová Compatibility: CapacitorCordova framework for backward compatibility

Capabilities

Bridge Integration

Core bridge setup and view controller integration for embedding Capacitor web applications in iOS apps.

open class CAPBridgeViewController: UIViewController {
    open func instanceDescriptor() -> InstanceDescriptor
    open func webViewConfiguration(for instanceConfiguration: InstanceConfiguration) -> WKWebViewConfiguration
    open func capacitorDidLoad()
    
    public var bridge: CAPBridgeProtocol? { get }
    public var webView: WKWebView? { get }
    public var isStatusBarVisible: Bool { get set }
    public var statusBarStyle: UIStatusBarStyle { get set }
    public var supportedOrientations: [Int] { get set }
}

Bridge Integration

Application Configuration

Instance configuration system for customizing Capacitor behavior, webview settings, and runtime options.

@objc(CAPInstanceDescriptor)
public class InstanceDescriptor: NSObject {
    public init()
    public init(at appURL: URL, configuration configURL: URL?, cordovaConfiguration cordovaURL: URL?)
    
    // Core Configuration
    public var appLocation: URL
    public var appStartPath: String?
    public var serverURL: String?
    public var urlScheme: String?
    public var urlHostname: String?
    
    // WebView Configuration  
    public var backgroundColor: UIColor?
    public var scrollingEnabled: Bool
    public var zoomingEnabled: Bool
    public var allowLinkPreviews: Bool
    public var isWebDebuggable: Bool
    
    // Security & Navigation
    public var allowedNavigationHostnames: [String]
    public var limitsNavigationsToAppBoundDomains: Bool
    
    // Plugin Configuration
    public var pluginConfigurations: NSDictionary
}

Application Configuration

Plugin Development

Comprehensive plugin development framework for creating custom native functionality accessible from JavaScript.

@interface CAPPlugin : NSObject
- (void)load;
- (void)addEventListener:(NSString *)eventName listener:(CAPPluginCall *)listener;
- (void)notifyListeners:(NSString *)eventName data:(NSDictionary<NSString *, id> *)data;
- (void)checkPermissions:(CAPPluginCall *)call;
- (void)requestPermissions:(CAPPluginCall *)call;

@property (nonatomic, weak, nullable) WKWebView *webView;
@property (nonatomic, weak, nullable) id<CAPBridgeProtocol> bridge;
@property (nonatomic, strong, nonnull) NSString *pluginId;
@property (nonatomic, strong, nonnull) NSString *pluginName;
@end

@protocol CAPBridgedPlugin <NSObject>
@property (nonnull, readonly) NSString *identifier;
@property (nonnull, readonly) NSString *jsName;
@property (nonnull, readonly) NSArray<CAPPluginMethod *> *pluginMethods;
@end

Plugin Development

Method Calls & Type Safety

Type-safe JavaScript-to-native method invocation with structured parameter access and response handling.

@objc(CAPPluginCall)
public class CAPPluginCall: NSObject {
    public let callbackId: String
    public let methodName: String
    public let options: NSDictionary
    public var keepAlive: Bool
    
    // Response Methods
    public func resolve()
    public func resolve(_ data: PluginCallResultData?)
    public func reject(_ message: String, _ code: String?, _ error: Error?, _ data: PluginCallResultData?)
    public func unimplemented(_ message: String)
    public func unavailable(_ message: String)
    
    // Type-Safe Accessors
    public func getString(_ key: String, _ defaultValue: String?) -> String?
    public func getBool(_ key: String, _ defaultValue: Bool) -> Bool
    public func getInt(_ key: String, _ defaultValue: Int) -> Int
    public func getObject(_ key: String, _ defaultValue: JSObject?) -> JSObject?
    public func getArray(_ key: String, _ defaultValue: JSArray?) -> JSArray?
}

Method Calls & Type Safety

Notification Handling

Comprehensive notification routing system for managing push notifications and local notifications with plugin integration.

@objc(CAPNotificationRouter)
public class NotificationRouter: NSObject, UNUserNotificationCenterDelegate {
    public weak var pushNotificationHandler: NotificationHandlerProtocol?
    public weak var localNotificationHandler: NotificationHandlerProtocol?
    public var handleApplicationNotifications: Bool { get set }
}

@objc(CAPNotificationHandlerProtocol) 
public protocol NotificationHandlerProtocol {
    func willPresent(notification: UNNotification) -> UNNotificationPresentationOptions
    func didReceive(response: UNNotificationResponse)
}

Notification Handling

Types

Core Bridge Types

@objc public protocol CAPBridgeProtocol {
    var webView: WKWebView? { get }
    var config: InstanceConfiguration { get }
    var notificationRouter: NotificationRouter { get }
    
    func plugin(withName name: String) -> CAPPlugin?
    func registerPluginType(_ pluginType: CAPPlugin.Type)
    func eval(js: String)
}

public typealias JSObject = [String: JSValue]
public typealias JSArray = [JSValue]
public typealias PluginCallResultData = JSObject

public protocol JSValue {}
extension String: JSValue {}
extension Bool: JSValue {}
extension Int: JSValue {}
extension Float: JSValue {}
extension Double: JSValue {}
extension NSNumber: JSValue {}
extension NSString: JSValue {}
extension NSArray: JSValue {}
extension NSDictionary: JSValue {}

Configuration Types

public enum InstanceType: Int {
    case fixed
    case variable
}

public struct InstanceWarning: OptionSet {
    public static let missingAppDir = InstanceWarning(rawValue: 1 << 0)
    public static let missingFile = InstanceWarning(rawValue: 1 << 1)
    public static let invalidFile = InstanceWarning(rawValue: 1 << 2)
    public static let missingCordovaFile = InstanceWarning(rawValue: 1 << 3)
    public static let invalidCordovaFile = InstanceWarning(rawValue: 1 << 4)
}

public struct InstanceLoggingBehavior: OptionSet {
    public static let none = InstanceLoggingBehavior(rawValue: 1 << 0)
    public static let debug = InstanceLoggingBehavior(rawValue: 1 << 1)
    public static let production = InstanceLoggingBehavior(rawValue: 1 << 2)
}

Plugin Development Types

@objc(CAPPluginMethod)
public class CAPPluginMethod: NSObject {
    public init(name: String, returnType: CAPPluginReturnType)
    
    public let name: String
    public let selector: Selector
    public let returnType: CAPPluginReturnType
}

public enum CAPPluginReturnType: Int {
    case none
    case callback
    case promise
}

@objc(CAPPluginCallResult)
public class CAPPluginCallResult: NSObject {
    public let data: PluginCallResultData?
}

@objc(CAPPluginCallError)
public class CAPPluginCallError: NSObject {
    public let message: String
    public let code: String?
    public let error: Error?
    public let data: PluginCallResultData?
}