Skip to content

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:

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.

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” is true (the default), "visible", "interactive" and false; see Flags. ssr = false (rendered in the browser only) and prerender = true work 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 with vite build: the sizes move with each framework release.
  • .tsx and .jsx belong to four renderers; see Which renderer a .tsx file 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 renderers

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.

Terminal window
npx djs add counter --framework react

When 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):

  1. It installs what the project lacks, with the package manager that runs it (--pm picks another):

    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
  2. It adds the renderer to vite.config.ts: an import after the last one, and react() at the end of renderers. In a project that has svelte() 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 (renderers built elsewhere, a spread, two droplets() calls) is left as it is, and djs add prints these two lines to add by hand.

  3. If it is the project's first .tsx framework, it turns JSX on in tsconfig.json:"jsx": "react-jsx", "jsxImportSource": "react", and src/**/*.tsx ininclude when the patterns there leave .tsx out. A tsconfig.json that setsjsx already, itself or through a relative extends, is left alone.

  4. 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:

Terminal window
npx djs add counter --framework react --target full --hydrate visible --with server,error --yes

Every option is in the djs add reference. By hand, it is the same:

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

then the import and react() in renderers, as above.

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() to vite-plugin-solid;
  • plugin: false leaves the compiling to you, on those four and on preact() and honoJsx(), 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.

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 neutral lib/format.tsx imported 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 whatever jsxImportSource tsconfig.json names; that setting only types the files, and a @jsxImportSource comment 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 build walks every droplet’s module graph; vite dev checks each import as it resolves. The same check keeps CSS out of +droplet.ts and +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).

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

An +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.

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.

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.