Développement Web

Cloudflare Workers : tutoriel edge compute 2026

11 min de lecture

Les Cloudflare Workers permettent d’exécuter du code JavaScript ou Wasm à l’edge, à chaque requête, sans gérer de serveur. 100 000 requêtes/jour gratuit. Cas d’usage : redirections intelligentes, A/B testing, transformations de réponse, géo-routing, edge auth.

Voir notre guide Cloudflare.

Premier Worker

# Installer wrangler CLI
npm install -g wrangler
wrangler login

# Créer un projet
wrangler init mon-worker
cd mon-worker
// src/index.ts
export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    
    // Géo-routing simple
    const country = request.headers.get("CF-IPCountry") ?? "XX";
    if (country === "SN" || country === "CI") {
      url.hostname = "afrique.exemple.sn";
      return Response.redirect(url.toString(), 302);
    }
    
    return fetch(request);
  },
};
# Tester
wrangler dev

# Déployer
wrangler deploy

Cas d’usage : A/B testing

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const cookie = request.headers.get("Cookie") ?? "";
    let variant = cookie.match(/ab_variant=(\w)/)?.[1];

    if (!variant) {
      variant = Math.random() < 0.5 ? "A" : "B";
    }

    // Modifier l'URL selon variant
    if (variant === "B") {
      url.pathname = "/v2" + url.pathname;
    }

    const response = await fetch(url.toString());
    const newResponse = new Response(response.body, response);
    newResponse.headers.append("Set-Cookie", `ab_variant=${variant}; Path=/; Max-Age=2592000`);
    return newResponse;
  },
};

Cas d’usage : transform response

export default {
  async fetch(request: Request): Promise<Response> {
    const response = await fetch(request);
    
    return new HTMLRewriter()
      .on("a[href*='old-domain.com']", {
        element(el) {
          const href = el.getAttribute("href");
          if (href) el.setAttribute("href", href.replace("old-domain.com", "new-domain.sn"));
        },
      })
      .transform(response);
  },
};

Limites Free

  • 100 000 requêtes/jour
  • 10 ms CPU par requête (largement suffisant pour transformations légères)
  • 1 Mo bundle taille
  • Plan Paid : 5 USD/mois pour 10M requêtes + 50 ms CPU

Pour explorer plus loin

Cloudflare Workers : pourquoi l’edge change la donne

Cloudflare Workers exécute votre code JavaScript ou TypeScript dans plus de 330 datacenters mondiaux, dont Dakar (DKR) et Lagos (LOS). Au lieu d’un serveur unique à Paris ou Frankfurt avec 70 ms de latence pour vos utilisateurs sénégalais, le code répond depuis un PoP local en 5 à 15 ms. La technologie sous-jacente n’est pas Docker : ce sont des V8 isolates, des sandboxes JavaScript ultralégères qui démarrent en moins de 5 ms à froid.

Pour un dev à Abidjan ou Cotonou, le free tier généreux (100 000 requêtes par jour) permet de prototyper sans carte bancaire. Le palier payant à 5 USD/mois ≈ 3 280 FCFA débloque 10 millions de requêtes incluses.

Étape 1 : installer Wrangler et créer un compte

Wrangler est le CLI officiel pour développer, tester et déployer des Workers. Il s’installe via npm et requiert Node 20 ou plus récent.

npm install -g wrangler@latest
wrangler --version
wrangler login

Sortie de référence : un onglet navigateur s’ouvre pour OAuth Cloudflare. Une fois autorisé, le terminal affiche Successfully logged in. Le token est stocké dans ~/.config/.wrangler/config/default.toml.

Étape 2 : initialiser un projet Worker minimal

La commande wrangler init génère un squelette TypeScript ou JavaScript prêt à déployer. Choisissez TypeScript pour bénéficier de l’autocomplétion sur les bindings Cloudflare.

npm create cloudflare@latest hello-edge
# Choisir : Hello World example, TypeScript, Yes au git
cd hello-edge
ls src/

Ce que vous devez voir : un fichier src/index.ts contenant un handler fetch qui répond « Hello World ». Le wrangler.toml définit le nom du Worker, la compatibilité date (très important pour reproduire les builds) et les variables d’environnement.

Étape 3 : tester localement avec Miniflare

Wrangler intègre Miniflare, un émulateur Workers qui tourne en local sur Node. Vous testez sans déployer ni consommer le free tier.

cd hello-edge
npx wrangler dev
# Ouvre http://localhost:8787

Résultat attendu : un message Ready on http://localhost:8787. Modifiez src/index.ts, le rechargement à chaud actualise le Worker en moins de 200 ms. Idéal pour itérer rapidement sans pousser à chaque test.

Étape 4 : écrire un handler Request/Response

