React
React 19 components, compiled by @vitejs/plugin-react, rendered on the
server with renderToString (React’s edge build on Workers) and hydrated
with hydrateRoot. The droplet below is a React component served by the
demo server: its load sets the start, React renders it to HTML, and the
button works once the bundle hydrates it.
counter · React
Server HTML: the button works once React hydrates.
/** @jsxImportSource react */import { use, useEffect, useState } from "react";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 className="demo-card" data-hydrated={String(hydrated)}> <p className="demo-row"> <span className="demo-tag">counter · {framework}</span> </p> <p className="demo-row"> <output className="demo-title" aria-live="polite"> {start + added} </output> <button type="button" className="demo-button" onClick={() => setAdded((n) => n + 1)}> Add one </button> </p> <p className="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: "React", start: 3 };};Add it to a project
Section titled “Add it to a project”npx djs add counter --framework reactIt installs what the project lacks and adds react() 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": "react" in tsconfig.json.
Every step it takes is in Add a renderer. What it installs for React:
| Package | Installed as |
|---|---|
@dropletsjs/renderer-react | a dev dependency, at exactly the version of @dropletsjs/droplets you have |
@types/react@^19.0.0 | a dev dependency |
@types/react-dom@^19.0.0 | a dev dependency |
react@^19.0.0 | a dependency |
react-dom@^19.0.0 | a dependency |
By hand:
npm install react react-domnpm install -D @dropletsjs/renderer-react @types/react @types/react-domthen import { react } from "@dropletsjs/renderer-react" and react() in renderers.
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 of this file. |
+error.tsx, +error.jsx |
The error page, optional. It follows the droplet’s flags. |
+droplet.ts, +droplet.server.ts |
The loads, as for every framework: Writing droplets. |
The flags are literal export const declarations of the component file. A
flag exported from +droplet.ts or +droplet.server.ts is ignored.
Which .tsx files are React’s. When React is the only .tsx
framework in renderers, all of them. Next to Preact, Solid or Hono JSX, a droplet file is
React’s when it imports react, react-dom or @dropletsjs/renderer-react, a subpath included (react/jsx-runtime), or carries a /** @jsxImportSource react */
comment (djs add writes one at the top of every React component), and
names no other .tsx framework. See
Which renderer a .tsx file belongs to.
import { use, useState } from "react";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} </> );}import type { DropletErrorProps } from "./$types";import "./error.css";
export default function HelloError({ error, children }: DropletErrorProps) { return ( <> <p className="oops">{error.message}</p> {children} </> );}error is what handleError in +droplet.server.ts (or +droplet.ts)
returned; see Errors.
What it supports
Section titled “What it supports”| Server rendering | yes: ssr = true, the default; ssr = false mounts it in the browser only (createRoot) |
hydrate |
true (the default), "visible", "interactive", false |
| Prerendering | yes: prerender = true, once per event entries returns: Prerendering |
| Forms | useEnhanceDropletForm(formRef, options?) of @dropletsjs/renderer-react/form |
Two mistakes fail vite build, and vite dev as well, with a message that
names the fix:
-
a
.tsxdroplet that names no framework, or two, when several share the extension. Withreact()andpreact()inrenderers:droplets: counter/+droplet.tsx: react and preact both handle this file and it imports neither; import from react or preact, or add a /** @jsxImportSource <package> */ commentThe message lists every renderer that shares the extension, in the order of
renderers. -
a React droplet that reaches another configured framework, even through a neutral file:
droplets: a react droplet imports preact code: src/droplets/counter/+droplet.tsx -> src/lib/preact-label.ts -> preact/dist/preact.mjs. A droplet uses its own framework's modules and neutral code only.
Other mistakes are ignored, with a warning:
-
a flag that is not a literal, such as
export const hydrate = isMobile, warns undervite devandvite build, and the flag keeps its default:[droplets:framework] `export const hydrate` must be true, false, "visible" or "interactive"; ignoring it { droplet: 'counter', found: 'isMobile' } -
an
+error.tsxthat names another framework is not used; undervite devandvite buildwarn oncecounter/+error.tsx is not a react component like the droplet; ignored, the error page is written in the droplet's framework.
Specifics
Section titled “Specifics”- Data as a promise:
use(data)suspends while it is one (a droplet mounted from scratch: client-only, remounted in dev). With an error page, the droplet renders under<Suspense>inside the renderer’s error boundary, and a rejection, or anything else that throws while rendering, shows+error.tsxwith whathandleErrorreturned. - Children:
childrenrenders the host’s content, in+droplet.tsxand in+error.tsx. - Styles: imported CSS goes to the droplet’s stylesheet, the error page’s included: React components carry no inline styles, and the element links that stylesheet whenever the droplet is on the page.
- Forms: keep the action’s URL from the first render,
const [add] = useState(() => actionUrl("add"))withactionUrlof$droplets/form, then<form method="post" action={add}>.useEnhanceDropletForm(formRef, { action: "add" })sends it withfetchand shows the result in place; withoutonResult, it callsresult.update(). See Actions. - Errors in the browser: React’s recoverable, uncaught and caught errors
go to
console.erroras[droplets] <droplet> (<kind>, react); what the renderer’s own boundary catches is reported by the framework instead. - Fast Refresh works on any host page under
vite dev, withdev.strategy: "hmr"(the default). The renderer installs React’s preamble itself and compiles Fast Refresh into React’s modules only, never another framework’s. As in any React app, an edit keeps the component’s state when every export of the file is a component or unchanged. The flags (ssr,hydrate,prerender) are exports Fast Refresh ignores. A new value for one is a new render contract, which shows a notice and leaves the droplet as it is. Another non-component export whose value changes makes Fast Refresh give up, and the droplet remounts in place: the page never reloads. An edit to the load (+droplet.server.ts,+droplet.ts) brings newdatato the live component, which keeps its state. See Hot updates. - Options:
react({ vitePlugin })passes options to@vitejs/plugin-react. Withreact({ plugin: false })you register the plugin yourself; the renderer still needs it there, since the Fast Refresh preamble comes from it.
The example
Section titled “The example”examples/frameworks/react
has one droplet per mode, client (ssr = false), ssr-hydrate (with
+error.tsx) and ssr-nohydrate (hydrate = false), with loads, a props
schema, /api endpoints, env variables and a handle hook. Its droplets
render in <djs-react>. From a clone of the repository:
pnpm install && pnpm buildpnpm --filter @dropletsjs/example-react dev # http://localhost:5173: the devtools pagepnpm --filter @dropletsjs/example-react build then start serves it on
http://localhost:8000; /droplets/ssr-hydrate?who=Ana is the fragment a
host pastes into its page.