Contexte

Un objet Context est créé pour chaque requête et reste disponible jusqu’au renvoi de la réponse. Vous pouvez y stocker des valeurs, définir des en-têtes et le code d’état souhaité, et accéder aux objets HonoRequest et Response.

req

req est une instance de HonoRequest. Consultez HonoRequest pour en savoir plus.

app.get('/hello', (c) => {
  const userAgent = c.req.header('User-Agent')
  // ...
})

status()

Vous pouvez définir un code d’état HTTP avec c.status(). Sa valeur par défaut est 200. Il n’est pas nécessaire d’appeler c.status() pour le code d’état 200.

app.post('/posts', (c) => {
  // Set HTTP status code
  c.status(201)
  return c.text('Your post is created!')
})

header()

Vous pouvez définir les en-têtes HTTP de la réponse.

app.get('/', (c) => {
  // Set headers
  c.header('X-Message', 'My custom message')
  return c.text('Hello!')
})

body()

Renvoie une réponse HTTP.

Information

Remarque : pour du texte ou du HTML, il est recommandé d’utiliser c.text() ou c.html().

app.get('/welcome', (c) => {
  c.header('Content-Type', 'text/plain')
  // Return the response body
  return c.body('Thank you for coming')
})

Vous pouvez également écrire ceci.

app.get('/welcome', (c) => {
  return c.body('Thank you for coming', 201, {
    'X-Message': 'Hello!',
    'Content-Type': 'text/plain',
  })
})

La réponse correspond à l’objet Response suivant.

new Response('Thank you for coming', {
  status: 201,
  headers: {
    'X-Message': 'Hello!',
    'Content-Type': 'text/plain',
  },
})

text()

Renvoie du texte avec Content-Type: text/plain.

app.get('/say', (c) => {
  return c.text('Hello!')
})

json()

Renvoie du JSON avec Content-Type: application/json.

app.get('/api', (c) => {
  return c.json({ message: 'Hello!' })
})

html()

Renvoie du HTML avec Content-Type: text/html.

app.get('/', (c) => {
  return c.html('<h1>Hello! Hono!</h1>')
})

notFound()

Renvoie une réponse Not Found. Vous pouvez la personnaliser avec app.notFound().

app.get('/notfound', (c) => {
  return c.notFound()
})

redirect()

Effectue une redirection. Le code d’état par défaut est 302.

app.get('/redirect', (c) => {
  return c.redirect('/')
})
app.get('/redirect-permanently', (c) => {
  return c.redirect('/', 301)
})

res

Vous pouvez accéder à l’objet Response qui sera renvoyé.

// Response object
app.use('/', async (c, next) => {
  await next()
  c.res.headers.append('X-Debug', 'Debug message')
})

set() / get()

Permet de lire et de définir des paires clé-valeur arbitraires conservées pendant toute la durée de la requête en cours. Vous pouvez ainsi transmettre des valeurs entre les middlewares, ou d’un middleware aux gestionnaires de routes.

app.use(async (c, next) => {
  c.set('message', 'Hono is cool!!')
  await next()
})

app.get('/', (c) => {
  const message = c.get('message')
  return c.text(`The message is "${message}"`)
})

Passez Variables comme paramètre générique au constructeur de Hono pour garantir la vérification des types.

type Variables = {
  message: string
}

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

Les valeurs de c.set / c.get ne sont conservées que pour une même requête. Elles ne peuvent pas être partagées entre plusieurs requêtes ni stockées de façon persistante.

var

Vous pouvez également accéder à la valeur d’une variable avec c.var.

const result = c.var.client.oneMethod()

Pour créer un middleware proposant une méthode personnalisée, écrivez le code suivant :

type Env = {
  Variables: {
    echo: (str: string) => string
  }
}

const app = new Hono()

const echoMiddleware = createMiddleware<Env>(async (c, next) => {
  c.set('echo', (str) => str)
  await next()
})

app.get('/echo', echoMiddleware, (c) => {
  return c.text(c.var.echo('Hello!'))
})

Pour utiliser le middleware dans plusieurs gestionnaires, vous pouvez employer app.use(). Dans ce cas, vous devez passer Env comme paramètre générique au constructeur de Hono pour garantir la vérification des types.

const app = new Hono<Env>()

app.use(echoMiddleware)

app.get('/echo', (c) => {
  return c.text(c.var.echo('Hello!'))
})

render() / setRenderer()

Vous pouvez définir une mise en page avec c.setRenderer() dans un middleware personnalisé.

app.use(async (c, next) => {
  c.setRenderer((content) => {
    return c.html(
      <html>
        <body>
          <p>{content}</p>
        </body>
      </html>
    )
  })
  await next()
})

