Skip to content

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

3

Server HTML: the button works once React hydrates.

Live: rendered by the demo server, hydrated in this page.
src/droplets/counter-react/+droplet.tsx
/** @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>
);
}
Terminal window
npx djs add counter --framework react

It 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:

PackageInstalled as
@dropletsjs/renderer-reacta dev dependency, at exactly the version of @dropletsjs/droplets you have
@types/react@^19.0.0a dev dependency
@types/react-dom@^19.0.0a dev dependency
react@^19.0.0a dependency
react-dom@^19.0.0a dependency

By hand:

Terminal window
npm install react react-dom
npm install -D @dropletsjs/renderer-react @types/react @types/react-dom

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

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.

src/droplets/hello/+droplet.tsx
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}
</>
);
}
src/droplets/hello/+error.tsx
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.

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 .tsx droplet that names no framework, or two, when several share the extension. With react() and preact() in renderers:

    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> */ comment

    The 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 under vite dev and vite 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.tsx that names another framework is not used; under vite dev and vite build warn once counter/+error.tsx is not a react component like the droplet; ignored, the error page is written in the droplet's framework.

  • 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.tsx with what handleError returned.
  • Children: children renders the host’s content, in +droplet.tsx and 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")) with actionUrl of $droplets/form, then <form method="post" action={add}>. useEnhanceDropletForm(formRef, { action: "add" }) sends it with fetch and shows the result in place; without onResult, it calls result.update(). See Actions.
  • Errors in the browser: React’s recoverable, uncaught and caught errors go to console.error as [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, with dev.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 new data to the live component, which keeps its state. See Hot updates.
  • Options: react({ vitePlugin }) passes options to @vitejs/plugin-react. With react({ plugin: false }) you register the plugin yourself; the renderer still needs it there, since the Fast Refresh preamble comes from it.

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:

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

pnpm --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.