Cloudflare Deployment Patterns

# Build local
pnpm build

# Deploy direct
wrangler pages deploy ./dist --project-name=my-app

wrangler.toml pour Pages

name = "my-app"
compatibility_date = "2025-01-01"
pages_build_output_dir = "./dist"

[vars]
API_URL = "https://api.example.com"

[[d1_databases]]
binding = "DB"
database_name = "my-app-db"
database_id = "<d1-id>"

[[kv_namespaces]]
binding = "SESSIONS"
id = "<kv-id>"

[[r2_buckets]]
binding = "MEDIA"
bucket_name = "my-app-media"

3. Workers (compute edge)

wrangler.toml pour un Worker

name = "my-api"
main = "src/index.ts"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]

[vars]
ENV = "production"

[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "<d1-id>"

[[r2_buckets]]
binding = "UPLOADS"
bucket_name = "my-uploads"

Worker minimal avec bindings

// src/index.ts
export interface Env {
  DB: D1Database
  UPLOADS: R2Bucket
  SESSIONS: KVNamespace
  ENV: string
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url)

    if (url.pathname === '/api/posts') {
      const { results } = await env.DB.prepare('SELECT * FROM posts LIMIT 10').all()
      return Response.json(results)
    }

    if (url.pathname.startsWith('/upload/')) {
      const key = url.pathname.replace('/upload/', '')
      const file = await env.UPLOADS.get(key)
      if (!file) return new Response('Not found', { status: 404 })
      return new Response(file.body, {
        headers: { 'Content-Type': file.httpMetadata?.contentType ?? 'application/octet-stream' },
      })
    }

    return new Response('Hello from edge')
  },
}

4. R2 (object storage)

// Upload
await env.UPLOADS.put('avatars/user-123.jpg', request.body, {
  httpMetadata: { contentType: 'image/jpeg' },
  customMetadata: { userId: '123' },
})

// Read
const object = await env.UPLOADS.get('avatars/user-123.jpg')
if (!object) return new Response('Not found', { status: 404 })

// List
const list = await env.UPLOADS.list({ prefix: 'avatars/', limit: 100 })

R2 vs S3 : API compatible, mais R2 a zéro egress fee (grosse économie vs AWS S3 sur les apps à fort download).

5. D1 (SQLite edge)

// Créer une DB
wrangler d1 create my-app-db

// Migrer
wrangler d1 migrations create my-app-db init
wrangler d1 migrations apply my-app-db

// Query depuis un Worker
const { results } = await env.DB
  .prepare('SELECT * FROM users WHERE email = ?')
  .bind('[email protected]')
  .all()

// Write
await env.DB
  .prepare('INSERT INTO users (email, name) VALUES (?, ?)')
  .bind('[email protected]', 'Jane')
  .run()

// Batch
await env.DB.batch([
  env.DB.prepare('INSERT INTO logs VALUES (?)').bind('event1'),
  env.DB.prepare('INSERT INTO logs VALUES (?)').bind('event2'),
])

Limites D1 actuelles : 10 GB par DB, 1000 writes/s pour un même row-key. Pour plus, utiliser Hyperdrive vers Postgres externe.

6. KV (key-value)

// Set avec TTL
await env.SESSIONS.put('session:abc123', JSON.stringify(data), {
  expirationTtl: 3600, // 1 heure
})

// Get
const raw = await env.SESSIONS.get('session:abc123')
const data = raw ? JSON.parse(raw) : null

// Delete
await env.SESSIONS.delete('session:abc123')

// List
const { keys } = await env.SESSIONS.list({ prefix: 'session:' })

KV est eventually consistent (propagation globale en ~60s). Pour du strict consistency, utiliser Durable Objects.

7. Durable Objects (stateful edge)

// src/chat-room.ts
export class ChatRoom {
  state: DurableObjectState
  sessions: WebSocket[] = []

  constructor(state: DurableObjectState) {
    this.state = state
  }

  async fetch(request: Request) {
    if (request.headers.get('Upgrade') === 'websocket') {
      const [client, server] = Object.values(new WebSocketPair())
      this.handleSession(server)
      return new Response(null, { status: 101, webSocket: client })
    }
    return new Response('WebSocket only', { status: 426 })
  }

  handleSession(ws: WebSocket) {
    ws.accept()
    this.sessions.push(ws)
    ws.addEventListener('message', (event) => {
      this.sessions.forEach((s) => s.send(event.data))
    })
  }
}

// wrangler.toml
[[durable_objects.bindings]]
name = "CHAT_ROOM"
class_name = "ChatRoom"

Durable Objects = single-instance stateful compute pour chat rooms, game lobbies, collaborative editors, rate limiters.

8. Queues

// Producer
await env.MY_QUEUE.send({ type: 'send_email', userId: 123 })

// Consumer (autre Worker)
export default {
  async queue(batch: MessageBatch, env: Env) {
    for (const msg of batch.messages) {
      try {
        await processMessage(msg.body)
        msg.ack()
      } catch (err) {
        msg.retry()
      }
    }
  },
}

9. Cron Triggers

[triggers]
crons = ["0 9 * * *", "*/15 * * * *"]

export default {
  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    if (event.cron === '0 9 * * *') {
      await sendDailyDigest(env)
    }
  },
}

10. Workers AI (inference on-edge)

const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [
    { role: 'user', content: 'Summarize: ...' },
  ],
})

return Response.json(response)

Catalogue : https://developers.cloudflare.com/workers-ai/models/

11. Secrets

wrangler secret put STRIPE_SECRET_KEY
# Paste value

wrangler secret list
wrangler secret delete OLD_KEY

Secrets sont chiffrés, jamais en clair dans les logs.

Anti-patterns

1. Drivers SQL natifs (pg, mysql2) dans un Worker → cassent, utiliser D1 ou Hyperdrive
2. fs, path, crypto Node sans nodejs_compat → erreurs runtime
3. Gros bundles (> 1 MB) → Workers limitent le bundle size, optimiser avec tree-shaking
4. R2 public sans CORS → bloque les lectures depuis un autre domain
5. KV en source of truth → KV est eventually consistent, utiliser D1 ou DO pour la strong consistency
6. Cron longs (> 30s) → timeout, passer par Queues
7. Durable Objects sans raison → chaque DO = coût + complexité, utiliser uniquement pour du stateful nécessaire

Checklist deploy Cloudflare

• wrangler.toml committé
• Bindings déclarés (D1 / KV / R2 / DO / Queues)
• Secrets via wrangler secret put
• Custom domain configuré dans le dashboard
• Migrations D1 versionnées et appliquées
• CORS configurés sur R2 si accès public
• Rate limiting via Cloudflare Waiting Room ou Worker custom
• Monitoring via Workers Analytics + Logpush si besoin

Quand déléguer

• Deploy Vercel-native → deploy-vercel
• Backend lourd Docker → deploy-fly
• PostgreSQL full → deploy-railway
• Mobile deployment → deploy-eas, deploy-app-store, deploy-play-store

Ressources

• https://developers.cloudflare.com/workers/
• https://developers.cloudflare.com/pages/
• https://developers.cloudflare.com/r2/
• https://developers.cloudflare.com/d1/
• https://developers.cloudflare.com/workers-ai/