Cloudflare Workers

Cloudflare Workers ist eine JavaScript-Edge-Laufzeitumgebung auf dem Cloudflare-CDN.

Mit Wrangler kannst du deine Anwendung lokal entwickeln und mit wenigen Befehlen veröffentlichen. Wrangler enthält einen Transcompiler, sodass wir den Code in TypeScript schreiben können.

Erstellen wir deine erste Anwendung für Cloudflare Workers mit Hono.

1. Einrichtung

Für Cloudflare Workers steht eine Projektvorlage zur Verfügung. Starte dein Projekt mit dem Befehl „create-hono“. Wähle für dieses Beispiel die Vorlage cloudflare-workers aus.

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

Wechsle nach my-app und installiere die Abhängigkeiten.

npm

cd my-app
npm i

yarn

cd my-app
yarn

pnpm

cd my-app
pnpm i

bun

cd my-app
bun i

2. Hello World

Bearbeite src/index.ts wie folgt.

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

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

export default app

3. Ausführen

Starte den Entwicklungsserver lokal. Öffne anschließend http://localhost:8787 in deinem Webbrowser.

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

Portnummer ändern

Wenn du die Portnummer ändern musst, folge diesen Anweisungen, um die Dateien wrangler.toml / wrangler.json / wrangler.jsonc anzupassen: Wrangler-Konfiguration

Alternativ kannst du diesen Anweisungen folgen, um CLI-Optionen festzulegen: Wrangler-CLI

4. Bereitstellung

Wenn du ein Cloudflare-Konto hast, kannst du die Anwendung auf Cloudflare bereitstellen. In package.json musst du $npm_execpath auf den Paketmanager deiner Wahl ändern.

npm

npm run deploy

yarn

yarn deploy

pnpm

pnpm run deploy

bun

bun run deploy

Das ist alles!

Hono mit anderen Ereignishandlern verwenden

Im Module-Worker-Modus kannst du Hono mit anderen Ereignishandlern wie scheduled kombinieren.

Exportiere dazu app.fetch als fetch-Handler des Moduls und implementiere weitere Handler nach Bedarf:

const app = new Hono()

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

Statische Dateien ausliefern

Um statische Dateien auszuliefern, kannst du die Funktion für statische Assets von Cloudflare Workers verwenden. Gib das Verzeichnis der Dateien in wrangler.jsonc an:

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

Erstelle anschließend das Verzeichnis public und lege die Dateien darin ab. Beispielsweise wird ./public/static/hello.txt unter /static/hello.txt ausgeliefert.

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

Typen

Wenn du Workers-Typen verwenden möchtest, musst du @cloudflare/workers-types installieren.

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

Für Tests empfehlen wir @cloudflare/vitest-pool-workers. Sieh dir die Beispiele zur Einrichtung an.

Angenommen, die folgende Anwendung ist vorhanden.

import { Hono } from 'hono'

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

Mit diesem Code können wir testen, ob sie eine Antwort „200 OK“ zurückgibt.

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

Bindings

In Cloudflare Workers können wir Umgebungswerte, KV-Namespaces, R2-Buckets oder Durable Objects binden. Du kannst in c.env darauf zugreifen. Wenn du die „Typdefinition“ für die Bindings als generischen Typparameter an Hono übergibst, erhalten sie die entsprechenden Typen.

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!`)
})

Binding-Typen automatisch generieren

Anstatt Binding-Typen von Hand zu definieren, kannst du sie mit dem Befehl wrangler types aus deiner wrangler.toml generieren. Verwende das Flag --env-interface, um einen Namenskonflikt mit Honos integriertem Typ Env zu vermeiden:

wrangler types --env-interface CloudflareBindings

Dadurch wird eine Datei worker-configuration.d.ts mit dem angegebenen Schnittstellennamen generiert. Übergib diesen Typ anschließend an 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!`)
})

Variablen in Middleware verwenden

Dies gilt nur für den Module-Worker-Modus. Wenn du Variablen oder geheime Variablen in Middleware verwenden möchtest, etwa „username“ oder „password“ in der Middleware für Basic-Authentifizierung, musst du den Code wie folgt schreiben.

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)
})

Das gilt ebenso für die Middleware für Bearer-Authentifizierung, JWT-Authentifizierung und andere.

Über GitHub Actions bereitstellen

Bevor du Code über CI auf Cloudflare bereitstellst, benötigst du ein Cloudflare-Token. Du kannst es unter Benutzer-API-Tokens verwalten.

Wenn du ein neues Token erstellst, wähle die Vorlage Edit Cloudflare Workers aus. Wenn du bereits ein anderes Token hast, stelle sicher, dass es die entsprechenden Berechtigungen besitzt.

Öffne anschließend die Einstellungen deines GitHub-Repositorys unter Settings->Secrets and variables->Actions->Repository secrets und füge ein neues Secret namens CLOUDFLARE_API_TOKEN hinzu.

Erstelle dann im Stammverzeichnis deines Hono-Projekts .github/workflows/deploy.yml und füge den folgenden Code ein:

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 }}

Bearbeite anschließend wrangler.jsonc und füge diesen Code nach der Zeile compatibility_date ein.

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

Alles ist bereit! Pushe jetzt deinen Code.

Umgebungsvariablen bei der lokalen Entwicklung laden

Um die Umgebungsvariablen für die lokale Entwicklung zu konfigurieren, erstelle eine Datei .dev.vars oder .env im Stammverzeichnis des Projekts. Diese Dateien müssen die dotenv-Syntax verwenden. Zum Beispiel:

SECRET_KEY=value
API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Weitere Informationen zu diesem Abschnitt findest du in der Cloudflare-Dokumentation: https://developers.cloudflare.com/workers/wrangler/configuration/#secrets

Verwende anschließend c.env.*, um die Umgebungsvariablen in deinem Code abzurufen.

Info

Standardmäßig ist process.env in Cloudflare Workers nicht verfügbar. Daher empfiehlt es sich, Umgebungsvariablen aus c.env abzurufen. Wenn du process.env verwenden möchtest, musst du das Flag nodejs_compat_populate_process_env aktivieren. Du kannst auch env aus cloudflare:workers importieren. Details findest du unter Zugriff auf env in der Cloudflare-Dokumentation.

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)
})

Bevor du dein Projekt auf Cloudflare bereitstellst, denke daran, die Umgebungsvariablen und Secrets in der Konfiguration des Cloudflare-Workers-Projekts festzulegen.

Weitere Informationen zu diesem Abschnitt findest du in der Cloudflare-Dokumentation: https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard