El tamaño del bundle

Hay un límite que no se manifiesta en tiempo de ejecución sino en el momento de desplegar, y por eso sorprende: el tamaño del script. Tu Worker no viaja a la red tal como lo escribes, sino empaquetado en un único bundle, comprimido con gzip, y ese paquete no puede pasar de cierto peso. El número parece generoso hasta que metes una librería pesada o incrustas un fichero de datos, y de pronto el despliegue se niega. Entender qué entra en ese paquete, y qué no debería, es una habilidad de arquitectura tanto como de empaquetado.

El límite del script comprimido

El tope se mide sobre el bundle ya comprimido con gzip, no sobre tu código fuente. En el plan Free son 3 MB comprimidos; en Paid, 10 MB. Hay además un límite antes de comprimir, de 64 MB en ambos planes, pero el que sueles tocar es el de gzip, porque el JavaScript comprime muy bien y el fuente rara vez se acerca a los 64.

Que el límite sea sobre el comprimido tiene una consecuencia práctica: no puedes estimarlo mirando el tamaño de tu carpeta src. Un árbol de dependencias de varios megabytes puede caber holgado tras la compresión, o un solo fichero binario incrustado puede dispararlo pese a parecer pequeño en disco. Hay que medir el número real, no intuirlo.

# empaqueta sin desplegar y muestra el tamano comprimido
npx wrangler deploy --outdir bundled/ --dry-run

# la salida se parece a esto: fijate en la cifra tras gzip
Total Upload: 259.61 KiB / gzip: 47.23 KiB

La cifra que importa es la que va después de gzip. Esa es la que se compara contra tu límite, y la que conviene vigilar en integración continua para que un despliegue no se rompa por sorpresa el día que alguien añade una dependencia gorda.

Por qué el tamaño frena el arranque

El peso del bundle no es solo una cuestión de si el despliegue pasa o no: también moldea la latencia de la primera petición. Antes de atender nada, el isolate tiene que parsear y ejecutar el ámbito global de tu script —todo el código de nivel superior, fuera de los manejadores— y para eso tiene un presupuesto de un segundo.

Un bundle grande tarda más en parsearse, y si además tu código de nivel superior hace trabajo caro al arrancar —construir tablas enormes, compilar expresiones regulares, inicializar librerías— consumes ese segundo antes de haber respondido a nadie. La regla es mantener el ámbito global liviano: declara, no ejecutes; y deja el trabajo caro para dentro del manejador o, mejor, para la primera vez que de verdad se necesita.

Adelgazar el bundle

La primera pregunta ante un bundle gordo no es cómo comprimir más, sino qué no tendría que estar ahí dentro. Los datos son el sospechoso habitual: ficheros de configuración, activos estáticos, blobs binarios, tablas de traducción. Nada de eso pertenece al script.

El code splitting merece un matiz. El empaquetador elimina por sí solo el código muerto si tus dependencias son módulos ESM que permiten tree-shaking; una librería que solo se exporta como CommonJS a menudo entra entera aunque uses una función. Por eso, a igualdad de utilidad, la dependencia moderna y modular pesa menos en tu bundle final que la veterana monolítica.

// en vez de importar el generador de PDF arriba y cargarlo siempre,
// lo traes solo cuando la ruta que lo usa se pide de verdad
export default {
  async fetch(request, env): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname === "/informe.pdf") {
      const { generarPdf } = await import("./pdf.ts");
      return generarPdf(env);
    }
    return new Response("ok");
  },
};

flowchart LR
SRC[Tu codigo y dependencias] --> BUND[Empaquetado y tree shaking]
BUND --> GZIP[Comprimido con gzip]
GZIP --> CHK{Cabe en el limite del plan}
CHK -- si --> DEPLOY[Se despliega]
CHK -- no --> FIX[Saca datos y parte el codigo]
FIX --> BUND
DATA[Configuracion activos y binarios] --> STORE[KV R2 D1 o Static Assets]
style GZIP fill:#89b4fa,color:#11111b
style DEPLOY fill:#a6e3a1,color:#11111b
style FIX fill:#fab387,color:#11111b
style STORE fill:#cba6f7,color:#11111b