Skip to content

Qbix/QBridge

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

7 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

QBridge

QBridge is a modern, lightweight native bridge for iOS that lets you build hybrid apps using idiomatic Swift, while exposing only the native APIs you explicitly choose to JavaScript.

It is designed as a clean, native-first alternative to Cordova and Capacitor, without legacy constraints, global magic, or opaque runtime behavior.

Qbix, the company behind QBridge, designs web-first applications. Get in touch if you need help or would like to collaborate with us. We've released our entire module platform as open-source to help developers. You're welcome:

Area Software Description
iOS QBridge Helps you easily make your web apps hybrid/native. Learn why you should be building serverless web apps.
Web Front End Q.js A modern, modular alternative to React/Angular/Vue. Q.minimal.js weighs ~40KB and can be dropped into any web app.
Web Full Stack Qbix Platform A battle-tested, modular framework for launching full sites (even build your own Facebook / LinkedIn). Explore this only after you built a serverless web app.
AI AI Agents Working on an AI Agency to make all this easy to configure for non-developers starting in 2026

๐ŸŒ‰ What QBridge Is

Concept What it means
Native-first You write real Swift, not adapters around adapters
Explicit API surface Only methods you expose are callable from JS
WKWebView-native Built directly on WKWebView, no extra runtime
Extension-safe Works in apps, App Clips, and Share Extensions
Minimal bridge No plugin XML, no manifests, no global JS soup

๐Ÿงฑ How QBridge Works (High Level)

Step Description
1 QBridge attaches to a WKWebView
2 JavaScript sends structured messages via WKScriptMessageHandler
3 Messages are routed by service + action
4 Swift methods are invoked directly
5 Results are returned via a callback ID

There is no polling, no hidden lifecycle, and no background JavaScript runtime.


๐Ÿ“Core Design Principles

Principle Why it matters
Single bridge instance Predictable behavior, easy debugging
Message-based routing Clear mental model
Obj-C compatible selectors Zero Swift/JS impedance mismatch
Thread-safe execution Native work happens off the main thread
Explicit callbacks No promises disappearing into the void

๐Ÿ†š QBridge vs Cordova vs Capacitor

Feature QBridge Cordova Capacitor
Write plugins in Swift Yes No Partial
Expose only selected methods Yes No Partial
Plugin discovery Compile-time Runtime Runtime
WebView storage durability Solved natively Fragile Fragile
IndexedDB backed by SQLite Built-in No No
App Clips / Extensions First-class Unsupported Limited
JS bridge size Minimal Large Medium
Debuggability High Low Medium

Cordova and Capacitor try to hide native. QBridge embraces native and makes it safe.


๐Ÿš€ Getting Started

Add QBridge to Your Xcode Project

Step Action
1 Add the QBridge Swift files to your app target
2 Include them in App / App Clip / Extension targets as needed
3 No CocoaPods, no CLI tools, no config files

Attach QBridge to a WKWebView

Swift:

let webView = WKWebView(frame: .zero)
QBridge.shared.attach(to: webView)

Send Messages from JavaScript

JavaScript:

window.webkit.messageHandlers.QBridge.postMessage({
  service: "DeviceBridgePlugin",
  action: "info",
  args: [],
  callbackId: "cb1"
});

Receive Results in JavaScript

window.QBridge = {
  onNative(payload) {
    console.log(payload.data);
  }
};

Write Your First Plugin

Swift:

@objc class MyPlugin: QBridgeBaseService {
  @objc func hello(_ args: Any?, callbackId: String?) {
    bridge.sendEvent(callbackId ?? "", data: ["message": "Hello from Swift"])
  }
}

๐Ÿงฉ Plugins

The plugins below are production-grade, written in idiomatic Swift, and designed to solve real problems in hybrid apps. Like continuing to use the same storage Web APIs you're already used to (IndexedDB and localStorage) but have them actually continue to work in your app. Use the same code on the Web and in your app!

They are listed in order of importance.


Persistent Web Storage (localStorage Backup)

๐Ÿ•ด"It would be a shame if your app's storage was suddenly deleted."

Problem Reality on iOS
WebView localStorage Can be purged
IndexedDB Can disappear
Silent data loss Happens in production
Capability Description
Load storage Restores saved localStorage on launch
Save deltas Writes changes to disk
File-backed Uses real files you control
Session tracking Detects fresh vs restored sessions

IndexedDB (SQLite-backed, Native)

IndexedDB Feature WebView Reality
Object stores Opaque
Indexes Opaque
Persistence Unreliable
Backups Impossible
Feature Implementation
IndexedDB-style API JavaScript-compatible
SQLite backend Real .sqlite files
Versioned upgrades Deterministic
Indexes & cursors Native-speed
Import / export Supported
Native toggle Optional

Secure Identity & Signing

Capability Why it exists
Secure Enclave keys Hardware-backed identity
App Attest fallback Works in App Clips
Continuity Identity survives upgrades
Payload signing Anti-fraud, trust

Clipboard Access

Feature Why
Read clipboard User workflows
Write clipboard Sharing
Native permissions Predictable behavior

Device Information

Data Use case
Model Debugging
OS version Feature gating
Name Diagnostics

Share Extensions (Email & SMS)

Problem Solution
JS canโ€™t close extensions Native completion
Broken share flows Fixed
Attachments Supported

View / Extension Closer

Context Behavior
App UI Dismiss controller
Extension UI Complete request
Fallback Safe default

Contacts & Address Book

Capability Notes
Permissions Correctly handled
Read contacts Structured
Groups Supported
Native picker Included
Add / update / delete Full lifecycle

Final Notes

QBridge is intentionally small, explicit, and honest.

If you want predictable storage, strong security, App Clips support, and clean Swift-native plugins, QBridge is the modern choice.

About

Modern, lightweight alternative to Cordova and Capacitor

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages