Hono

Hono is a small, simple, and ultrafast web framework for Cloudflare Pages and Workers, Deno, and Bun. In this guide, you will create a new Hono application and deploy it using Cloudflare Pages.

Create a new project

Use the create-cloudflare CLI (C3) to create a new project. C3 will create a new project directory, initiate Hono’s official setup tool, and provide the option to deploy instantly.

To use create-cloudflare to create a new Hono project, run the following command:

$ npm create cloudflare@latest my-hono-app -- --framework=hono

Open your project and create a src/server.js file (or src/server.ts if you are using TypeScript). Add the following content to your file:

import { Hono } from "hono";
const app = new Hono();

app.get("/", (ctx) => ctx.text("Hello world, this is Hono!!"));

export default app;

To serve static files like CSS, image or JavaScript files, add the following to your src/server.js/ts file:

app.get("/public/*", async (ctx) => {
  return await ctx.env.ASSETS.fetch(ctx.req.raw);
});

This will cause all the files in the public folder within dist to be served in your application.

Note

The dist directory is created and used during the bundling process. You will need to create a public directory in the dist directory. Having public inside dist is not generally wanted as dist is not a directory to commit to your repository whilst public is.

There are different alternatives to fix this issue. For example, you can configure your .gitignore file to include the dist directory, but ignore all its context except the public directory. Alternatively, you can create a public directory somewhere else and copy it inside dist as part of the bundling process.

Open your package.json file and update the scripts section:

js

    "scripts": {
        "dev": "run-p dev:*",
        "dev:wrangler": "wrangler pages dev dist --live-reload",
        "dev:esbuild": "esbuild --bundle src/server.js --format=esm --watch --outfile=dist/_worker.js",
        "build": "esbuild --bundle src/server.js --format=esm --outfile=dist/_worker.js",
        "deploy": "wrangler pages publish dist"
    },

ts

    "scripts": {
        "dev": "run-p dev:*",
        "dev:wrangler": "wrangler pages dev dist --live-reload",
        "dev:esbuild": "esbuild --bundle src/server.ts --format=esm --watch --outfile=dist/_worker.js",
        "build": "esbuild --bundle src/server.ts --format=esm --outfile=dist/_worker.js",
        "deploy": "wrangler pages publish dist"
    },

Then, run the following command.

$ npm install npm-run-all --save-dev

Installing npm-run-all enables you to use a single command (npm run dev) to run npm run dev:wrangler and npm run dev:esbuild simultaneously in watch mode.

Run in local dev

Start your dev workflow by running:

$ npm run dev

You should be able to review your generated web application at http://localhost:8788.

Before you continue

All of the framework guides assume you already have a fundamental understanding of Git. If you are new to Git, refer to this summarized Git handbook on how to set up Git on your local machine.

If you clone with SSH, you must generate SSH keys on each computer you use to push or pull from GitHub.

Refer to the GitHub documentation and Git documentation for more information.

Create a GitHub repository

Create a new GitHub repository by visiting repo.new. After creating a new repository, go to your newly created project directory to prepare and push your local application to GitHub by running the following commands in your terminal:

$ git init
$ git remote add origin https://github.com/<your-gh-username>/<repository-name>
$ git add .
$ git commit -m "Initial commit"
$ git branch -M main
$ git push -u origin main

Deploy with Cloudflare Pages

Deploy via the create-cloudflare CLI (C3)

If you use create-cloudflare(C3) to create your new Hono project, C3 will install all dependencies needed for your project and prompt you to deploy your project via the CLI. If you deploy, your site will be live and you will be provided with a deployment URL.

Deploy via the Cloudflare dashboard

1. Log in to the Cloudflare dashboard and select your account.
2. In Account Home, select Workers & Pages > Create application > Pages > Connect to Git.
3. Select the new GitHub repository that you created and, in the Set up builds and deployments section, provide the following information:

Configuration option	Value
Production branch	main
Build command	npm run build
Build directory	dist

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing my-hono-app, your project dependencies, and building your site before deploying it.

Note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the Get started guide.

After deploying your site, you will receive a unique subdomain for your project on *.pages.dev. Every time you commit new code to your Hono site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to preview deployments on new pull requests, so you can preview how changes look to your site before deploying them to production.

Related resources

Tutorials

For more tutorials involving Hono, refer to the following resources:

• Build a Comments API : In this tutorial, you will learn how to use D1 to add comments to a static blog site. To do this, you will construct a new D1 database, and build a JSON API that allows the creation and retrieval of comments.
• Build a Staff Directory Application : In this tutorial, you will learn how to use D1 to build a staff directory. This application will allow users to access information about an organization’s employees and give admins the ability to add new employees directly within the app. To do this, you will first need to set up a D1 database to manage data seamlessly, then you will develop and deploy your application using the HonoX Framework and Cloudflare Pages.
• Recommend products on e-commerce sites using Workers AI and Stripe : E-commerce and media sites often work on increasing the average transaction value to boost profitability. One of the strategies to increase the average transaction value is “cross-selling,” which involves recommending related products. Cloudflare offers a range of products designed to build mechanisms for retrieving data related to the products users are viewing or requesting. In this tutorial, you will experience developing functionalities necessary for cross-selling by creating APIs for related product searches and product recommendations.
• Use R2 As static asset storage for your Pages app
• Build a Retrieval Augmented Generation (RAG) AI
• Build a Slackbot
• Create a fine-tuned OpenAI model with R2
• Create a serverless, globally distributed REST API with Fauna

Demo apps

For demo applications using Hono, refer to the following resources:

• shrty.dev : A URL shortener that makes use of KV and Workers Analytics Engine. The admin interface uses Function Calling. Go Shorty!
• Homie - Home Automation using Function Calling : A home automation tool that uses AI Function calling to change the color of lightbulbs in your home.
• Hackathon Helper : A series of starters for Hackathons. Get building quicker! Python, Streamlit, Workers, and Pages starters for all your AI needs!
• NBA Finals Polling and Predictor : This stateful polling application uses Cloudflare Workers AI, Cloudflare Pages, Cloudflare Durable Objects, and Hono to keep track of users' votes for different basketball teams and generates personal predictions for the series.
• Workers for Platforms Example Project : Explore how you could manage thousands of Workers with a single Cloudflare Workers account.
• Whatever-ify : Turn yourself into...whatever. Take a photo, get a description, generate a scene and character, then generate an image based on that calendar.
• Staff Directory demo : Built using the powerful combination of HonoX for backend logic, Cloudflare Pages for fast and secure hosting, and Cloudflare D1 for seamless database management.
• Phoney AI : This application uses Cloudflare Workers AI, Twilio, and AssemblyAI. Your phone is an input and output device.
• Vanilla JavaScript Chat Application using Cloudflare Workers AI : A web based chat interface built on Cloudflare Pages that allows for exploring Text Generation models on Cloudflare Workers AI. Design is built using tailwind.