Compatibility dates y flags

El runtime de Workers se actualiza constantemente, pero tú tienes Workers desplegados hace meses que no piensas volver a tocar. ¿Cómo avanza Cloudflare sin romperlos? Con un mecanismo elegante: cada Worker declara una compatibility_date, y el runtime se comporta ante él como se comportaba en esa fecha. El progreso queda tras una puerta que tú abres cuando quieres. Es, en el fondo, un sistema de feature flags versionado por fecha e incrustado en el propio motor.

El problema: un runtime vivo bajo código congelado

Node resuelve la evolución con semver: publican una versión mayor con cambios que rompen, y tú decides cuándo actualizar reinstalando. El control lo tiene el operador, que elige la versión del runtime que instala junto a su aplicación.

Cloudflare no tiene ese lujo. No hay una versión del runtime por Worker que tú instales; hay un único runtime global, actualizado continuamente, que ejecuta a la vez el Worker que desplegaste esta mañana y el que desplegaste hace dos años y nunca volviste a mirar. Multiplica eso por millones de Workers de clientes distintos, muchos sin mantenimiento activo, y tienes el problema en toda su crudeza: cualquier cambio de comportamiento es, potencialmente, una regresión masiva y silenciosa.

Si Cloudflare cambiara un comportamiento observable —como corrigió en su día la presencia del navigator global, o la forma de construir ciertos streams— rompería en silencio miles de Workers en producción cuyos autores no están mirando. La solución no puede ser “no cambiar nunca”, porque el runtime necesita corregir errores, cerrar agujeros de seguridad y adoptar estándares nuevos. Tampoco puede ser forzar a todos a redesplegar, porque muchos Workers están en producción sin nadie que los mantenga.

La salida es hacer que cada cambio que rompe sea opcional y esté anclado a una fecha. El runtime lleva dentro de sí todas las versiones de comportamiento a la vez, y decide cuál aplicar según lo que cada Worker declare. Es un condicional gigante sobre una fecha, no una bifurcación de binarios.

Conviene subrayar el matiz: solo se gestionan así los cambios que rompen. Las correcciones puras, las mejoras de rendimiento y las APIs nuevas que no alteran el comportamiento existente llegan a todos los Workers de inmediato, sin esperar a ninguna fecha. La puerta versionada es únicamente para lo que podría cambiar el resultado observable de un Worker que ya funciona.

compatibility_date: fijar el comportamiento

Cada Worker declara en su configuración una fecha de compatibilidad:

{
  "name": "mi-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23"
}

Si prefieres el formato TOML, la misma declaración se escribe igual de directa, y puede acompañarse ya de los flags que verás en la siguiente sección:

name = "mi-worker"
main = "src/index.ts"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]

Esa línea le dice al runtime: compórtate conmigo como te comportabas el 23 de septiembre de 2024. Aunque el motor se actualice cien veces después de esa fecha, los cambios que rompen quedan desactivados para este Worker. Su comportamiento queda congelado en el tiempo y, por tanto, es reproducible: el mismo código con la misma fecha produce el mismo resultado hoy, el año que viene y dentro de cinco.

Para adoptar mejoras, subes la fecha deliberadamente a una más reciente, pruebas, y despliegas. La actualización del runtime deja de ser un evento que te ocurre y pasa a ser una decisión que tomas. Cloudflare recomienda mantener una fecha reciente y avanzarla con regularidad, no dejarla anclada en el pasado para siempre: una fecha muy vieja acumula deuda y te aparta de las correcciones y de las APIs nuevas.

Hay un detalle práctico que se olvida a menudo: la fecha viaja con el proyecto, no con tu máquina. Vive en el wrangler.jsonc versionado —o en el wrangler.toml, si prefieres ese formato—, de modo que cualquiera que despliegue, tú, un compañero o CI, obtiene exactamente el mismo comportamiento del runtime. Es el mismo principio de reproducibilidad que un lockfile, aplicado no a las dependencias sino al motor que ejecuta tu código.

