wrangler.jsonc: el manifiesto del Worker

Un Worker es dos cosas: el código que ejecutas y el contrato de todo lo que ese código puede tocar. Ese contrato vive en wrangler.jsonc, el manifiesto que declara cómo se llama el Worker, dónde está su punto de entrada, contra qué versión del runtime se comporta y a qué bases de datos, buckets o colas tiene derecho a acceder. No es un archivo de configuración accesorio: es la frontera formal entre tu compute y la plataforma, y aprender a leerlo es aprender a leer la arquitectura del proyecto de un vistazo.

Config como código: la fuente de la verdad

El manifiesto encarna un principio: la infraestructura no es un panel que alguien tocó una vez, sino un archivo cuya historia cuenta git. Todo lo que define al Worker —su identidad, su runtime, sus permisos— está en un solo lugar, revisable en un pull request y reproducible en cualquier máquina. wrangler lo detecta automáticamente en la raíz del proyecto, y un editor con soporte de esquema te autocompleta y valida cada campo si añades la línea $schema, que apunta al esquema que wrangler trae consigo.

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "mi-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-15",
  "compatibility_flags": ["nodejs_compat"],
  "observability": { "enabled": true }
}

Los campos de identidad

Cuatro campos definen qué es el Worker antes de hablar de recursos. name es su identificador: da nombre al script en tu cuenta y, salvo dominio propio, al subdominio en workers.dev. main apunta al punto de entrada que wrangler empaqueta —normalmente src/index.ts—; a partir de ahí, el bundler sigue los import y arma un único módulo.

Los dos campos de compatibilidad son los más profundos y los más incomprendidos. compatibility_date fija una fecha, y esa fecha congela el comportamiento del runtime: workerd decide qué APIs y qué semántica te ofrece según el día que declaraste, no según el día que despliegas. Es control de versiones del runtime por fecha. compatibility_flags permite activar o desactivar cambios puntuales sin mover toda la fecha —el caso más común, nodejs_compat, habilita un subconjunto de APIs de Node.

Alrededor de ese núcleo, un puñado de campos gobierna dónde y cómo se sirve el Worker: workers_dev decide si se expone en el subdominio gratuito workers.dev, routes lo engancha a un dominio propio, triggers define horarios cron, y placement activa el Smart Placement para acercar el compute a los datos. El account_id es opcional en el archivo —conviene dejarlo fuera y pasarlo por variable de entorno para no fijar una cuenta en el repositorio—.

Bindings: capacidades declaradas

Aquí está el modelo mental que distingue a Cloudflare. Un Worker no accede a una base de datos con una cadena de conexión llena de secretos: declara un binding en el manifiesto, y el runtime inyecta ese recurso en el objeto env que recibe cada handler. Declaras una capacidad; recibes un objeto ya conectado. No hay credenciales que filtrar porque no hay credenciales: hay derechos concedidos en la config.

{
  "vars": { "ENTORNO": "produccion" },
  "kv_namespaces": [
    { "binding": "CACHE", "id": "0f2ac..." }
  ],
  "d1_databases": [
    { "binding": "DB", "database_name": "app", "database_id": "8c1e..." }
  ],
  "r2_buckets": [
    { "binding": "MEDIA", "bucket_name": "uploads" }
  ],
  "ai": { "binding": "AI" }
}

Cada entrada tiene un binding: el nombre bajo el que aparece en env. La declaración de arriba hace que tu código pueda usar env.CACHE, env.DB, env.MEDIA y env.AI directamente, ya tipados si corriste wrangler types. El nombre lo eliges tú; el recurso al otro lado lo identifica un id o un database_id.

flowchart LR
A[wrangler.jsonc declara un binding] --> B[El runtime inyecta env]
B --> C[env.DB apunta al recurso]
C --> D[Sin cadena de conexion ni secreto en el codigo]

El catálogo de bindings cubre toda la plataforma, y todos siguen el mismo patrón: una clave en el manifiesto, un nombre en env. Reconocer las familias te deja leer la superficie completa de un Worker sin abrir su código.

Un matiz que separa a los bindings de datos de los demás: algunos necesitan más que su declaración. Un durable_objects exige además una entrada de migrations que registre la clase, porque un Durable Object tiene ciclo de vida propio; ahí el manifiesto no solo concede acceso a un recurso, también versiona su existencia. Es la pista de que un binding no siempre apunta a algo que ya existe: a veces lo declara por primera vez.

Entornos, y jsonc frente al viejo toml

Un mismo Worker suele vivir en varias encarnaciones: producción, staging, previsualización. El manifiesto modela esto con la clave env: la configuración del nivel superior es el entorno por defecto, y cada entrada bajo env.<nombre> la especializa.

{
  "name": "mi-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-15",
  "vars": { "ENTORNO": "produccion" },
  "env": {
    "staging": {
      "vars": { "ENTORNO": "staging" }
    }
  }
}

Hay una trampa clásica: las claves no heredables —vars, los bindings, routes— no pasan del nivel superior a un entorno con nombre. Si un entorno declara cualquier vars, debe redeclarar todas las que necesite; el manifiesto no las mezcla por ti. Esta ausencia de herencia parcial es deliberada —evita que un entorno arrastre un binding de producción sin querer—, pero sorprende a quien la descubre en caliente.

Históricamente este archivo era wrangler.toml. El toml sigue soportado, pero desde finales de 2024 el formato por defecto es wrangler.jsonc —JSON con comentarios—, y en 2026 es lo que genera C3 y lo que verás en la documentación. La razón es práctica: JSON lo genera y lo lee una máquina sin ambigüedad, encaja con el resto del ecosistema y expresa mejor la estructura anidada de bindings y entornos; el sufijo jsonc recupera lo único bueno que el JSON puro no tenía, los comentarios.