rodolfo.gg
Go back

Cómo desplegar una aplicación de Svelte+SvelteKit en Cloudflare Workers (free).

CC BY-NC-ND 4.0
Rodolfo González González
de en es fr
Cómo desplegar una aplicación de Svelte+SvelteKit en Cloudflare Workers (free).

Introducción

De acuerdo con Wikipedia:

Cloudflare, Inc. es una empresa estadounidense que proporciona una red de entrega de contenido, servicios de seguridad de Internet y servicios de servidores de nombres de dominio distribuidos, localizados entre el visitante y el proveedor de alojamiento del usuario de Cloudflare, y que actúan como proxy inverso para sitios web.

Workers se basa en un motor de ejecución ligero basado en Node.js (no es Node.js directamente). Es mucho más rápido y práctico que utilizar una FaaS en Aliyun FC o Amazon Lambda para desplegar aplicaciones como este blog hecho en Astro, aunque cada tecnología tiene sus ventajas y desventajas. Una ventaja de Workers es la rapidez de su ejecución. Otra, su costo.

Esta guía muestra cómo desplegar una aplicación de Svelte+SvelteKit en Cloudflare Workers (free).

1) Qué hacer en Cloudflare (dashboard)

  1. Crear/usar una cuenta de Cloudflare (plan Free).
  2. Ir a Desarrollo -> Workers y Pages y habilitar Workers en la cuenta.
  3. (Recomendado) Crear un API Token para deploy desde CLI:
  4. Ir a Administrar cuenta -> Tokens de API de cuenta.
  5. En Account Resources: selecciona tu cuenta.
  6. Crear token
  7. Usa la plantilla Edit Cloudflare Workers (tiene los permisos mínimos necesarios)
  8. Si usarás dominio propio:
  1. Seleccionar los Recursos de zona según las zonas que cubrirá el token.
  2. Haz clic en Continue to summary → Create Token.

  1. Si usarás dominio propio:

    • Tener la zona (tudominio.com) en Cloudflare.
    • En el Worker desplegado: Settings -> Domains & Routes -> Add Custom Domain

  2. El nuevo token se puede probar:

Terminal window
curl "https://api.cloudflare.com/client/v4/accounts/xxx123/tokens/verify" \
-H "Authorization: Bearer cfat_ABCD_my_token"

2) Qué configurar en el proyecto

El proyecto debe estar alineado a Worker puro:

wrangler.toml
  - `main = "build/_worker.js"`
  - `[assets] directory = "build", binding = "ASSETS"`

Si no tienes el account_id, agrégalo:

wrangler.toml
account_id = "tu_account_id"

El account_id lo encuentras en el dashboard de Cloudflare, en la barra lateral derecha de tu dominio, o con:

bunx wrangler whoami

Es, por supuesto, muy importante usar el adapter-cloudflare:

svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';

Requisitos locales

  1. Dependencias:
  1. Configurar el token en tu entorno local
Terminal window
export CLOUDFLARE_API_TOKEN=cfat_ABCD_my_token

O de forma permanente en ~/.bashrc, ~/.zshrc o el archivo adecuado para tu shell:

Terminal window
echo 'export CLOUDFLARE_API_TOKEN=tu_token_aqui' >> ~/.bashrc

Alternativamente con wrangler:

Terminal window
bunx wrangler login

Esto abre un navegador para OAuth. Personalmente no me gusta.

Si prefieres token directo:

Terminal window
bunx wrangler config

3) Variables y secretos (importante)

En tu app actual

Si se usa import.meta.env.VITE_* (build-time), eso significa que:

Ejemplos críticos podrían ser:

Secretos runtime (opcional)

Si luego quieres agregar secretos en runtime:

Terminal window
bunx wrangler secret put NOMBRE_VARIABLE

y leerlos desde env.NOMBRE_VARIABLE.

4) Build + deploy (paso a paso)

En los siguientes pasos puedes reemplazar npm por bun en los comandos:

  1. Instalar dependencias:
Terminal window
npm ci
  1. Configurar token:
Terminal window
export CLOUDFLARE_API_TOKEN=tu_token

  1. Preparar .env de build (con tus VITE_* correctas).

  2. Build:

Terminal window
make build
# npm run build
# bun run build
  1. Verificar salida:
  1. Probar localmente el Worker:
Terminal window
make preview
# bunx wrangler dev
  1. Deploy:
Terminal window
make deploy
# bunx wrangler deploy
  1. Probar el Worker, que quedará en:

https://example-frontend.tu-subdominio.workers.dev

o en tu dominio personalizado si lo configuras en el dashboard.

5) Configuración OIDC (Zitadel o algún otro proveedor) para producción

En caso de utilizar algún proveedor de OIDC como Zitadel, debes registrar en el proveedor los endpoints requeridos:

  1. Redirect URI(s) (callback login).
  2. Post-logout redirect URI(s).
  3. Web origins del frontend.

6) Verificaciones post-deploy

Para ver logs:

Terminal window
npx wrangler tail

7) Límites de Workers Free que debes considerar (revisados el 7 de abril de 2026)

Si excedes estos límites, tendrás errores tipo 1027/cuotas.

8) Errores típicos

  1. Cannot read properties of undefined (reading 'fetch')
  1. Variables VITE_* vacías en producción
  1. Login Zitadel falla en prod

9) Deploy en dominio propio

Hay 2 formas de hacerlo, asumiendo que el dominio se encuentra en Cloudflare:

A. Usando wrangler.toml

Configurar las rutas:

routes = [
  { pattern = "www.example.com/*", zone_name = "example.com" }
]

Y luego hacer el deploy normal:

Terminal window
bunx wrangler deploy

B. En el dashboard de Cloudflare

  1. Ve a Workers & Pages → tu worker → Settings → Triggers
  2. Clic en Add Custom Domain
  3. Escribe www.example.com
  4. Cloudflare crea automáticamente el registro DNS y el certificado TLS

Dominio fuera de Cloudflare

Si el dominio no está en Cloudflare:

Primero debes agregar el dominio a Cloudflare (o al menos usar un registro DNS externo):

En el DNS de tu registrador, crea un registro CNAME:

En tinydns, por ejemplo:

Terminal window
Cwww:tu-proyecto.tu-subdominio.workers.dev:86400

Luego en Cloudflare, ve al worker y en Triggers clic en Add Custom Domain y agrega www.example.com.

Diferencia entre routes y custom_domain

Característicaroutescustom_domain
Requiere zona en CFSíSí
Configurable en tomlSíSí
TLS automáticoManual (ya existente)Automático
Comparte con otros workersSí (por patrón)No

Para un subdominio dedicado al worker, custom_domain es la opción más limpia:

wrangler.toml
routes = [
  { pattern = "ssr.example.com/*", custom_domain = true, zone_name = "example.com" }
]

O la sintaxis alternativa:

[[env.production.routes]]
pattern = "ssr.example.com/*"
zone_name = "example.com"

Bonus: Reglas de Makefile útiles

deploy:
  bunx wrangler deploy


preview:
  bunx wrangler dev


build:
  @echo "Building with $(DOTENV_FILE)"
  DOTENV_FILE=$(DOTENV_FILE) bun run build

Fuentes oficiales usadas

Share this post on:
Share this post via WhatsApp Share this post on Facebook Share this post on X Share this post via Telegram Share this post on Pinterest Share this post via email
Previous Post
Cómo instalar caveman en Visual Studio Code para Claude Code.
Next Post
Cómo obtener tokens de autorización en HuggingFace.