wrangler.jsonc — Configuración completa de DataPulse API
Todos los bindings del proyecto en un único archivo de configuración JSON
{ // 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
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.