describe it well:
[It] will "attach" your components' logic to the initial generated HTML from the server. Hydration turns the initial HTML snapshot from the server into a fully interactive app that runs in the browser.
In this guide we'll go over how to build an Hono app with client-side logic, unlocking the full potential of your projects.
What are we building?
We're building a simple app that renders a counter component server-side and hydrates it client-side.
It runs in Cloudflare Workers, leveraging its we'll set up two build steps: one for the client-side logic and one for the server-side logic.
Let's build!
First, let's get started with scaffolding a new Hono app.
# Using npm
npm create hono@latest hono-client
# Using yarn
yarn create hono hono-client
# Using pnpm
pnpm create hono hono-client
# Using bun
bunx create-hono hono-client
Make sure to select the
cloudflare-workerstemplate when prompted.
The src directory contains a single index.ts file with a simple Hono app. We're adding a client directory with an index and component:
- src
- index.ts
- client
- index.tsx # logic to mount the app on the client
- Counter.tsx # component to demonstrate client-side logic
Adding the component & mounting point
Let's start by setting up a simple counter component that increments a count when a button is clicked:
// src/client/Counter.tsx
import { useState } from "hono/jsx";
export function Counter() {
const [count, setCount] = useState(0);
return (
<div>
<button onClick={() => setCount((c) => c + 1)} type="button">
Increase count
</button>
<span>Count: {count}</span>
</div>
);
}
Then we import the component & hydrate it in the client entry file:
// src/client/index.tsx
import { StrictMode } from "hono/jsx";
import { hydrateRoot } from "hono/jsx/dom/client";
import { Counter } from "./Counter";
const root = document.getElementById("root");
if (!root) {
throw new Error("Root element not found");
}
hydrateRoot(
root,
<StrictMode>
<Counter />
</StrictMode>
);
We're hydrating the app client-side as opposed to rendering it; the static HTML is rendered server-side by Hono. If you're interested in client-side rendering only, check out the to the
/route and return the statically rendered<Counter />component:
CODE// src/index.tsx
import { Hono } from "hono";
import { jsxRenderer } from "hono/jsx-renderer";
import { Counter } from "./client/Counter";
const app = new Hono();
app.use(
jsxRenderer(
({ children }) => (
<html lang="en">
<head>
<meta charSet="utf-8" />
<meta content="width=device-width, initial-scale=1" name="viewport" />
<title>hono-client</title>
</head>
<div id="root">{children}</div>
</html>
),
{ docType: true }
)
);
app.get("/", (c) => {
return c.render(<Counter />);
});
export default app;
We're almost there. If you run the app now with the
devscript, you'll get an error. Let's fix that by adding the build steps!
Adding build steps and scripts
At this point, we have both server-side and client-side logic and need to add two build steps to our project. Let's install Vite and two plugins to facilitate this.
CODE# Using npm
npm install vite
npm install -D @hono/vite-build @hono/vite-dev-server
# Using yarn
yarn add vite
yarn add -D @hono/vite-build @hono/vite-dev-server
# Using pnpm
pnpm add vite
pnpm add -D @hono/vite-build @hono/vite-dev-server
# Using bun
bun add vite
bun add -D @hono/vite-build @hono/vite-dev-server
In the root of your project, create a
vite.config.tsfile. We'll define the config for both the client-side build and the server-side build:
CODE// vite.config.ts
import build from "@hono/vite-build/cloudflare-workers";
import devServer from "@hono/vite-dev-server";
import cloudflareAdapter from "@hono/vite-dev-server/cloudflare";
import { defineConfig } from "vite";
export default defineConfig(({ mode }) => {
if (mode === "client") {
return {
build: {
rollupOptions: {
input: "./src/client/index.tsx",
output: {
entryFileNames: "assets/[name].js",
},
},
outDir: "./public"
}
};
}
const entry = "./src/index.tsx";
return {
server: { port: 8787 },
plugins: [
devServer({ adapter: cloudflareAdapter, entry }),
build({ entry })
]
};
});
For the client build, the
outDiris set to./public. This is the directory where the Worker will find the client-side script.
Now we need to adjust the
package.jsonscripts to facilitate the new build steps. Additionally, we set the type tomoduleto allow for ESM imports:
CODE// package.json
{
"name": "hono-client",
"type": "module",
"scripts": {
"dev": "vite dev",
"build": "vite build --mode client && vite build",
"deploy": "wrangler deploy --minify"
}
// ...
}
This would be a good moment to add the
publicdirectory to your.gitignore.
Running the app
If you run the app now with the
devscript, you'll see the counter component rendered server-side. The client-side script hasn't been loaded yet, so the counter component won't work.
CODE# Using npm
npm run dev
# Using yarn
yarn dev
# Using pnpm
pnpm dev
# Using bun
bun dev
There's only one step left to make the counter component work. We're almost there!
Load the client-side script
As a final step we need to load the client-side script in the document's head.
For the script that we're loading we need to make a distinction between a development and production environment. Vite allows us to do this easily with its if you'd like to see the full application code. It has a few additional features, like a simple Hono RPC implementation, and a SPA example.
SOCIAL SHARE CARD GENERATOR