Skip to content

Handlebars

Handlebars templates, precompiled at build and rendered on the server with handlebars/runtime. A template has no code of its own in the browser: there is nothing to hydrate it with. The droplet below is the same counter as on the other pages, rendered by the same demo server, and it stops there: it shows the start from the load, but there is no button, because nothing in the page could make one count.

counter · Handlebars

3

Server HTML only: a Handlebars template has no code in the browser, so there is no button to press.

Live: rendered by the demo server. hydrate = false, so the page loads no JavaScript for it.
src/droplets/counter-handlebars/+droplet.hbs
{{!--
export ssr = true
export hydrate = false
--}}
{{!-- A template has no browser code: rendered on the server, never hydrated. --}}
<section class="demo-card" data-hydrated="false">
<p class="demo-row"><span class="demo-tag">counter · {{data.framework}}</span></p>
<p class="demo-row">
<output class="demo-title">{{data.start}}</output>
</p>
<p class="demo-muted">Server HTML only: a Handlebars template has no code in the browser, so there is no button to press.</p>
</section>
Terminal window
npx djs add counter --framework handlebars

It installs what the project lacks and adds handlebars() to renderers invite.config.ts, asking first, then writes src/droplets/counter/+droplet.hbs.

Every step it takes is in Add a renderer. What it installs for Handlebars:

PackageInstalled as
@dropletsjs/renderer-handlebarsa dev dependency, at exactly the version of @dropletsjs/droplets you have

The renderer brings Handlebars itself: handlebars is its dependency, not yours.

By hand:

Terminal window
npm install -D @dropletsjs/renderer-handlebars

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

File What it is
+droplet.hbs The template. Its flags go in the comment it opens with.
+error.hbs The error page, optional.
src/partials/**/*.hbs Partials, registered by their path without the extension: {{> footer}}, {{> cards/item}}.
src/handlebars.ts Helpers: every exported function is a helper of the same name, on the server and in the browser.
+droplet.ts, +droplet.server.ts The loads, as for every framework: Writing droplets.

.hbs is Handlebars’ alone: any +droplet.hbs is a Handlebars droplet.

A template sees {{data.…}} (what the loads returned), {{form.…}} after a form action, {{error.…}} in the error page and {{{children}}} for the host’s content (triple braces: it is HTML). @droplet, @kind and @renderId are data variables of the render.

{{!-- src/droplets/hello/+droplet.hbs --}}
{{!--
export ssr = true
export hydrate = false
--}}
<h1>{{data.greeting}}</h1>
<p>{{upper data.who}}</p>
{{> footer}}
{{{children}}}
<style>
h1 { font-family: system-ui, sans-serif; }
</style>
<style src="./theme.css"></style>
{{!-- src/droplets/hello/+error.hbs --}}
<p class="oops">{{error.message}}</p>
{{{children}}}
<style>
.oops { color: crimson; }
</style>
// src/handlebars.ts: every exported function is a helper
export const upper = (value: unknown) => String(value).toUpperCase();
Server rendering yes: ssr = true, the default; ssr = false renders the template in the browser instead
hydrate true (the default), "visible", "interactive", false; none adds behavior, see below
Prerendering yes: prerender = true with entries
Forms <form method="post" action="{{action "add"}}">, posted natively; data-droplet-enhance posts it by fetch

The flags comment is Droplets’ own syntax inside a Handlebars comment, so nothing else would catch a mistake in it: every mistake stops vite build, and the vite dev server reports it too. A flag line in any other comment:

droplets: counter/+droplet.hbs: flags go in the comment the template starts with, before anything else

A misspelled flag, one declared twice, a value that is not a literal, and a line in the flags comment that is no flag:

