Cloudflare Workers Assets: Reemplaza Vercel a $0

Revolución en la arquitectura de Cloudflare: la integración perfecta de Pages y Workers

En el antiguo ecosistema de Cloudflare, la creación de aplicaciones web full-stack (React, Vue, Astro, Svelte) y APIs backend serverless obligaba a elegir entre dos opciones complejas:

1. Cloudflare Pages + Functions: Conveniente para servir archivos estáticos frontend, pero las reglas de enrutamiento quedaban fragmentadas entre el directorio functions/ y archivos comodín _routes.json, lo que dificultaba el procesamiento de middlewares complejos (autenticación, GeoIP).
2. Cloudflare Workers: Ofrecía el potente cómputo edge de V8, pero para publicar assets estáticos (HTML/CSS/JS/WebP) era necesario codificar y almacenar los archivos como texto en KV o implementar un contenedor sobre un bucket de R2.

[Arquitectura dual fragmentada del pasado de Cloudflare]
Frontend (Cloudflare Pages)  <--- Fragmentación _routes.json --->  Backend API (Cloudflare Workers)
         * Gestión de 2 proyectos por separado                      * Imposible servir assets estáticos directamente
         * Ocurren restricciones de middleware edge                 * Requiere implementación de desvío con KV/R2

La función Cloudflare Workers Assets (vinculación assets), presentada a finales de 2024 y elevada a estándar oficial (Standard GA) en 2025/2026, eliminó por completo esta persistente fragmentación.

Ahora, con solo declarar una línea en un único archivo de configuración wrangler.jsonc: "assets": { "directory": "./dist", "binding": "ASSETS" }, su sitio web estático (Vite/Astro/Next.js) y sus APIs serverless edge (Hono.js) funcionan perfectamente integrados en un único entorno de ejecución edge V8 con una latencia menor a 0.1 ms.

En esta guía, cubriremos en detalle desde el mecanismo de integración de Workers Assets hasta la configuración más reciente de wrangler.jsonc, el pipeline de intercepción edge env.ASSETS.fetch(request), autenticación JWT edge, redirecciones por GeoIP y comparativas de migración desde Vercel/Netlify.

Mecanismo clave de Cloudflare Workers Assets

Workers Assets conecta archivos estáticos y scripts dinámicos de Worker en un único pipeline edge.

+-----------------------------------------------------------------------------------+
| Pipeline de streaming híbrido de Cloudflare Workers Assets                        |
+-----------------------------------------------------------------------------------+

