Forem: Giovani Fouz

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

Android Virtual Host and Fake Server

Giovani Fouz — Tue, 14 Apr 2026 20:29:30 +0000

🚀 Virtual Host para Android: Mi réplica nativa del SetVirtualHostNameToFolderMapping de Microsoft WebView2... ¡pero para WebView de Android!

Durante algún tiempo observé una característica elegante de WebView2 en .NET: SetVirtualHostNameToFolderMapping. Te permite mapear un hostname virtual (como https://miapp.local/) directamente a una carpeta local, sirviendo archivos estáticos de forma limpia, segura y con soporte perfecto para Single Page Applications (SPA) como React, Svelte, Vue o Angular.

En Android, la historia siempre ha sido más complicada. La mayoría de soluciones recurren a trucos, copiar assets a archivos internos, servidores locales embebidos (como react-native-static-server) o frameworks completos que añaden capas de abstracción.

Hasta ahora.

Presento VirtualHostManager: mi implementación propia, ligera y optimizada en Java/Kotlin para Android. Una clase con responsabilidad única que transforma tu WebView en un mini-servidor virtual inteligente, inspirada directamente en la solución de Microsoft pero adaptada al ecosistema Android.

¿Qué hace exactamente?

Sirve todos tus assets estáticos desde la carpeta assets/ (o un subdirectorio).
Maneja automáticamente el fallback a index.html para rutas de React Router, Vue Router, etc. (cualquier ruta sin extensión se trata como SPA).
Soporta dominio virtual seguro (https://tudominio.local/).
Optimizada para bajo consumo de RAM: solo cachea index.html (el archivo más solicitado), el resto se sirve con InputStream directo sin cargar todo en memoria.
Manejo seguro de paths (evita ../ y accesos no deseados).
Headers inteligentes de caché (immutable para JS/CSS/imágenes).
Compatible con versiones antiguas de Android.

Aquí el corazón de la clase (código completo en los comentarios o en el repo si lo publico):

// Ejemplo de uso súper simple
VirtualHostManager vhm = new VirtualHostManager(context, "miapp.local", "dist/");

webView.setWebViewClient(new WebViewClient() {
    @Override
    public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) {
        if (vhm.shouldIntercept(request.getUrl().toString())) {
            return vhm.serveStaticAsset(request.getUrl().toString());
        }
        return super.shouldInterceptRequest(view, request);
    }
});

webView.loadUrl(vhm.getVirtualBaseUrl() + "index.html");

¿Es esto una innovación a nivel de sistemas y arquitectura?

No, no es una innovación
disruptiva a nivel de sistemas o arquitectura, pero sí es una buena solución y mejora de calidad sobre las soluciones típicas.

Algunas ventajas:

Portabilidad de conceptos maduros de escritorio a móvil — Llevamos una feature potente de WebView2 (.NET) de Microsoft al mundo Android de forma limpia y nativa, sin depender de bibliotecas pesadas ni servidores embebidos.
Arquitectura minimalista y eficiente — En lugar de lanzar un servidor HTTP completo (con overhead de hilos, sockets y consumo de batería), usamos el mecanismo nativo de shouldInterceptRequest del WebView. Es más directo, ligero y respeta el ciclo de vida de la app.
Optimización consciente de recursos móviles — El diseño prioriza bajo uso de RAM y CPU, algo crítico en dispositivos Android de gama media/baja. El cacheo lazy y thread-safe de solo index.html es un detalle pequeño pero poderoso para SPAs con navegación frecuente.

No es "reinventar la rueda". Es traer la rueda correcta al vehículo correcto, con mejoras específicas para el entorno móvil.

Ventajas frente a soluciones modernas existentes

Vs. React Native + WebView (o react-native-webview):

React Native obliga a un puente JS → Native, añade complejidad de ecosistema y tamaño de APK. Con VirtualHostManager cargas tu SPA React/Vue directamente en un WebView nativo puro. Menos capas = mejor rendimiento, menor tamaño y mantenimiento más simple si ya tienes el frontend web.
Vs. Capacitor / Ionic / Cordova:

Estos frameworks son geniales para acceso a APIs nativas, pero introducen su propio runtime, plugins y bridge. Si tu app es principalmente una SPA web bien hecha, VirtualHostManager te da control total sin el overhead. Quieres cámara o notificaciones? Añades solo los permisos y llamadas nativas que necesites, sin arrastrar todo el framework.
Vs. WebViewAssetLoader (oficial de AndroidX):

Es buena, pero más básica. No maneja automáticamente el fallback SPA de forma tan elegante, ni domina el concepto de "virtual host" con dominio personalizado. Mi implementación es más cercana a la experiencia de WebView2.
Vs. servidores locales embebidos (NanoHTTPD, etc.):

Mucho más pesado en memoria y batería. Mi solución es interceptación directa: cero sockets, cero hilos extras.

Resultado: una app más ligera, más rápida al arrancar, con mejor ahorro de batería y que se siente como una experiencia web premium dentro de un contenedor nativo.

¿Para quién es ideal?

Desarrolladores que tienen una SPA moderna (React, Vue, Svelte, etc.) y quieren empaquetarla como app Android con mínima fricción.
Equipos que buscan máximo rendimiento y control fino sin adoptar un framework completo.
Quienes valoran la simplicidad y la inspiración cross-platform (de .NET a Android).

Esta clase es open-source en espíritu: la comparto porque creo que la comunidad Android merece herramientas más elegantes para servir SPAs locales, teniendo muy en cuenta que las aplicaciones web son cada vez más sofisticadas y de alta tecnología.

¿Qué opinas?

¿Te ha pasado que luchas con WebView + SPA y terminas añadiendo capas innecesarias?

¿Crees que vale la pena priorizar esta simplicidad sobre frameworks más "todo en uno"?

Me encantaría leer tus experiencias en comentarios. Si te sirve, ¡úsala, mejórala y compártela!

Android #WebView #React #typescript #tailwindcss #SPA #MobileDevelopment #Architecture #DotNet #Kotlin #Java

Virtual Host for Android

Giovani Fouz — Tue, 14 Apr 2026 04:37:16 +0000

Implementando el Patrón UseSpa de ASP.NET Core en Android WebView: Una Alternativa Ligera a Cordova para SPAs Offline

Cómo construí un enrutador SPA eficiente para apps React que se ejecutan completamente desde los assets de Android, sin servidor HTTP y con consumo mínimo de batería y de RAM.

El Problema: El Enrutamiento SPA se Rompe en Android WebView

Si alguna vez has intentado empaquetar una app React o Vue dentro de un WebView de Android usando file:///android_asset/index.html, te has topado con este muro:

net::ERR_FILE_NOT_FOUND

La página de inicio carga perfectamente. Pero cuando el usuario navega a /inventario y refresca la página (o recibe un enlace profundo), el WebView intenta buscar el archivo físico /inventario dentro de la carpeta assets. No existe. La app se rompe.

Las soluciones tradicionales son pesadas:

Solución Problema
Cordova / Capacitor Levanta un servidor HTTP real en localhost. Funciona, pero consume batería y RAM.
PWA con Service Workers Requiere HTTPS e internet para la primera carga. No es verdaderamente offline-first.

Pero espera—Microsoft ya resolvió esto elegantemente en ASP.NET Core:

app.UseStaticFiles();
app.UseSpa(spa => spa.Options.DefaultPage = "/index.html");

Este middleware sirve archivos estáticos normalmente, pero hace fallback a index.html para cualquier ruta que no tenga extensión de archivo. React Router toma el control a partir de ahí.

Entonces me pregunté: "¿Por qué Android no tiene algo así?"

La Solución: VirtualHostManager

Desarrollé una clase Java ligera que replica el comportamiento de UseSpa de ASP.NET completamente dentro de la capa de interceptación de peticiones del WebView. Sin servidor HTTP local. Sin Cordova. Android SDK puro o Java sin dependencias ni librerías externas.

El Corazón de la idea

/**
 * Determina si una ruta solicitada es una ruta de React Router.
 * Lógica: Si no tiene extensión de archivo, es una ruta SPA.
 */
private boolean isReactRouterRoute(String assetPath) {
    if (assetPath == null || assetPath.isEmpty()) return true;
    int lastDot = assetPath.lastIndexOf('.');
    return lastDot == -1; // Sin extensión = ruta SPA
}

Esta simple validación es lo que permite que /inventario, /reportes o /configuracion no devuelvan 404, sino que entreguen index.html para que React Router maneje la navegación.

Configuración del WebView

VirtualHostManager vhm = new VirtualHostManager(this, "app.local", "www");

webView.setWebViewClient(new WebViewClient() {
    @Override
    public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) {
        String url = request.getUrl().toString();
        if (vhm.shouldIntercept(url)) {
            return vhm.serveStaticAsset(url);
        }
        return super.shouldInterceptRequest(view, request);
    }
});

