Declarar bindings en wrangler.jsonc

Un binding no existe hasta que lo declaras, y el lugar de esa declaración es wrangler.jsonc, el manifiesto del Worker. Aquí es donde una capacidad abstracta —quiero acceso a esta base de datos— se convierte en una entrada concreta que la plataforma sabrá resolver. Cada tipo de recurso tiene su propia sección con su propia forma, pero todas obedecen a un mismo patrón: un nombre lógico para tu código y un puntero al recurso real del mundo.

La anatomía de una declaración

Toda declaración de binding tiene dos mitades. La primera es el nombre lógico —la clave binding, o name en el caso de los Durable Objects— que se convertirá en la propiedad homónima de env. La segunda es un puntero al recurso concreto: un id, un bucket_name, un database_id, según el tipo. Tu código habla siempre del nombre lógico; la config es la única que conoce el recurso real detrás.

{
  // el nombre logico se vuelve env.MI_KV en tu codigo
  "kv_namespaces": [
    { "binding": "MI_KV", "id": "a1b2c3d4e5f6" }
  ]
}

Empieza el manifiesto con la clave $schema: apunta al esquema que trae Wrangler y hace que tu editor autocomplete cada sección y valide cada clave. No es obligatoria, pero escribir bindings sin ella es renunciar a la red de seguridad que evita la mayoría de los errores de tipeo.

Una sección por tipo de recurso

Cada familia de bindings tiene su propia clave de nivel superior, y su forma refleja lo que la plataforma necesita para resolver el recurso. Este manifiesto reúne las secciones más frecuentes en un solo lugar para que veas el patrón repetirse:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "mi-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-07-15",

  // KV: nombre logico + id del namespace
  "kv_namespaces": [
    { "binding": "MI_KV", "id": "<ID_DEL_NAMESPACE>" }
  ],

  // R2: nombre logico + nombre del bucket
  "r2_buckets": [
    { "binding": "MI_BUCKET", "bucket_name": "mis-archivos" }
  ],

  // D1: nombre logico + nombre e id de la base de datos
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "produccion",
      "database_id": "<ID_DE_LA_DB>"
    }
  ],

  // Durable Objects: name + la clase que lo implementa
  "durable_objects": {
    "bindings": [
      { "name": "SALA", "class_name": "SalaDeChat" }
    ]
  },

  // Queues: productor (send) y consumidor (handler)
  "queues": {
    "producers": [
      { "binding": "MI_COLA", "queue": "trabajos" }
    ],
    "consumers": [
      { "queue": "trabajos" }
    ]
  },

  // service binding: apunta a otro Worker por su nombre
  "services": [
    { "binding": "AUTH", "service": "worker-de-auth" }
  ],

  // Workers AI: basta el nombre del binding
  "ai": { "binding": "AI" },

  // Vectorize: nombre logico + nombre del indice
  "vectorize": [
    { "binding": "VEC", "index_name": "embeddings-productos" }
  ],

  // variables de texto plano, publicas y versionadas
  "vars": { "MODO": "produccion" }
}

El patrón salta a la vista. Los almacenes se listan como arrays de objetos, cada uno con su binding y su puntero: id para KV, bucket_name para R2, database_name con database_id para D1. Los Durable Objects viven bajo durable_objects.bindings y usan name en lugar de binding, más class_name para señalar la clase de tu código que los implementa. Queues se parte en producers y consumers. Un service binding apunta a otro Worker por su service, y Vectorize a su índice por index_name.

Del nombre lógico al recurso real

Esa separación entre nombre y puntero es la que hace portátil a tu código. Como env.DB es un nombre lógico, puedes apuntarlo a una base de datos en desarrollo y a otra en producción cambiando solo el database_id de la config —o usando entornos—, sin tocar una línea del Worker. El código pide una capacidad por su nombre; la config decide qué recurso concreto la satisface.

Las variables encajan aquí con naturalidad: la sección vars guarda pares de texto plano que son públicos y viajan versionados en el repositorio junto al manifiesto. Los secretos, en cambio, son la excepción deliberada. No van en wrangler.jsonc, porque todo lo que escribes ahí acaba en el control de versiones. Se suben por un canal aparte, cifrados, y solo entonces aparecen en env como cadenas.

# un secreto NO va en wrangler.jsonc: se sube cifrado, aparte
npx wrangler secret put MI_SECRETO

# .dev.vars — secretos solo para desarrollo local, fuera del control de versiones
MI_SECRETO=valor-solo-local
API_KEY=clave-de-pruebas

flowchart LR
DECL[seccion en wrangler jsonc] --> NAME[nombre logico como binding o name]
DECL --> PTR[puntero al recurso como id o nombre]
NAME --> ENV[propiedad en env]
PTR --> RES[recurso real de tu cuenta]
ENV --> USO[tu codigo usa env.LO_QUE_SEA]
RES --> USO
style DECL fill:#89b4fa,color:#11111b
style USO fill:#a6e3a1,color:#11111b