Why This Project Exists
Capacitor is a highly popular cross-platform mobile development framework today. Its biggest strength is "one set of web code, reused across multiple platforms" — it runs frontend code through the built-in WebView on Android, allowing developers to deliver native apps using only HTML/JS/CSS.
However, there is a long-overlooked problem here: the kernel version of Android's built-in WebView is not unified.
Different vendors, different system versions, and even different models come with vastly different system WebView kernels. Older devices may have WebView stuck at Chrome versions from years ago, while newer devices run the latest versions. This means:
- The new APIs you confidently use during development may directly throw errors on users' older devices.
- To support legacy kernels, you have to write piles of polyfills and stick to outdated syntax.
- "Same code, inconsistent behavior" becomes the norm, and testing costs remain high.
The Solution: Introducing GeckoView
To make the kernel always controllable and always up‑to‑date, I introduced GeckoView — the browser engine behind Firefox.
As an independent engine that can be packaged with your app, GeckoView's greatest advantage is that the engine version is determined by you. Whatever kernel version you bundle with the app is what runs on users' devices, completely breaking the dependency on the system WebView.
Advantages
- Unified and up‑to‑date kernel version: No matter what device or system version the user has, they all run the same Firefox engine, ensuring fully consistent behavior.
- No more compatibility worries during development: You can safely use the latest HTML/JS/CSS features without writing hacks for old WebViews. The development experience is almost identical to modern web development.
- Same usage as vanilla Capacitor: Build commands and development workflows are exactly the same as native Capacitor, making the learning curve minimal and migration smooth.
Disadvantages
- Increased package size: Bundling a complete browser engine makes the installation package larger than the default solution. However, after minimal trimming, it is now compressed to about 120MB for the arm64 architecture — much smaller than the default 200MB, with further optimization possible.
Plugin Compatibility
Since most Capacitor native plugins are written for the system WebView, some plugins are not 100% compatible with GeckoView. Common reasons include:
- Plugins rely on WebView‑specific features or interfaces.
- Gradle version mismatches (this project uses Gradle 9, while some plugins are written for Gradle 8 and need manual upgrades).
To address this, I have prepared a Migration Guide to help you quickly adapt existing plugins to run on GeckoView.
Resources
| Content | Link |
|---|---|
| Main open‑source project | https://github.com/wszgrcy/capacitor-geckoview |
| Starter template (ready to use) | https://github.com/wszgrcy/capacitor-geckoview-starter |
| Plugin migration guide | https://github.com/wszgrcy/capacitor-geckoview-plugins/blob/main/docs/webview-to-geckoview-%E8%BF%81%E7%A7%BB%E6%8C%87%E5%8D%97.md |
Feedback & Discussion
If you encounter any issues while using this project, feel free to send an email to wszgrcy@gmail.com. I will do my best to help.
I hope this project helps you break free from WebView kernel fragmentation, so you can focus your energy on building your business logic with peace of mind.
Top comments (0)