Zenn
💪

Vercel templateのHono.jsをローカル環境で動かしたい(vercelにデプロイまで)

に公開
Next.js
React
TypeScript
Vercel
Hono
tech

はじめに

この記事を作成した経緯としては、vercel上にデプロイするAPIをHono.jsを使って作成していて、開発環境(localhost)で動作確認を行おうとしたところ、デフォルトではpackage.jsonにdevコマンドがなくどのようにローカル環境で動かせば良いのか躓いたためです。
筆者のように最近Hono.jsを触り始めたという方の参考になれば幸いです。
下記の方法でも動作はしますが、より良い方法ございましたら是非ご教示ください。

Hono.jsのセットアップ

今回パッケージマネージャーはnpmを使用します。
他のパッケージマネージャーを使用している方は別途お使いのコマンドに書き換えてください。
https://hono.dev/docs/getting-started/vercel

以下のコマンドでHonoアプリを作成します。
templateでvercelを選択します。

npm create hono@latest my-app


Need to install the following packages:
create-hono@0.18.0
Ok to proceed? (y)y


> npx
> create-hono

create-hono version 0.18.0
✔ Using target directory … my-app
? Which template do you want to use?
  netlify
  nextjs
  nodejs
❯ vercel   #vercelを選択します
  cloudflare-pages
  x-basic
  aws-lambda

? Do you want to install project dependencies? yes # Yesを選択
? Which package manager do you want to use? (Use arrow keys)
❯ npm #今回はnpmを選択します
  bun
  pnpm
  yarn

✔ Cloning the template
✔ Installing project dependencies
🎉 Copied project files
Get started with: cd my-app

上記のメッセージが出ればセットアップは完了です。
完了したらcd で作成したディレクトリに移動しディレクトリを開きましょう。

$ cd my-app
$ code .

中身の確認

ディレクトリ構成は以下のようになっていると思います。

MY-APP/
├─ api/index.ts
├─ node_modules/
├─ public/
├─ .gitignore
├─ package-lock.json
├─ package.json
├─ README.md
├─ tsconfig.json
└─ vercel.json

apiディレクトリ内のindex.tsを開いてください。
以下のような記載があると思います。
vercel上で動くようにHonoの方で必要なコードが書き足されています。

import { Hono } from 'hono'
import { handle } from 'hono/vercel'

export const config = {
  runtime: 'edge'
}

const app = new Hono().basePath('/api')

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

export default handle(app)

(本題)開発環境での動作確認について

では、本題である開発環境での動作確認をする方法に入ります。
というのもpackage.jsonの中身を見ていただくと分かりますが、デフォルトではdevコマンドが定義されていないため、ローカル環境で動作確認するためのnpm run devが実行できないのです。

{
  "name": "my-app",
  "scripts": {
    "start": "vercel dev",
    "deploy": "vercel"
  },
  "dependencies": {
    "hono": "^4.7.7"
  },
  "devDependencies": {
    "vercel": "^32.4.1"
  }
}

調べていく中で、以下2通りのやり方があるかなと思ってます。

方法1: デフォルトで実行できる"start": "vercel dev" を使用

npm run start  # package.jsonに定義された "start": "vercel dev" を実行

メリット:

  • Vercel本番環境に近い環境でテストできる
  • 環境変数やVercel固有の機能を正確に再現

デメリット:

  • .vercelディレクトリが自動生成される
  • Vercelアカウントとの連携が必要
  • 初期設定が少し複雑

方法2: 別途設定を行いhono-node-serverとtsxを使用 (今回解説)

npm run dev  # 自分で追加する "dev": "tsx watch api/index.ts" を実行

メリット:

  • シンプルで軽量な開発環境
  • Vercelアカウントの連携が不要
  • 高速な起動とホットリロード

デメリット:

  • 別途インストールや記述が必要
  • そのままvercelにデプロイすると実行環境の違いによるエラーが発生する

今回は方法2を実装してみたいと思います。

実装してみる

計3ステップで開発環境での動作確認ができます。

①hono-node-serverとtsxのインストール

$ npm i @hono/node-server tsx --save-dev

②package.jsonにdevコマンドを追加

{
  "name": "my-app",
  "scripts": {
    "start": "vercel dev",
    "deploy": "vercel",
    "dev": "tsx watch api/index.ts" ##追加
  },
  "dependencies": {
    "hono": "^4.7.7"
  },
  "devDependencies": {
    "@hono/node-server": "^1.14.1",
    "tsx": "^4.19.3",
    "vercel": "^32.4.1"
  }
}

③index.tsに開発環境で実行するサーバーの記述を追加

import { Hono } from "hono";
import { handle } from "hono/vercel";
import { serve } from "@hono/node-server"; ##追加

export const config = {
  runtime: "edge",
};

const app = new Hono().basePath("/api");

app.get("/", (c) => {
  return c.json({ message: "Hello Hono!" });
});

##追加
// 開発環境でのみ実行されるサーバー設定 

const port = 8080;
console.log(`Server is running on http://localhost:${port}`);

serve({
  fetch: app.fetch,
  port,
}); 
##追加ここまで

export default handle(app);

上記の対応を行ったら、npm run devで開発環境でサーバーを立ちあげることが出来るので実行してみてください。

hono-node-serverの特徴

  • シンプルな開発サーバー: TypeScriptファイルを直接実行できるため、ビルドせずに開発できます
  • ホットリロード: ファイルの変更を検知して自動的に再起動するため、開発体験が向上します
  • Node.js環境での実行: Vercelなどのサーバーレス環境とは異なりますが、ローカル開発に最適化されています

tsxの特徴

  • シンプルな設定: 特別な設定ファイルなしでTypeScriptファイルを直接実行できます
  • ライブリロード: watchオプションにより、ファイルの変更を検知して自動的に再起動します
  • 高速: esbuildを利用しているため、起動が非常に高速です

※注意

先述しましたが開発環境で動作させるために追加したコードは、vercelにデプロイすると以下のようなエラーが出て失敗します。
理由は開発環境（node-server）と本番環境（Vercel）では実行環境が異なるためです。

  • 開発環境: Node.jsランタイム上で実行
  • Vercel本番環境: サーバーレス関数として実行
Error: The Edge Function "api/index" is referencing unsupported modules:
	- __vc__ns__/0/api/index.js: @hono/node-server

そのため先ほど追加した開発用のコードは、デプロイする前にコメントアウトをするか、
開発環境でのみサーバーを起動するように別途対応をする必要があります。

これにより開発環境でのみサーバーを起動し、本番環境（Vercel）ではエクスポートされたハンドラーが使用されるようにすることができるためエラーが出なくなります。

（任意）Vercelにデプロイして動作確認

git hubのリポジトリにpushして実際にvercel上にデプロイしてみます。
Framework Presetはotherを選択してください。
Build Commandは今回はデフォルトのままで大丈夫です。

デプロイが完了したらvisitボタンを押してください。

特にAPIのエンドポイントなどを変更していない場合は以下のような画面になると思います。

デフォルトのコードでは、/apiを叩くとHello Honoが表示される記述になっているので試してみましょう。

レスポンスが返ってきました。問題なく動作しています。

終わりに

今回はvercel templateを使用したHono.jsの開発環境での起動方法について解説しました。
まだ勉強中の為、もしもっと簡単な方法などご存じでしたら是非ご教示ください。

Discussion