Crear un proyecto con C3

Todo Worker empieza con un problema banal y tozudo: la página en blanco. Qué archivos necesito, cómo se llama la config, qué versión de wrangler instalo, cómo declaro el primer binding. Cloudflare resuelve esa fricción con create-cloudflare —C3 para los amigos—, un andamiador que no solo copia plantillas: materializa en archivos la opinión de la plataforma sobre cómo debe verse un proyecto del edge. Entender qué hace C3 en cada fase es entender, de paso, el esqueleto que vas a habitar el resto del track.

npm create cloudflare: qué es C3

El comando npm create cloudflare@latest parece magia, pero obedece a una convención vieja de npm: npm create foo es azúcar sintáctico para descargar y ejecutar el paquete create-foo. Aquí ese paquete es create-cloudflare, y por eso el mismo andamiaje existe en todos los gestores: pnpm create cloudflare@latest, yarn create cloudflare o bun create cloudflare. El sufijo @latest no es decorativo: C3 evoluciona rápido siguiendo a la plataforma, y anclar a la última versión evita reproducir un esqueleto obsoleto.

# la forma interactiva: C3 te pregunta nombre, plantilla y lenguaje
npm create cloudflare@latest

# equivalente con otros gestores
pnpm create cloudflare@latest
bun create cloudflare@latest

C3 no es un mero copiador de archivos. Encadena varias fases: recoge tus respuestas, escribe el andamiaje, instala las dependencias con tu gestor, inicializa un repositorio git con un primer commit y, al final, te ofrece desplegar. Cada fase es un paso que tendrías que dar a mano; C3 los orquesta con las decisiones por defecto que Cloudflare considera correctas en 2026.

flowchart LR
A[npm create cloudflare] --> B[Elegir plantilla y lenguaje]
B --> C[Escribir el andamiaje]
C --> D[Instalar dependencias]
D --> E[Iniciar git y primer commit]
E --> F[Desplegar opcional]

La fase final —desplegar— es opcional y te pide autenticarte con wrangler login si aún no lo hiciste; puedes declinarla y publicar más tarde. Ese “más tarde” es lo normal cuando aún no tienes cuenta o quieres tocar el código antes de que nadie lo vea.

Las plantillas: del Worker mínimo al framework

C3 agrupa sus plantillas en categorías, y la elección determina radicalmente el resultado. La plantilla Hello World genera un Worker desnudo: un fetch handler y poco más, ideal para aprender. Las plantillas de framework (Astro, Next, Remix, SvelteKit, TanStack) no las escribe C3 por su cuenta: delega en la herramienta de andamiaje del propio framework y luego cablea el adaptador de Cloudflare y wrangler encima. Las plantillas de aplicación parten de casos con bindings ya conectados —una cola, un Durable Object, una API con D1—.

Puedes evitar el diálogo interactivo pasando las respuestas como flags. Todo lo que va tras -- se reenvía a C3 sin que npm lo interprete como propio:

# no interactivo: nombre, framework y lenguaje de una sola vez
npm create cloudflare@latest -- mi-app --framework=astro --lang=ts

# un Worker mínimo en TypeScript, sin desplegar al terminar
npm create cloudflare@latest -- mi-worker --type=hello-world --deploy=false

# arrancar desde un repositorio de GitHub como plantilla
npm create cloudflare@latest -- mi-app --template=cloudflare/templates/worker-typescript

La estructura resultante

Un Worker mínimo en TypeScript deja un árbol pequeño y legible. Nada sobra, y cada archivo responde a una pregunta distinta de la cadena de herramientas:

mi-worker/
├── src/
│   └── index.ts            # el Worker: el fetch handler
├── test/
│   └── index.spec.ts       # pruebas con vitest sobre workerd
├── package.json            # scripts y wrangler como devDependency
├── tsconfig.json           # config de TypeScript
├── vitest.config.mts       # el pool de vitest para Workers
├── worker-configuration.d.ts   # tipos generados por wrangler types
└── wrangler.jsonc          # el manifiesto del Worker

El corazón es src/index.ts, y su forma revela el modelo mental de la plataforma: un objeto con handlers, exportado por defecto, tipado contra tu propio entorno.

export default {
	async fetch(request, env, ctx): Promise<Response> {
		return new Response('Hello World!');
	},
} satisfies ExportedHandler<Env>;

Ese satisfies ExportedHandler<Env> merece una pausa: Env no es un tipo que escribas tú, sino uno que wrangler types genera a partir de tus bindings declarados en wrangler.jsonc y deja en worker-configuration.d.ts. Tu infraestructura se convierte en tipos de TypeScript. El package.json cierra el círculo: incluye wrangler como dependencia de desarrollo y un puñado de scripts que estabilizan el vocabulario del proyecto.

{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "cf-typegen": "wrangler types"
  }
}

El resto del árbol es andamiaje de calidad, silencioso pero deliberado. tsconfig.json fija una configuración de TypeScript coherente con el runtime del edge, y la carpeta test/ trae vitest ya cableado con el pool de Workers: tus pruebas no corren en Node, sino dentro de workerd, el mismo runtime que ejecutará el Worker en producción. Es la idea de fidelidad que atraviesa todo el ecosistema llevada hasta los tests —validar el código en una aproximación sería volver a abrir la grieta que la plataforma se esfuerza por cerrar—.