Skip to Content
Vuesho

Plugins with UI

Ship a plugin with components, like a feedback form under every page.

A plugin runs on the server, and the server can't send a component. So a plugin with UI comes in two parts: the plugin, and a theme with its components. A site lists the plugin in .plugins() and the theme in extends.

The Plugin

The plugin gives its components what they need. Data of a page goes in the page data, with transformPage, and data of the site in a data route. theme names the theme of its UI:

feedback/index.ts
import type { AppShape, Plugin } from "vuesho/config";

declare module "vuesho/config" {
  interface PageData {
    /** where the feedback form of the page posts */
    feedback?: { action: string };
  }
}

export function feedbackPlugin<C extends AppShape>(): Plugin<C> {
  return {
    name: "feedback",
    theme: "feedback",
    routes({ createApi }) {
      createApi({
        path: "/api/feedback",
        POST: async (request) => Response.json(await save(await request.json())),
      });
    },
    transformPage(_data, { page }) {
      if (page) return { feedback: { action: this.withBase("/api/feedback") } };
    },
  };
}

The Theme

The theme of the package has the same name, and puts its components in slots:

feedback/theme.ts
import { defineAsyncComponent } from "vue";
import type { PluginTheme } from "vuesho/client";

export default {
  name: "feedback",
  slots: { "page-bottom": defineAsyncComponent(() => import("./Feedback.vue")) },
} satisfies PluginTheme;

A component of a slot reads the page with usePage(), and renders nothing on a page without the data of the plugin:

feedback/Feedback.vue
<script setup lang="ts">
import { usePage } from "vuesho/client";

const page = usePage();

function send(opinion: "good" | "bad") {
  void fetch(page.value.pageData.feedback!.action, {
    method: "POST",
    body: JSON.stringify({ url: page.value.url, opinion }),
  });
}
</script>

<template>
  <form v-if="page.pageData.feedback" @submit.prevent>
    <button type="button" @click="send('good')">Good</button>
    <button type="button" @click="send('bad')">Bad</button>
  </form>
</template>

A plugin with views has their components in the same theme. PluginTheme takes the types of the plugin, and checks the component of each view against its props:

export default {
  name: "releases",
  views: { releases: () => import("./Releases.vue") },
} satisfies PluginTheme<{ views: { releases: ReleasesProps } }>;

The package lists vuesho in its peerDependencies. The Vite plugin of Vuesho compiles the files of every dependency of the site that lists vuesho, so the package can ship .vue files as they are.

The Site

The site adds the plugin and its theme:

vuesho.config.ts
import { feedbackPlugin } from "acme-feedback";

export default createSite(docs.toFumadocsSource()).plugins(feedbackPlugin()).config({});
src/theme.ts
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";
import feedbackTheme from "acme-feedback/theme";

export default defineTheme({ extends: [defaultTheme, feedbackTheme] });

Without the theme in extends, the site fails to start, in development and in the build, with an error that names the plugin, its theme and the line to add. A site without src/theme.ts creates it.

The compiled stylesheet of Vuesho has the classes of its own UI only: a component of a plugin brings its own styles, like a <style> block, or the site adds Tailwind CSS.