DEV Community: Giovani Fouz

I Built a Perceptual Virtualization Engine for React — Optimized for Android WebViews and Low-End Devices

Giovani Fouz — Sun, 31 May 2026 18:47:46 +0000

I Built a Perceptual Virtualization Engine for React — Optimized for Android WebViews and Low-End Devices

Most React virtualization libraries optimize for desktop browsers.

Very few survive this scenario:

Android 12
Low-end phone
Embedded WebView
Hundreds of complex interactive forms
Real-time database updates
Continuous touch scrolling
Controlled React inputs
Dynamic calculations
Conditional rendering
Zero visual instability

That was the problem I needed to solve.

After months of experimentation, profiling, recycling strategies, motion analysis, predictive rendering, and WebView debugging, I ended up building something that evolved far beyond a traditional virtualized list.

I call it:

Perceptual Engine

A perceptual rendering engine for React.

The Problem

Traditional virtualization libraries are excellent for static rows.

But deeply interactive UI is a completely different challenge.

Especially on low-end Android devices running inside embedded WebViews.

I tested this extensively on a Samsung Galaxy A03 Core running Android 12 inside a WebView environment.

That environment exposes problems most desktop browsers hide:

transform hit-testing bugs
recycled layer interaction issues
GPU compositing instability
focus loss during recycling
touch event inconsistencies
invisible layers intercepting input
stacking-context rendering quirks

The goal was ambitious:

«Render 120–150 heavy interactive forms smoothly on low-end Android hardware without blinking, layout jumps, or input instability.»

These Were Not Lightweight Rows

Each rendered item was effectively a mini application.

Every form contained:

controlled React inputs
derived calculations
conditional rendering
dynamic sections
navigation handlers
validation logic
live state synchronization
IndexedDB persistence through Dexie
multiple interactive components
touch interactions
real-time updates

In practice, every row behaved more like a fully interactive UI surface than a simple list item.

That distinction matters enormously when building virtualization systems.

The Architecture

Perceptual Engine is composed of multiple specialized systems working together.

Motion Analyzer

Tracks scroll velocity, acceleration, deceleration, and motion patterns to dynamically adapt rendering behavior.

const motionState = motionAnalyzer.update(scrollTop, performance.now());

This allows predictive overscan and smarter scheduling decisions.

Predictive Rendering

Instead of rendering only what's visible, the engine predicts where the user is going next.

predictFuturePosition(200);

The result is a scrolling experience that feels significantly smoother under rapid touch movement.

Recycling Pool

DOM nodes are aggressively recycled instead of recreated.

recyclingPool.acquireWithOrigin(virtualItem);

This dramatically reduces:

garbage collection
layout thrashing
memory pressure
mount/unmount churn

Especially important on low-end Android devices.

Adaptive Quality System

The engine continuously monitors FPS and rendering pressure.

If performance drops:

overscan is reduced
predictive rendering can be disabled
GPU compositing can be downgraded
rendering complexity adapts automatically

private degradeQuality(): void

This keeps the UI responsive even under stress.

The Hardest Bug

Ironically, performance was not the hardest problem.

Interaction was.

At one point:

scrolling was perfect
rendering was stable
150 complex forms rendered smoothly
memory usage was controlled

…but inputs and buttons stopped working.

The cause turned out to be an invisible stacking-context and hit-testing issue involving:

absolute positioning
recycled layers
touch routing
compositing layers
Android rendering behavior

The final fix?

A single z-index adjustment on the interactive form layer.

That one line restored:

input focus
text selection
button interaction
touch handling
keyboard interaction

without sacrificing performance.

This was a reminder that mobile rendering engines still behave very differently from desktop browsers.

Performance Results

Test device:

Samsung Galaxy A03 Core
Android 12
Embedded WebView

Results:

120–150 heavy interactive forms
stable scrolling
no blinking
no layout jumping
no focus flickering
minimal re-renders
low memory pressure
responsive touch interactions
stable controlled inputs

The engine remained stable even under rapid touch scrolling.

Key Optimizations

Some implementation details that made a huge difference:

Deferred Recycling During Touch Scroll

private isTouchScrolling: boolean = false;

Recycling is temporarily deferred while touch scrolling is active.

This prevents focus destruction and touch instability.

requestAnimationFrame Mutation Batching

requestAnimationFrame(() => {
this.applyMutationBatch();
});

DOM mutations are batched into animation frames to reduce layout thrashing.

Adaptive Overscan

Overscan changes dynamically depending on motion intensity.

Fast scroll → larger predictive window.

Slow scroll → lower memory pressure.

Pool-Based DOM Lifecycle

The engine almost never destroys DOM nodes.

It aggressively reuses them instead.

This dramatically improves consistency in WebView environments.

Why “Perceptual”?

Because the engine optimizes for perceived smoothness, not just raw rendering metrics.

Users don’t care how many DOM nodes exist.

They care about:

responsiveness
touch stability
visual continuity
interaction reliability
absence of flicker
stable inputs
smooth scrolling

Perceptual Engine prioritizes those things first.

What I Learned

Building virtualization systems for desktop browsers is one thing.

Building them for Android WebViews on low-end hardware is another level entirely.

That environment forces you to care about:

compositing behavior
touch hit-testing
GPU layer stability
DOM recycling safety
mobile rendering quirks
focus preservation
stacking contexts
interaction consistency

And honestly, those constraints produced a much better architecture than I originally planned.

What’s Next

Planned improvements:

grid virtualization
masonry layouts
sticky regions
smarter predictive heuristics
accessibility improvements
React Native experiments
worker-assisted scheduling
improved measurement prediction
advanced interaction preservation

Final Thoughts

Perceptual Engine started as a performance experiment.

It evolved into a rendering system focused on one core idea:

«Smoothness is not just about FPS.
It’s about perception, interaction stability, and continuity.»

And surprisingly, some of the hardest problems were not rendering problems at all.

They were interaction problems.

Especially inside Android WebViews.

If you're interested in virtualization, rendering systems, scheduling, recycling strategies, or performance engineering, I’d love to hear your thoughts.

GitHub repository coming soon.

Perceptual Engine: Un motor de renderizado que predice el movimiento del usuario

Giovani Fouz — Mon, 25 May 2026 10:03:23 +0000

🧠 Perceptual Engine: Un motor de renderizado que predice el movimiento del usuario

La mayoría de las librerías de virtualización optimizan el número de nodos en el DOM.

Yo me empecé a preguntar:

¿Y si el problema real no es el tamaño del DOM… sino la percepción humana?

Esa pregunta se convirtió en Perceptual Engine, un runtime de renderizado experimental para React centrado en la fluidez percibida, el desplazamiento predictivo, la calidad adaptativa y el renderizado consciente de la GPU.

No se trata de "renderizar menos nodos".

Se trata de renderizar lo que el usuario está a punto de necesitar.

El problema que no se abordó realmente

Las librerías tradicionales de desplazamiento virtual son geométricas.

Calculan la visibilidad así:

scrollTop → índices visibles → renderizar

Eso funciona… hasta que fuerzas la UI al límite:

Formularios complejos

WebViews de Android

Inputs con teclados IME

Cálculos en tiempo real

Layouts dinámicos grandes

Desplazamiento rápido con flick

Ahí las cosas empiezan a fallar:

Parpadeos

Pérdida de foco

Tirones en el scroll

Caída de frames

Rotación excesiva de portales

Destrucción de estado

Me topé con todo esto construyendo un sistema TPV que corre dentro de un WebView de Android.

Y las soluciones existentes no estaban diseñadas para ese entorno.

Lo que construí

Perceptual Engine trata el desplazamiento como un problema de predicción de movimiento.

En lugar de reaccionar solo a la posición del scroll, el motor analiza continuamente:

velocidad

aceleración

sobreaceleración (cambio en la aceleración)

distancia de frenado prevista

presión de renderizado

presupuesto de frames

uso de capas de GPU

Pipeline:

ENTRADA ↓ ANÁLISIS DE MOVIMIENTO ↓ PREDICCIÓN ↓ VISIBILIDAD ↓ MEDICIÓN ↓ MUTACIÓN DEL DOM ↓ COMPOSICIÓN EN GPU

Cada etapa puede:

dividir el trabajo entre frames

cancelarse a sí misma

degradar la calidad

repriorizar tareas

Se comporta más como un pequeño motor de videojuegos que como una lista tradicional de React.

Ideas centrales

Overscan basado en movimiento

En lugar de un overscan fijo:

overscan={5}

El motor predice hacia dónde se mueve el usuario usando la sobreaceleración y la velocidad.

Los desplazamientos rápidos aumentan automáticamente el renderizado predictivo.

Los movimientos lentos reducen el trabajo automáticamente.

Sistema de calidad adaptativa

Si los FPS bajan:

el overscan se reduce

las capas de GPU disminuyen

las predicciones se simplifican

las mediciones costosas se posponen

Muy similar a los sistemas de calidad adaptativa usados en motores de videojuegos.

Pool de DOM persistente

En lugar de montar/desmontar constantemente:

los nodos del DOM se mantienen vivos

los elementos se reciclan a través de pools

los portales inyectan contenido incrementalmente

el estado sobrevive al desplazamiento

Esto fue crítico para formularios complejos y teclados de Android.

Planificador con presupuesto de frames

El planificador usa:

prioridades

división de tiempo (time slicing)

lógica anti-inanición

presupuestos de frames

No todo el trabajo de renderizado merece la misma urgencia.

API sencilla

import { PerceptualList } from 'perceptual-engine';

function ProductForms({ products }) {
  return (
    <PerceptualList
      items={products}
      estimatedItemSize={600}
      overscan="auto"
      enableGPUCompositing
      persistenceKey="product-forms"
      renderItem={(product) => (
        <ProductForm product={product} />
      )}
    />
  );
}

El motor se encarga de:

overscan predictivo

reciclaje de DOM

restauración del scroll

degradación adaptativa

composición en GPU

planificación

agrupación de mediciones

Caso de uso real en producción

Actualmente uso Perceptual Engine en producción dentro de un sistema TPV en WebView de Android.

Escenario:

15 formularios complejos simultáneos

Cálculos en tiempo real

Inputs numéricos

Validación

Totales dinámicos

Alta interacción

Hardware Android de gama baja

Con virtualización tradicional:

pérdida de foco

parpadeo con IME

estado que desaparece

desplazamiento inestable

Con Perceptual Engine:

desplazamiento estable a 60fps

interacción persistente

cero parpadeos

sin destrucción de foco

Ese entorno moldeó toda la arquitectura.

Arquitectura

React
  ↓
PerceptualList
  ↓
usePerceptualEngine
  ↓
PerceptualEngine
  ├── MotionAnalyzer
  ├── LayoutPredictor
  ├── ViewportManager
  ├── RecyclingPool
  ├── CompositorLayer
  ├── Scheduler
  └── ScrollRestoration

Qué lo hace diferente

La mayoría de librerías de virtualización optimizan:

memoria

número de nodos en el DOM

matemáticas de visibilidad

Perceptual Engine optimiza:

fluidez percibida

continuidad de la interacción

predicción de movimiento

estabilidad de frames

presión sobre la GPU

Es una filosofía muy diferente.

Estado actual

El motor está actualmente en alfa avanzada.

Funcionando hoy:

✅ Overscan adaptativo

✅ Pools de reciclaje de DOM

✅ Caché incremental de portales

✅ Restauración de scroll multiestrategia

✅ Degradación consciente de los FPS

✅ Agrupación compartida de ResizeObserver

✅ Overlay de rendimiento

✅ Controles de composición en GPU

Hoja de ruta:

🔜 Publicación en npm

🔜 Benchmarks

🔜 Renderizado sin portales

🔜 Capa de preservación de foco

🔜 Planificación basada en workers

🔜 Suite de tests completa

Limitaciones conocidas

Los portales de React aún introducen sobrecarga a escalas extremas

Los WebViews de Android antiguos pueden comportarse de forma inconsistente

La API aún está evolucionando antes del lanzamiento en npm

La documentación sigue en progreso

Filosofía

No estoy intentando construir "otra librería de virtualización".

Estoy explorando cómo podría ser el renderizado si tratáramos el desplazamiento como una señal perceptiva en lugar de un problema geométrico.

Los usuarios no experimentan:

"índices visibles"

Los usuarios experimentan:

fluidez, continuidad y capacidad de respuesta.

Eso cambia la arquitectura por completo.

Buscando feedback

Me encantaría recibir feedback de gente que trabaje con:

WebViews de Android

formularios complejos

conjuntos de datos enormes

casos límite de virtualización

hardware de gama baja

infraestructura de renderizado

Especialmente si se han topado con limitaciones en soluciones existentes.

GitHub

github.com/fouzstack/perceptual-engine

Lanzamiento en npm próximamente.

¿Qué opinas?

¿Es el renderizado predictivo el siguiente paso después de la virtualización?

Perceptual Engine — A Rendering Engine That Predicts User Movement

Giovani Fouz — Mon, 25 May 2026 09:37:27 +0000

🧠 Perceptual Engine — A Rendering Engine That Predicts User Movement

Most virtualization libraries optimize DOM count.

I started wondering:

«What if the real problem is not DOM size… but human perception?»

That question became Perceptual Engine — an experimental rendering runtime for React focused on perceived smoothness, predictive scrolling, adaptive quality, and GPU-aware rendering.

Not “render fewer nodes”.

Render what the user is about to need.

The Problem Nobody Really Solved

Traditional virtual scrolling libraries are geometric.

They calculate visibility like this:

scrollTop → visible indexes → render

That works… until you push the UI hard:

Complex forms
Android WebViews
Inputs with IME keyboards
Real-time calculations
Large dynamic layouts
Fast flick scrolling

Then things start breaking:

Flicker
Lost focus
Scroll jitter
Frame drops
Portal churn
State destruction

I hit all of this while building a POS system running inside Android WebView.

And existing solutions weren’t designed for that environment.

What I Built

Perceptual Engine treats scrolling as a motion prediction problem.

Instead of reacting to scroll position only, the engine continuously analyzes:

velocity
acceleration
jerk (change in acceleration)
predicted stopping distance
rendering pressure
frame budget
GPU layer usage

Pipeline:

INPUT
↓
MOTION ANALYSIS
↓
PREDICTION
↓
VISIBILITY
↓
MEASUREMENT
↓
DOM MUTATION
↓
GPU COMPOSITING

Each stage can:

split work across frames
cancel itself
degrade quality
reprioritize tasks

It behaves more like a small game engine than a traditional React list.

Core Ideas

Motion-Based Overscan

Instead of fixed overscan:

overscan={5}

The engine predicts where the user is moving next using jerk + velocity.

Fast flicks increase predictive rendering automatically.

Slow movement reduces work automatically.

Adaptive Quality System

If FPS drops:

overscan shrinks
GPU layers reduce
predictions simplify
expensive measurements defer

Very similar to adaptive quality systems used in game engines.

Persistent DOM Pool

Instead of constantly mounting/unmounting:

DOM nodes stay alive
elements recycle through pools
portals inject content incrementally
state survives scrolling

This was critical for complex forms and Android keyboards.

Scheduler With Frame Budgeting

The scheduler uses:

priorities
time slicing
anti-starvation logic
frame budgets

Not all rendering work deserves the same urgency.

Simple API

import { PerceptualList } from 'perceptual-engine';

function ProductForms({ products }) {
return (
items={products}
estimatedItemSize={600}
overscan="auto"
enableGPUCompositing
persistenceKey="product-forms"
renderItem={(product) => (

)}
/>
);
}

The engine handles:

predictive overscan
DOM recycling
scroll restoration
adaptive degradation
GPU compositing
scheduling
measurement batching

Real Production Use Case

I’m currently using Perceptual Engine in production inside an Android WebView POS system.

Scenario:

15 simultaneous complex forms
Real-time calculations
Numeric inputs
Validation
Dynamic totals
Heavy interaction
Low-end Android hardware

With traditional virtualization:

focus loss
IME flicker
disappearing state
unstable scrolling

With Perceptual Engine:

stable 60fps scrolling
persistent interaction
zero flicker
no focus destruction

That environment shaped the entire architecture.

Architecture

React
↓
PerceptualList
↓
usePerceptualEngine
↓
PerceptualEngine
├── MotionAnalyzer
├── LayoutPredictor
├── ViewportManager
├── RecyclingPool
├── CompositorLayer
├── Scheduler
└── ScrollRestoration

What Makes It Different

Most virtualization libraries optimize:

memory
DOM count
visibility math

Perceptual Engine optimizes:

perceived smoothness
interaction continuity
motion prediction
frame stability
GPU pressure

That’s a very different philosophy.

Current Status

The engine is currently in advanced alpha.

Working today:

✅ Adaptive overscan
✅ DOM recycling pools
✅ Incremental portal caching
✅ Multi-strategy scroll restoration
✅ FPS-aware degradation
✅ Shared ResizeObserver batching
✅ Performance overlay
✅ GPU compositing controls

Roadmap:

🔜 npm release
🔜 benchmarks
🔜 portal-less rendering
🔜 focus preservation layer
🔜 worker-based scheduling
🔜 full test suite