La fecha no es opcional. Si la omites, las herramientas te avisan y, según el contexto, aplican una por defecto o rechazan el despliegue, porque un Worker sin fecha declarada sería un Worker cuyo comportamiento podría cambiar bajo tus pies. Declararla siempre, de forma explícita, es parte de la higiene mínima de cualquier proyecto de Workers.

compatibility_flags: control granular

La fecha es un instrumento grueso: activa de golpe todos los comportamientos cuyo día por defecto es esa fecha o uno anterior. Los compatibility_flags son el bisturí: activan o desactivan comportamientos concretos con independencia de la fecha.

{
  "compatibility_date": "2024-09-23",
  "compatibility_flags": ["nodejs_compat", "no_global_navigator"]
}

Cada flag suele venir en pareja —un nombre para activarlo y otro para desactivarlo— más una fecha en la que pasa a ser el valor por defecto. Ese doble mando te da dos superpoderes complementarios:

• Adoptar un comportamiento nuevo antes de que sea el estándar, encendiéndolo con su flag.
• Retrasar un comportamiento que aún no puedes absorber, apagándolo con su flag inverso pese a haberte pasado ya su fecha por defecto.

Un ejemplo concreto ayuda a ver el efecto. El flag global_navigator controla si existe el objeto navigator global, un comportamiento que se alinea con el del navegador:

// Con global_navigator activo (por fecha o por flag):
console.log(typeof navigator);     // "object"
console.log(navigator.userAgent);  // "Cloudflare-Workers"
// Sin ese comportamiento, navigator no existe y el acceso lanzaria.

No tienes que memorizar el catálogo entero: la documentación de Cloudflare mantiene una página con todos los flags, su descripción y su fecha por defecto. Algunos flags son experimentales y se marcan como tales mientras se estabilizan; con el tiempo, muchos acaban graduándose a comportamiento por defecto y quedan absorbidos por una fecha, momento en el que dejar de escribirlos explícitamente es lo correcto.

La existencia misma de los flags revela una intención de diseño: Cloudflare quiere que la adopción de cada cambio sea gradual y reversible. Puedes probar un comportamiento nuevo en un único Worker con su flag, comprobar que nada se rompe, y solo entonces subir la fecha global del proyecto para adoptarlo en todos. El flag es la unidad de experimentación; la fecha, la de compromiso.

En el día a día, los flags aparecen sobre todo en tres situaciones concretas:

• Habilitar nodejs_compat porque una dependencia lo necesita, como verás en la lección 4.
• Silenciar temporalmente un comportamiento nuevo que rompió algo, mientras adaptas el código.
• Probar por adelantado una mejora anunciada, antes de que llegue su fecha por defecto.

La relación entre fechas y flags

El modelo mental exacto es este: una compatibility_date no es más que un atajo para “activa todos los flags cuya fecha por defecto sea igual o anterior a esta”. Fijar una fecha equivale a marcar una casilla por cada flag que ya se volvió estándar en ese momento.

Los compatibility_flags son entonces las excepciones que escribes encima de ese paquete: enciendes algo del futuro o apagas algo del presente. La fecha resuelve el caso común de un solo trazo; los flags cubren los casos de borde sin obligarte a mover la fecha entera.

De esta relación se deduce una consecuencia útil para razonar: dos configuraciones distintas pueden producir el mismo comportamiento. Una fecha reciente equivale a una fecha vieja más la lista explícita de todos los flags que se volvieron estándar entre ambas. Normalmente prefieres la fecha reciente, más limpia; pero entender la equivalencia te permite auditar exactamente qué comportamientos tiene activos un Worker cualquiera.

Y de aquí sale la práctica recomendada, que cierra el círculo: mantén una compatibility_date reciente en todo el proyecto, usa los compatibility_flags solo como excepciones puntuales y temporales, y trata cada avance de la fecha como un cambio revisable con su prueba en staging. Así el runtime avanza contigo, en pasos pequeños y deliberados, en lugar de acumular una deuda que algún día te obligue a saltar años de comportamiento de una vez.

flowchart TD
A[compatibility_date] --> B[activa los flags con fecha por defecto anterior o igual]
C[compatibility_flags] --> D[excepciones explicitas sobre ese paquete]
B --> E[comportamiento efectivo del Worker]
D --> E