webView.loadUrl(vhm.getVirtualBaseUrl()); // https://app.local/

El Código Completo (Fragmentos Clave)

Interceptación y Fallback al Index

public WebResourceResponse serveStaticAsset(String url) {
    try {
        String relativePath = urlToAssetPath(url);
        String fullAssetPath;

        // 🧠 Aquí está la innovación: detección de rutas SPA
        if (isReactRouterRoute(relativePath) || relativePath.isEmpty()) {
            fullAssetPath = indexAssetPath; // Fallback a index.html
        } else {
            fullAssetPath = assetSubfolder + relativePath;
        }

        // Servir desde assets con MIME types y headers de caché
        // ...
    } catch (IOException e) {
        return create404Response();
    }
}

Cacheo Thread-Safe de index.html

private volatile byte[] indexHtmlCache;

// Double-checked locking para evitar bloqueos innecesarios en lecturas concurrentes
if (fullAssetPath.equals(indexAssetPath)) {
    if (indexHtmlCache == null) {
        synchronized (this) {
            if (indexHtmlCache == null) {
                indexHtmlCache = loadAssetBytes(fullAssetPath);
            }
        }
    }
    dataStream = new ByteArrayInputStream(indexHtmlCache);
}

Validación de Seguridad contra Path Traversal

private void validatePath(String path) {
    if (path.isEmpty() || path.contains("..") || path.contains("\\") || path.startsWith("/")) {
        throw new SecurityException("Path inválido: " + path);
    }
}