Known Limitations

React portals still introduce overhead at extreme scales
Legacy Android WebViews can behave inconsistently
API still evolving before npm release
Documentation still in progress

Philosophy

I’m not trying to build “another virtualization library”.

I’m exploring what rendering could look like if we treated scrolling as a perceptual signal instead of a geometry problem.

Users don’t experience:

«“visible indexes”»

Users experience:

«smoothness, continuity, and responsiveness.»

That changes the architecture completely.

Looking for Feedback

I’d love feedback from people working with:

Android WebViews
complex forms
huge datasets
virtualization edge cases
low-end hardware
rendering infrastructure

Especially if you’ve hit limitations with existing solutions.

GitHub

github.com/fouzstack/perceptual-engine

npm release coming soon.

What do you think?

Is predictive rendering the next step after virtualization?

Turning Android WebView into a Real Local HTTP Runtime

Giovani Fouz — Sat, 16 May 2026 04:04:42 +0000

Turning Android WebView into a Real Local HTTP Runtime

Most Android hybrid apps still load their frontend using:

file://

And that comes with problems:

broken SPA routing

CORS limitations

weak caching

inconsistent offline behavior

poor asset management

no real HTTP semantics

After fighting these issues repeatedly while building React-based Android applications, I started working on something different.

Not another WebView wrapper.

Not another local server dependency.

A real embedded HTTP runtime for Android WebView.

That project became:

WebVirt v3.6.0

A hybrid runtime engine that intercepts requests directly inside WebView and serves assets from the APK with:

intelligent caching

SPA fallback

ETag support

request coalescing

precaching

range requests

CSP security headers

zero configuration

Why I Built It

Modern SPAs expect a real HTTP environment.

React, Vue, Angular, Vite, Svelte — they all assume things like:

cache validation

proper MIME types

routing

headers

immutable assets

partial requests

But Android WebView with:

file://

doesn't behave like a real runtime.

So instead of forcing the frontend to adapt to WebView limitations…

I decided to make WebView behave like a real web runtime.

What WebVirt Actually Does

WebVirt transforms Android WebView into a local virtual HTTP engine.

Example:

WebVirt.with(context) .host("app.local") .bind(webView); webView.loadUrl("https://app.local/");

From WebView’s perspective:

it’s loading HTTPS

requests are real HTTP requests

assets have cache headers

ETags work

SPA routing works

offline works

But everything is served locally from the APK.

No external server.

No localhost daemon.

No internet required.

Internal Architecture

WebVirt uses a modular runtime architecture built around a central orchestrator:

WebVirt └── WebVirtFileLoader ├── RequestRouter ├── AssetLoader ├── ResponseCache ├── ResponseHeaders ├── AssetPreloader ├── RequestCoalescer ├── RangeRequestHandler └── ErrorPages

The goal was simple:

minimal overhead

predictable behavior

low memory pressure

high cache efficiency

production-ready concurrency

Performance Results

One of the things that surprised me most was how efficient the runtime became after optimization.

Real metrics from Android WebView:

AssetSizeLoad Timevendor.js510 KB25–34msmain.js279 KB19–26msCSS bundle362 KB16–22msDexie bundle96 KB8–17ms

Total initial payload:

~1.4 MB

Despite that, repeated cached assets frequently return in:

0ms

which means:

cache hits are real

headers are precomputed

responses are already materialized

the hot path is highly optimized

At this point, the bottleneck is no longer the runtime itself.

The heavier costs now come from:

React rendering

V8 parsing

CSS

animation libraries

frontend hydration

Which is exactly where I wanted the runtime to be.

Features

SPA Fallback

React Router, Vue Router and Angular routing work automatically.

/dashboard/settings → index.html

No extra configuration needed.

HTTP Cache Validation

WebVirt supports:

ETag

304 Not Modified

If-Modified-Since

immutable cache policies

This dramatically reduces unnecessary asset transfers.

Intelligent Precaching

Critical assets are preloaded automatically:

index.html

main bundles

global CSS

runtime assets

With backpressure limits to avoid memory issues.

Request Coalescing

Concurrent requests to the same asset are merged into a single real load.

1 disk read → N consumers

This reduced redundant IO significantly during startup.

Security Headers

WebVirt injects:

CSP

X-Content-Type-Options

X-Frame-Options

CORS policies

directly into responses.

One Interesting Discovery

The more optimized WebVirt became…

the more obvious it became that the real bottleneck in hybrid apps is often not WebView itself.

It’s:

oversized frontend bundles

CSS frameworks

hydration cost

runtime JS weight

After optimizing the runtime pipeline, frontend architecture suddenly mattered much more.

That was a fascinating shift.

Use Cases

WebVirt works especially well for:

offline-first apps

POS systems

kiosk apps

enterprise dashboards

embedded admin panels

local business tools

React/Vite Android apps

internal tools

educational offline apps

Current State

WebVirt currently includes:

intelligent HTTP cache

lock-free request routing

asset precaching

SPA fallback

range requests

metrics system

cache statistics

memory trimming

configurable security policies

custom path handlers

offline runtime support

And it’s still evolving.

Final Thoughts

I originally built WebVirt to solve practical problems inside Android WebView.

But over time it evolved into something much bigger:

a lightweight hybrid runtime layer for Android.

Not a wrapper.

Not a helper.

A real embedded web runtime.

And honestly, watching a React SPA behave like a real cached HTTP application entirely inside Android WebView is surprisingly satisfying.

If you're building hybrid Android apps, I’d love to hear your thoughts.

Native-Like Android Performance Using Standard Web Technologies ⚡

Giovani Fouz — Wed, 13 May 2026 02:57:39 +0000

Native-Like Android Performance Using Standard Web Technologies ⚡

What if a web-based Android app could boot almost as fast as a native app — while using a fraction of the memory compared to React Native, Flutter, or Electron?

After benchmarking WebVirt v3.5.1, the results were honestly surprising.

🏆 Benchmark Results

MetricResultRatingCold Start255ms🟢 ExcellentWarm Start38ms🟢 InstantMemory Usage14.4MB🟢 MinimalCache Hit Rate100%🟢 PerfectPreload Improvement-20.3%🟢 Significant

📊 Performance Comparison

TechnologyCold StartWarm StartMemoryBundle SizeWebVirt255ms38ms14.4MB1.4MBReact Native800-1200ms200-400ms40-60MB8-15MBFlutter600-900ms150-300ms35-50MB5-10MBPWA (Chrome)400-800ms100-200ms20-30MB1-3MBIonic/Capacitor1000-2000ms300-500ms45-70MB3-8MBNative Android200-400ms30-80ms10-20MB500KB-2MBElectron1500-3000ms500-1000ms80-150MB50-100MB

📈 Cold Start Performance

Cold Start (lower is better) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ WebVirt 255ms ██████░░░░░░░░░░░░░░░░░░ Native 300ms ████████░░░░░░░░░░░░░░░░░ Flutter 750ms ██████████████████░░░░░░░ React Native 1000ms ████████████████████████░░ Ionic 1500ms ████████████████████████████████████ Electron 2250ms ██████████████████████████████████████████████████

⚡ Warm Start Performance

Warm Start (lower is better) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ WebVirt 38ms █░░░░░░░░░░░░░░░░░░░░░░ Native 55ms ██░░░░░░░░░░░░░░░░░░░░░ PWA 150ms █████░░░░░░░░░░░░░░░░░░ Flutter 225ms ████████░░░░░░░░░░░░░░░ React Native 300ms ██████████░░░░░░░░░░░░░ Ionic 400ms █████████████░░░░░░░░░░ Electron 750ms ████████████████████████

🔬 Detailed Resource Loading Metrics

ResourceTypeSizeFirst LoadCachedindex.htmlHTML577B67msInstantindex-.cssCSS354KB118msCachedindex-.jsJS1.04MB152msCachedroot-*.jsJS24KB83msCachedwww.pngPNG11KB82msCachedandroid.pngPNG40KB66msCached

🎯 Smart Preloading Efficiency

BEFORE preloading: Cold 320ms | Warm 40ms | Mem 15.5MB AFTER preloading: Cold 255ms | Warm 38ms | Mem 14.4MB ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ IMPROVEMENT: -20.3% -5% -7.1%

💪 Why WebVirt Performs So Well

vs React Native

✅ 74% faster cold start

✅ 87% faster warm start

✅ 72% lower memory usage

✅ No JavaScript bridge overhead

vs Flutter

✅ 66% faster cold start

✅ 83% faster warm start

✅ 67% lower memory usage

✅ Uses standard HTML/CSS/JS

vs PWA

✅ 36% faster cold start

✅ 75% faster warm start

✅ 35% lower memory usage

✅ Full native API access

vs Ionic/Capacitor

✅ 83% faster cold start

✅ 90% faster warm start

✅ 73% lower memory usage

✅ No WebView bridge overhead

🏗️ Architecture Overview

┌─────────────────────────────────────┐ │ ANDROID APPLICATION │ ├─────────────────────────────────────┤ │ WebVirt Runtime Engine │ │ ┌───────────────────────────────┐ │ │ │ FileLoader + Precache │ │ │ │ ├─ Smart Cache (ETag) │ │ │ │ ├─ Request Coalescing │ │ │ │ ├─ GZip/Brotli Compression │ │ │ │ └─ Async Preloading │ │ │ └───────────────────────────────┘ │ │ ┌───────────────────────────────┐ │ │ │ Optimized WebView │ │ │ │ ├─ V8/JavaScriptCore │ │ │ │ ├─ Native Rendering │ │ │ │ └─ Hardware Acceleration │ │ │ └───────────────────────────────┘ │ └─────────────────────────────────────┘

📋 Production Metrics

Benchmark Quick (2 iterations)

metric,value coldStart_ms,255 warmStart_ms,38 memory_kb,14374 timestamp,1778640627136

FileLoader Metrics

PRECACHE: 5/5 assets cached (100%) CACHE_HIT: 100% critical assets REQUEST COALESCING: No race conditions COMPRESSION: Enabled SECURITY: CSP, CORS, XSS Protection

🔒 Production-Ready Security

✅ Content Security Policy (CSP) ✅ CORS Headers ✅ XSS Protection ✅ ETag Cache Validation ✅ Range Requests (Streaming) ✅ Subresource Integrity ✅ Path Traversal Protection ✅ Memory Trim on Low Memory

📈 Roadmap

VersionFeatureExpected Impactv3.5.1Smart Preloading-20% cold startv3.6.0Automatic Code Splitting-25% bundle sizev3.7.0Offline Service WorkerFull offline supportv4.0.0Multi-thread Rendering-40% render time

🎯 Best Use Cases

Use CaseWebVirtReact NativeFlutterPWAEnterprise Apps🟢 Ideal🟡 Acceptable🟡 Acceptable🔴 LimitedE-commerce🟢 Ideal🟡 Acceptable🟢 Good🟡 AcceptableAdmin Dashboards🟢 Ideal🟡 Acceptable🟢 Good🟡 AcceptableSocial Apps🟡 Acceptable🟢 Ideal🟢 Ideal🔴 LimitedCasual Games🔴 Limited🟢 Good🟢 Ideal🔴 LimitedMVPs / Prototypes🟢 Ideal🟡 Acceptable🟡 Acceptable🟢 Good

🏁 Final Thoughts

WebVirt demonstrates that web technologies on Android do not necessarily mean slow startup times or excessive memory usage.

With:

🚀 255ms cold start

⚡ 38ms warm start

💾 14.4MB memory usage

🎯 100% cache hit rate

🔒 Built-in production security

…it’s possible to achieve near-native performance while keeping the flexibility and developer experience of standard web technologies.

This could be especially valuable for startups and teams wanting:

Faster development cycles

Shared web expertise

Smaller APKs

Lower memory consumption

Native-level responsiveness

📚 References

Android Developer Benchmarks

React Native Performance Docs

Flutter Performance Best Practices

Google Web Vitals

PWA Benchmark Studies (2025)

android #webdev #performance #reactnative #flutter #webview #java #opensource #mobiledev #benchmark

Capacitor: 8–15 ms con servidor. WebVirt: 4–5 ms con interceptor. La diferencia es arquitectónica.

Giovani Fouz — Sun, 10 May 2026 04:29:31 +0000

Capacitor: 8–15 ms con servidor. WebVirt: 4–5 ms con interceptor. La diferencia es arquitectónica.

WebVirt: El Runtime Web para Android que Hace que las SPAs Vuelen 🚀

5ms por asset. 64.7% cache hit rate. Sin servidor HTTP. Sin plugins pesados.

Mientras muchos siguen metiendo servidores embebidos dentro de WebViews… yo probé otro enfoque.

Y los resultados fueron abruptamente rápidos.

🤔 El Problema Real de las SPAs en Android

Construir una SPA React es fácil.

Hacer que funcione bien dentro de Android WebView… no tanto.

Normalmente terminamos usando:

· Capacitor
· Cordova
· NanoHTTPD
· file://
· o algún servidor HTTP embebido

Todos funcionan.

Pero casi todos añaden:

· Latencia innecesaria
· Más consumo de RAM
· Más complejidad
· Más superficie de ataque
· Más APK size

Entonces me hice una pregunta:

¿Y si el WebView nunca necesitó un servidor HTTP real?

Así comenzó WebVirt.

⚡ ¿Qué es WebVirt?

WebVirt es un runtime web para Android que sirve SPAs directamente desde assets/ usando interceptación nativa del WebView.

👉 Código abierto en GitHub: github.com/fouzstack/webvirt-engine

Sin sockets.
Sin puertos.
Sin threads HTTP.
Sin dependencias externas.

Solo:

App → WebView → Interceptor → Asset

📊 Resultados Reales

Probé WebVirt con una SPA React real (~1.6MB).

Resultados capturados en Android:

╔══════════════════════════════════════════════════╗
║     WEBVIRT ENGINE - PERFORMANCE REPORT         ║
╠══════════════════════════════════════════════════╣
║  Session duration:           15945 ms           ║
║  Total assets loaded:        17                 ║
║  Avg load time:              5 ms               ║
║  Min load time:              0 ms               ║
║  Max load time:              48 ms              ║
╠══════════════════════════════════════════════════╣
║  Cache hits:                 11                 ║
║  Cache misses:               6                  ║
║  Cache hit rate:             64.7%              ║
║  Total bytes loaded:         1633735 bytes      ║
╠══════════════════════════════════════════════════╣
║  HTTP errors:                0                  ║
║  SPA fallbacks:              1                  ║
║  Range requests:             0                  ║
╚══════════════════════════════════════════════════╝

🔥 Lo Más Interesante

✅ 5ms promedio por asset

Eso es prácticamente velocidad nativa.

✅ 64.7% cache hit rate en frío

La mayoría de frameworks ni siquiera tienen caché LRU interna para assets.
WebVirt sí.

✅ SPA Routing Automático

Esto:

/dashboard
/settings
/profile/123

funciona automáticamente.

Sin .htaccess.
Sin rewrites.
Sin servidor real.

🆚 Comparativa Directa

Solución Velocidad Caché inteligente SPA Routing Peso
WebVirt 4-5ms ✅ LRU integrada ✅ Automático ~30KB
Capacitor 8-15ms ❌ HTTP estándar ✅ Plugins ~2MB
Cordova 10-20ms ❌ HTTP estándar ✅ Plugins ~1.5MB
NanoHTTPD 10-25ms ❌ Manual ❌ Manual ~100KB
file:// 2-5ms ❌ Ninguno ❌ Roto 0KB

🧠 ¿Por Qué es Más Rápido?

Porque elimina capas innecesarias.

Stack tradicional:

App → WebView → Plugin → HTTP Server → Socket → File

Stack de WebVirt:

App → WebView → Interceptor → Asset

No hay:

· sockets
· serialización HTTP real
· threads extra
· networking interno

Solo lectura optimizada desde assets.

🏗️ Integración en 3 Líneas

WebVirt.with(context)
    .host("app.local")
    .bind(webView);

Y listo.

Tu SPA empieza a funcionar con:

· HTTPS virtual
· caché LRU
· métricas integradas
· CSP
· soporte SPA
· range requests
· headers automáticos

📈 Métricas Integradas

WebVirt incluye un sistema de métricas extensible:

WebVirt.with(context)
    .withMetricsCollector(new FirebaseCollector())
    .bind(webView);

Puedes conectar:

· Firebase
· Datadog
· Sentry
· tu propio collector

Y obtener reportes reales de rendimiento.

🔒 Seguridad por Defecto

Cada respuesta incluye:

Content-Security-Policy
X-Frame-Options
X-Content-Type-Options
X-XSS-Protection

Sin configuración manual.

🎯 ¿Para Quién es Esto?

WebVirt está pensado para:

· React + Android WebView
· Vue + Android
· Angular offline-first
· Apps híbridas ultra rápidas
· Equipos cansados de servidores embebidos

🚫 Lo Que NO Es

WebVirt NO intenta reemplazar:

· Capacitor plugins
· React Native
· Flutter
· servidores HTTP reales

No compite ahí.

WebVirt resuelve otra cosa:

