Cloudflare Workers

Cloudflare Workers est un environnement d'exécution JavaScript edge sur le CDN Cloudflare.

Vous pouvez développer l'application localement et la publier en quelques commandes avec Wrangler. Wrangler inclut un transpileur, ce qui vous permet d'écrire le code en TypeScript.

Créons votre première application Cloudflare Workers avec Hono.

1. Configuration

Un modèle de démarrage est disponible pour Cloudflare Workers. Créez votre projet avec la commande « create-hono ». Sélectionnez le modèle cloudflare-workers pour cet exemple.

npm

npm create hono@latest my-app

yarn

yarn create hono my-app

pnpm

pnpm create hono my-app

bun

bun create hono@latest my-app

deno

deno init --npm hono my-app

Ouvrez my-app et installez les dépendances.

npm

cd my-app
npm i

yarn

cd my-app
yarn

pnpm

cd my-app
pnpm i

bun

cd my-app
bun i

2. Bonjour le monde

Modifiez src/index.ts comme ci-dessous.

import { Hono } from 'hono'
const app = new Hono()

app.get('/', (c) => c.text('Hello Cloudflare Workers!'))

export default app

3. Exécution

Démarrez le serveur de développement localement. Ensuite, ouvrez http://localhost:8787 dans votre navigateur web.

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

Modifier le numéro de port

Pour modifier le numéro de port, suivez ces instructions afin de mettre à jour les fichiers wrangler.toml / wrangler.json / wrangler.jsonc : Configuration de Wrangler

Vous pouvez aussi suivre ces instructions pour définir les options de la CLI : CLI Wrangler

4. Déploiement

Si vous avez un compte Cloudflare, vous pouvez déployer sur Cloudflare. Dans package.json, remplacez $npm_execpath par le gestionnaire de paquets de votre choix.

npm

npm run deploy

yarn

yarn deploy

pnpm

pnpm run deploy

bun

bun run deploy

Et voilà !

Utiliser Hono avec d'autres gestionnaires d'événements

Vous pouvez intégrer Hono à d'autres gestionnaires d'événements (tels que scheduled) en mode Module Worker.

Pour cela, exportez app.fetch comme gestionnaire fetch du module, puis implémentez les autres gestionnaires nécessaires :

const app = new Hono()

export default {
  fetch: app.fetch,
  scheduled: async (batch, env) => {},
}

Servir des fichiers statiques

Pour servir des fichiers statiques, vous pouvez utiliser la fonctionnalité Static Assets de Cloudflare Workers. Précisez leur répertoire dans wrangler.jsonc :

"assets": { "directory": "public" }

Créez ensuite le répertoire public et placez-y les fichiers. Par exemple, ./public/static/hello.txt sera servi à l'adresse /static/hello.txt.

.
├── package.json
├── public
│   ├── favicon.ico
│   └── static
│       └── hello.txt
├── src
│   └── index.ts
└── wrangler.jsonc

Types

Vous devez installer @cloudflare/workers-types pour disposer des types de Workers.

npm

npm i --save-dev @cloudflare/workers-types

yarn

yarn add -D @cloudflare/workers-types

pnpm

pnpm add -D @cloudflare/workers-types

bun

bun add --dev @cloudflare/workers-types

Tests

Pour les tests, nous recommandons @cloudflare/vitest-pool-workers. Consultez les exemples pour le configurer.

Supposons que vous ayez l'application ci-dessous.

import { Hono } from 'hono'

const app = new Hono()
app.get('/', (c) => c.text('Please test me!'))

Ce code permet de vérifier qu'elle renvoie une réponse « 200 OK ».

describe('Test the application', () => {
  it('Should return 200 response', async () => {
    const res = await app.request('http://localhost/')
    expect(res.status).toBe(200)
  })
})

Bindings

Dans Cloudflare Workers, vous pouvez associer des valeurs d'environnement, un espace de noms KV, un bucket R2 ou un Durable Object. Vous pouvez y accéder dans c.env. Ils seront typés si vous passez la « définition de type » des bindings à Hono comme paramètre générique.

