導入

Hono 4のアプリを用意する

npm、pnpm、Yarn、Bunのいずれかと、起動できるHono 4アプリが必要です。この手順が終わると、2枚のスライドを/decks/welcomeで表示できます。

パッケージを追加し、設定ファイルを作る

以下の例ではnpmを使います。initを実行すると、CLIと実行時の共通設定hono-decks.config.tsと、生成コードをアプリにつなぐsrc/decks.tsが作られます。既存のファイルは上書きされません。

npm install hono-decks
npx hono-decks init

<command>にはinitやcompileを指定します。以降の例も、利用中のパッケージマネージャーに合わせて読み替えてください。

最初のデッキを作ってコンパイルする

decks/welcome/deck.mdxを作成します。先頭のフロントマターはデッキ全体の情報、その次の---からが1枚目のスライドです。

---
title: Welcome
description: My first hono-decks presentation
---

---
layout: cover
---

# Welcome

This deck is served from my Hono app.

---

## Next slide

- Write slides in MDX
- Serve them with Hono

MDXをHono JSXモジュールへ変換します。成功するとsrc/generated/が作成されます。

npx hono-decks compile

hono-decks.config.ts   # CLIと実行時の共通設定
decks/
└── welcome/
    └── deck.mdx
src/
├── decks.ts              # アプリ側で編集
└── generated/
    └── decks.ts          # 自動生成。編集しない

src/decks.tsとdeck.mdxは編集してかまいません。一方、src/generated/はコンパイルのたびに上書きされるため、直接編集しないでください。

生成したルーターをHonoに登録する

生成したルーターを、既存のHonoアプリの/decks配下に登録します。

// src/index.ts
import { Hono } from "hono"
import { decks } from "./decks"

const app = new Hono()
app.route(decks.mountPath, decks.router())

export default app

decks.mountPathは設定ファイルの値から生成されるため、コンパイル時と実行時で公開パスがずれません。

普段の開発コマンドにコンパイルを組み込む

HonoXやViteでは、既存のVite設定へプラグインを追加します。Viteの起動前に初回コンパイルを行い、MDXの変更を検知して再生成した後、ブラウザを更新します。

import { honoDecks } from "hono-decks/vite"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [honoDecks()],
})

{
  "scripts": {
    "decks:compile": "hono-decks compile",
    "dev": "vite",
    "build": "vite build"
  }
}

Wranglerを直接使うCloudflare Workerでは、wrangler.jsoncのカスタムビルドへ登録します。--live-reloadを付けると、普段の開発コマンドだけでデッキの変更監視とブラウザ更新まで行えます。

{
  "build": {
    "command": "hono-decks compile",
    "watch_dir": ["decks"]
  }
}

{
  "scripts": {
    "dev": "wrangler dev --live-reload"
  }
}

ブラウザで表示を確認する

npm run dev

開発サーバーが表示したURLの/decks/welcomeを開きます。Welcomeスライドが表示され、左右の操作または矢印キーで2枚目へ移動できれば導入は完了です。

うまくいかないとき

src/generated/decks.tsがない

npx hono-decks compileを再実行し、設定ファイルのbuild.rootとbuild.outDirを確認します。

/decksが404になる

app.route(decks.mountPath, decks.router())になっているか確認します。

WorkerのビルドにNode.js用モジュールが含まれる

実行時APIはhono-decksから読み込みます。hono-decks/nodeはコンパイル用スクリプトだけで使用してください。

次に読む

次はスライドの書き方へ進みます。環境変数を使うときは設定、公開する画面を変えるときはルートと画面を参照してください。