Ejecutar SPAs dentro de Android con el menor overhead posible.

🧩 La Idea Más Importante

Capacitor y Cordova tratan al WebView como "un navegador conectado a un servidor".

WebVirt trata al WebView como un runtime local.

Ese cambio arquitectónico cambia todo.

🏆 Conclusión

WebVirt probablemente no sea para todos.

Pero si estás construyendo:

· SPAs offline-first
· dashboards locales
· apps empresariales híbridas
· runtimes React embebidos

…el modelo tradicional empieza a sentirse innecesariamente pesado.

Y honestamente:

Ver una SPA React cargar assets en ~4ms dentro de Android se siente estupendamente bien.

🔗 Repo en GitHub: github.com/fouzstack/webvirt-engine

¿Qué opinas?
¿Seguimos necesitando servidores HTTP embebidos dentro de WebViews en 2026?

Android #WebView #React #SPA #Performance #OpenSource #Capacitor #Cordova #MobileDev #Java

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

Giovani Fouz — Sun, 03 May 2026 18:50:28 +0000

🚀 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?

WebVirt + Nexus: Run Your React/Vue/Svelte SPA Inside an Android WebView

Giovani Fouz — Sun, 03 May 2026 15:40:34 +0000

WebVirt + Nexus: Run Your React/Vue/Svelte SPA Inside an Android WebView — No Capacitor, No Server, No Permissions

TL;DR — Two decoupled Android libraries: one serves your SPA from APK assets like a real web server, the other bridges JavaScript to native code. Used together in a production app serving local businesses. Open source, JitPack-ready. Engine v3 and Nexus v2 coming soon.

The Problem Nobody Talks About

You built a great SPA in React + Vite + TypeScript. It runs beautifully at localhost:5173. Now your client wants it packaged as an Android app.

Your options:

Approach	Reality
Capacitor / Cordova	+25MB runtime, opinionated structure, black-box WebView
`file://` protocol	CORS broken, SPA routes 404, APIs blocked
Embedded HTTP server (NanoHTTPD)	Threads, ports, network permissions, overkill
Raw WebView	You write everything from scratch

What you actually want: your SPA thinks it's on https://app.local, everything comes from assets/, zero server, zero permissions, zero overhead.

That's exactly what WebVirt does.

What Is WebVirt?

WebVirt is a Java Android library that intercepts WebViewClient.shouldInterceptRequest() and serves your SPA assets directly from the APK — no actual server involved.

WebVirt.with(this)
    .host("app.local")
    .bind(webView);

webView.loadUrl("https://app.local/");

Your React app loads. Routes work. CORS works. No permissions needed.

Already published:

GitHub: github.com/fouzstack/fouzstack-webvirt
JitPack: implementation 'com.github.fouzstack:fouzstack-webvirt:1.0.0'

Real Production Use Case

WebVirt v1 + Nexus are currently running in a financial management app used by small local businesses. The tech stack:

⚛️ React + Vite + TypeScript + Tailwind CSS v4
📦 ~5MB of assets served entirely from APK
📋 Product lists of 90+ items — fast scrolling, no lag
📤 JSON export (native)
📥 JSON import with file picker (no permissions)
📄 PDF export (native)
🔒 Restrictive CSP
⚡ Near-instant load time

No internet required. No server running. Just assets + native bridges.

What's Coming: WebVirt Engine v3 + Nexus v2

The production experience revealed what was missing. Two new libraries are in the works:

WebVirt Engine — The Production-Grade Upgrade

Built on the same shouldInterceptRequest() approach but adds what real apps need:

Smart caching with LRU + ETags

First load:  index.html → read → ETag generated → cached (LRU)
Second load: index.html → ETag match → 304 Not Modified → 0 bytes transferred

Real Range Requests for video streaming

Client:  GET /video.mp4   Range: bytes=1048576-2097151
Server:  206 Partial Content
         Content-Range: bytes 1048576-2097151/52428800
         [only the requested bytes — file never fully loaded into RAM]

Security headers on every response

Content-Security-Policy: default-src 'self'; script-src 'self'...
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

Virtual API routes

WebVirt.with(this)
    .host("app.local")
    .route("/api/config", req -> json("{\"version\": \"1.0\"}"))
    .cspPolicy("default-src 'self'; connect-src https://api.example.com")
    .bind(webView);

The architecture uses Chain of Responsibility for request routing and Strategy for path handlers — the same GoF patterns you'd use in a backend framework, applied to Android's WebView layer.

Nexus — The Native Bridge

Nexus is a completely separate library for JavaScript-to-native communication. It doesn't know WebVirt exists. WebVirt doesn't know Nexus exists.

Nexus nexus = Nexus.installOn(webView)
    .withDebugMode(false)
    .withGlobalTimeout(30_000)
    .registerHandler("export", new ExportHandlerAdapter(handler))
    .registerHandler("import", new ImportHandlerAdapter(context))
    .initialize()
    .withFilePicker(activity);

nexus.attachToWebViewLifecycle();

From JavaScript:

const result = await window.__nexus.call("export", { format: "json" });

What makes Nexus interesting:

