Skip to content

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

3

Server HTML: the button works once Vue hydrates.

Live: rendered by the demo server, hydrated in this page.
src/droplets/counter-vue/+droplet.vue
<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>
Terminal window
npx djs add counter --framework vue

It 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:

PackageInstalled as
@dropletsjs/renderer-vuea dev dependency, at exactly the version of @dropletsjs/droplets you have
vue@^3.5.0a dependency

By hand:

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

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

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:

src/droplets/hello/+droplet.vue
<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>
src/droplets/hello/+error.vue
<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.

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 under vite dev and vite 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 dev and vite build warn once counter/+error.svelte is not a vue component like the droplet; ignored, the error page is written in the droplet's framework.

  • await props.data works. 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), await waits for it. A droplet mounted that way with an +error.vue also gets an error boundary (onErrorCaptured): +error.vue shows in place of whatever throws while rendering, a rejected await props.data included, with what handleError returned.
  • Children: <DropletChildren /> of @dropletsjs/renderer-vue/children, since <slot> in a Vue template is Vue’s own slot. DropletProps has no children.
  • Styles: SFC <style> blocks, scoped included, go to the droplet’s stylesheet. +error.vue compiles 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/form in <script setup>, before the first await, then <form method="post" :action="add">. useEnhanceDropletForm(formRef, { action: "add" }) sends it with fetch and shows the result in place; without onResult, it calls result.update(). The poll on Actions is a Vue droplet with an enhanced form.
  • Options: vue({ vitePlugin }) passes options to @vitejs/plugin-vue as given, except features.customElement, which is combined with the error page pattern (customElement: true keeps every component in custom-element mode). With vue({ plugin: false }) you register @vitejs/plugin-vue yourself, and give +error.vue files features.customElement.
  • Hot updates. Under vite dev, with dev.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 new data to the live component, its state kept, when the component reads data in its template or a computed. A component whose setup awaits props.data ran that setup once, with the old data, so it remounts instead. See Hot updates.

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:

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

pnpm --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.