L’API Workers suit le standard Web Fetch (Request, Response, fetch). Si vous connaissez le Service Worker du navigateur, vous êtes en terrain connu. Pas de Express, pas de Koa : la plateforme expose directement les primitives Web.

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname === '/api/hello') {
      return Response.json({ message: 'Bonjour Dakar', cf: request.cf });
    }
    return new Response('Not Found', { status: 404 });
  }
};

Vous devriez obtenir en local : curl http://localhost:8787/api/hello renvoie un JSON contenant le pays, la ville et le PoP Cloudflare détectés. Le champ cf est ajouté automatiquement par la plateforme et ne fonctionne que sur le edge réel.

Étape 5 : déployer en production

Le déploiement est instantané : Cloudflare propage votre code sur les 330+ PoPs en moins de 30 secondes. Aucune build d’image, aucun container.

wrangler deploy
# Output: Published hello-edge to https://hello-edge.<votre-sous-domaine>.workers.dev

Sortie de référence : une URL workers.dev immédiatement disponible. Pour brancher un domaine personnalisé itskillscenter.io, ajoutez une route dans wrangler.toml et un enregistrement DNS proxifié orange dans le dashboard Cloudflare.

Étape 6 : utiliser KV pour un cache global

Cloudflare KV est un store clé-valeur répliqué globalement, idéal pour configurations, sessions ou cache. Lectures sub-milliseconde depuis le PoP local, écritures éventuellement cohérentes en 60 secondes.

wrangler kv namespace create CACHE
# Output : id et binding à coller dans wrangler.toml

# Dans src/index.ts
const cached = await env.CACHE.get('user:42');
if (cached) return new Response(cached);
const fresh = await fetchFromOrigin();
await env.CACHE.put('user:42', fresh, { expirationTtl: 3600 });
return new Response(fresh);

Sortie attendue : la première requête prend 200 ms (origin), les suivantes 5 ms (KV cache). Le binding env.CACHE est typé automatiquement si vous utilisez TypeScript avec wrangler types.

Étape 7 : router avec Hono

Pour des APIs avec plusieurs endpoints, Hono est le framework léger recommandé sur Workers. 14 ko gzipped, pas de dépendances Node, démarrage à froid négligeable.

npm install hono

// src/index.ts
import { Hono } from 'hono';
const app = new Hono();
app.get('/', (c) => c.text('Welcome'));
app.get('/users/:id', (c) => c.json({ id: c.req.param('id') }));
app.post('/users', async (c) => {
  const body = await c.req.json();
  return c.json(body, 201);
});
export default app;

Sortie de référence : routes opérationnelles avec parsing JSON automatique et middleware compatible. Hono inclut aussi un middleware cors() et jwt() qui couvrent 90 % des besoins API edge.

Étape 8 : sécuriser avec un secret et limiter le rate

Stockez les clés API et tokens dans les secrets Wrangler, jamais dans le code commité. Pour limiter le débit, utilisez la nouvelle API Rate Limiting de Cloudflare disponible directement dans Workers.

wrangler secret put OPENAI_API_KEY
# Saisir la valeur en stdin

// src/index.ts
const ratelimit = await env.RL.limit({ key: ip });
if (!ratelimit.success) return new Response('Too many', { status: 429 });

Résultat type : un secret stocké chiffré au repos, accessible via env.OPENAI_API_KEY à l’exécution. Le rate limiting réjette les abus avant qu’ils consomment vos quotas Workers ou vos credits OpenAI.

Étape 9 : observer et débugger en production

Wrangler tail diffuse les logs en temps réel depuis le edge. Utile pour traquer une erreur intermittente sur un PoP particulier.

wrangler tail --format pretty
# Filtrer par status :
wrangler tail --status error

Résultat type : chaque requête s’affiche avec son URL, son statut, et les console.log du code. Pour des dashboards persistants, branchez Logpush vers R2 ou Workers Analytics Engine. La conservation native des logs est de 24 heures, suffisante pour le debug mais pas pour la conformité.

Cas d’usage typiques pour un projet ouest-africain

Cas 1 : signer des URLs S3/B2/R2 sans exposer la clé secrète au client. Cas 2 : proxifier une API tierce avec cache KV pour réduire les coûts (ex. taux de change FCFA/EUR mis en cache 1h). Cas 3 : redirections SEO 301 massives sans toucher au serveur d’origine. Cas 4 : authentification JWT avant de servir des contenus protégés. Cas 5 : transformation d’images via Cloudflare Images intégré aux Workers.

Pour approfondir, voir le tutoriel Cloudflare R2 et le guide API REST Hono.

Pièges fréquents

Premier piège : utiliser des modules Node-only comme fs ou net. Workers tourne sur V8 pur, pas Node : ces APIs n’existent pas. Solution : importer des libs compatibles Web (fetch, crypto, streams). Deuxième piège : dépasser la limite de CPU 10 ms en plan gratuit, 50 ms en payant. Pour du calcul lourd, déplacez vers Workers Unbound (50 secondes max) ou un service externe. Troisième piège : croire que request.cf.country est fiable. Le champ est correct sur le edge réel, mais null en dev local.