Limpieza de URLs con Fragmentos y Query Params

private String urlToAssetPath(String url) {
    String path = url.replace("https://", "").replace("http://", "")
        .replace(virtualHost + "/", "").replace(virtualHost, "");

    if (path.contains("?")) path = path.split("\\?")[0];
    if (path.contains("#")) path = path.split("#")[0];

    return path;
}

Optimizaciones que Marcan la Diferencia

Característica Implementación Beneficio
Cacheo de index.html volatile + double-checked locking Acceso concurrente sin bloqueos
Cero sobrecarga de RAM para otros assets InputStream directo, sin byte[] Memoria mínima en dispositivos viejos
Headers de caché inmutables max-age=31536000 para assets con hash El WebView no re-descarga archivos
Protección contra Path Traversal Bloqueo de ../ y rutas absolutas Seguridad en apps offline
Soporte para subcarpetas assetSubfolder configurable Compatible con npm run build sin cambios

Comparativa: VirtualHostManager vs. Soluciones Existentes

Métrica Cordova/Capacitor WebView + file:// VirtualHostManager
Soporte SPA Routing ✅ Sí ❌ Roto ✅ Sí
Requiere Servidor HTTP ✅ Sí (localhost) ❌ No ❌ No
Consumo de Batería Alto Bajo Mínimo
Consumo de RAM ~40-60 MB ~10 MB ~8 MB
Deep Linking ✅ Sí ❌ No ✅ Sí
Hot Updates ❌ No ❌ No ✅ Sí (reemplazar assets)
Tiempo de inicio Lento (espera al servidor) Instantáneo Instantáneo

Caso de Uso Real: App de Inventarios en Cuba

Esta solución está actualmente en producción en una app de control de inventarios para pequeños negocios en Cuba, donde:

· El internet es caro e inestable.
· Los dispositivos tienen RAM y batería limitadas.
· El trabajo por turnos requiere traspaso de datos offline vía exportación de archivos.

La app funciona completamente offline, sincroniza mediante archivos exportados, y genera reportes PDF—todo desde un único WebView con persistencia de datos utilizando a IndexDB.

Código Fuente Completo
En fin quiero compartir este pensamiento:

No necesitas Cordova para tener una SPA funcional en Android. A veces, una clase Java de 150 líneas es todo lo que necesitas para que React Router funcione como si estuviera en un servidor real.

Microsoft lo hizo bien con UseSpa. Ahora Android también lo tiene, (VirtualHostManager) una clase de 150 líneas en Java.

¿Preguntas? ¿Ideas?

Déjamelas en los comentarios. Si estás construyendo algo similar para entornos offline-first en Latinoamérica, me encantaría saber de tu proyecto.

Giovani Fouz
Desarrollador de Software. No deberíamos aferrarnos a ciertas tecnologías donde radica nuestra zona de comodidad sino explorar nuevas alternativas, pero no termino sin mencionar: ¡ Wow vaya éxito el de React o Typescript o Tailwindcss ! ¡ Que grandiosas herramientas!
Cuba, 2026

