Wrangler CLI v4

Referencia completa para Cloudflare Workers · DataPulse Analytics

Wrangler v4.x TypeScript + Hono datapulse-api · prod
Proyecto
datapulse-api
Compatibility date
2026-01-01
Bindings activos
D1 · KV · R2 · AI · Queues · Vectorize · Workflows
Environments
staging · production
Stack
Workers + Hono + Vitest
⚙️
wrangler.jsonc — Configuración completa de DataPulse API
Todos los bindings del proyecto en un único archivo de configuración JSON
wrangler.jsonc
{
  // Configuración DataPulse Analytics — API serverless edge
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "datapulse-api",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "compatibility_flags": ["nodejs_compat"],

  // Variables de entorno no sensibles
  "vars": {
    "ENVIRONMENT": "production",
    "APP_VERSION": "2.4.1",
    "LOG_LEVEL": "info"
  },

  // KV: caché de configuraciones por tenant
  "kv_namespaces": [
    { "binding": "TENANT_CONFIG", "id": "a1b2c3d4e5f6789012345678901234ab" }
  ],

  // R2: exportaciones CSV/JSON de reportes
  "r2_buckets": [
    { "binding": "REPORTS_BUCKET", "bucket_name": "datapulse-reports" }
  ],

  // D1: métricas agregadas SQLite en el edge
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "datapulse-metrics",
      "database_id": "f7a9b1c2-d3e4-5f60-a7b8-c9d0e1f23456",
      "migrations_dir": "./migrations"
    }
  ],

  // Workers AI: resumen automático de tendencias (siempre remoto)
  "ai": { "binding": "AI" },

  // Vectorize: búsqueda semántica sobre histórico de productos
  "vectorize": [
    { "binding": "PRODUCT_SEARCH", "index_name": "datapulse-products" }
  ],

  // Queues: procesamiento asíncrono de eventos
  "queues": {
    "producers": [
      { "binding": "EVENT_QUEUE", "queue": "datapulse-events" }
    ],
    "consumers": [
      { "queue": "datapulse-events", "max_batch_size": 50, "max_batch_timeout": 10 }
    ]
  },

  // Workflows: pipeline de reportes mensuales
  "workflows": [
    {
      "binding": "REPORT_PIPELINE",
      "name": "monthly-reports",
      "class_name": "MonthlyReportWorkflow"
    }
  ],

  // Cron: generar reportes el 1 de cada mes a las 03:00 UTC
  "triggers": {
    "crons": ["0 3 1 * *"]
  },

  // Observabilidad
  "observability": { "enabled": true, "head_sampling_rate": 1 },

  // Environments: staging hereda todo, sobreescribe name y vars
  "env": {
    "staging": {
      "name": "datapulse-api-staging",
      "vars": { "ENVIRONMENT": "staging", "LOG_LEVEL": "debug" }
    }
  }
}
📦
Recursos Cloudflare — DataPulse Stack
Todos los bindings y sus nombres de variable en el Worker
🗂️
KV Store
TENANT_CONFIG
🪣
R2 Bucket
REPORTS_BUCKET
🗃️
D1 Database
DB
🤖
Workers AI
AI
🔍
Vectorize
PRODUCT_SEARCH
📨
Queues
EVENT_QUEUE
⚙️
Workflows
REPORT_PIPELINE
🔐
Secrets
STRIPE_KEY
🚀 Core Commands
🚀
Comandos esenciales
Dev · Deploy · Types · Logs · Rollback
DEV wrangler dev
DEV wrangler dev --env staging
DEV wrangler dev --test-scheduled
DEPLOY wrangler deploy
DEPLOY wrangler deploy --env staging
DRY wrangler deploy --dry-run
TYPES wrangler types
HEALTH wrangler check startup
LOGS wrangler tail --status error
AUTH wrangler whoami
ROLLBACK wrangler rollback
🔄
Pipeline de despliegue
Flujo recomendado para DataPulse: dev → staging → prod
1 · Local
Develop & test
wrangler dev
2 · Migraciones
Aplicar a staging
wrangler d1 migrations apply datapulse-metrics --remote --env staging
3 · Deploy staging
Validar en edge
wrangler deploy --env staging
4 · Dry run prod
Verificar sin impacto
wrangler deploy --dry-run
5 · Producción
Deploy final
wrangler deploy
📦 Gestión de Recursos
🗂️
KV — Tenant Config Cache
Namespace: TENANT_CONFIG
Setup
CREATE wrangler kv namespace create TENANT_CONFIG
LIST wrangler kv namespace list
Operaciones
PUT wrangler kv key put --namespace-id <ID> "tenant:abc123" '{"plan":"pro"}'
GET wrangler kv key get --namespace-id <ID> "tenant:abc123"
BULK wrangler kv bulk put --namespace-id <ID> tenants.json
LIST wrangler kv key list --namespace-id <ID>
DEL wrangler kv key delete --namespace-id <ID> "tenant:abc123"
🪣
R2 — Reports Bucket
Bucket: datapulse-reports · Binding: REPORTS_BUCKET
Setup
CREATE wrangler r2 bucket create datapulse-reports --location wnam
INFO wrangler r2 bucket info datapulse-reports
Objetos
PUT wrangler r2 object put datapulse-reports/2026/06/report.csv --file ./report.csv
GET wrangler r2 object get datapulse-reports/2026/06/report.csv
DEL wrangler r2 object delete datapulse-reports/2026/06/report.csv
🗃️
D1 — Métricas SQL en el edge
DB: datapulse-metrics · Binding: DB · Migrations: ./migrations/
Setup
CREATE wrangler d1 create datapulse-metrics --location wnam
INFO wrangler d1 info datapulse-metrics
Migraciones
CREATE wrangler d1 migrations create datapulse-metrics create_events_table
LOCAL wrangler d1 migrations apply datapulse-metrics --local
REMOTE wrangler d1 migrations apply datapulse-metrics --remote
LIST wrangler d1 migrations list datapulse-metrics --local
SQL directo
QUERY wrangler d1 execute datapulse-metrics --remote --command "SELECT COUNT(*) FROM events WHERE tenant_id='abc'"
BACKUP wrangler d1 export datapulse-metrics --remote --output backup-2026-06.sql
🤖
Workers AI + Vectorize
AI: binding AI · Vectorize: datapulse-products (768 dims, cosine)
Workers AI
MODELS wrangler ai models
FINETUNES wrangler ai finetune list
Vectorize: Índice de productos
CREATE wrangler vectorize create datapulse-products --preset @cf/baai/bge-base-en-v1.5
INFO wrangler vectorize get datapulse-products
INSERT wrangler vectorize insert datapulse-products --file products.ndjson
QUERY wrangler vectorize query datapulse-products --vector "[0.12, 0.45, ...]" --top-k 5
📨
Queues + Workflows
Queue: datapulse-events · Workflow: monthly-reports
Queues
CREATE wrangler queues create datapulse-events
LIST wrangler queues list
CONSUMER wrangler queues consumer add datapulse-events datapulse-api
Workflows
LIST wrangler workflows list
TRIGGER wrangler workflows trigger monthly-reports --params '{"month":"2026-05"}'
DESCRIBE wrangler workflows describe monthly-reports
INSTANCES wrangler workflows instances list monthly-reports
🔐
Secrets — Gestión segura
STRIPE_KEY · ANALYTICS_TOKEN · WEBHOOK_SECRET
PUT wrangler secret put STRIPE_KEY
PUT wrangler secret put ANALYTICS_TOKEN
BULK wrangler secret bulk secrets.json
LIST wrangler secret list
DELETE wrangler secret delete STRIPE_KEY
# .dev.vars (local secrets — NUNCA en git)
STRIPE_KEY=sk_test_localdev
ANALYTICS_TOKEN=token-dev-123
WEBHOOK_SECRET=whsec_localdev
🌍
Environments — Staging vs Production
Variables que difieren entre entornos en DataPulse
⚠️ Staging
namedatapulse-api-staging
ENVIRONMENTstaging
LOG_LEVELdebug
wrangler deploy --env staging
✅ Production
namedatapulse-api
ENVIRONMENTproduction
LOG_LEVELinfo
wrangler deploy
🔒 Seguridad
🔒
Reglas de seguridad para secrets y credenciales
Obligatorias en todos los proyectos CULTIVA · DataPulse
🚫
NUNCA pasar secrets como argumento CLI Evitar wrangler secret put API_KEY myvalue123 — el valor queda en el historial del shell. Usar siempre el prompt interactivo o redirección desde fichero.
🚫
NUNCA usar echo para pasar secrets Prohibido echo "sk_live_xxx" | wrangler secret put STRIPE_KEY. Usar wrangler secret put STRIPE_KEY < secrets/stripe.txt o el prompt.
⚠️
.dev.vars nunca debe estar en git Añadir .dev.vars al .gitignore. Este archivo contiene credenciales locales de desarrollo.
⚠️
secrets.json (bulk) no debe comitearse El archivo usado con wrangler secret bulk secrets.json contiene valores en claro. Añadirlo a .gitignore o generarlo dinámicamente en CI con variables de entorno seguras.
Forma correcta: prompt interactivo (preferred) wrangler secret put STRIPE_KEY → Wrangler pide el valor de forma segura en el terminal, sin dejarlo en logs ni historial.
En CI/CD: usar variables de entorno del pipeline Configurar secrets en GitHub Actions como secrets.STRIPE_KEY y pasar con echo "$STRIPE_KEY" | wrangler secret put STRIPE_KEY — nunca hardcodear.
🔧
Resolución de problemas frecuentes
Errores comunes en el desarrollo con Wrangler v4
Error / Síntoma Solución
command not found: wrangler Instalar localmente: npm install -D wrangler@latest y ejecutar con npx wrangler
Authentication error / 401 Ejecutar wrangler login para autenticar vía browser OAuth
Worker startup time exceeded Perfilar con wrangler check startup; eliminar imports pesados del top-level
Type errors tras cambiar config Regenerar tipos: wrangler types; añadir al paso de build en CI
Binding undefined en Worker Verificar que el nombre en código coincide exactamente con "binding" en wrangler.jsonc
Local storage no persiste entre reinicios Revisar directorio .wrangler/state/; no borrar si necesitas persistencia local
D1: migration already applied Listar con wrangler d1 migrations list datapulse-metrics --local para ver estado actual
Workers AI: no responde en local dev Workers AI siempre es remoto. Añadir "remote": true al binding AI en wrangler.jsonc
Best Practices — DataPulse Wrangler Setup
Aplicadas al proyecto según las directrices oficiales de Cloudflare
1
Usar wrangler.jsonc, no TOMLPreferir JSON con comentarios. Nuevas funciones (Workflows, Containers) son JSON-only. TOML quedará deprecated.
2
Actualizar compatibility_date trimestralFijar fecha dentro de los últimos 30 días para acceder a runtime features nuevas. Revisar breaking changes en la docs.
3
wrangler types en cada PRAñadir wrangler types --check al CI para detectar desincronización entre config y código TypeScript.
4
Environments staging/productionNunca desplegar directamente a producción sin pasar por staging. Usar --env staging en el primer deploy.
5
--dry-run antes de cambios críticosEspecialmente ante cambios de bindings o migraciones D1. Validar sin impacto real antes del deploy.
6
Local dev con bindings simuladosPor defecto, dev usa almacenamiento local. Solo usar remote: true para AI, Vectorize o cuando se necesiten datos reales.
7
Secrets: nunca en argumentos CLIUsar siempre prompt interactivo o redirección desde fichero. Secretos en argumentos CLI quedan expuestos en logs y shell history.
8
wrangler check startup regularmenteCloudflare tiene límite de startup time. Perfilar periódicamente, sobre todo al añadir dependencias npm nuevas.