Application — Hono

Hono est l’objet principal. Il est importé en premier et utilisé jusqu’à la fin.

import { Hono } from 'hono'

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

export default app // for Cloudflare Workers or Bun

Méthodes

Une instance de Hono possède les méthodes suivantes.

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

Les premières méthodes servent au routage. Consultez la section sur le routage pour en savoir plus.

Ressource introuvable

app.notFound permet de personnaliser la réponse lorsqu’une ressource est introuvable.

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

Attention

La méthode notFound est appelée uniquement par l’application de premier niveau. Consultez ce ticket pour plus de détails.

Gestion des erreurs

app.onError permet de traiter les erreurs non interceptées et de renvoyer une réponse personnalisée.

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

Information

Si l’application parente et ses routes possèdent des gestionnaires onError, ceux des routes sont prioritaires.

fire()

Attention

app.fire() est obsolète. Utilisez plutôt fire() de @hono/service-worker. Consultez la documentation des Service Workers pour plus de détails.

app.fire() ajoute automatiquement un écouteur global pour l’événement fetch.

Cela peut être utile dans les environnements qui suivent l’API Service Worker, comme Cloudflare Workers sans modules ES.

app.fire() exécute les instructions suivantes pour vous :

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

fetch()

app.fetch est le point d’entrée de votre application.

Pour Cloudflare Workers, vous pouvez écrire :

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

Ou simplement :

export default app

Bun:

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

request()

request est une méthode utile pour les tests.

Vous pouvez passer une URL ou un chemin pour envoyer une requête GET. app renvoie un objet Response.

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

Vous pouvez aussi passer un objet Request :

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

Attention

app.mount() est obsolète. Utilisez plutôt le middleware Mount.

La méthode mount() permet de monter des applications d’autres frameworks dans votre application Hono.

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)

Par défaut, mount() transmet une nouvelle Request dont l’URL ne contient plus le chemin de montage. Vous pouvez personnaliser la Request transmise à l’application montée avec une fonction replaceRequest :

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

Pour transmettre la Request d’origine sans modification, définissez replaceRequest sur false. Il s’agit d’un raccourci pour la fonction ci-dessus :

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

Mode strict

Le mode strict vaut true par défaut et distingue les routes suivantes.

• /hello
• /hello/

app.get('/hello') ne correspond pas à GET /hello/.

En définissant le mode strict sur false, les deux chemins sont traités de la même manière.

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

Option router

L’option router définit le routeur utilisé. Le routeur par défaut est SmartRouter. Pour utiliser RegExpRouter, passez-le à une nouvelle instance de Hono :

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

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

Paramètres génériques

Vous pouvez utiliser des paramètres génériques pour préciser les types des bindings de Cloudflare Workers et des variables utilisées par c.set et c.get.

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