Debugging react-snap en CI/CD: Cuando Puppeteer Se Niega a Terminar
Este artículo técnico detalla la resolución de problemas al usar react-snap en un entorno CI/CD, específicamente cuando Puppeteer no finaliza la pre-renderización. Se exploran tres causas principales: llamadas API pendientes que impiden que Puppeteer considere la página como inactiva, bucles infinitos de `requestAnimationFrame` que mantienen el thread principal ocupado y el crawling automático de react-snap que reintroduce rutas problemáticas. Aprenderás a diagnosticar y solucionar estos problemas, optimizando la configuración de react-snap para un pre-renderizado exitoso en CI/CD.

El Punto de Partida
Después de implementar las optimizaciones del Post 10, la configuración de react-snap era ambiciosa:
{
"reactSnap": {
"include": ["/", "/blog", "/cv", "/contact", "/ai-search", "/login"],
"puppeteerArgs": ["--no-sandbox", "--disable-setuid-sandbox"],
"skipThirdPartyRequests": true
}
}
Seis rutas estáticas para pre-renderizar. Simple, ¿no?
El primer build con Kaniko cache funcionó perfectamente para la capa de Chromium:
INFO[0005] RUN apk add --no-cache chromium
INFO[0005] Found cached layer, extracting to filesystem
Chromium cacheado. Excelente. Pero luego react-snap empezó a ejecutarse... y nunca terminó.
Build 1: Home Se Queda Colgado
Síntoma
Cloud Build alcanzó el timeout de 25 minutos. Los logs mostraban:
✅ crawled 5 out of 7 (/login)
✅ crawled 6 out of 7 (/contact)
Seis de siete rutas completadas. La séptima: / (Home).
Diagnóstico
¿Por qué 7 rutas si solo configuré 6 en include? La respuesta estaba en una configuración por defecto que desconocía: react-snap incluye /200.html automáticamente como fallback page.
Pero el problema real era / (Home). Revisando el código de Home.js:
useEffect(() => {
const fetchStats = async () => {
const res = await client.get('/blog/posts/', { params: { page_size: 1 } });
setStats({ totalPosts: res.data.count });
};
fetchStats();
}, []);
useEffect(() => {
const fetchPosts = async () => {
const res = await client.get('/blog/posts/', { params: { ordering: '-published_at' } });
setPosts(res.data.results);
};
fetchPosts();
}, []);
Home hace dos llamadas API al montarse. En Cloud Build, el backend no está disponible. Estas llamadas nunca resuelven. Puppeteer espera "network idle" (sin actividad de red durante 500ms) y nunca llega a ese estado porque las peticiones HTTP quedan pendientes indefinidamente.
Fix (commit 7c96593)
"include": ["/blog", "/cv", "/contact", "/ai-search", "/login"]
Removí / y agregué "timeout": 10000 como safety net.
Build 2: /blog También Cuelga
Síntoma
Mismo comportamiento. El build llegaba a 6/7 rutas y se detenía.
Diagnóstico
PostList.js tiene exactamente el mismo problema:
useEffect(() => {
const fetchPosts = async () => {
const response = await client.get('/blog/posts/', { params });
setPosts(response.data.results);
};
fetchPosts();
}, [searchParams]);
Cualquier página que haga fetch al montar se cuelga en Puppeteer cuando el backend no está disponible.
Fix (commit 79b4219)
"include": ["/cv", "/contact", "/ai-search", "/login"]
Build 3: /cv y el requestAnimationFrame Infinito
Síntoma
Este fue el más sutil. Las rutas /contact, /ai-search y /login se completaban rápidamente. Pero el build se colgaba en la ruta 6/7 (después de /cv).
Diagnóstico
CV.js no hace llamadas API. El componente es puramente estático — renderiza un curriculum hardcodeado. ¿Entonces por qué cuelga?
El culpable era un componente aparentemente inocente en la sección de habilidades:
<Rating
name={`skill-${skill.name}`}
value={skill.level}
max={5}
readOnly
size="small"
/>
Material UI's <Rating> usa internamente requestAnimationFrame en un loop para manejar animaciones de hover y transiciones. Aunque el componente está en modo readOnly, el bucle de animación sigue activo.
Puppeteer interpreta requestAnimationFrame como "el main thread tiene trabajo pendiente" y nunca declara la página como idle. Es un comportamiento documentado pero poco conocido:
Puppeteer's
networkidle0waits for no network connections for 500ms, but also considers the page "busy" if there are active animation frames or long tasks.
Fix (commit 6372097)
"include": ["/contact", "/ai-search", "/login"]
Build 4: El Descubrimiento del Crawling
Síntoma
Con solo 3 rutas explícitas, esperaba 4 páginas a pre-renderizar (3 + /200.html). Los logs mostraban... 7 rutas.
✅ crawled 1 out of 7 (/contact)
✅ crawled 2 out of 7 (/ai-search)
✅ crawled 3 out of 7 (/login)
✅ crawled 4 out of 7 (/blog)
✅ crawled 5 out of 7 (/)
Las rutas que acababa de remover habían vuelto.
Diagnóstico: La Causa Raíz
react-snap tiene una opción activada por defecto llamada crawl:
// react-snap internals (simplified)
const defaultOptions = {
crawl: true, // ← THE PROBLEM
// ...
};
Con crawl: true, react-snap:
1. Pre-renderiza las rutas de include
2. Escanea el HTML generado buscando <a href="..."> tags
3. Agrega esas URLs a la cola de pre-renderizado
4. Repite hasta que no quedan URLs nuevas
Mi navbar tiene links a /, /blog, /cv, /contact, /ai-search y /login. Después de pre-renderizar /contact, react-snap encontraba estos links y los agregaba a la cola. Volvían a aparecer las rutas problemáticas.
Esta era la causa raíz real. Los builds anteriores no fallaban por las rutas individuales per se — fallaban porque el crawling re-descubría rutas que yo había removido explícitamente.
Fix (commit 7635476)
{
"reactSnap": {
"include": ["/contact", "/ai-search", "/login"],
"crawl": false,
"timeout": 10000
}
}
Build 5: /contact Se Queda Colgado
Síntoma
Con crawling desactivado, el build progresó: /login ✅, /ai-search ✅. Pero se colgó 10+ minutos en la tercera ruta.
Diagnóstico
Contact.js es un formulario simple con Material UI <TextField> y <Button>. No hace API calls al montar. Sin embargo, MUI's <TextField> usa internamente:
- Ripple animations en el <Button> (via requestAnimationFrame)
- Focus management que mantiene listeners activos
- <Alert> component con transiciones CSS que Puppeteer interpreta como actividad
Aunque el timeout de 10s debería haber terminado la captura, la combinación específica de componentes MUI en este formulario causaba que Puppeteer no pudiera capturar un snapshot limpio dentro del timeout.
Fix (commit 24f5f16)
{
"reactSnap": {
"include": ["/ai-search", "/login"],
"crawl": false,
"timeout": 10000
}
}
De 6 rutas originales, intento con solo 2.
Build 6: /ai-search También Falla
Síntoma
El build completó /login ✅. Pero se colgó indefinidamente en /ai-search:
✅ crawled 1 out of 2 (/login)
Duó 19+ minutos sin avanzar.
Diagnóstico
RagSearch.js inicialmente parecía "seguro" porque no hace API calls al montar. Pero revisándolo en detalle:
import { motion } from 'framer-motion';
import { useTypewriter } from '../hooks/useTypewriter';
// Componentes envueltos en <motion.div> con animaciones
<motion.div
initial={{ opacity: 0, y: 20 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.5 }}
>
{/* Contenido */}
</motion.div>
// Hook useTypewriter con setInterval interno
const displayText = useTypewriter(responseText, 20);
framer-motion usa internamente:
- requestAnimationFrame para animaciones suaves
- Timers para transiciones
- Loops de actualización del state
useTypewriter tiene un setInterval activo incluso cuando no hay texto que animar.
Material UI <TextField> también contribuye con sus propios listeners y efectos de ripple.
La combinación de estos tres factores hizo que Puppeteer nunca detectara "idle" en esta página tampoco.
Conclusión: react-snap No Es Viable
Después de 7 builds fallidos (incluyendo el inicial con 6 rutas), la realidad se impuso:
Cualquier página moderna con Material UI + framer-motion + hooks personalizados NO puede pre-renderizarse confiablemente con Puppeteer en CI/CD.
Las tecnologías que hacen que las SPAs sean atractivas (animaciones, componentes interactivos, state management) son precisamente las que Puppeteer interpreta como "la página aún no está lista".
Build 7: Eliminando react-snap Por Completo
Decisión Final (commit d6b1aa2)
Después de intentar con 6 → 5 → 4 → 3 → 2 rutas y fallar todas, la única opción viable era:
{
"scripts": {
"build": "react-scripts build"
}
}
Cambios:
- Removido react-snap de dependencies
- Eliminada config reactSnap de package.json
- Removido Chromium del Dockerfile (170 paquetes, 719 MB)
- Simplificado index.js (solo createRoot, sin hydrateRoot)
Resultado Final
Nivel 1: Code Splitting → 70% reducción bundle ✅ Intacto
Nivel 2: Nginx Cache → 85% cache hit rate ✅ Intacto
Nivel 3: Pre-rendering → SEO + FCP ❌ Eliminado
Nivel 4: Kaniko Cache → Build 3-5 min* ✅ Intacto
Sin Chromium, el build se reduce a 2-3 minutos* (aún más rápido).
Lo que se conserva: - Bundle reducido 70% (357 KB → 105 KB) - Cache Nginx (immutable assets) - Code splitting (lazy loading de rutas) - Builds rápidos y confiables
Lo que se pierde: - HTML pre-renderizado (~100-200ms de FCP) - SEO instantáneo (Google indexa SPAs correctamente, con delay de horas) - Previews en redes sociales (Twitter/LinkedIn)
¿Por Qué Esto Es Aceptable?
- Google ejecuta JS desde 2015: Las SPAs se indexan correctamente
- El 90% del beneficio viene de code splitting + cache, no de pre-rendering
- Blog personal: No hay presión de SEO competitivo
- Confiabilidad > Perfección: Builds que completan en 3 min son más valiosos que builds que fallan por optimizaciones marginales
La Configuración Final
package.json:
{
"scripts": {
"build": "react-scripts build"
}
}
Dockerfile:
FROM node:18-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
FROM nginx:1.25-alpine
COPY --from=build /app/build /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 8080
Sin Chromium. Sin Puppeteer. Sin react-snap.
Todas las Rutas: SPA Pura
| Ruta | ¿API calls? | ¿Animaciones? | Estado |
|---|---|---|---|
/ (Home) |
✅ 2 calls (posts, stats) | ✅ framer-motion | 🔄 SPA |
/blog |
✅ 1 call (posts) | ❌ | 🔄 SPA |
/cv |
❌ | ✅ Rating (rAF loop) | 🔄 SPA |
/contact |
❌ | ✅ TextField ripple | 🔄 SPA |
/ai-search |
❌* | ✅ framer-motion + typewriter | 🔄 SPA |
/login |
❌ | ❌ (form simple) | 🔄 SPA |
Todas las rutas renderizan client-side. El HTML inicial es:
<div id="root"></div>
<script src="/static/js/main.abc123.js"></script>
React monta la aplicación y renderiza el contenido en el navegador.
¿Implicaciones en Rendimiento?
Sin pre-rendering, ¿se perdió todo el beneficio de las optimizaciones?
No. Las 4 optimizaciones eran capas independientes:
Nivel 1: Code Splitting → 70% reducción bundle ✅ Intacto
Nivel 2: Nginx Cache → 85% cache hit rate ✅ Intacto
Nivel 3: Pre-rendering → SEO + FCP ❌ Eliminado
Nivel 4: Kaniko Cache → Build 2-3 min ✅ Intacto (+ rápido sin Chromium)
El pre-rendering aportaba ~10% del beneficio total. El 90% viene de code splitting (menos JS descargado) y nginx cache (assets no se re-descargan).
Métricas Finales vs Originales
| Métrica | Original (sin opt) | Con react-snap (fallido) | Final (sin pre-render) |
|---|---|---|---|
| Bundle principal | 357 KB | 105 KB | 105 KB |
| LCP estimado | ~3.5s | ~1.2s (teórico) | ~1.5s |
| Build time | 6 min | 1-2h (fallas) | 2-3 min |
| Build reliability | 100% | ~14% (1/7) | 100% |
| SEO delay | Horas/días | Instantáneo | Horas/días |
Tradeoff aceptable: Perdemos 300ms de FCP y SEO instantáneo, pero ganamos builds confiables que completan en 2-3 minutos.
Lecciones de Debugging en CI/CD
1. Puppeteer "Network Idle" Es Más Estricto De Lo Que Piensas
Puppeteer no solo espera a que no haya conexiones HTTP abiertas. También espera:
- No hay requestAnimationFrame callbacks pendientes
- No hay long tasks (>50ms) en el main thread
- No hay setTimeout/setInterval activos (en algunos modos)
Esto significa que componentes aparentemente estáticos (<Rating readOnly />) pueden bloquear la captura indefinidamente.
2. Defaults Silenciosos Te Matan
crawl: true como default de react-snap es probablemente responsable del 80% de los problemas que desarrolladores tienen con esta herramienta. No está documentado prominentemente y su efecto es devastador: re-descubre rutas que eliminaste explícitamente.
Regla: Siempre revisa los defaults de herramientas que controlan crawling, discovery, o auto-expansion.
3. Cloud Build ≠ Local
En local, npm run build completa react-snap rápidamente porque el backend dev server está corriendo. En Cloud Build:
- No hay backend disponible → API calls cuelgan
- No hay display → Chromium usa headless mode
- Alpine Linux → Chromium funciona diferente que en macOS/Windows
- Timeout del build (25min) es el único safety net
Regla: Si tu herramienta de build depende del runtime (API calls, window size, etc.), fallará en CI/CD.
4. Debugging Iterativo > Debugging Teórico
Podría haber intentado predecir qué rutas fallarían analizando el código. En la práctica, cada build revelaba un problema diferente:
- Build 1: API calls → obvio
- Build 2: API calls → predecible
- Build 3: requestAnimationFrame → sorpresa
- Build 4: Crawling automático → sorpresa total
- Build 5: MUI internals → sutil
A veces la forma más eficiente es iterar: remover, buildear, observar, repetir.
5. El Timeout No Es Suficiente
Configurar "timeout": 10000 debería haber protegido contra cuelgues. En la práctica, react-snap no siempre respeta el timeout limpiamente — puede quedarse esperando en el cierre de la instancia de Chromium después de que el timeout expire.
Regla: El timeout es un safety net, no una solución. Mejor prevenir el cuelgue que depender del timeout para matarlo.
6. Saber Cuándo Abandonar Una Herramienta
Después de 7 builds iterativos intentando hacer que react-snap funcionara, el problema no era "encontrar la configuración correcta" — el problema era que react-snap es fundamentalmente incompatible con aplicaciones React modernas que usan: - Material UI (ripple animations, focus management) - framer-motion (requestAnimationFrame loops) - Hooks personalizados con timers - API calls condicionales
Regla: Si una herramienta requiere más de 3 intentos de debugging para un caso de uso básico, evalúa si el beneficio justifica el costo. En este caso: 10% de beneficio (FCP + SEO) vs 7 builds fallidos = no justificado.
7. Kaniko + Cloud Build: No Uses images: Para Verificación
Después de remover react-snap exitosamente, el Build 7 completó la construcción y Kaniko pusheó la imagen:
INFO[0102] Pushed gcr.io/blog-479107/blog-frontend@sha256:b77dda8f...
Pero Cloud Build falló con:
ERROR: failed to find one or more images after execution of build steps
El problema: cloudbuild.yaml tenía una sección images: que le indica a Cloud Build verificar si la imagen está disponible después del build:
steps:
- name: 'gcr.io/kaniko-project/executor:latest'
args:
- --destination=gcr.io/$PROJECT_ID/blog-frontend:latest
images:
- 'gcr.io/$PROJECT_ID/blog-frontend:latest' # ← EL PROBLEMA
Con Kaniko, esto causa un race condition: Kaniko pushea directamente al registry con --destination, pero Cloud Build verifica la imagen antes de que GCR termine de indexarla. La imagen existe, pero Cloud Build no puede encontrarla en su verificación.
Solución (commit aca0a76): Eliminar la sección images: completamente. Kaniko ya se encarga del push via --destination, Cloud Build no necesita verificar:
steps:
- name: 'gcr.io/kaniko-project/executor:latest'
args:
- --destination=gcr.io/$PROJECT_ID/blog-frontend:latest
# (sin sección images:)
Regla: Con Kaniko, usa --destination para el push. NO agregues images: en cloudbuild.yaml porque crea un race condition entre el push de Kaniko y la verificación de Cloud Build.
Cronología Completa de Commits
| Build | Commit | Cambio | Resultado |
|---|---|---|---|
| 1 | d0ad056 |
6 rutas, sin crawl/timeout config | ❌ Timeout en / |
| 2 | 7c96593 |
Removido /, agregado timeout 10s |
❌ Timeout en /blog |
| 3 | 79b4219 |
Removido /blog |
❌ Timeout en /cv (rAF) |
| 4 | 6372097 |
Removido /cv |
❌ Crawling re-descubre rutas |
| 5 | 7635476 |
crawl: false |
❌ Timeout en /contact |
| 6 | 24f5f16 |
Removido /contact → 2 rutas |
❌ Timeout en /ai-search |
| 7 | d6b1aa2 |
Eliminado react-snap completamente | ✅ Build completa, ❌ Verificación falla |
| 8 | aca0a76 |
Removida sección images: de cloudbuild.yaml |
✅ Build exitoso (2-3 min) |
Ocho builds para llegar a una arquitectura estable: los primeros 6 intentando salvar react-snap, el 7º eliminándolo, y el 8º corrigiendo la configuración de Kaniko.
Alternativas (Evaluadas y Descartadas)
Opción A: Mantener react-snap con 1 Ruta
Podría haber intentado solo /login (la única que completó consistentemente). Pero:
- Pre-renderizar 1 de 6 páginas no aporta beneficio significativo
- Mantiene la complejidad (Chromium, Puppeteer, 719 MB)
- Builds siguen siendo 15-20 minutos sin cache, 5 minutos con cache
- Francamente irrisorio desde una perspectiva de costo-beneficio
Opción B: Migrar a Next.js
Next.js 14+ con App Router elimina todos estos problemas: - SSR/SSG nativo: No necesita Puppeteer - ISR (Incremental Static Regeneration): Re-genera páginas sin rebuild completo - React Server Components: Reduce bundle drásticamente
Desventaja: migración costosa desde CRA. Evaluaré esto como un proyecto futuro.
Opción C: Usar prerender-spa-plugin (Webpack)
Alternativa a react-snap que usa jsdom en lugar de Chromium. Más rápido y predecible. Sin embargo: - Requiere eject de CRA para acceder a config de Webpack - jsdom no soporta todos los APIs del DOM real (Material UI podría fallar) - Aún introduce complejidad en el pipeline de build
Para un blog personal, no justificado.
Conclusión: Cuando Menos Es Más
La lección principal de esta experiencia: la optimización tiene rendimientos decrecientes.
El camino de: - 357 KB → 105 KB (code splitting) = 70% de mejora - Cache browsers (nginx) = 85% menos tráfico - Pre-rendering (intenté) = 10% de mejora teórica, 7 builds fallidos de costo real
La arquitectura final es más simple, más rápida de buildear, y más fácil de mantener que la "optimizada" con react-snap:
Build time: 6 min → 2-3 min (sin Chromium)
Reliability: Fallos constantes → 100% estable
Bundle size: 357 KB → 105 KB (code splitting intacto)
Maintenance: Alto → Bajo (sin Puppeteer)
A veces optimizar significa saber qué NO hacer.
Recursos
- Puppeteer networkidle0 documentation
- react-snap configuration options
- requestAnimationFrame and browser idle
- Cloud Build timeout configuration
- Material UI internal animation system
Anterior: Optimización de Rendimiento Frontend: Code Splitting, Pre-renderizado y Caché Docker
Siguiente: De Blog Personal a Portafolio Profesional: Por Qué y Cómo
Este artículo es parte de la serie "Construyendo un Blog con IA". El código fuente completo está en GitHub.