Smart re-injection — The JS runtime re-injects only on real page navigations, not on React Router hash changes (#/products, #/settings). This was a real pain point discovered in production.

// From the actual source
String baseUrl = url.contains("#") 
    ? url.substring(0, url.indexOf("#")) 
    : url;

if (!baseUrl.equals(previousBaseUrl)) {
    previousBaseUrl = baseUrl;
    notifyPageLoaded(); // Only re-inject here
}

FilePicker without permissions — Uses Android's Storage Access Framework (SAF). No READ_EXTERNAL_STORAGE in your manifest.

nexus.withFilePicker(activity); // That's it. No permissions.

Interceptor chain — Add cross-cutting concerns (logging, auth, rate limiting) without touching your handlers:

Nexus.installOn(webView)
    .registerInterceptor(new AuthInterceptor())
    .registerInterceptor(new LoggingInterceptor())
    .registerHandler("export", new ExportHandler())
    .initialize();

Event emission from native to JS:

nexus.emitEvent("syncComplete", Map.of("records", 42));

window.__nexus.on("syncComplete", (data) => {
    console.log(`Synced ${data.records} records`);
});

The Architecture: Two Libraries That Don't Know Each Other

This is the part I'm most proud of.

┌─────────────────────────────────────────────────────┐
│                      WebView                        │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │         WebVirt Engine                       │   │
│  │  shouldInterceptRequest() → assets/          │   │
│  │  "app.local/index.html" → real index.html    │   │
│  │  CSP, ETags, Range Requests, LRU Cache      │   │
│  └─────────────────────────────────────────────┘   │
│                    ▲                                │
│                    │ Decorates (doesn't override)   │
│  ┌─────────────────────────────────────────────┐   │
│  │         Nexus WebViewLifecycleObserver       │   │
│  │  Observes onPageFinished, onPageStarted      │   │
│  │  Delegates everything else to WebVirt        │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │         Nexus JSInterface (parallel channel) │   │
│  │  window.__nexus.call("export", data)         │   │
│  │  Does NOT go through shouldInterceptRequest  │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

The key design decision: WebViewLifecycleObserver wraps WebVirt's client using the Decorator pattern. It adds lifecycle hooks without overriding or replacing WebVirt's request handling.

WebVirt doesn't know...	Nexus doesn't know...
That Nexus exists	That WebVirt exists
There's a JS bridge	How assets are served
What handlers are registered	What virtual host is used

This is actual decoupling, not just marketing copy.

Honest Comparison

Feature	WebVirt Engine	Capacitor	Raw WebView
Runtime size	0KB overhead	~25MB	0KB
Smart cache (LRU + ETags)	✅	❌	❌
Range Requests (video)	✅ Real	Delegates to system	❌
Configurable CSP	✅	❌	❌
SPA route fallback	✅ Automatic	✅	❌
Offline mode	✅ Built-in	✅	✅
Hot reload (dev)	❌	✅	❌
Native JS bridge	With Nexus	✅	Manual
No permissions needed	✅	✅	✅
Interceptor chain	✅ (Nexus)	❌	N/A
Setup time	~5 min	~2 hours	Variable

Who Should Use This

✅ React/Vue/Svelte developers who need Android without Capacitor's complexity

✅ Small teams who want full control with minimal dependencies

✅ Offline-first apps (no internet required after install)

✅ Apps where clean architecture matters

❌ If you need live hot reload during development

❌ If your team is already deep in the Capacitor ecosystem

What's Available Now vs. Coming Soon

	Status
WebVirt v1.0.0	✅ GitHub + JitPack
Nexus (production)	✅ Running in production
WebVirt Engine v3.1.1	🔜 Coming soon — github.com/fouzstack/webvirt-engine
Nexus v2.0.0	🔜 Coming soon — github.com/fouzstack/nexus
Kotlin DSL (-ktx modules)	🔜 Planned
Unit tests + benchmarks	🔜 Planned

When Engine and Nexus launch, I'll post a follow-up with concrete benchmarks: cold start times, cache hit rates, memory footprint.

Try WebVirt Now

// settings.gradle
dependencyResolutionManagement {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

// build.gradle (app)
dependencies {
    implementation 'com.github.fouzstack:fouzstack-webvirt:1.0.0'
}

WebVirt.with(this)
    .host("app.local")
    .bind(webView);

webView.loadUrl("https://app.local/");

Put your React/Vite build output in assets/ and you're done.

Questions, feedback, or contributions welcome.

What native handler would you find most useful with Nexus — camera access, biometrics, Bluetooth, local database? Let me know in the comments, it'll help prioritize what gets documented first.

Built by @fouzstack — open source Android libraries for the WebView ecosystem.

WebVirt Engine + Nexus: La dupla perfecta para SPAs en Android

Giovani Fouz — Sun, 03 May 2026 15:12:15 +0000

🚀 WebVirt Engine + Nexus: La dupla perfecta para SPAs en Android que sí respeta tu arquitectura

Sirve tu SPA desde assets como un servidor web profesional + puente nativo JavaScript sin fricción. La arquitectura que Capacitor no puede ofrecerte.

🤔 El problema que todos enfrentamos

Tienes una SPA hermosa en React, Vue o Svelte. Corre perfecto en localhost:3000. Ahora necesitas llevarla a Android.

Tus opciones tradicionales:

Solución Resultado
Capacitor / Cordova +30MB de runtime, configuración compleja, WebView propio
file:// protocol CORS roto, rutas SPA no funcionan, APIs bloqueadas
WebView + servidor embebido Overkill, hilos, puertos, problemas de red
Script casero de 50 líneas Funciona... hasta que agregas video, PDF, o edge cases

Lo que realmente quieres: Que tu SPA crea que está en https://app.local, pero todo venga de assets/. Sin servidor. Sin permisos. Sin overhead.

✨ La solución: WebVirt Engine + Nexus

Dos librerías diseñadas para coexistir sin conocerse. Como hermanos que comparten cuarto sin pelearse.

┌─────────────────────────────────────────────────────┐
│                    WebView                          │
│                                                     │
│  ┌───────────────────────────────────────────────┐ │
│  │         WebVirt Engine (dueño del cliente)    │ │
│  │  shouldInterceptRequest() → assets/           │ │
│  │  "app.local/index.html" → index.html real     │ │
│  │  CSP, ETags, Range Requests, Caché LRU       │ │
│  └───────────────────────────────────────────────┘ │
│                    ▲                                │
│                    │ Decora (no sobrescribe)         │
│  ┌───────────────────────────────────────────────┐ │
│  │         Nexus WebViewLifecycleObserver        │ │
│  │  Observa onPageFinished, onPageStarted        │ │
│  │  Delega todo lo demás a WebVirt               │ │
│  └───────────────────────────────────────────────┘ │
│                                                     │
│  ┌───────────────────────────────────────────────┐ │
│  │         Nexus JSInterface (canal paralelo)    │ │
│  │  window.__nexus.call("export", data)          │ │
│  │  NO pasa por shouldInterceptRequest           │ │
│  └───────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

🎯 5 líneas y tu SPA está viva

// 1. WebVirt: Sirve tu SPA desde assets
WebVirt.with(this)
    .host("app.local")
    .bind(webView);

// 2. Nexus: Puente nativo
Nexus.installOn(webView)
    .registerHandler("export", new ExportAdapter())
    .registerHandler("import", new ImportAdapter())
    .initialize()
    .withFilePicker(this);

// 3. Nexus observa sin romper
nexus.attachToWebViewLifecycle();

// 4. Tu SPA carga como si estuviera en un servidor real
webView.loadUrl("https://app.local/");

Eso es todo. Tu React app funcionando, rutas SPA intactas, APIs nativas disponibles. Sin configuración extraña.

🏗️ Arquitectura: El secreto está en el desacoplamiento

A diferencia de frameworks monolíticos, WebVirt Engine y Nexus usan capas que no compiten:

Capa 1: Red Virtual → WebVirt Engine

WebViewClient.shouldInterceptRequest()
  ├── ¿Es app.local? → Sirve desde assets/
  ├── ¿Ruta SPA? → index.html (fallback)
  ├── ¿API virtual? → RouteHandler (respuesta JSON falsa)
  └── ¿Externo permitido? → Deja pasar

Patrones: Builder, Chain of Responsibility, Strategy (PathHandlers)

Capa 2: Puente Nativo → Nexus

WebView.addJavascriptInterface(nexusInterface, "__nexus")
  └── window.__nexus.call("export", params, callbackId)
        ├── Thread pool para handlers
        ├── Timeout automático
        ├── Serialización JSON
        └── Callback al WebView vía evaluateJavascript()

Patrones: Observer, Command, Mediator, Callback

Capa 3: Ciclo de Vida → Nexus (Decorator)

WebViewLifecycleObserver envuelve al cliente de WebVirt
  ├── shouldInterceptRequest() → delega a WebVirt ✅
  ├── onPageFinished() → WebVirt + notifica a Nexus ✅
  └── Todos los demás métodos → delega a WebVirt ✅

Patrón: Decorator — El más elegante del sistema

¿Por qué funciona tan bien?

WebVirt NO sabe Nexus NO sabe
Que Nexus existe Que WebVirt existe
Que hay un bridge JS Cómo se sirven los assets
Qué handlers hay registrados Qué host virtual se usa

Esto es desacoplamiento real. No es marketing.

🔒 Seguridad de grado producción

WebVirt Engine hereda el enfoque de WebVirt original pero lo lleva a nivel empresarial:

Defensa en profundidad

Capa 1: Path Traversal Protection
  ├── Normalización de rutas
  ├── Bloqueo de ".."
  └── Validación de esquema

Capa 2: Content Security Policy
  ├── CSP configurable por el desarrollador
  ├── Default restrictivo
  └── Headers de seguridad automáticos

Capa 3: Offline Mode
  ├── Bloquea TODAS las peticiones externas
  └── Whitelist de dominios explícita

Capa 4: Extensiones permitidas
  └── Solo sirve archivos con extensiones seguras

Headers de seguridad automáticos

Cada respuesta de WebVirt Engine incluye:

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: *

Y tú puedes personalizar el CSP:

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

🎬 Streaming de video sin cargar en RAM

¿Tu SPA tiene videos? WebVirt Engine soporta Range Requests reales:

Cliente: GET /video.mp4
         Range: bytes=1048576-2097151

Servidor: 206 Partial Content
          Content-Range: bytes 1048576-2097151/52428800
          [solo envía los bytes solicitados]

El archivo nunca se carga completo en memoria. Streaming real desde InputStream.

⚡ Rendimiento: Caché que aprende

Primera carga:
  index.html → leído → ETag generado → cacheado (LRU)

Segunda carga:
  index.html → ETag coincide → 304 Not Modified → 0 bytes transferidos

· LruCache con control de memoria real
· ETags SHA-1 para validación
· If-Modified-Since para archivos
· Se limpia automáticamente con onTrimMemory()

🧩 ¿Juntos o separados?

Solo WebVirt Engine

Perfecto para SPAs que no necesitan APIs nativas:

WebVirt.with(this)
    .host("app.local")
    .route("/api/config", req -> json("{...}"))  // API falsa
    .bind(webView);

Solo Nexus

Perfecto para WebViews tradicionales que necesitan bridge nativo:

Nexus.installOn(webView)
    .registerHandler("camera", new CameraHandler())
    .initialize();

WebVirt Engine + Nexus

La combinación completa. SPA servida profesionalmente + APIs nativas:

WebVirt.with(this).host("app.local").bind(webView);
Nexus.installOn(webView)
    .registerHandler("export", exportAdapter)
    .registerHandler("import", importAdapter)
    .registerHandler("camera", cameraAdapter)
    .initialize()
    .withFilePicker(this);
nexus.attachToWebViewLifecycle();

📊 Comparación honesta

Característica WebVirt Engine Capacitor Cordova WebView puro
Tamaño runtime 0KB (solo tu código) ~25MB ~15MB 0KB
Caché inteligente ✅ LRU + ETags ❌ ❌ ❌
Range Requests ✅ Streaming real ✅ ✅ ❌
CSP personalizable ✅ ❌ ✅ ❌
Rutas SPA ✅ Automático ✅ ✅ ❌
Offline mode ✅ Built-in ✅ ✅ ✅
Hot reload ❌ ✅ ✅ ❌
JS Bridge nativo Con Nexus ✅ ✅ Manual
Sin permisos ✅ ✅ ✅ ✅
Curva aprendizaje 5 minutos 2 horas 3 horas Variable
Desacoplamiento ✅ Total ❌ ❌ N/A

🚀 Producción probada

No es teoría. WebVirt (versión lite) + Nexus ya funcionan en producción en una app financiera real:

· ⚛️ React + TypeScript + TailwindCSS
· 📦 5MB de assets servidos sin conexión
· 📤 Export JSON nativo
· 📥 Import JSON con FilePicker (sin permisos)
· 📄 Export PDF nativo
· 🔒 CSP restrictivo
· ⚡ Carga instantánea

📦 Próximamente

WebVirt Engine v3.1.1

· Repositorio: github.com/fouzstack/webvirt-engine
· JitPack: implementation 'com.github.fouzstack:webvirt-engine:3.1.1'
· Documentación completa
· Módulo Kotlin -ktx

Nexus v2.0.0

· Repositorio: github.com/fouzstack/nexus
· JitPack: implementation 'com.github.fouzstack:nexus:2.0.0'
· Documentación completa
· Templates de proyecto

🎯 ¿Quién debería usar esto?

✅ Desarrolladores React/Vue/Svelte que necesitan Android sin Capacitor

✅ Equipos pequeños que quieren control total sin dependencias pesadas

✅ Apps offline-first que necesitan rendimiento máximo

✅ Cualquiera que valore arquitecturas limpias y desacoplamiento real

❌ Si necesitas hot reload en desarrollo (por ahora)

❌ Si tu empresa ya está comprometida con Capacitor/Cordova

💬 Lo que dicen los patrones de diseño

"Programa contra interfaces, no implementaciones" — GoF

WebVirt Engine y Nexus no se conocen. Se respetan. Colaboran sin acoplarse.

"Separa lo que cambia de lo que permanece" — Clean Architecture

WebVirt cambia (assets, CSP, rutas). Nexus cambia (handlers, timeouts).
Ninguno rompe al otro.

"Una clase debería tener solo una razón para cambiar" — SRP

WebVirt: servir assets. Nexus: bridge nativo. Una responsabilidad cada uno.

🔗 Enlaces

· WebVirt (lite): github.com/fouzstack/fouzstack-webvirt
· WebVirt Engine: Próximamente en github.com/fouzstack/webvirt-engine
· Nexus: Próximamente en github.com/fouzstack/nexus

🙏 Agradecimientos

A la comunidad de Android que sigue buscando formas más limpias de integrar WebViews.
A los patrones de diseño del GoF que 30 años después siguen vigentes.
Y a ti, por leer hasta aquí.

¿Preguntas? ¿Ideas? ¿Quieres contribuir? Los repositorios estarán abiertos para issues y PRs.

Comenta abajo: ¿Qué handler nativo te gustaría ver implementado con Nexus?

WebVirt : Load your SPA in Android WebView with 3 lines of code

Giovani Fouz — Mon, 27 Apr 2026 14:02:38 +0000

# 🚀 WebVirt: Load your SPA in Android WebView with just 3 lines of code

Tired of writing 100+ lines of boilerplate just to display a SPA in a WebView?

**WebVirt reduces it to 3 lines.**

---

## 😩 The problem (we've all been there)

Packaging a SPA (React, Vue, Angular, Svelte, SolidJs...) into an Android WebView should be trivial… but it's not:

- Manually configuring `WebViewClient`
- Intercepting requests (`shouldInterceptRequest`)
- Resolving SPA routes (`/products/42` → `index.html`)
- Handling MIME types correctly
- Implementing asset caching
- Preventing directory traversal attacks
- Controlling external traffic

All that… before you even start building your app.

---

## ✨ The solution: WebVirt

java
WebVirt.with(this)
.host("myapp.local")
.bind(webView);

webView.loadUrl("https://myapp.local/");


That's it.

WebVirt turns your APK into an internal virtual web server.

Your SPA lives in /assets and is served exactly like it would be in production.

---

🔒 Offline-first security by default

WebVirt follows a simple rule:

If you don't explicitly allow it, it's blocked.

· 🚫 External traffic blocked by default
· ✅ Whitelist with allowExternalDomains()
· 🔌 Offline mode with offlineOnly(true)
· 🛡 Directory traversal protection

📦 Automatic HTTP headers

java
WebVirt.with(this)
.host("myapp.local")
.allowExternalDomains("api.myapp.com", "cdn.myapp.com")
.bind(webView);


---

🧠 Automatic SPA routing

Using React Router, Vue Router, or Angular?

WebVirt detects extensionless routes and serves index.html automatically:

· /about → index.html ✅
· /products/42 → index.html ✅
· /app.js → app.js ✅
· /style.css → style.css ✅

No configuration. No hacks. No 404s.

---

⚡ Smart in-memory caching

Optimized for real performance:

· 🧠 index.html → memory-cached (never stale)
· 📦 Assets (JS, CSS, JSON, WASM, fonts) → immutable cache (max-age=31536000)

java
webVirt.clearCache(); // Ideal in onDestroy()


---

📦 Installation

settings.gradle

gradle
dependencyResolutionManagement {
repositories {
maven { url 'https://jitpack.io' }
}
}


build.gradle

gradle
dependencies {
implementation 'com.github.fouzstack:fouzstack-webvirt:v1.0.0'
}


---

🎨 Advanced configuration (optional)

java
WebVirt.with(this)
.host("myapp.local")
.subfolder("dist")
.allowExternalDomains("api.example.com")
.config(cfg -> {
cfg.setCacheEnabled(true);
cfg.setJavaScriptEnabled(true);
cfg.setDomStorageEnabled(true);
})
.bind(webView);


Full access to WebViewSettings without breaking the fluent API.

---

📊 Before vs After

Without WebVirt With WebVirt
~100 lines of code 3 lines
Manual WebViewClient Automatic
Broken SPA routing Works out-of-the-box
Manual caching Included
MIME type hell Included
Manual security Offline-first

---

🌐 Repository

👉 github.com/fouzstack/fouzstack-webvirt

---

🤔 Why "WebVirt"?

Because your APK becomes a:

Virtual web server without a real server

· No ports
· No network
· No real localhost

Just your SPA running like in production.

---

🧪 Requirements

· Android 4.4+ (API 19)
· AndroidX
· Compile SDK 34+

---

📄 License

MIT — use it without fear.

---

💭 Final thought

The best tools aren't the biggest.

They're the ones you set up in seconds… and then forget.

WebVirt doesn't want the spotlight.
It wants you to focus on your product.

---

⭐ Did it help you?

· Star it on GitHub
· Open an issue if you find something
· PRs are welcome

Happy coding 🚀

🚀 WebVirt: Carga tu SPA en Android WebView con solo 3 líneas de código

Giovani Fouz — Fri, 24 Apr 2026 05:16:55 +0000

La primera vez que intenté cargar una SPA de React en un WebView pensé que sería trivial. No lo fue. Terminé escribiendo más de 150 líneas solo para:

servir archivos desde assets
interceptar requests manualmente
arreglar rutas de React Router
y evitar errores 404 en producción

Después de repetir ese proceso varias veces… decidí simplificarlo. Así nació WebVirt.

🎯 El problema

Cargar una SPA (React, Vue, Angular, Svelte) dentro de un WebView en Android implica:

WebViewAssetLoader
shouldInterceptRequest
manejo manual de rutas
configuración de headers y MIME types
cache

No es difícil… pero sí repetitivo, verboso y propenso a errores.

⚡ La solución

Con WebVirt, todo se reduce a esto:

WebVirt.with(this)
    .host("miapp.local")
    .bind(webView);

Eso es todo.

Tu WebView ya puede cargar una SPA completa desde assets sin configuración adicional.

✨ ¿Qué hace WebVirt?

WebVirt actúa como un servidor web virtual dentro de tu APK.

Intercepta las peticiones del WebView y sirve los archivos directamente desde assets, resolviendo automáticamente los problemas más comunes.

🔁 SPA routing automático

Si usas React Router (o similar), no necesitas configuración extra.

/dashboard → WebVirt sirve index.html → tu router toma el control

💾 Caché inteligente

HTML → no cacheado (para reflejar cambios)
JS/CSS → cacheado agresivamente (tipo CDN)
Otros archivos → streaming directo

🔒 Seguridad básica integrada

Prevención de directory traversal (../)
Validación de rutas
Headers seguros por defecto

📁 MIME types listos

Soporte para HTML, JS, CSS, JSON, imágenes, fuentes, WASM y más.

🧪 Ejemplo real

Supongamos que tienes un build de React (Vite, CRA, etc.):

app/src/main/assets/
├── index.html
└── assets/
    ├── index.js
    └── index.css

Solo haces:

webView.loadUrl("https://miapp.local/");

¡Y listo!

✅ React Router funciona
✅ No hay 404 en rutas internas
✅ No necesitas lógica extra

🧠 ¿Cómo funciona?

A alto nivel:

WebView → intercept request → WebVirt → assets → response

Detecta si la URL pertenece a tu host virtual.
Resuelve si es archivo o ruta SPA.
Sirve desde memoria o desde assets.

Sin magia, solo encapsulación de lo que normalmente harías a mano.

🤔 ¿Por qué usarlo?

Porque evita repetir lo mismo en cada proyecto:

menos código boilerplate
menos errores en routing
mejor experiencia de desarrollo

No reemplaza las herramientas existentes,
simplemente las abstrae en una API más simple.

🚀 Uso rápido en tu MainActivity

WebVirt.with(this)
    .host("miapp.local")
    .bind(webView);

webView.loadUrl("https://miapp.local/");

🔮 Próximamente

Publicación en Maven Central / JitPack
Kotlin DSL
LRU cache configurable
Hooks para personalización

📦 Código y documentación

Estoy preparando el repo público con README completo y ejemplos.

Si te interesa el proyecto o quieres probarlo antes:

👉 Déjame un comentario
👉 o sígueme para actualizaciones

🎯 Conclusión

Cargar una SPA en un WebView no debería tomar 150 líneas.

Con WebVirt:

✅ es simple
✅ es rápido
✅ funciona

¿Te ha pasado lo mismo con WebView?
Me interesa saber cómo lo estás resolviendo tú 👇

Tu WebView no necesita un servidor HTTP. Necesita un Virtual Host.

Giovani Fouz — Sun, 19 Apr 2026 09:01:38 +0000

Cómo un patrón de los años 90 resolvió uno de los problemas más frustrantes del desarrollo móvil moderno

Hay una idea en ingeniería de software que reaparece una y otra vez, con décadas de distancia y en plataformas completamente distintas. Una idea tan elegante que la industria la redescubre cada cierto tiempo, la viste con nueva ropa, y la presenta como si fuera nueva.

Esta es la historia de esa idea. Y de cómo terminó viviendo dentro de una app Android.

El problema que nadie quiere admitir

Construir una app móvil con React, Vue o cualquier framework web moderno es tentador. Tienes un equipo que ya sabe web, una base de código compartida, y la promesa de "escribe una vez, corre en todas partes."

Hasta que llega el momento de cargar tu app en Android sin conexión a internet.

Android no tiene un servidor local. WebView no sabe hablar con tu carpeta assets/ como si fuera un dominio real. Y React Router — el corazón de la navegación en casi toda SPA moderna — necesita que las rutas como /dashboard o /perfil/123 devuelvan siempre el mismo index.html, sin importar qué tan profunda sea la URL.

Sin eso, tu app se rompe. El usuario navega, presiona atrás, recarga — y ve una pantalla en blanco o un error 404 que no debería existir.

La solución obvia sería levantar un servidor HTTP local. Pero eso consume batería, requiere permisos, complica el ciclo de vida de la app, y abre vectores de seguridad innecesarios. No es la respuesta correcta.

La respuesta correcta tiene 30 años de historia detrás.

1991: Cuando los servidores aprendieron a mentir (bien)

En los primeros días de la web, cada URL correspondía a un archivo físico en el disco del servidor. /pagina.html era literalmente un archivo llamado pagina.html. Simple, predecible, rígido.

El problema llegó cuando los sitios crecieron. Un servidor físico, múltiples dominios. ¿Cómo diferenciaba el servidor a cuál de ellos le hablaba el visitante?

La respuesta fue el Virtual Hosting: la capacidad de un solo servidor de hacerse pasar por muchos, respondiendo diferente según el dominio que el cliente pedía. Apache HTTP Server lo popularizó a mediados de los 90. Un servidor físico podía alojar empresa-a.com, empresa-b.com y empresa-c.com simultáneamente, cada uno con su propio espacio de archivos, sus propias reglas, su propia identidad.

Era, en esencia, enseñarle a un servidor a interceptar una petición y decidir: ¿quién eres tú y qué te mereces recibir?

Nginx lo refinó. Los CDNs lo escalaron a millones de dominios. Y el patrón quedó grabado en el ADN de la infraestructura web moderna.

2010: Las SPAs rompen todo (de nuevo)

Cuando llegaron las Single Page Applications, el Virtual Hosting tuvo que evolucionar.

Una SPA tiene una sola entrada: index.html. Todo lo demás — rutas, vistas, estados — es JavaScript puro que corre en el navegador. El servidor no sabe nada de /dashboard o /usuario/perfil. Cuando alguien recarga esa URL, el servidor busca un archivo llamado dashboard en el disco. No existe. 404.

La solución fue tan simple como poderosa: el fallback a index.html. Si el servidor no encuentra el archivo estático solicitado, en lugar de responder con un error, devuelve siempre index.html. React Router toma el control desde ahí y reconstruye la vista correcta.

En Nginx, son dos líneas:

try_files $uri $uri/ /index.html;

En ASP.NET Core, Microsoft lo formalizó como middleware oficial con MapFallbackToFile("index.html"). El patrón tenía nombre, documentación, y respaldo institucional.

Pero todo eso asume que tienes un servidor. ¿Qué pasa cuando no lo tienes?

2024: El mismo patrón, sin servidor

Android tiene un mecanismo poco conocido pero extraordinariamente poderoso: shouldInterceptRequest. Cada vez que el WebView está a punto de hacer una petición de red, se detiene y pregunta: ¿alguien quiere manejar esto antes que yo?

La mayoría de los desarrolladores lo ignora. Algunos lo usan para bloquear anuncios o inyectar headers. Pero hay una tercera posibilidad: usarlo para construir un servidor virtual completo que nunca hace una petición de red real.

Eso es exactamente lo que hace VirtualHostManager.

Cuando el WebView intenta cargar https://app.gfouz.com/assets/main.js, la clase intercepta esa petición antes de que salga al mundo. Busca el archivo en la carpeta assets/ del APK. Lo sirve directamente, con el MIME type correcto, con los headers de caché apropiados, sin tocar internet.

Y cuando el WebView pide https://app.gfouz.com/dashboard — una ruta de React Router que no existe como archivo — la clase reconoce que no tiene extensión, asume que es una ruta SPA, y devuelve index.html. React Router hace el resto.

El servidor está dentro de la app. El dominio es ficticio. Las peticiones nunca salen del dispositivo. Y React Router nunca se entera de la diferencia.

Por qué esto importa más de lo que parece

La mayoría de soluciones para este problema siguen uno de dos caminos: usar file:// (que rompe CORS y tiene restricciones de seguridad severas) o levantar un servidor HTTP local con librerías como NanoHTTPD (que consume recursos y complica el ciclo de vida de la app).

VirtualHostManager toma un tercer camino: habitar la infraestructura existente del WebView en lugar de luchar contra ella o rodearla.

El resultado es una clase que:

· No abre puertos de red.
· No requiere permisos adicionales.
· Cachea solo lo que vale cachear (index.html, que se pide en cada navegación).
· Transmite archivos grandes como streams, sin cargarlos completos en RAM.
· Valida rutas para prevenir path traversal attacks.
· Soporta 25 tipos de archivo con sus MIME types correctos.
· Funciona en Android 4.1 en adelante.

Y hace todo eso en menos de 200 líneas de Java.

El patrón que no envejece

Lo fascinante de esta historia no es la clase en sí. Es que el problema — ¿cómo sirvo contenido estático con inteligencia? — ha tenido exactamente la misma solución en cada era de la computación:

1995 → Apache Virtual Hosting
2005 → Nginx try_files
2016 → ASP.NET Core MapFallbackToFile
2024 → Android shouldInterceptRequest + SPA fallback

El contexto cambia. El hardware cambia. Los frameworks cambian. El patrón permanece.

Eso, en ingeniería de software, es la señal más confiable de que algo es fundamentalmente correcto.

VirtualHostManager es parte de FouzStack — una colección de soluciones de ingeniería para desarrollo móvil con tecnologías web.

gfouz (Giovani Fouz) · GitHub

Welcome, I'm excited to share my journey, skills, and projects with you. Dive in, explore my projects, and get to know the developer behind the screen. - gfouz

github.com