droplets: counter/+droplet.hbs: unknown flag "hydrat" (expected ssr, hydrate, prerender)
droplets: counter/+droplet.hbs: flag "hydrate" is declared twice
droplets: counter/+droplet.hbs: flag "hydrate" must be true, false, "visible" or "interactive", found "maybe"
droplets: counter/+droplet.hbs: flag "ssr" must be true or false, found "yes"
droplets: counter/+droplet.hbs: expected `export <flag> = true|false` in the flags comment, found "keep it simple"

A leading comment with no export line in it is an ordinary comment: it declares no flags, and the defaults apply.

A <style> block is static CSS, and the build refuses one it cannot take out of the template:

droplets: src/droplets/counter/+droplet.hbs:1: a <style> block cannot contain {{…}}: CSS is static
droplets: src/droplets/counter/+droplet.hbs:4: a <style> block goes at the top of the template, outside {{#…}} blocks
droplets: src/partials/footer.hbs: a partial has no <style>: put it in the droplet templates that use it
  • No behavior in the browser. A template is HTML with holes; Handlebars has no events or state, so the renderer has nothing to attach. hydrate keeps the server’s HTML and wires the host’s children into it; mount renders the template in the browser (an ssr = false droplet, an error page shown there, a remount in dev), after awaiting a load’s promise. For a droplet without children or a browser load, hydrate = false is the lean choice, as in the demo: no JavaScript at all for it. With hydrate = true the same counter loads 7.3 kB (gzip) for the runtime and the template, and still shows no button.
  • A button that does something needs one of two things:
    • a form: {{action "add"}} writes where it posts for an action in +droplet.server.ts, and data-droplet-enhance on the <form> makes /index.js post it by fetch and render the result in place, even with hydrate = false: the server renders the fragment again, with the props and page that {{action}} wrote into the action URL. See Actions;
    • or browser code next to it, in another droplet: a plain script builds its own UI from its data.
  • Templates are precompiled by the renderer’s Vite plugin, in vite dev and vite build; only handlebars/runtime ships, bundled into the server build and, for a droplet that hydrates, sent to the browser.
  • Partials and helpers go into the renderer’s own Handlebars environment, never the global one. action and children are the renderer’s helpers; a project helper by those names is ignored.
  • Styles are <style> blocks in +droplet.hbs and +error.hbs, inline or with src (a file, relative to the template). They are taken out of the template at build, in order, and become the droplet’s stylesheet like a component’s CSS elsewhere: through Vite (PostCSS, Tailwind, lang="scss"), scoped to the element, nothing left in the HTML. A block is static: at the template’s top level, outside {{#…}} blocks, with no {{…}} inside, and a src block stays empty. Partials have none, since every droplet registers them.
  • Flags are export <flag> = <value> lines (export const works too) in the comment the template opens with, one per line or all on one line ({{!-- export hydrate = false; export prerender = true --}}). ssr and prerender take true or false; hydrate also takes "visible" or "interactive", in quotes. A flag exported from +droplet.ts or +droplet.server.ts is ignored. +error.hbs follows the droplet’s flags: flags it declares are ignored, with a warning under vite dev.
  • Options: handlebars({ partials, helpers, compile }) moves the partials folder (false for none) or the helpers module (false for none), and passes options to Handlebars.precompile (strict, noEscape, …).
  • Hot updates: under vite dev with dev.strategy: "hmr" (the default), an edit to a template that does not hydrate asks the server for the fragment again and swaps the droplet’s markup in place; one that hydrates remounts in place, since a template has no HMR of its own and no state to keep. Neither reloads the page. An edit to a load brings a hydrated template new data: it renders again in place. See Hot updates.

examples/frameworks/handlebars has one droplet per mode (client, ssr-hydrate with an error page, ssr-nohydrate), each rendering the card partial of src/partials/, with loads, a props schema, /api endpoints, env variables and a handle hook. From a clone of the repository:

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

pnpm --filter @dropletsjs/example-handlebars build then start serves it on http://localhost:8000; /droplets/ssr-hydrate?who=Ana is the fragment a host pastes into its page.