Premiers pas

Hono est très facile à utiliser. Vous pouvez rapidement configurer un projet, écrire du code, développer avec un serveur local et déployer. Le même code fonctionne sur n'importe quel environnement d'exécution, avec des points d'entrée différents. Voyons les bases de Hono.

Modèle de démarrage

Des modèles de démarrage sont disponibles pour chaque plateforme. Utilisez la commande « create-hono » suivante.

npm

npm create hono@latest my-app

yarn

yarn create hono my-app

pnpm

pnpm create hono@latest my-app

bun

bun create hono@latest my-app

deno

deno init --npm hono@latest my-app

Vous devrez ensuite choisir le modèle à utiliser. Sélectionnons Cloudflare Workers pour cet exemple.

? Which template do you want to use?
    aws-lambda
    bun
    cloudflare-pages
❯   cloudflare-workers
    deno
    fastly
    nextjs
    nodejs
    vercel

Le modèle sera téléchargé dans my-app. Ouvrez ce dossier 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

Une fois les paquets installés, exécutez la commande suivante pour démarrer un serveur local.

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

Bonjour le monde

Vous pouvez écrire du code TypeScript avec l'outil de développement Cloudflare Workers « Wrangler », Deno, Bun ou d'autres outils sans vous préoccuper de la transpilation.

Écrivez votre première application Hono dans src/index.ts. L'exemple ci-dessous est une application Hono de départ.

Les parties import et export default final peuvent varier selon l'environnement d'exécution, mais le code de l'application fonctionne de la même manière partout.

import { Hono } from 'hono'

const app = new Hono()

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

export default app

Démarrez le serveur de développement et ouvrez http://localhost:8787 dans votre navigateur.

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

Renvoyer du JSON

Renvoyer du JSON est également facile. Voici un exemple qui traite une requête GET vers /api/hello et renvoie une réponse application/json.

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

Requête et réponse

Voici comment récupérer un paramètre de chemin, une valeur de requête URL et ajouter un en-tête de réponse.

app.get('/posts/:id', (c) => {
  const page = c.req.query('page')
  const id = c.req.param('id')
  c.header('X-Message', 'Hi!')
  return c.text(`You want to see ${page} of ${id}`)
})

Vous pouvez facilement traiter POST, PUT et DELETE, en plus de GET.

app.post('/posts', (c) => c.text('Created!', 201))
app.delete('/posts/:id', (c) =>
  c.text(`${c.req.param('id')} is deleted!`)
)

Renvoyer du HTML

Vous pouvez écrire du HTML avec le helper html ou la syntaxe JSX. Pour utiliser JSX, renommez le fichier en src/index.tsx et configurez-le (consultez les instructions de votre environnement d'exécution, car elles varient). Voici un exemple utilisant JSX.

const View = () => {
  return (
    <html>
      <body>
        <h1>Hello Hono!</h1>
      </body>
    </html>
  )
}

app.get('/page', (c) => {
  return c.html(<View />)
})

Renvoyer une réponse brute

Vous pouvez aussi renvoyer directement une Response brute.

app.get('/', () => {
  return new Response('Good morning!')
})

Utiliser les middlewares

Les middlewares peuvent effectuer les tâches complexes à votre place. Vous pouvez par exemple ajouter une authentification Basic.

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

// ...

app.use(
  '/admin/*',
  basicAuth({
    username: 'admin',
    password: 'secret',
  })
)

app.get('/admin', (c) => {
  return c.text('You are authorized!')
})

Des middlewares intégrés utiles sont disponibles, notamment pour l'authentification Bearer et JWT, CORS et ETag. Hono propose aussi des middlewares tiers reposant sur des bibliothèques externes, comme GraphQL Server et Firebase Auth. Vous pouvez également créer vos propres middlewares.

Adaptateur

Il existe des adaptateurs pour les fonctionnalités propres aux plateformes, telles que la gestion des fichiers statiques ou de WebSocket. Ils sont distribués dans des paquets distincts. Par exemple, pour gérer WebSocket sur Cloudflare Workers, installez et importez @hono/cloudflare-workers.

import { upgradeWebSocket } from '@hono/cloudflare-workers'

app.get(
  '/ws',
  upgradeWebSocket((c) => {
    // ...
  })
)

Étape suivante

La plupart du code fonctionne sur toutes les plateformes, mais chacune dispose de guides spécifiques. Ils expliquent par exemple comment configurer un projet ou le déployer. Consultez la page de la plateforme que vous souhaitez utiliser pour créer votre application !