🚀 I Served My React SPA from Android Assets Like a Professional Web Server — Here's What Happened
First load: 77ms. Reload: 2ms. 38x faster with LRU cache. No server, no permissions, no dependencies.
🤔 The Problem Every React Dev Faces
You've got your SPA running perfectly on localhost:5173. React, TypeScript, TailwindCSS, React Router, lazy loading... everything works beautifully.
Now you need to take it to Android.
Your traditional options:
// Option 1: Capacitor — 30MB runtime, complex config
// Option 2: Cordova — 15MB, outdated plugins
// Option 3: file:// protocol — broken CORS, SPA routes don't work
// Option 4: 50-line homemade script — fragile, no cache, no security
None of them feel right. You want something lightweight, fast, secure, and respectful of your architecture.
✨ The Solution: WebVirt Engine
An Android library of ~600 lines that simulates a virtual web server inside the WebView. Your SPA thinks it's at https://app.local, but everything comes from assets/.
// 5 lines. That's it.
WebVirt.with(this)
.host("app.local")
.bind(webView);
webView.loadUrl("https://app.local/");
That's all. Your React app running. SPA routes intact. No weird configuration.
🔬 But Don't Take My Word for It. Look at the Real Data.
To validate that WebVirt Engine was as fast as promised, I needed real metrics. Not synthetic benchmarks. Not "it feels fast." Cold, hard data.
The Secret Weapon: WebVirtMetrics
WebVirt Engine includes an optional metrics module that captures every asset load in real time:
// Enable only in debug. Zero overhead in production.
WebVirtMetrics.ENABLED = BuildConfig.DEBUG;
WebVirtMetrics.startSession();
// Every asset WebVirt loads gets recorded:
// - File path
// - Load time in milliseconds
// - Whether it came from cache or disk
// - Size in bytes
// - MIME type
Metrics are automatically persisted using LoggingUtil, which writes a log file to the device storage without requiring any permissions.
📊 The Results (Real Financial App)
Stack: React 18 + TypeScript + TailwindCSS + Vite + React Router
Assets: 1.4MB (3 main files + 13 lazy chunks)
Device: Physical Android, mid-range
First Load (Assets from Disk)
╔══════════════════════════════════════════════════╗
║ WEBVIRT ENGINE - PERFORMANCE REPORT ║
╠══════════════════════════════════════════════════╣
║ Session duration: 4214 ms ║
║ Total assets loaded: 3 ║
║ Total load time: 77 ms ║
║ Avg load time: 25 ms ║
║ Min load time: 10 ms ║
║ Max load time: 49 ms ║
╠══════════════════════════════════════════════════╣
║ Cache hits: 0 ║
║ Cache misses: 3 ║
║ Cache hit rate: 0.0% ║
║ Bytes from cache: 0 bytes ║
║ Total bytes loaded: 1426251 bytes ║
╠══════════════════════════════════════════════════╣
║ HTTP errors: 0 ║
║ SPA fallbacks: 1 ║
║ Range requests: 0 ║
╠══════════════════════════════════════════════════╣
║ BY MIME TYPE: ║
║ HTML x1 avg 10ms ║
║ CSS x1 avg 18ms ║
║ JavaScript x1 avg 49ms ║
╠══════════════════════════════════════════════════╣
║ RECENT LOADS (last 5): ║
║ 📄 /index.html 10ms║
║ 📄 /assets/index-DGe01YXs.css 18ms║
║ 📄 /assets/index-B3g6t1vt.js 49ms║
╚══════════════════════════════════════════════════╝
3 assets. 77ms total. Zero errors.
The 4214ms "session" includes: app startup, welcome animation, and the user tapping the "Start" button. WebVirt only took 77ms.
Second Load (LRU Cache in RAM)
By long-pressing the WebView (a hidden debug gesture), I forced a reload to measure cache performance:
╔══════════════════════════════════════════════════╗
║ WEBVIRT ENGINE - PERFORMANCE REPORT ║
╠══════════════════════════════════════════════════╣
║ Session duration: 513 ms ║
║ Total assets loaded: 3 ║
║ Total load time: 2 ms ║
║ Avg load time: 0 ms ║
║ Min load time: 0 ms ║
║ Max load time: 1 ms ║
╠══════════════════════════════════════════════════╣
║ Cache hits: 3 ║
║ Cache misses: 0 ║
║ Cache hit rate: 100.0% ║
║ Bytes from cache: 1426251 bytes ║
║ Total bytes loaded: 1426251 bytes ║
╠══════════════════════════════════════════════════╣
║ RECENT LOADS (last 5): ║
║ 💾 /index.html 1ms║
║ 💾 /assets/index-B3g6t1vt.js 0ms║
║ 💾 /assets/index-DGe01YXs.css 1ms║
╚══════════════════════════════════════════════════╝
3 assets. 2ms total. 100% cache hit rate.
Notice the emoji: 💾 = served from cache. The JS bundle took 0ms (less than 1ms, rounded down). HTML took 1ms. CSS took 1ms.
📈 The Side-by-Side Comparison
Metric First Load Reload (Cache) Improvement
Total load time 77ms 2ms 38.5x faster
Average time 25ms 0ms Instant
Slowest asset 49ms (JS) 1ms (CSS) 49x faster
Cache hit rate 0% 100% Perfect
Bytes transferred 1.4MB 0 All from RAM
HTTP errors 0 0 Perfect
🧠 Why Is It So Fast?
WebVirt Engine uses an in-memory LRU cache with SHA-1 ETags:
First load:
assets/index-B3g6t1vt.js → read from APK → cached in RAM → ETag generated
Second load:
assets/index-B3g6t1vt.js → ETag match? → Yes → 304 Not Modified → 0ms
· No asset decoding (Android stores them compressed in the APK)
· No disk I/O on reloads (everything in RAM)
· No real HTTP header parsing (everything is local)
· LruCache with memory awareness that cleans up on onTrimMemory()
🔒 Security That Doesn't Sacrifice Speed
Every response includes automatic security headers:
Content-Security-Policy: default-src 'self'; script-src 'self'...
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Access-Control-Allow-Origin: *
And CSP is fully configurable:
WebVirt.with(this)
.host("app.local")
.cspPolicy("default-src 'self'; script-src 'self' https://api.external.com")
.bind(webView);
🤝 Plays Beautifully with Nexus
Need native APIs? Nexus is a JavaScript ↔ Android bridge that doesn't interfere with WebVirt:
// WebVirt: serves the SPA
WebVirt.with(this).host("app.local").bind(webView);
// Nexus: export, import, PDF, camera, whatever you need
Nexus.installOn(webView)
.registerHandler("export", new ExportAdapter())
.registerHandler("import", new ImportAdapter())
.registerHandler("pdf", new PdfAdapter())
.initialize()
.withFilePicker(this);
nexus.attachToWebViewLifecycle(); // Doesn't break WebVirt
webView.loadUrl("https://app.local/");
WebVirt doesn't know Nexus exists. Nexus doesn't know WebVirt exists. They collaborate without coupling. This is real architecture.
🏗️ The Architecture That Makes This Possible
WebView
├── WebViewClient → WebVirt (owner)
│ └── shouldInterceptRequest() → assets/
│
├── WebViewLifecycleObserver → Nexus (decorator)
│ └── Wraps WebVirt's client without breaking it
│
└── JavascriptInterface → Nexus (parallel channel)
└── window.__nexus.call("export", data)
Three layers that don't compete. Decorator Pattern for lifecycle. Builder Pattern for fluent configuration. Strategy Pattern for PathHandlers.
📦 Production Proven
This isn't a "hello world" library. It's running in production in a real financial app with:
· ⚛️ React 18 + TypeScript + TailwindCSS
· 📦 5MB of assets (1.4MB main bundle)
· 🔀 React Router with lazy loading
· 📤 Native JSON export
· 📥 Native JSON import with FilePicker (no permissions required)
· 📄 Native PDF export
· 🔒 Restrictive CSP
· ⚡ 77ms first load, 2ms reloads
🚀 Coming Soon to GitHub & JitPack
WebVirt Engine v3.1.1
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.fouzstack:webvirt-engine:3.1.1'
}
Nexus v2.0.0
implementation 'com.github.fouzstack:nexus:2.0.0'
🎯 Is This for You?
✅ Use WebVirt Engine if you:
· Have an SPA in React/Vue/Svelte
· Want full control without heavy dependencies
· Need maximum offline performance
· Value clean architecture and real decoupling
❌ Not for you if you:
· Need hot reload during development (for now)
· Your company is already committed to Capacitor/Cordova
· Your app is purely native with no web content
🙏 Acknowledgments
To Fouzstack for creating and maintaining both WebVirt and Nexus.
To the GoF design patterns that still hold up 30 years later.
To WebVirtMetrics and LoggingUtil for making it possible to collect this data without extra permissions.
And to you, for reading this far.
Questions? Ideas? Want to contribute? The repos will be open for issues and PRs as soon as they go live.
Drop a comment: Which metric surprised you most? The 77ms first load or the 2ms cached reload?
Top comments (0)