Anwendung – Hono

Hono ist das zentrale Objekt. Es wird zuerst importiert und bis zum Ende verwendet.

import { Hono } from 'hono'

const app = new Hono()
//...

export default app // for Cloudflare Workers or Bun

Methoden

Eine Instanz von Hono stellt die folgenden Methoden bereit.

• app.HTTP_METHOD([path,]handler|middleware...)
• app.all([path,]handler|middleware...)
• app.on(method|method[], path|path[], handler|middleware...)
• app.use([path,]middleware)
• app.route(path, [app])
• app.basePath(path)
• app.notFound(handler)
• app.onError(err, handler)
• app.mount(path, anotherApp, [options])
• app.fire()
• app.fetch(request, env, event)
• app.request(path, options)

Die ersten Methoden dienen dem Routing. Weitere Informationen findest du im Abschnitt zum Routing.

Nicht gefunden

Mit app.notFound kannst du die Antwort für nicht gefundene Ressourcen anpassen.

app.notFound((c) => {
  return c.text('Custom 404 Message', 404)
})

Achtung

Die Methode notFound wird nur von der obersten Anwendung aufgerufen. Weitere Informationen findest du in diesem Issue.

Fehlerbehandlung

Mit app.onError kannst du nicht abgefangene Fehler behandeln und eine eigene Antwort zurückgeben.

app.onError((err, c) => {
  console.error(`${err}`)
  return c.text('Custom Error Message', 500)
})

Info

Wenn sowohl eine übergeordnete Anwendung als auch ihre Routen onError-Handler besitzen, haben die Handler auf Routenebene Vorrang.

fire()

Achtung

app.fire() ist veraltet. Verwende stattdessen fire() aus @hono/service-worker. Einzelheiten findest du in der Service-Worker-Dokumentation.

app.fire() fügt automatisch einen globalen Listener für das Ereignis fetch hinzu.

Das ist in Umgebungen nützlich, die der Service-Worker-API folgen, beispielsweise Cloudflare Workers ohne ES-Module.

app.fire() führt Folgendes für dich aus:

addEventListener('fetch', (event: FetchEventLike): void => {
  event.respondWith(this.dispatch(...))
})

fetch()

app.fetch ist der Einstiegspunkt deiner Anwendung.

Für Cloudflare Workers kannst du Folgendes verwenden:

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    return app.fetch(request, env, ctx)
  },
}

Oder einfach:

export default app

Bun:

export default app 
export default {  
  port: 3000, 
  fetch: app.fetch, 
} 

request()

request ist eine nützliche Methode zum Testen.

Du kannst eine URL oder einen Pfadnamen übergeben, um eine GET-Anfrage zu senden. app gibt ein Response-Objekt zurück.

test('GET /hello is ok', async () => {
  const res = await app.request('/hello')
  expect(res.status).toBe(200)
})

Du kannst auch ein Request-Objekt übergeben:

test('POST /message is ok', async () => {
  const req = new Request('Hello!', {
    method: 'POST',
  })
  const res = await app.request(req)
  expect(res.status).toBe(201)
})

mount()

Achtung

app.mount() ist veraltet. Verwende stattdessen die Mount-Middleware.

Mit mount() kannst du Anwendungen anderer Frameworks in deine Hono-Anwendung einbinden.

import { Router as IttyRouter } from 'itty-router'
import { Hono } from 'hono'

// Create itty-router application
const ittyRouter = IttyRouter()

// Handle `GET /itty-router/hello`
ittyRouter.get('/hello', () => new Response('Hello from itty-router'))

// Hono application
const app = new Hono()

// Mount!
app.mount('/itty-router', ittyRouter.handle)

Standardmäßig übergibt mount() eine neue Request, bei deren URL der Einbindungspfad entfernt wurde. Mit einer Funktion replaceRequest kannst du festlegen, welche Request an die eingebundene Anwendung übergeben wird:

app.mount('/app', handler, {
  replaceRequest: (originalRequest) => originalRequest,
})

Um die ursprüngliche Request unverändert zu übergeben, setze replaceRequest auf false. Das ist eine Kurzform der obigen Funktion:

app.mount('/app', handler, {
  replaceRequest: false,
})

Strikter Modus

Der strikte Modus ist standardmäßig true und unterscheidet die folgenden Routen.

• /hello
• /hello/

app.get('/hello') stimmt nicht mit GET /hello/ überein.

Wenn du den strikten Modus auf false setzt, werden beide Pfade gleich behandelt.

const app = new Hono({ strict: false })

Router-Option

Die Option router legt fest, welcher Router verwendet wird. Der Standardrouter ist SmartRouter. Wenn du RegExpRouter verwenden möchtest, übergib ihn einer neuen Instanz von Hono:

import { RegExpRouter } from 'hono/router/reg-exp-router'

const app = new Hono({ router: new RegExpRouter() })

Generische Typen

Mit generischen Typen kannst du die Typen der Cloudflare-Workers-Bindings und der in c.set/c.get verwendeten Variablen festlegen.

type Bindings = {
  TOKEN: string
}

type Variables = {
  user: User
}

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

app.use('/auth/*', async (c, next) => {
  const token = c.env.TOKEN // token is `string`
  // ...
  c.set('user', user) // user should be `User`
  await next()
})