wrangler deploy: publicar en el edge

Desplegar en la mayoría de las plataformas es reiniciar un servidor y cruzar los dedos mientras se calienta. En Cloudflare, wrangler deploy es otra cosa: empaqueta tu Worker en un artefacto, lo sube junto a su contrato de infraestructura y lo propaga a cientos de ubicaciones del planeta en segundos, sin cold starts porque no hay nada que arrancar. Entender qué sube exactamente, cómo se enruta el tráfico y cómo separar “subir una versión” de “activarla” es lo que convierte un deploy a ciegas en una estrategia de publicación controlada.

Qué sube de verdad

wrangler deploy —el comando que antes se llamaba wrangler publish— no sube tu carpeta de proyecto. Primero empaqueta: esbuild sigue los import desde el main del manifiesto y produce un único módulo con solo el código que tu Worker usa de verdad. Lo que viaja a Cloudflare es ese bundle más un puñado de metadatos, no tu node_modules ni tus archivos de configuración.

• El script empaquetado: tu JavaScript y cualquier módulo WASM, minificado y resuelto.
• La metadata: la compatibility_date, los flags y la lista de bindings del manifiesto, para que el runtime sepa qué inyectar en env.
• Los source maps: opcionales pero valiosos, permiten que la observabilidad te muestre stack traces con tus nombres originales en vez del código minificado.
• Los assets estáticos, si configuraste assets, que se suben aparte y se sirven desde el edge.

# empaqueta y despliega, enrutando el 100 por ciento del trafico
wrangler deploy

# ver que subiria, sin subir nada, y volcar el bundle a disco
wrangler deploy --dry-run --outdir dist

El --dry-run --outdir dist es una herramienta de aprendizaje infravalorada: te deja inspeccionar el bundle exacto que subiría, sin tocar producción. Y hay un motivo práctico para mirarlo: el tamaño del Worker está acotado —del orden de unos pocos megabytes comprimidos—, así que ese bundle no es solo curiosidad, es un presupuesto que conviene vigilar antes de que un import descuidado lo dispare.

Los source maps merecen una nota aparte. Cuando los subes, la observabilidad de Workers los usa para revertir la minificación en los stack traces: un error en producción te señala tu archivo y tu línea originales, no una columna ininteligible del bundle. Es la diferencia entre depurar con nombres y depurar a ciegas, y por eso subirlos casi nunca es opcional en un servicio serio.

El rollout: un push global en segundos

Cuando el bundle llega, Cloudflare crea una versión —un artefacto inmutable e identificado— y, por defecto, la enruta al 100 por ciento del tráfico. La propagación a la red global no tarda minutos: en segundos, ese código se ejecuta cerca de cada usuario del planeta. No hay servidores que reiniciar ni instancias que calentar, porque un Worker es un isolate que arranca en cero milisegundos.

flowchart LR
A[wrangler deploy] --> B[esbuild empaqueta el Worker]
B --> C[Sube script mas metadata mas source maps]
C --> D[Se crea una version inmutable]
D --> E[Se enruta al 100 por ciento del trafico]
E --> F[Propagacion a la red global en segundos]

Cada versión, incluso antes de recibir tráfico, obtiene su propia URL de previsualización, lo que te permite probar exactamente el artefacto desplegado antes de enviarle usuarios reales. Un deploy normal deja además un registro en el historial de despliegues, de modo que siempre sabes qué versión está sirviendo y desde cuándo.

Dónde se sirve esa versión lo dice el manifiesto: si workers_dev está activo, responde en el subdominio gratuito workers.dev; si declaraste routes, atiende tu dominio propio. El despliegue no cambia esas rutas —las fija la config—; lo único que cambia es qué código hay detrás de ellas.

Versiones: subir sin desplegar

Aquí aparece la distinción más poderosa del modelo. wrangler deploy funde en un gesto dos actos que en realidad son distintos: subir una versión y activarla para el tráfico. wrangler versions los separa. Puedes subir una versión nueva que quede al 0 por ciento —desplegada en la infraestructura pero sin recibir un solo usuario— y decidir más tarde, y gradualmente, cuánto tráfico merece.

# sube una version nueva SIN enrutarle trafico (queda al 0 por ciento)
wrangler versions upload

# reparte el trafico entre versiones de forma gradual
wrangler versions deploy

# listar el historial e inspeccionar una version
wrangler versions list

wrangler versions upload te da una URL de previsualización de esa versión concreta sin arriesgar producción. Es el equivalente en Workers a “compilar el artefacto de release” sin publicarlo todavía: el artefacto existe, es probable, pero nadie lo está usando aún.

Despliegues graduales y rollback

wrangler versions deploy es donde se cierra el círculo: te deja repartir el tráfico entre versiones por porcentaje —por ejemplo, un 10 por ciento a la versión nueva y un 90 por ciento a la estable—, observar métricas y errores en esa fracción, y solo entonces subir el porcentaje. Es entrega progresiva (progressive delivery) horneada en la plataforma, sin balanceadores ni infraestructura extra.

# reparto explicito de trafico entre dos versiones concretas
wrangler versions deploy <id-version-nueva>@10 <id-version-actual>@90

Por defecto, ese reparto se decide petición a petición: dos llamadas seguidas del mismo usuario podrían caer en versiones distintas. Cuando eso importa —una sesión que no debe saltar de versión a media interacción—, la afinidad de versión fija a cada cliente en una versión durante su sesión, de modo que el reparto porcentual no rompe la coherencia de una experiencia en curso. Y conviene conocer los bordes: el reparto gradual no aplica al primerísimo despliegue de un Worker, porque no hay dos versiones entre las que repartir.

Y si algo va mal, revertir es instantáneo porque la versión anterior nunca dejó de existir: wrangler rollback devuelve el tráfico a una versión previa sin reempaquetar ni resubir nada. La inmutabilidad de las versiones es lo que hace del rollback una operación de enrutado, no de reconstrucción.

# revertir el trafico a una version anterior, al instante
wrangler rollback

# consultar el historial de despliegues y la version activa
wrangler deployments list