Vous pouvez ensuite créer des réponses dans cette mise en page avec c.render().

app.get('/', (c) => {
  return c.render('Hello!')
})

Le résultat est le suivant :

<html>
  <body>
    <p>Hello!</p>
  </body>
</html>

Vous pouvez aussi adapter librement les arguments de cette fonction. Pour garantir la vérification des types, définissez-les comme suit :

declare module 'hono' {
  interface ContextRenderer {
    (
      content: string | Promise<string>,
      head: { title: string }
    ): Response | Promise<Response>
  }
}

Voici un exemple d’utilisation :

app.use('/pages/*', async (c, next) => {
  c.setRenderer((content, head) => {
    return c.html(
      <html>
        <head>
          <title>{head.title}</title>
        </head>
        <body>
          <header>{head.title}</header>
          <p>{content}</p>
        </body>
      </html>
    )
  })
  await next()
})

app.get('/pages/my-favorite', (c) => {
  return c.render(<p>Ramen and Sushi</p>, {
    title: 'My favorite',
  })
})

app.get('/pages/my-hobbies', (c) => {
  return c.render(<p>Watching baseball</p>, {
    title: 'My hobbies',
  })
})

executionCtx

Vous pouvez accéder à l’ExecutionContext propre à Cloudflare Workers.

// ExecutionContext object
app.get('/foo', async (c) => {
  c.executionCtx.waitUntil(c.env.KV.put(key, data))
  // ...
})

L’ExecutionContext possède également un champ exports. Pour bénéficier de la saisie automatique avec les types générés par Wrangler, vous pouvez utiliser une augmentation de module :

import 'hono'

declare module 'hono' {
  interface ExecutionContext {
    readonly exports: Cloudflare.Exports
  }
}

event

Vous pouvez accéder au FetchEvent propre à Cloudflare Workers. Il était utilisé dans la syntaxe « Service Worker », qui n’est plus recommandée aujourd’hui.

// Type definition to make type inference
type Bindings = {
  MY_KV: KVNamespace
}

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

// FetchEvent object (only set when using Service Worker syntax)
app.get('/foo', async (c) => {
  c.event.waitUntil(c.env.MY_KV.put(key, data))
  // ...
})

env

Dans Cloudflare Workers, les variables d’environnement, les secrets, les espaces de noms KV, les bases de données D1, les buckets R2 et les autres ressources associées à un Worker sont appelés bindings. Quel que soit leur type, les bindings sont toujours disponibles comme variables globales et accessibles depuis le contexte avec c.env.BINDING_KEY.

// Type definition to make type inference
type Bindings = {
  MY_KV: KVNamespace
}

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

// Environment object for Cloudflare Workers
app.get('/', async (c) => {
  c.env.MY_KV.get('my-key')
  // ...
})

error

Si le gestionnaire lève une erreur, l’objet d’erreur est placé dans c.error. Vous pouvez y accéder depuis votre middleware.

app.use(async (c, next) => {
  await next()
  if (c.error) {
    // do something...
  }
})

ContextVariableMap

Attention

ContextVariableMap étend les types globalement pour tous les contextes, que le middleware définissant la variable se soit exécuté ou non. Ainsi, c.get('result') peut sembler correctement typé même dans les gestionnaires où votre middleware n’a jamais été enregistré. Cela peut masquer des erreurs liées à undefined à l’exécution.

Examinez l’exemple suivant :

declare module 'hono' {
  interface ContextVariableMap {
    result: string
  }
}

const mw = createMiddleware(async (c, next) => {
  c.set('result', 'some values')
  await next()
})

const app = new Hono()

// handler uses the middleware
app.get('/foo', mw, (c) => {
  const val = c.get('result') // ✅ val is a string and typed as such, as expected
})

// handler doesn't use the middleware
app.get('/bar', (c) => {
  const val = c.get('result') // ❌ val is undefined but typed as a string, which can lead to runtime errors
})

Vous pouvez étendre l’interface ContextVariableMap pour définir globalement les types des variables de contexte dans toute votre application. Cette approche convient aux variables définies par un middleware appliqué à l’ensemble de l’application et dont la présence dans le contexte est garantie.

Par exemple :

declare module 'hono' {
  interface ContextVariableMap {
    result: string
  }
}

Vous pouvez ensuite l’utiliser dans votre middleware :

const mw = createMiddleware(async (c, next) => {
  c.set('result', 'some values') // result is a string
  await next()
})

Dans un gestionnaire, le type de la variable est correctement inféré :

app.get('/', (c) => {
  const val = c.get('result') // val is a string
  // ...
  return c.json({ result: val })
})