Tipado con wrangler types

Has declarado tus bindings en wrangler.jsonc y sabes que llegan a env como objetos vivos. Falta un último eslabón para cerrar el círculo: que TypeScript sepa exactamente qué contiene ese env. El comando wrangler types es quien tiende ese puente. Lee tu manifiesto y genera una interfaz Env que describe, con precisión, cada capacidad que tu Worker recibió. Tu infraestructura se convierte, literalmente, en tipos.

De wrangler.jsonc a la interfaz Env

El comando no adivina: lee tu wrangler.jsonc, recorre cada binding declarado y escribe un fichero de definiciones —worker-configuration.d.ts por defecto— con una interfaz Env cuyas propiedades son tus bindings, cada uno con el tipo que le corresponde. De paso, incluye los tipos del runtime de Workers según tu compatibility_date, de modo que APIs como Response o KVNamespace estén disponibles sin importar nada.

# lee wrangler.jsonc y (re)genera worker-configuration.d.ts
npx wrangler types

El resultado tiene una forma característica que conviene reconocer. Los bindings se declaran dentro de un namespace Cloudflare, y luego una interfaz Env global la extiende. Esa indirección permite que tanto tu código como las herramientas de la plataforma compartan la misma definición.

// worker-configuration.d.ts (generado, no editar a mano)
declare namespace Cloudflare {
  interface Env {
    MI_KV: KVNamespace;
    DB: D1Database;
    MI_BUCKET: R2Bucket;
    AI: Ai;
    MODO: string;
  }
}
interface Env extends Cloudflare.Env {}

Cada línea es la traducción de una sección del manifiesto: el binding de KV se vuelve un KVNamespace, el de D1 un D1Database, el de R2 un R2Bucket, el de AI un Ai, y la variable MODO una simple string. La correspondencia es exacta y automática: no escribes tú esta interfaz, la deriva la herramienta del manifiesto.

El tipo generado es, además, más fino de lo que sugiere el ejemplo. Un binding a un Durable Object no se tipa como un DurableObjectNamespace a secas, sino parametrizado con tu clase —DurableObjectNamespace de SalaDeChat—, de modo que el stub que obtienes conoce sus métodos. Un service binding hereda los tipos del Worker al que apunta, así que invocar su RPC autocompleta como si fuera código local. Toda esa riqueza sale del manifiesto sin que muevas un dedo.

Tipar el handler y evitar la deriva

Con la interfaz Env disponible, tipas tu Worker contra ella. El patrón canónico usa satisfies ExportedHandler<Env>, que ata la firma de tus handlers a tu entorno real y hace que env conozca cada binding por su nombre y su tipo.

export default {
  async fetch(request, env, ctx): Promise<Response> {
    // env.DB autocompleta y expone prepare; env.DBB no existe: error de compilacion
    const { results } = await env.DB.prepare('SELECT 1').all();
    return Response.json(results);
  },
} satisfies ExportedHandler<Env>;

Para que TypeScript encuentre el fichero generado, inclúyelo en el array types de tu tsconfig.json. A partir de ahí, escribir mal el nombre de un binding, o usar un método que ese recurso no ofrece, deja de ser un fallo silencioso en producción y pasa a ser un error rojo en tu editor.

{
  "compilerOptions": {
    "types": ["./worker-configuration.d.ts"]
  }
}

El riesgo que acecha a este esquema es la deriva: que cambies el manifiesto y olvides regenerar los tipos, dejando que el código crea en un env que ya no coincide con la realidad. Para blindarte, wrangler types ofrece un modo de verificación que falla si los tipos no reflejan el wrangler.jsonc actual. Colócalo en tu integración continua y ningún cambio de bindings pasará sin sus tipos al día.

# en CI: falla si worker-configuration.d.ts esta desactualizado
npx wrangler types --check

Un matiz fino sobre las variables cierra el cuadro. Por defecto, wrangler types las tipa con su valor literal: si MODO vale produccion, su tipo no es un string cualquiera, sino esa cadena exacta, lo que convierte una comparación imposible en un error de compilación. Si tus variables cambian a menudo entre entornos y ese rigor estorba más de lo que ayuda, el flag --strict-vars false las relaja a string.

flowchart LR
CFG[wrangler jsonc con bindings] --> CMD[wrangler types]
CMD --> DTS[worker-configuration d ts con la interfaz Env]
DTS --> HANDLER[satisfies ExportedHandler de Env]
HANDLER --> SAFE[env tipado en tiempo de compilacion]
style CFG fill:#89b4fa,color:#11111b
style SAFE fill:#a6e3a1,color:#11111b

Por qué capacidades y no credenciales

Ahora puedes ver el modelo completo de este nivel en una sola imagen. Una credencial es un secreto que tu código posee y debe custodiar; una capacidad tipada es un objeto que la plataforma te entrega, que no puedes falsificar y que tu compilador conoce por su nombre. La diferencia no es de comodidad, sino de garantías: con capacidades tipadas no hay secreto que filtrar, no hay acceso que no esté declarado y no hay binding que puedas invocar sin que exista de verdad.