Étape 10 : utiliser Durable Objects pour l’état

Quand vous avez besoin d’un état cohérent entre requêtes (compteur global, salle de chat, jeu temps réel), KV ne suffit pas car éventuellement cohérent. Durable Objects fournit un acteur unique avec stockage transactionnel.

export class Counter {
  state: DurableObjectState;
  constructor(state: DurableObjectState) { this.state = state; }
  async fetch() {
    let count: number = (await this.state.storage.get('count')) || 0;
    count += 1;
    await this.state.storage.put('count', count);
    return Response.json({ count });
  }
}

Sortie de référence : un compteur global incrémenté de manière atomique, peu importe le PoP qui sert la requête. Cloudflare route automatiquement vers l’instance unique de l’objet. Idéal pour synchronisation faible volume sans déployer Redis.

Étape 11 : connecter à une base de données

Cloudflare D1 est SQLite serverless intégré aux Workers, gratuit jusqu’à 5 Go. Pour une base PostgreSQL existante (ex. Supabase, Neon), Hyperdrive cache les connexions au niveau du edge et réduit la latence considérablement.

wrangler d1 create itsc-edge-db
wrangler d1 execute itsc-edge-db --command \
  "CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT)"

// src/index.ts
const result = await env.DB.prepare(
  'SELECT * FROM users WHERE email = ?'
).bind(email).first();

Vous devriez obtenir : un objet user ou la valeur null si l’email n’existe pas. Les bindings préparés évitent toute injection SQL. D1 utilise SQLite avec réplication read-only globale et écritures vers la région primaire choisie à la création.

Étape 12 : workflow CI/CD GitHub Actions

Pour automatiser le déploiement sur chaque push vers main, créez un workflow GitHub Actions avec un token API Cloudflare scoppé strictement aux Workers.

name: Deploy Worker
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: secrets.CF_API_TOKEN

Ce que vous devez voir : chaque commit déclenche un déploiement en moins d’une minute. Créez le token API dans Dashboard Cloudflare avec la permission Workers Scripts Edit uniquement, jamais une clé Global API qui donnerait accès à tout votre compte.

FAQ Cloudflare Workers

Combien de Workers puis-je déployer en gratuit ? Jusqu’à 100 Workers par compte, 100 000 requêtes par jour cumulées tous Workers confondus.

Workers fonctionne-t-il avec Python ? Oui depuis 2024, support Python via Pyodide en bêta. Les performances et l’écosystème JavaScript restent supérieurs en production.

Puis-je migrer une app Express vers Workers ? Pas directement. Réécrivez avec Hono ou itty-router. La logique métier se garde, le routing change de paradigme.

Le PoP de Dakar (DKR) est-il fiable ? Oui, ouvert depuis 2020 et utilisé par les sites majeurs ouest-africains. En cas de panne locale, Cloudflare bascule transparent vers Lagos ou Casablanca.

Récapitulatif

Cloudflare Workers est aujourd’hui la plateforme edge la plus mûre pour des APIs et applications web légères. La courbe d’apprentissage est courte si vous connaissez les API Web standards, le free tier suffit pour des projets pédagogiques et des MVPs, et le coût marginal en payant reste inférieur d’un ordre de grandeur à un VPS dédié pour des charges burst. Pour un dev à Dakar ou Abidjan qui veut une latence sub-20ms sans gérer de serveur, c’est devenu le choix par défaut en 2026 sur les projets neufs.

Étape 13 : tests automatisés avec Vitest

Wrangler intègre une intégration Vitest pour tester unitairement vos Workers contre Miniflare. Vous validez la logique avant de déployer en prod.

npm install -D vitest @cloudflare/vitest-pool-workers
// vitest.config.ts
import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
export default defineWorkersConfig({
  test: { poolOptions: { workers: { wrangler: { configPath: './wrangler.toml' } } } }
});

Vous devriez obtenir : npx vitest exécute les tests dans un environnement Workers réaliste, avec accès aux bindings KV et D1 mockés. Couvre la dérive entre dev et prod sans déployer pour chaque PR.

Limites à connaître

Workers ne convient pas à tout : pas de WebSockets longs au-delà de quelques minutes (utilisez Durable Objects), pas de connexions TCP brutes hors Hyperdrive, pas de filesystem local persistant (R2 ou KV à la place). Pour un service qui doit tourner en continu avec un état important, gardez une architecture serveur classique en complément. Workers brille sur les APIs sans état, le edge transform et les redirections SEO.

Cette plateforme évolue vite : surveillez le changelog officiel pour les nouvelles primitives ajoutées chaque trimestre par les équipes Cloudflare.

Partager
#2026 #Frontend #Tutoriel

Articles Similaires