Skip to content

Hono JSX

Components written with hono/jsx, the JSX Hono ships: the server the droplets run on already has it. Rendered on the server with hono/jsx, then rendered again in the browser with hono/jsx/dom. The droplet below is a Hono JSX component served by the demo server: its load sets the start, Hono renders it to HTML, and the button works once the bundle takes over.

counter · Hono JSX

3

Server HTML: the button works once Hono JSX hydrates.

Live: rendered by the demo server, hydrated in this page.
src/droplets/counter-hono-jsx/+droplet.tsx
/** @jsxImportSource hono/jsx */
import { use, useEffect, useState } from "hono/jsx";
import type { DropletProps } from "./$types";
export const ssr = true;
export const hydrate = true;
export default function Counter({ data }: DropletProps) {
// What the server load returned. A value when hydrating, a promise when
// the element mounts it fresh: `use` suspends on it.
const { framework, start } = data instanceof Promise ? use(data) : data;
const [added, setAdded] = useState(0);
// False in the server's HTML; true once this component runs in the browser.
const [hydrated, setHydrated] = useState(false);
useEffect(() => setHydrated(true), []);
return (
<section class="demo-card" data-hydrated={String(hydrated)}>
<p class="demo-row">
<span class="demo-tag">counter · {framework}</span>
</p>
<p class="demo-row">
<output class="demo-title" aria-live="polite">
{start + added}
</output>
<button type="button" class="demo-button" onClick={() => setAdded((n) => n + 1)}>
Add one
</button>
</p>
<p class="demo-muted">
{hydrated ? `Hydrated: ${framework} runs the button in this tab.` : `Server HTML: the button works once ${framework} hydrates.`}
</p>
</section>
);
}
Terminal window
npx djs add counter --framework hono-jsx

It installs what the project lacks and adds honoJsx() to renderers invite.config.ts, asking first, then writes src/droplets/counter/+droplet.tsx.

As the project's first .tsx framework, it also sets"jsx": "react-jsx", "jsxImportSource": "hono/jsx" in tsconfig.json.

Every step it takes is in Add a renderer. What it installs for Hono JSX:

PackageInstalled as
@dropletsjs/renderer-hono-jsxa dev dependency, at exactly the version of @dropletsjs/droplets you have
hono@^4.13.0a dependency

By hand:

Terminal window
npm install hono
npm install -D @dropletsjs/renderer-hono-jsx

then import { honoJsx } from "@dropletsjs/renderer-hono-jsx" and honoJsx() in renderers.

--framework hono works too.

File What it is
+droplet.tsx, +droplet.jsx The component, the file’s default export. Its flags are named exports.
+error.tsx, +error.jsx The error page, optional.
+droplet.ts, +droplet.server.ts The loads, as for every framework: Writing droplets.

Which .tsx files are Hono’s. When Hono JSX is the only .tsx framework in renderers, all of them. Next to React, Preact or Solid, a droplet file is Hono’s when it imports hono/jsx or @dropletsjs/renderer-hono-jsx, a subpath included (hono/jsx/dom; hono/client and hono/cookie do not count), or carries a /** @jsxImportSource hono/jsx */ comment (djs add writes one at the top of every Hono JSX component), and names no other .tsx framework. See Which renderer a .tsx file belongs to.

src/droplets/hello/+droplet.tsx
import { use, useState } from "hono/jsx";
import type { DropletProps } from "./$types";
export const hydrate = true;
export default function Hello({ data, children }: DropletProps) {
const [clicks, setClicks] = useState(0);
// A value when hydrating, a promise when mounted from scratch.
const { greeting } = data instanceof Promise ? use(data) : data;
return (
<>
<h1>{greeting}</h1>
<button onClick={() => setClicks((n) => n + 1)}>{clicks}</button>
{children}
</>
);
}
src/droplets/hello/+error.tsx
/** @jsxImportSource hono/jsx */
import type { DropletErrorProps } from "./$types";
import "./error.css";
export default function HelloError({ error, children }: DropletErrorProps) {
return (
<>
<p class="oops">{error.message}</p>
{children}
</>
);
}
Server rendering yes: ssr = true, the default; ssr = false renders it in the browser only
hydrate true (the default), "visible", "interactive", false; each renders again, see below
Prerendering yes: prerender = true with entries
Forms useEnhanceDropletForm(formRef, options?) of @dropletsjs/renderer-hono-jsx/form

Two mistakes stop vite build, and the vite dev server reports them too, each with a message that says what to change:

  • a .tsx droplet that names no framework, or two, when several share the extension:

    droplets: counter/+droplet.tsx: react, solid, preact and hono-jsx all handle this file and it imports none of them; import from react, solid-js, preact or hono/jsx, or add a /** @jsxImportSource <package> */ comment
  • importing another framework, even through a neutral file:

    droplets: a hono-jsx droplet imports react code: src/droplets/counter/+droplet.tsx -> src/droplets/counter/lib.ts -> react/index.js. A droplet uses its own framework's modules and neutral code only.

Flags are read from +droplet.tsx alone. A flag that is not a literal (export const hydrate = isMobile) is ignored, with a warning under vite dev and vite build; a flag exported from +droplet.ts or +droplet.server.ts is ignored.

  • Hydration renders again. hono/jsx/dom cannot adopt server markup, so hydrate replaces the server’s HTML with a fresh render, in the same task. The page never shows a gap, and the host’s children are carried over, but what the visitor did before the bundle loaded (a typed value, focus, a click) is lost: core holds a click on server markup to replay it after hydration, and here the node it hit is gone. In the demo, the count the server rendered is the one the browser renders again, so nothing visible changes.
  • One import path. Hooks, use, Suspense and ErrorBoundary are imported from hono/jsx on both sides. The renderer compiles each module twice, with the automatic runtime of hono/jsx for the server and of hono/jsx/dom for the browser, and resolves hono/jsx to hono/jsx/dom in the browser itself. Attributes are HTML’s: class, for.
  • Data as a promise: use(data) suspends; a rejection reaches the renderer’s error boundary, which shows +error.tsx. Async components work on the server only: in the browser, read data with use.
  • Children: children renders the host’s content.
  • Styles: imported CSS goes to the droplet’s stylesheet.
  • Forms: actionUrl of $droplets/form knows the droplet only while the component first renders, so keep its URL in state, const [add] = useState(() => actionUrl("add")), then <form method="post" action={add}>.
  • Hot updates: Hono JSX has no HMR of its own. Under vite dev with dev.strategy: "hmr" (the default), an edit to a component remounts the droplet in place, without a page reload, and its state starts over. An edit to the load brings new data to the live component, its state kept. See Hot updates.
  • Options: honoJsx({ plugin: false }) leaves compiling to you: the server build then needs jsxImportSource: "hono/jsx", the browser build hono/jsx/dom, with hono/jsx resolving to hono/jsx/dom there.

examples/frameworks/hono-jsx has one droplet per mode (client, ssr-hydrate with an error page, ssr-nohydrate), with loads, a props schema, /api endpoints, env variables and a handle hook. From a clone of the repository:

Terminal window
pnpm install && pnpm build
pnpm --filter @dropletsjs/example-hono-jsx dev # http://localhost:5173: the devtools page

pnpm --filter @dropletsjs/example-hono-jsx build then start serves it on http://localhost:8000; /droplets/ssr-hydrate?who=Ana is the fragment a host pastes into its page.