Vue
Vue 3 single-file components (3.5 or later), compiled by @vitejs/plugin-vue,
rendered on the server with vue/server-renderer and hydrated with
createSSRApp. The droplet below is a Vue component served by the demo
server: its load sets the start, Vue renders it to HTML, and the button works
once the bundle hydrates it.
counter · Vue
Server HTML: the button works once Vue hydrates.
<script lang="ts">export const ssr = true;export const hydrate = true;</script>
<script setup lang="ts">import { onMounted, ref } from "vue";import type { DropletProps } from "./$types";
const props = defineProps<DropletProps>();// What the server load returned. A value when hydrating, a promise when the// element mounts it fresh: the renderer's <Suspense> waits for it.const { framework, start } = await props.data;
const added = ref(0);// False in the server's HTML; true once this component runs in the browser.const hydrated = ref(false);onMounted(() => (hydrated.value = true));</script>
<template> <section class="demo-card" :data-hydrated="hydrated"> <p class="demo-row"><span class="demo-tag">counter · {{ framework }}</span></p> <p class="demo-row"> <output class="demo-title" aria-live="polite">{{ start + added }}</output> <button type="button" class="demo-button" @click="added += 1">Add one</button> </p> <p class="demo-muted"> {{ hydrated ? `Hydrated: ${framework} runs the button in this tab.` : `Server HTML: the button works once ${framework} hydrates.` }} </p> </section></template>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: "Vue", start: 3 };};Add it to a project
Section titled “Add it to a project”npx djs add counter --framework vueIt installs what the project lacks and adds vue() to renderers invite.config.ts, asking first, then writes src/droplets/counter/+droplet.vue.
Every step it takes is in Add a renderer. What it installs for Vue:
| Package | Installed as |
|---|---|
@dropletsjs/renderer-vue | a dev dependency, at exactly the version of @dropletsjs/droplets you have |
vue@^3.5.0 | a dependency |
By hand:
npm install vuenpm install -D @dropletsjs/renderer-vuethen import { vue } from "@dropletsjs/renderer-vue" and vue() in renderers.
The files
Section titled “The files”| File | What it is |
|---|---|
+droplet.vue |
The component. Its flags go in a plain <script> next to <script setup>. |
+error.vue |
The error page, optional. It follows the droplet’s flags, and compiles in custom-element mode, so its styles travel with its markup. |
+droplet.ts, +droplet.server.ts |
The loads, as for every framework: Writing droplets. |
.vue is Vue’s alone: any +droplet.vue is a Vue droplet. Other .vue
files a droplet imports are Vue’s own too, so only Vue droplets may import
them.
The flags are read from the plain <script> block alone, the one block that
can export, as literal export const declarations. Vue wants both blocks in
the same lang. A flag in a comment, the template, +droplet.ts or
+droplet.server.ts is ignored.
The props are data (what the loads returned) and form after a form
action. The host’s content goes where <DropletChildren /> is:
<script lang="ts">export const hydrate = true;</script>
<script setup lang="ts">import { ref } from "vue";import { DropletChildren } from "@dropletsjs/renderer-vue/children";import type { DropletProps } from "./$types";
const props = defineProps<DropletProps>();// A value when hydrating, a promise when mounted from scratch.const { greeting } = await props.data;const clicks = ref(0);</script>
<template> <h1>{{ greeting }}</h1> <button @click="clicks += 1">{{ clicks }}</button> <DropletChildren /></template><script setup lang="ts">import { DropletChildren } from "@dropletsjs/renderer-vue/children";import type { DropletErrorProps } from "./$types";defineProps<DropletErrorProps>();</script>
<template> <p class="oops">{{ error.message }}</p> <DropletChildren /></template>
<style scoped>.oops { color: crimson; }</style>error is what handleError in +droplet.server.ts (or +droplet.ts)
returned; see Errors.
What it supports
Section titled “What it supports”| Server rendering | yes: ssr = true, the default; ssr = false mounts it in the browser only (createApp) |
hydrate |
true (the default), "visible", "interactive", false |
| Prerendering | yes: prerender = true, once per event entries returns: Prerendering |
| Forms | useEnhanceDropletForm(formRef, options?) of @dropletsjs/renderer-vue/form |
Two mistakes fail vite build, and vite dev as well, with a message that
names the fix:
-
a Vue droplet that reaches another configured framework, even through a neutral file (the import goes through the component’s
<script setup>block, which the chain folds into the file):droplets: a vue droplet imports react code: src/droplets/counter/+droplet.vue -> src/lib/react-label.ts -> react/index.js. A droplet uses its own framework's modules and neutral code only. -
a second component in the folder:
droplets: counter/ has 2 droplet components (+droplet.svelte, +droplet.vue); keep one
Other mistakes are ignored, with a warning:
-
a flag that is not a literal, such as
export const hydrate = isMobile, warns undervite devandvite 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 page in another framework next to a Vue droplet (an
+error.svelte, say) is not used;vite devandvite buildwarn oncecounter/+error.svelte is not a vue component like the droplet; ignored, the error page is written in the droplet's framework.
Specifics
Section titled “Specifics”await props.dataworks. The component renders under<Suspense>: when hydrating, the value is there at once and Suspense adds nothing to the server’s markup; when the droplet mounts from scratch (client-only, remounted in dev),awaitwaits for it. A droplet mounted that way with an+error.vuealso gets an error boundary (onErrorCaptured):+error.vueshows in place of whatever throws while rendering, a rejectedawait props.dataincluded, with whathandleErrorreturned.- Children:
<DropletChildren />of@dropletsjs/renderer-vue/children, since<slot>in a Vue template is Vue’s own slot.DropletPropshas nochildren. - Styles: SFC
<style>blocks, scoped included, go to the droplet’s stylesheet.+error.vuecompiles in custom-element mode, so its styles are inlined: on the server they come before its markup, and in the browser they are added to the document head, once per text, and taken out again when the last error page using them unmounts. - Forms:
actionUrl("add")of$droplets/formin<script setup>, before the firstawait, then<form method="post" :action="add">.useEnhanceDropletForm(formRef, { action: "add" })sends it withfetchand shows the result in place; withoutonResult, it callsresult.update(). The poll on Actions is a Vue droplet with an enhanced form. - Options:
vue({ vitePlugin })passes options to@vitejs/plugin-vueas given, exceptfeatures.customElement, which is combined with the error page pattern (customElement: truekeeps every component in custom-element mode). Withvue({ plugin: false })you register@vitejs/plugin-vueyourself, and give+error.vuefilesfeatures.customElement. - Hot updates. Under
vite dev, withdev.strategy: "hmr"(the default), an edit to a component goes through@vitejs/plugin-vue’s HMR. A template edit re-renders and keeps the component’s state; a<script>edit reloads the component, and its state starts over. An edit to the load brings newdatato the live component, its state kept, when the component readsdatain its template or acomputed. A component whosesetupawaitsprops.dataran thatsetuponce, with the old data, so it remounts instead. See Hot updates.
The example
Section titled “The example”examples/frameworks/vue
has one droplet per mode, client (ssr = false), ssr-hydrate (with
+error.vue) and ssr-nohydrate (hydrate = false), with loads, a props
schema, /api endpoints, env variables and a handle hook. Its droplets
render in <djs-vue>. From a clone of the repository:
pnpm install && pnpm buildpnpm --filter @dropletsjs/example-vue dev # http://localhost:5173: the devtools pagepnpm --filter @dropletsjs/example-vue build then start serves it on
http://localhost:8000; /droplets/ssr-hydrate?who=Ana is the fragment a
host pastes into its page.