Comprendiendo el uso del Asterisco (`*`) y Doble Asterisco (`**`) en Python

Giovani Fouz — Sat, 09 Nov 2024 11:15:03 +0000

Cuando trabajamos en Python, a menudo nos encontramos con situaciones en las que necesitamos que nuestras funciones sean flexibles y capaces de manejar diferentes tipos y cantidades de argumentos. Para facilitar esto, Python ofrece dos operadores muy útiles: el asterisco simple (*) y el doble asterisco (**). En este post, exploraremos en detalle su funcionamiento, así como su aplicación en funciones, clases y estructuras de datos como listas y diccionarios.

¿Qué son las estructuras de datos en Python?

Antes de entrar en el uso del asterisco, es importante entender qué son las estructuras de datos. En Python, las estructuras de datos son formas de organizar y almacenar datos en el programa. Las más comunes son:

Listas: Colecciones ordenadas que permiten elementos duplicados.
Tuplas: Similares a las listas, pero son inmutables.
Diccionarios: Colecciones no ordenadas de pares clave-valor.

Estas estructuras son fundamentales para manejar datos en Python y son el contexto donde los operadores * y ** se vuelven particularmente interesantes.

Usos del Asterisco Simple (`*`)

1. Funciones con Argumentos Variables

El asterisco simple se utiliza principalmente en funciones para permitir que acepten un número variable de argumentos posicionales. Esto significa que puedes pasarle cualquier cantidad de argumentos y todos serán tratados como una tupla dentro de la función.

def func(*args):
    for arg in args:
        print(arg)

func(1, 2, 3, 4)

# Esto imprime: 1 2 3 4

Desempaquetado de Listas o Tuplas También puedes usar el asterisco simple para desempaquetar elementos de una lista o tupla al pasar argumentos a una función.

numbers = [1, 2, 3]
print(*numbers)  # Esto imprime: 1 2 3

Este uso del asterisco puede ser muy conveniente cuando tienes una lista de elementos y quieres pasarlos como argumentos a otra función.

Usos del Doble Asterisco (`**`)

Funciones con Argumentos de Palabra Clave El doble asterisco se utiliza para permitir que una función acepte un número variable de argumentos de palabra clave (nombre-valor). Dentro de la función, estos argumentos se almacenan en un diccionario.

def func(**kwargs):
    for key, value in kwargs.items():
        print(f"{key}: {value}")

func(name="Alice", age=30)
# Salida:
# name: Alice
# age: 30

Desempaquetado de Diccionarios Al igual que el asterisco para listas y tuplas, puedes usar el doble asterisco para desempaquetar pares clave-valor desde un diccionario al llamar a una función.

data = {"name": "Alice", "age": 30}
func(**data)  # Osea es lo mismo que: func(name="Alice", age=30)

Usos Avanzados de * y ** en Clases

class MyClass:
    def __init__(self, *args, **kwargs):
        self.args = args
        self.kwargs = kwargs

obj = MyClass(1, 2, a=3, b=4)
print(obj.args)   # (1, 2)
print(obj.kwargs) # {'a': 3, 'b': 4}

En Herencia
Puedes utilizar *args y **kwargs para pasar argumentos al constructor de la clase base, lo que permite que la clase derivada extienda el comportamiento del constructor de la clase base.

class Base:
    def __init__(self, x):
        self.x = x

class Derived(Base):
    def __init__(self, x, *args, **kwargs):
        super().__init__(x)  # Llama al constructor de Base
        # Puedes hacer algo adicional con args y kwargs aquí

d = Derived(10)

Combinaciones de simple y doble asterisco:
A veces, puede ser útil combinar tanto los argumentos posicionales como los de palabra clave en tus funciones para permitir un manejo completo de los datos de entrada:

def mixed_args(a, b, *args, **kwargs):
    print(a, b)
    print(args)
    print(kwargs)

mixed_args(1, 2, 3, 4, x=5, y=6)

#Salida:

# 1 2
# (3, 4)
# {'x': 5, 'y': 6}

Documentación Oficial de Python sobre Funciones
Python para Todos - Curso Gratuito
Real Python - Unpacking in Python
W3Schools - Python Functions (Defining Functions)

Resumen:

args es útil para recibir un número variable de argumentos posicionales, mientras que kwargs es útil para recibir un número variable de argumentos de palabra clave.
Puedes usar simple y doble asterisco para desempaquetar listas/tuplas y diccionarios, respectivamente, al llamar funciones.
Ambos operadores pueden mejorar la flexibilidad y reutilización de tu código, permitiendo funciones que manejan diferentes tipos de entradas de manera eficiente.
Recursos Útiles

React query, hook personalizado.

Giovani Fouz — Sat, 09 Nov 2024 08:02:56 +0000

En aplicaciones de React, es común necesitar acceder a datos de una API externa. Tradicionalmente, muchos desarrolladores utilizan métodos nativos de javascript como fetch dentro de los componentes, lo que puede llevar a problemas de administración del estado y a un manejo complicado de efectos secundarios (side effects). Aquí es donde React Query entra en juego.

¿Qué es React Query?

React Query es una biblioteca destinada a simplificar las operaciones de obtención y manejo de datos en React. Proporciona potentes funciones para:

Efectuar solicitudes de datos de una API.
Almacenar y sincronizar el estado de la UI con los datos.
Realizar refetching automáticamente y gestionar cachés.
Nuestro Hook Personalizado

A continuación, veamos nuestro hook personalizado, useCustomQuery:

import { useQuery } from '@tanstack/react-query';

export type GenericObject = {
  [key: string]: any;
};

export type QueryFunction = (
  url: string,
  token?: string,
) => Promise<GenericObject>;

export const useCustomQuery = (
  queryFunction: QueryFunction,
  url: string,
  queryKey: string[],
  token?: string,
) => {
  const { isPending, isError, data, error, refetch, isLoading } = useQuery<
    GenericObject | GenericObject[]
  >({
    queryKey: [queryKey],
    queryFn: () => queryFunction(url, token),
  });

  return { data, error, isError, isPending, refetch, isLoading };
};

Desglose del Hook

GenericObject y QueryFunction:

Definimos tipos genéricos que facilitan el trabajo con objetos y funciones que realizan fetching de datos. Esto asegura que nuestro código pueda adaptarse a diferentes estructuras de datos que puedan regresar las APIs.

useQuery:

Usamos el hook useQuery de React Query, que maneja automáticamente el estado de nuestras solicitudes. Proporciona propiedades útiles para manejar la carga de datos, errores y refetching.

Esto mejora la calidad del código y reduce bugs.
Interfaces Genéricas: Utilizando interfaces genéricas, podemos definir estructuras de datos que se adaptan a diferentes situaciones. Esto hace que el código sea más reutilizable y fácil de mantener.
Mejor Documentación: El uso de TypeScript como una herramienta de documentación proporcionada por los tipos mejora la comprensión de cómo se deben usar las funciones y qué tipo de datos se esperan.

Enlaces Útiles

React Query:
- Documentación oficial: TanStack Query Documentation
- Guía de inicio rápido: Getting Started with React Query
TypeScript:
- Documentación oficial: TypeScript Documentation
- Guía de TypeScript para React: Using TypeScript with React
GitHub de React Query:
- Repositorio oficial: TanStack Query (React Query) GitHub
Ejemplos y Tutoriales:
- Tutorial de RapidAPI sobre React Query: Getting Started with React Query
- Artículo sobre los beneficios de utilizar React Query: Benefits of Using React Query

Conclusión

Integrar un hook personalizado junto con React Query y TypeScript en tus aplicaciones React transforma la forma en que gestionas las solicitudes de datos. No sólo mejora la experiencia de desarrollo al reducir la carga de lógica de manejo de estado, sino que también enriquece la robustez y facilidad de mantenimiento de tu código.
Espero que encuentren útil este enfoque y les animo a probarlo en sus propios proyectos. ¡Feliz codificación!

Errores Comunes de Pylint. Guía Práctica

Giovani Fouz — Mon, 27 May 2024 09:10:20 +0000

Pylint es una herramienta de análisis estático de código que se utiliza para encontrar errores y mejorar la calidad del código Python. Sin embargo, enfrentarse a los errores que reporta puede ser desalentador, especialmente para los desarrolladores novatos. Aquí exploramos algunos de los errores más comunes que lanza Pylint, cómo resolverlos y cómo podemos beneficiarnos de estas correcciones para escribir un código más limpio y eficiente.

1- C0103: Variable name "x" doesn't conform to snake_case naming style
Error:
Este error se produce cuando el nombre de una variable no sigue la convención de nombres en Python, que es usar snake_case.