vars: configuración en texto plano

Todo Worker acaba necesitando datos que cambian entre un despliegue y otro sin ser parte de la lógica: la URL de una API, el nombre del entorno, un umbral numérico, una bandera de funcionalidad. Cloudflare llama a esas piezas vars, y su promesa es simple y peligrosa a partes iguales: viven en texto plano dentro de tu manifiesto, versionadas junto al código, y llegan al Worker por el mismo objeto env que los secretos. Entender qué son —y sobre todo qué nunca deben ser— es el primer ladrillo de una configuración sana en el edge.

El manifiesto declara la configuración

Un Worker no tiene un entorno de proceso ambiente como un servidor tradicional. No existe un process.env global del que colgar la configuración: en el edge, todo lo que el código necesita del exterior llega por un único canal, el objeto env, que el runtime entrega como segundo argumento del handler fetch. Las vars son la forma declarativa de poblar ese objeto con valores estáticos, escritos a mano en el manifiesto del Worker.

Ese manifiesto es wrangler.jsonc —o su equivalente wrangler.toml—, y vars es una clave de nivel superior: un mapa de nombres a valores.

{
  "name": "tienda-api",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "vars": {
    "ENTORNO": "produccion",
    "API_BASE": "https://api.tienda.example",
    "NIVEL_LOG": "info",
    "MAX_ITEMS": 50
  }
}

Al ejecutar wrangler deploy, esos pares se suben como parte de la configuración del Worker y quedan disponibles en env en cada invocación. Los valores suelen ser cadenas, pero vars admite también JSON nativo —números, booleanos, objetos o arrays—, y el runtime te los entrega con esa misma forma. Dentro del código, leerlos es trivial:

export default {
  async fetch(request, env, ctx) {
    const base = env.API_BASE;          // "https://api.tienda.example"
    const limite = env.MAX_ITEMS;       // 50, ya como numero
    return new Response(`entorno: ${env.ENTORNO}`);
  },
} satisfies ExportedHandler<Env>;

Conviene subrayar el contraste con un servidor clásico. Allí, process.env es un cajón que puede rellenarse desde mil sitios —el shell, un .env, el sistema de init, un orquestador— y cuyo contenido en ejecución cuesta auditar. En un Worker no hay tal cajón: env se construye a partir de lo que declaras de forma explícita en el manifiesto y en el almacén de secretos, ni una clave de más. Esa explicitud es una ganancia de claridad que no conviene desperdiciar metiendo en vars cosas que no deberían estar a la vista.

Hay además una consecuencia temporal que define su carácter: como las vars se fijan en el momento del despliegue, son estáticas durante toda la vida de esa versión del Worker. Cambiar una var exige un wrangler deploy nuevo, que publica una versión nueva y deja la anterior disponible para un rollback. Eso es deseable —tu configuración queda atada a una versión concreta del código, reproducible y reversible—, pero implica que vars no sirve para valores que deban cambiar en caliente sin redeployar; para eso existe un almacén como KV.

Un matiz operativo lo confirma: si cambias una sola var y vuelves a desplegar, Cloudflare publica una versión nueva y entera del Worker, no un parche de esa variable. Encaja con el modelo de versiones inmutables —cada despliegue es un artefacto identificable y reversible— y explica por qué vars sirve para configuración que cambia al ritmo del código, no al ritmo del tráfico.

Por eso, cuando alguien propone usar una var como interruptor que se cambia muchas veces al día, la respuesta correcta suele ser otra pieza: una bandera en KV, leída en runtime, evita redeployar por cada ajuste y deja vars para lo que de verdad acompaña a una versión concreta del código.

Texto plano significa texto plano

Aquí está la propiedad que define a una var y que debes grabar antes que ninguna otra: su valor no está cifrado en ningún punto de su vida. Está escrito en wrangler.jsonc, un archivo que confirmas y subes a tu repositorio. Aparece tal cual en el panel de Cloudflare, legible para cualquier miembro de la cuenta. Se imprime en la salida de wrangler deploy y puede acabar en los registros de tu CI. Una var, en la práctica, es información pública dentro de tu equipo y semipública en tu tooling.

De ahí se deriva la única regla que importa: si la filtración de ese valor causara algún daño —por pequeño que sea—, ese valor no es una var. El nombre de tu entorno, la URL pública de una API, el tamaño de un lote: perfectos. Una clave de API, la contraseña de una base de datos, un token de firma: jamás. Para eso existen los secretos, que son la lección siguiente y viven en un almacén cifrado precisamente porque vars no lo es.

Merece la pena enumerar dónde queda expuesta exactamente una var, porque la lista sorprende: en el archivo del repositorio y todo su historial; en el panel del navegador, para cualquiera con acceso de lectura a la cuenta; en la configuración de la versión desplegada, que Wrangler puede volcar; y, con frecuencia, en los registros de la tubería de CI que ejecutó el despliegue. Cuatro superficies, ninguna cifrada. Cuando decides que un dato es una var, estás aceptando esas cuatro exposiciones a la vez.

Este no es un consejo paranoico sino la lección que muchos equipos aprenden por las malas: la mayoría de las credenciales filtradas en la industria no salieron por un ataque ingenioso, sino por un valor sensible confirmado en un repositorio que un día se hizo público o se compartió con quien no debía. Tratar vars como una vitrina, no como un cajón, es lo que evita engrosar esa estadística.

Nombres, tipos y el override local

Como vars y los secretos pueblan el mismo objeto env, comparten un único espacio de nombres: un binding no puede llamarse igual que otro sin que uno ensombrezca al otro. Mantén los nombres distintos y en mayúsculas por convención, para que al leer env.ALGO sea evidente de dónde sale.

Para no programar a ciegas contra env, Wrangler genera los tipos por ti. El comando wrangler types produce un worker-configuration.d.ts con una interfaz Env que refleja exactamente tus vars, secretos y bindings declarados, de modo que el editor te autocompleta env.API_BASE y te avisa si escribes un nombre que no existe. En un proyecto sano, ese archivo se regenera en cada cambio de configuración y el compilador se vuelve tu primera línea de defensa contra un env.TYPO silencioso.

En desarrollo, además, puedes sobreescribir cualquier var sin tocar el manifiesto: un archivo .dev.vars en la raíz del proyecto —ignorado por git— alimenta a wrangler dev con valores locales. Es el sitio natural para apuntar API_BASE a un servidor de pruebas mientras trabajas, sin arriesgarte a confirmar ese cambio.

Una advertencia de diseño cierra el apartado: que vars acepte JSON no es una invitación a meter ahí estructuras grandes. Una var es más útil cuanto más atómica —un valor, un propósito—. Si te descubres serializando un objeto de configuración complejo en una var, esa complejidad probablemente pertenece al código, a un asset versionado, o a un almacén con estructura propia. Reserva vars para las pocas palancas que de verdad cambian entre despliegues.

Conviene recordar, además, que las vars no son secretas ni siquiera frente a tu propio equipo ampliado: colaboradores, contratistas y cualquier integración con acceso de lectura a la cuenta las ven. Si un valor solo debería conocerlo un subconjunto de tu equipo, ya no es una var aunque no sea técnicamente una credencial; la visibilidad, y no solo el daño potencial, es un criterio válido para mandar algo al almacén cifrado.

Un último apunte sobre tipos: lo generado refleja lo que declaraste, no lo que de verdad llega en runtime. Si despliegas con una var mal escrita o ausente, el tipo dirá que existe y el código accederá a un valor indefinido sin quejarse en compilación. Los tipos te protegen de errar el nombre, no de olvidar el valor; para eso está probar el Worker desplegado, no solo compilarlo.

El viaje completo de una var, desde que la escribes hasta que la lees, cabe en un diagrama:

flowchart LR
CFG[wrangler jsonc mapa vars] --> DEP[wrangler deploy]
DEP --> META[config del worker en texto plano]
META --> RT[runtime del edge]
RT --> ENV[objeto env en cada peticion]
ENV --> CODE[el codigo lee env]
style CFG fill:#89b4fa,color:#11111b
style ENV fill:#a6e3a1,color:#11111b
style CODE fill:#f9e2af,color:#11111b

Elegir bien: var, secreto, binding o KV

Antes de escribir cualquier dato de configuración, conviene ubicarlo en el mapa de las cuatro piezas que pueblan o rodean a env. Confundirlas es la causa raíz de casi todos los errores de este nivel: meter un secreto en una var, o un dato dinámico donde solo caben valores estáticos.

Cada una de estas cuatro piezas existe porque resuelve un problema que las otras no: vars da transparencia, el secreto da confidencialidad, el binding da acceso gobernado a un recurso, y el almacén da dinamismo y volumen. Meter un dato en la pieza equivocada no es solo desordenado: sacrifica justo la propiedad que ese dato necesitaba.

La regla de decisión es una cascada de preguntas: ¿es sensible? Entonces es un secreto. ¿Es una conexión a un recurso? Entonces es un binding. ¿Cambia sin redeployar o es voluminoso? Entonces vive en un almacén. Solo lo que sobrevive a las tres preguntas —no sensible, escalar, estático— merece ser una var. Esa disciplina mantiene tu manifiesto legible y tu superficie de exposición mínima.