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
Server HTML: the button works once Hono JSX hydrates.
/** @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> );}import type { LoadEvent } from "./$types";
/** * Runs on the server only. The count starts where the server says, and the * name of the framework comes with it. The same for everyone, so a browser * (or a cache in front) may keep it for five minutes. */export const load = ({ setHeaders }: LoadEvent) => { setHeaders({ "cache-control": "public, max-age=300" }); return { framework: "Hono JSX", start: 3 };};Add it to a project
Section titled “Add it to a project”npx djs add counter --framework hono-jsxIt 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:
| Package | Installed as |
|---|---|
@dropletsjs/renderer-hono-jsx | a dev dependency, at exactly the version of @dropletsjs/droplets you have |
hono@^4.13.0 | a dependency |
By hand:
npm install hononpm install -D @dropletsjs/renderer-hono-jsxthen import { honoJsx } from "@dropletsjs/renderer-hono-jsx" and honoJsx() in renderers.
--framework hono works too.
The files
Section titled “The files”| 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.
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} </> );}/** @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} </> );}What it supports
Section titled “What it supports”| 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
.tsxdroplet 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.
Specifics
Section titled “Specifics”- Hydration renders again.
hono/jsx/domcannot adopt server markup, sohydratereplaces 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,SuspenseandErrorBoundaryare imported fromhono/jsxon both sides. The renderer compiles each module twice, with the automatic runtime ofhono/jsxfor the server and ofhono/jsx/domfor the browser, and resolveshono/jsxtohono/jsx/domin 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, readdatawithuse. - Children:
childrenrenders the host’s content. - Styles: imported CSS goes to the droplet’s stylesheet.
- Forms:
actionUrlof$droplets/formknows 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 devwithdev.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 newdatato the live component, its state kept. See Hot updates. - Options:
honoJsx({ plugin: false })leaves compiling to you: the server build then needsjsxImportSource: "hono/jsx", the browser buildhono/jsx/dom, withhono/jsxresolving tohono/jsx/domthere.
The example
Section titled “The example”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:
pnpm install && pnpm buildpnpm --filter @dropletsjs/example-hono-jsx dev # http://localhost:5173: the devtools pagepnpm --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.