[Solicitud HTTP del usuario: https://effidev.dev/dashboard]
                       |
                       v
     [Cloudflare V8 Edge Worker (Entrada en 0.1ms)]
                       |
        +--------------+--------------+
        |                             |
 (A) Lógica de middleware edge     (B) Solicitud de assets estáticos (HTML/CSS/JS)
   - Validación de token JWT          - env.ASSETS.fetch(request)
   - Redirección 301 por GeoIP        - Caché CDN edge de Cloudflare (TTFB < 5ms)
   - Ejecución de API edge /api/v1/*  - Inyección de index.html SPA 404 Fallback
        |                             |
        +--------------+--------------+
                       |
                       v
         [Respuesta intacta retornada al navegador del usuario en 0.1ms]

1. Servicio de archivos estáticos: Si existe un asset estático que coincida con la ruta de URL solicitada (por ejemplo, /assets/app.js, /hero.webp), se sirve de forma ultra rápida enrutándolo directamente en 0 ms a través de la red global de CDN edge de Cloudflare.
2. Intercepción de middleware edge (Edge Interceptor): Los desarrolladores pueden ejecutar cualquier código TypeScript deseado (verificación de autenticación, inyección de cookies para pruebas A/B, reescritura dinámica de HTML) en solo 0.1 ms antes o después de llamar al método env.ASSETS.fetch(request).

Paso 1: Declaración actualizada de Assets en wrangler.jsonc

Declare el directorio de artefactos estáticos y la vinculación ASSETS en el archivo de configuración wrangler.jsonc de su proyecto.

// wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "fullstack-edge-app",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-01",
  "compatibility_flags": ["nodejs_compat"],

  // Declaración de GA Workers Assets 2025/2026
  "assets": {
    "directory": "./dist",       // Ruta de salida del build de Vite / Astro / Next.js
    "binding": "ASSETS",         // Nombre de vinculación para acceder a env.ASSETS en el código del Worker
    "not_found_handling": "single-page-app" // Soporte para enrutamiento SPA (sirve index.html en 404)
  },

  // Vinculaciones adicionales (integración opcional con DB D1, KV, R2)
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "production_db",
      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ]
}

Paso 2: Implementación del interceptor edge Hono.js y router híbrido

Escriba código de producción en src/index.ts que gestione armónicamente el servicio de assets estáticos y el enrutamiento de la API backend.

src/index.ts

// src/index.ts
import { Hono } from "hono";

type Env = {
  Bindings: {
    ASSETS: Fetcher; // Tipo de vinculación para Workers Assets
    DB: D1Database;
  };
};

const app = new Hono<Env>();

// -------------------------------------------------------------------
// 1. Ruta de API backend edge (/api/*)
// -------------------------------------------------------------------
app.get("/api/v1/user/profile", async (c) => {
  const authHeader = c.req.header("authorization");
  if (!authHeader) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  // Consulta a base de datos D1
  const { results } = await c.env.DB.prepare(
    "SELECT id, email, name FROM users WHERE token = ?"
  ).bind(authHeader).all();

  return c.json({ user: results[0] ?? null });
});

// -------------------------------------------------------------------
// 2. Middleware de redirección 301 basado en geolocalización edge (GeoIP)
// -------------------------------------------------------------------
app.use("/landing", async (c, next) => {
  // Extraer código de país de origen del encabezado edge de Cloudflare (KR, US, JP, etc.)
  const country = c.req.header("cf-ipcountry") || "US";

  if (country === "KR" && !c.req.url.includes("/kr")) {
    return c.redirect("/landing/kr", 301);
  }

  await next();
});

// -------------------------------------------------------------------
// 3. Interceptor de verificación de autenticación JWT edge para área protegida (/dashboard/*)
// -------------------------------------------------------------------
app.use("/dashboard/*", async (c, next) => {
  const cookie = c.req.header("cookie") || "";
  const hasAuthToken = cookie.includes("session_token=");

  // Bloquear inmediatamente a usuarios no autenticados redirigiéndolos al login al acceder al HTML estático del panel
  if (!hasAuthToken) {
    return c.redirect("/login", 302);
  }

  await next();
});

// -------------------------------------------------------------------
// 4. Servicio Fallback de assets estáticos (env.ASSETS.fetch)
// -------------------------------------------------------------------
app.all("*", async (c) => {
  // Todas las solicitudes que no coincidan con la ruta /api se canalizan a la vinculación de Assets estáticos
  const response = await c.env.ASSETS.fetch(c.req.raw);

  // Inyección instantánea de encabezados de seguridad en la respuesta si es necesario
  const newHeaders = new Headers(response.headers);
  newHeaders.set("X-Frame-Options", "DENY");
  newHeaders.set("X-Content-Type-Options", "nosniff");
  newHeaders.set("Referrer-Policy", "strict-origin-when-cross-origin");

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: newHeaders,
  });
});

export default app;

Paso 3: Pipeline de compilación y despliegue a producción

Tras generar los artefactos de compilación del frontend (dist), despliegue en cuestión de segundos utilizando la CLI Wrangler de Cloudflare.

Configuración de scripts en package.json

{
  "name": "fullstack-edge-app",
  "private": true,
  "scripts": {
    "build:frontend": "vite build",
    "build": "npm run build:frontend",
    "deploy": "npm run build && wrangler deploy",
    "dev": "wrangler dev"
  }
}

Ejecución del despliegue y verificación de logs

# Ejecutar compilación y despliegue global
npm run deploy

Al ejecutar wrangler deploy, Wrangler CLI sube los archivos estáticos dentro de la carpeta ./dist al almacenamiento edge de Cloudflare, empaquetándolos junto con el script del Worker en una versión de lanzamiento única que se activa en más de 330 centros de datos edge en todo el mundo en cuestión de un segundo.

Comparativa: costos y rendimiento de Vercel/Netlify vs Cloudflare Workers Assets

Métricas de costo y rendimiento al operar la misma aplicación web full-stack (5 millones de visitas mensuales, 20 millones de llamadas a API).

Reporte comparativo de costos y rendimiento por plataforma

Conclusión: el nuevo estándar full-stack serverless

Cloudflare Workers Assets finalmente ha destruido por completo la antigua distinción artificial de “sitios estáticos en Pages, APIs edge en Workers”.

Los beneficios obtenidos con la adopción de Workers Assets (env.ASSETS) son abrumadores:

1. Reducción de costos del 96% frente a Vercel / Netlify: Servicio de archivos estáticos ilimitado sin sorpresas por cargos de transferencia (Egress Fee).
2. Máxima productividad en el desarrollo: Control completo del build frontend y la API backend edge mediante un único archivo wrangler.jsonc.
3. Potente middleware edge: Ejecute validaciones JWT, redirecciones por GeoIP e inyecciones dinámicas en HTML en tan solo 0.1 ms antes o después de env.ASSETS.fetch(request).
4. TTFB global ultra rápido: Carga instantánea del sitio web con una latencia mínima de menos de 5 ms desde más de 330 centros de datos edge globales.

Migre sus proyectos existentes a Cloudflare Workers Assets hoy mismo y experimente una arquitectura edge con costos de $0 y rendimiento de 0.1 ms.

Artículo relacionado: Puede consultar nuestra guía para construir una arquitectura de autenticación edge con Cloudflare Workers + Passkey (WebAuthn) a $0 sin Auth0 ni Clerk.