Saltar al contenido
hg.Héctor GarridoCiencia de datos · Estadística · Ingeniería de datos
← Volver al blog
Portafolio RAG

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.

Debugging react-snap en CI/CD: Cuando Puppeteer Se Niega a Terminar

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 networkidle0 waits 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?

  1. Google ejecuta JS desde 2015: Las SPAs se indexan correctamente
  2. El 90% del beneficio viene de code splitting + cache, no de pre-rendering
  3. Blog personal: No hay presión de SEO competitivo
  4. 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


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.