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
Server HTML only: a Handlebars template has no code in the browser, so there is no button to press.
{{!--export ssr = trueexport 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>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: "Handlebars", start: 3 };};Add it to a project
Section titled “Add it to a project”npx djs add counter --framework handlebarsIt 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:
| Package | Installed as |
|---|---|
@dropletsjs/renderer-handlebars | a dev dependency, at exactly the version of @dropletsjs/droplets you have |
The renderer brings Handlebars itself: handlebars is its dependency, not yours.
By hand:
npm install -D @dropletsjs/renderer-handlebarsthen import { handlebars } from "@dropletsjs/renderer-handlebars" and handlebars() in renderers.
The files
Section titled “The files”| 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 = trueexport 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 helperexport const upper = (value: unknown) => String(value).toUpperCase();What it supports
Section titled “What it supports”| 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 elseA 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 twicedroplets: 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 staticdroplets: src/droplets/counter/+droplet.hbs:4: a <style> block goes at the top of the template, outside {{#…}} blocksdroplets: src/partials/footer.hbs: a partial has no <style>: put it in the droplet templates that use itSpecifics
Section titled “Specifics”- No behavior in the browser. A template is HTML with holes; Handlebars
has no events or state, so the renderer has nothing to attach.
hydratekeeps the server’s HTML and wires the host’s children into it;mountrenders the template in the browser (anssr = falsedroplet, an error page shown there, a remount in dev), after awaiting a load’s promise. For a droplet without children or a browserload,hydrate = falseis the lean choice, as in the demo: no JavaScript at all for it. Withhydrate = truethe 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, anddata-droplet-enhanceon the<form>makes/index.jspost it byfetchand render the result in place, even withhydrate = 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.
- a form:
- Templates are precompiled by the renderer’s Vite plugin, in
vite devandvite build; onlyhandlebars/runtimeships, 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.
actionandchildrenare the renderer’s helpers; a project helper by those names is ignored. - Styles are
<style>blocks in+droplet.hbsand+error.hbs, inline or withsrc(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 asrcblock stays empty. Partials have none, since every droplet registers them. - Flags are
export <flag> = <value>lines (export constworks too) in the comment the template opens with, one per line or all on one line ({{!-- export hydrate = false; export prerender = true --}}).ssrandprerendertaketrueorfalse;hydratealso takes"visible"or"interactive", in quotes. A flag exported from+droplet.tsor+droplet.server.tsis ignored.+error.hbsfollows the droplet’s flags: flags it declares are ignored, with a warning undervite dev. - Options:
handlebars({ partials, helpers, compile })moves the partials folder (falsefor none) or the helpers module (falsefor none), and passes options toHandlebars.precompile(strict,noEscape, …). - Hot updates: under
vite devwithdev.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 newdata: it renders again in place. See Hot updates.
The example
Section titled “The example”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:
pnpm install && pnpm buildpnpm --filter @dropletsjs/example-handlebars dev # http://localhost:5173: the devtools pagepnpm --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.