DEV Community

Giovani Fouz
Giovani Fouz

Posted on

I Served My React SPA from Android Assets Like a Professional Web Server

#android #mobile #performance #react

🚀 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
Enter fullscreen mode Exit fullscreen mode

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/");
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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║
╚══════════════════════════════════════════════════╝
Enter fullscreen mode Exit fullscreen mode

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║
╚══════════════════════════════════════════════════╝
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

· 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: *
Enter fullscreen mode Exit fullscreen mode

And CSP is fully configurable:

WebVirt.with(this)
    .host("app.local")
    .cspPolicy("default-src 'self'; script-src 'self' https://api.external.com")
    .bind(webView);
Enter fullscreen mode Exit fullscreen mode

🤝 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/");
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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'
}
Enter fullscreen mode Exit fullscreen mode

Nexus v2.0.0

implementation 'com.github.fouzstack:nexus:2.0.0'
Enter fullscreen mode Exit fullscreen mode

🎯 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)