type Bindings = {
  MY_BUCKET: R2Bucket
  USERNAME: string
  PASSWORD: string
}

const app = new Hono<{ Bindings: Bindings }>()

// Access to environment values
app.put('/upload/:key', async (c, next) => {
  const key = c.req.param('key')
  await c.env.MY_BUCKET.put(key, c.req.body)
  return c.text(`Put ${key} successfully!`)
})

Générer automatiquement les types des bindings

Au lieu de définir les types des bindings à la main, vous pouvez les générer depuis votre wrangler.toml avec la commande wrangler types. Utilisez l'option --env-interface pour éviter un conflit de noms avec le type Env intégré à Hono :

wrangler types --env-interface CloudflareBindings

Cela génère un fichier worker-configuration.d.ts avec le nom d'interface indiqué. Passez-le ensuite à Hono :

const app = new Hono<{ Bindings: CloudflareBindings }>()

app.put('/upload/:key', async (c, next) => {
  const key = c.req.param('key')
  await c.env.MY_BUCKET.put(key, c.req.body)
  return c.text(`Put ${key} successfully!`)
})

Utiliser les variables dans les middlewares

Cela concerne uniquement le mode Module Worker. Pour utiliser des variables ou des variables secrètes dans un middleware, par exemple « username » ou « password » dans le middleware d'authentification Basic, écrivez comme suit.

import { basicAuth } from 'hono/basic-auth'

type Bindings = {
  USERNAME: string
  PASSWORD: string
}

const app = new Hono<{ Bindings: Bindings }>()

//...

app.use('/auth/*', async (c, next) => {
  const auth = basicAuth({
    username: c.env.USERNAME,
    password: c.env.PASSWORD,
  })
  return auth(c, next)
})

Il en va de même pour le middleware d'authentification Bearer, l'authentification JWT et les autres.

Déployer depuis GitHub Actions

Avant de déployer du code sur Cloudflare via la CI, vous avez besoin d'un jeton Cloudflare. Vous pouvez le gérer depuis la page User API Tokens.

Pour un nouveau jeton, sélectionnez le modèle Edit Cloudflare Workers. Si vous utilisez un jeton existant, assurez-vous qu'il dispose des autorisations correspondantes.

Ouvrez ensuite les paramètres de votre dépôt GitHub : Settings->Secrets and variables->Actions->Repository secrets, puis ajoutez un secret nommé CLOUDFLARE_API_TOKEN.

Créez ensuite .github/workflows/deploy.yml à la racine de votre projet Hono et collez le code suivant :

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Modifiez ensuite wrangler.jsonc et ajoutez ce code après la ligne compatibility_date.

"main": "src/index.ts",
"minify": true

Tout est prêt ! Il ne reste qu'à pousser le code.

Charger l'environnement en développement local

Pour configurer les variables d'environnement en développement local, créez un fichier .dev.vars ou .env à la racine du projet. Ces fichiers doivent respecter la syntaxe dotenv. Par exemple :

SECRET_KEY=value
API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Pour en savoir plus sur cette section, consultez la documentation Cloudflare : https://developers.cloudflare.com/workers/wrangler/configuration/#secrets

Utilisez ensuite c.env.* pour récupérer les variables d'environnement dans votre code.

Information

Par défaut, process.env n'est pas disponible dans Cloudflare Workers ; il est donc recommandé de récupérer les variables d'environnement depuis c.env. Pour l'utiliser, activez le flag nodejs_compat_populate_process_env. Vous pouvez également importer env depuis cloudflare:workers. Pour plus de détails, consultez Comment accéder à env dans la documentation Cloudflare.

type Bindings = {
  SECRET_KEY: string
}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/env', (c) => {
  const SECRET_KEY = c.env.SECRET_KEY
  return c.text(SECRET_KEY)
})

Avant de déployer votre projet sur Cloudflare, pensez à définir les variables d'environnement et les secrets dans la configuration du projet Cloudflare Workers.

Pour en savoir plus sur cette section, consultez la documentation Cloudflare : https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard