Renderers
The core of Droplets knows nothing about UI frameworks. A renderer turns
a component file into server HTML and a browser bundle, and claims the file
names it handles. You list the ones you use in vite.config.ts:
import { defineConfig } from "vite";import { droplets } from "@dropletsjs/droplets/vite";import { node } from "@dropletsjs/adapter-node";import { svelte } from "@dropletsjs/renderer-svelte";import { vue } from "@dropletsjs/renderer-vue";
export default defineConfig({ plugins: [droplets({ adapter: node(), renderers: [svelte(), vue()] })],});A +droplet.svelte then goes to Svelte and a +droplet.vue to Vue, in the
same project and on the same page. djs add <name> --framework <name>
installs a renderer and adds it there for you: see
Add a renderer.
Each page has the same droplet, live: the demo server’s load returns a start count and the framework’s name, the server renders it, the browser hydrates it, and a button adds one. Only the framework differs, so the code compares like for like.
The renderers side by side
Section titled “The renderers side by side”| Renderer | Droplet file | Server-rendered | hydrate |
Client JS | Notes |
|---|---|---|---|---|---|
| Svelte | +droplet.svelte |
yes | all four | 17 kB | Svelte 5 in runes mode; flags in <script module> |
| Vue | +droplet.vue |
yes | all four | 30 kB | wrapped in <Suspense>: await props.data works |
| React | +droplet.tsx, .jsx |
yes | all four | 70 kB | React 19; Fast Refresh on any host page |
| Preact | +droplet.tsx, .jsx |
yes | all four | 8 kB | data is always the value; no React alias |
| Solid | +droplet.tsx, .jsx |
yes | all four | 9 kB | hydration keyed per render |
| Hono JSX | +droplet.tsx, .jsx |
yes | all four | 9 kB | hono/jsx; hydration renders again |
| Handlebars | +droplet.hbs |
yes | all four | 0 with hydrate = false, 7 kB with true |
no behavior in the browser; flags in a comment |
| Lit | +droplet.lit.ts, .lit.js |
yes (Lit Labs) | all four | 11 kB | declarative shadow DOM; styles live in the shadow root |
| Plain script | +droplet.script.ts, .script.js |
no: an empty element | always true (client only) |
2 kB | built in, no package; (data, el) |
hydrate: “all four” istrue(the default),"visible","interactive"andfalse; see Flags.ssr = false(rendered in the browser only) andprerender = truework with every renderer but the plain script, which renders nothing on the server anyway.- Client JS, rounded: the gzipped JavaScript a page loads for that
renderer’s counter in a build of apps/demo, the droplet’s bundle and every
chunk it imports, the framework included. Every page also loads the
droplets runtime once, from
/index.js, whatever the frameworks, and a second droplet in the same framework shares the framework’s chunk. Measure your own withvite build: the sizes move with each framework release. .tsxand.jsxbelong to four renderers; see Which renderer a.tsxfile belongs to.
A droplet folder whose component no listed renderer claims fails the build and names the package to install:
droplets: counter/+droplet.vue: no renderer for .vue; install @dropletsjs/renderer-vue and add vue() to renderersAdd a renderer
Section titled “Add a renderer”djs add writes a droplet, and installs and registers its renderer when the
project lacks it. Here it adds React to a project that uses Svelte; each
renderer’s page has its own command and packages.
npx djs add counter --framework reactWhen vite.config.ts does not list React yet, djs add says what it will change and asks before it does (--yes goes ahead without asking):
It installs what the project lacks, with the package manager that runs it (
--pmpicks another):Package Installed 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 It adds the renderer to
vite.config.ts: an import after the last one, andreact()at the end ofrenderers. In a project that hassvelte()already:vite.config.ts import { defineConfig } from "vite";import { droplets } from "@dropletsjs/droplets/vite";import { node } from "@dropletsjs/adapter-node";import { svelte } from "@dropletsjs/renderer-svelte";import { react } from "@dropletsjs/renderer-react";export default defineConfig({plugins: [droplets({ adapter: node(), renderers: [svelte(), react()] })],});A config it cannot edit with confidence (
renderersbuilt elsewhere, a spread, twodroplets()calls) is left as it is, anddjs addprints these two lines to add by hand.If it is the project's first
.tsxframework, it turns JSX on intsconfig.json:"jsx": "react-jsx", "jsxImportSource": "react", andsrc/**/*.tsxinincludewhen the patterns there leave.tsxout. Atsconfig.jsonthat setsjsxalready, itself or through a relativeextends, is left alone.It asks for the target and the optional files, writes
src/droplets/counter/+droplet.tsx(and the files you picked), then its./$types.
With the renderer in vite.config.ts already, it installs and edits nothing: it only writes the droplet. To answer the questions up front, pass them:
npx djs add counter --framework react --target full --hydrate visible --with server,error --yesEvery option is in the djs add reference. By hand, it is the same:
npm install react react-domnpm install -D @dropletsjs/renderer-react @types/react @types/react-domthen the import and react() in renderers, as above.
Renderer options
Section titled “Renderer options”Every renderer compiles its components for you, with its framework’s Vite plugin where there is one. Two options change that:
vitePlugin: { … }forwards options to that plugin:svelte()to@sveltejs/vite-plugin-svelte,vue()to@vitejs/plugin-vue,react()to@vitejs/plugin-react,solid()tovite-plugin-solid;plugin: falseleaves the compiling to you, on those four and onpreact()andhonoJsx(), which compile their JSX themselves. Each page says what your own setup then needs.
Handlebars takes handlebars({ partials, helpers, compile }) and Lit
lit({ prefix }); see their pages. The plain script needs no renderer.
Several frameworks in one project
Section titled “Several frameworks in one project”Every renderer you list works side by side. Each droplet is in one framework, and so is everything it imports, apart from neutral code:
src/ droplets/ svelte-card/+droplet.svelte → Svelte react-card/+droplet.tsx → React: imports from "react" preact-card/+droplet.tsx → Preact: imports from "preact/hooks" solid-card/+droplet.tsx → Solid: imports from "solid-js" hono-card/+droplet.tsx → Hono JSX: imports from "hono/jsx" lit-card/+droplet.lit.ts → Lit tracker/+droplet.script.ts → built in: plain browser code lib/ api.ts neutral: any droplet can import it svelte/Card.svelte Svelte's own react/Card.tsx React's own preact/Card.tsx Preact's own: /** @jsxImportSource preact */ solid/Card.tsx Solid's own: /** @jsxImportSource solid-js */ hono/Card.tsx Hono's own: /** @jsxImportSource hono/jsx */-
Compiled once per framework. When two listed renderers share an extension, every module a droplet reaches is compiled for that droplet’s framework (the plugin tags it
?droplets-renderer=<name>), so a neutrallib/format.tsximported by a React droplet and a Solid droplet is compiled twice, once by each, and bundled with each. Each compiles for its own JSX runtime whateverjsxImportSourcetsconfig.json names; that setting only types the files, and a@jsxImportSourcecomment types one file for its framework. -
No crossing. A droplet that reaches another framework’s modules fails: its files (
.svelte,.svelte.ts,.vue, …) or its packages (svelte,vue,react,preact,solid-js,hono/jsx,lit, …).vite buildwalks every droplet’s module graph;vite devchecks each import as it resolves. The same check keeps CSS out of+droplet.tsand+droplet.server.ts: styles belong to the component. The error names the chain:droplets: a react droplet imports solid code: src/droplets/counter/+droplet.tsx -> src/droplets/counter/lib.ts -> solid-js/dist/solid.js. A droplet uses its own framework's modules and neutral code only.A script droplet is the exception: it may import any package.
-
One framework per droplet, its error page included: an
+error.*in another framework is ignored, with a warning in dev and build, and two components in one folder fail the build (counter/ has 2 droplet components (+droplet.svelte, +droplet.vue); keep one).
Which renderer a .tsx file belongs to
Section titled “Which renderer a .tsx file belongs to”React, Preact, Solid and Hono JSX all claim .tsx and .jsx. With only one
of them in renderers, every .tsx file is its own. With two or more, a
droplet file belongs to the one whose package it names, by an import (a
subpath included) or by a /** @jsxImportSource <package> */ comment:
| Renderer | Its packages |
|---|---|
| React | react, react-dom, @dropletsjs/renderer-react |
| Preact | preact, preact-render-to-string, @dropletsjs/renderer-preact |
| Solid | solid-js, @dropletsjs/renderer-solid |
| Hono JSX | hono/jsx, @dropletsjs/renderer-hono-jsx |
djs add writes the comment at the top of every component it creates. Hono
JSX owns hono/jsx, not hono, so a droplet that imports hono/client or
hono/cookie names nothing. A file that names none of the four, or two of
them, fails the build:
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> */ commentAn +error.tsx that names none, or several, is the droplet’s framework.
The comment also types the file’s JSX for its framework when
tsconfig.json names another jsxImportSource.
The examples
Section titled “The examples”examples/shop puts six frameworks in one project: nine droplets, each in
the framework that suits it. examples/frameworks/<name> has one project
per framework: one droplet per mode (client, ssr-hydrate,
ssr-nohydrate); the Svelte one adds a script droplet, the Lit one a form.
apps/demo, which serves the live droplets of these pages, has all nine
counters.
Writing a renderer
Section titled “Writing a renderer”The contract lives in @dropletsjs/droplets (DropletRenderer,
RendererServerModule, RendererClientModule): Vite plugins, a server module
that renders { data, form? } or { error } (form is an
action’s result, passed only when there
is one), a client module with mount,
hydrate and unmount, optional flag reading (readFlags, from the
component’s source only; readExportedFlags of @dropletsjs/droplets/vite
reads a module’s exports), a once-per-page client
setup (clientSetup), the package ./$types takes DropletProps and
DropletErrorProps from (componentTypes), and an optional clientDev module for vite dev alone. Its
update(instance, props) gives a live instance a load edit’s new data
without a remount; a production build leaves the module out.
For mixed projects, a renderer declares packages (its framework’s packages
and its own, which mark modules as its own; a subpath such as hono/jsx
claims that part of a package only) and suffixes (file endings
beyond its extensions, such as Svelte’s .svelte.ts). A renderer that may
share an extension passes plugins as a function of a RendererScope:
scope.include is a RegExp matching the modules tagged for it, to hand to
its framework’s Vite plugin (include) so that plugin leaves the others’
files alone. @dropletsjs/droplets/testing ships rendererConformance(), the
vitest suite every renderer passes (Lit’s shadow DOM included, see
its page), and fakeRenderer(), a complete
reference renderer. See the
API reference.