Skip to Content
Vuesho

Plugins

Add routes, pages, content sources and build steps to your site.

A plugin is an object with a name and hooks. Add it to your site with .plugins():

vuesho.config.ts
import { createSite } from "vuesho/config";
import { defineDocs } from "vuesho/content";

const docs = defineDocs();

export default createSite(docs.toFumadocsSource()).plugins({
  name: "site:status",
  routes({ createApi }) {
    createApi({
      path: "/api/status",
      GET: () => Response.json({ pages: this.getPages().length }), 
    });
  },
});

this in a hook is the context of the site: its config, its pages and helpers for URLs. Hooks run on the server only, so a plugin can read files, call APIs and use secrets.

To share a plugin, export a function that returns it, and type it with Plugin<C>. C is the site the plugin is added to, so its hooks receive the pages and languages of that site:

status-plugin.ts
import type { AppShape, Plugin } from "vuesho/config";

export function statusPlugin<C extends AppShape>(options: { path?: string } = {}): Plugin<C> {
  return {
    name: "acme:status",
    routes({ createApi }) {
      createApi({ path: options.path ?? "/api/status", GET: () => Response.json({ ok: true }) });
    },
  };
}

Each plugin needs a unique name. A site with two plugins of the same name fails to start. A key of a plugin that isn't a hook, like a misspelled one, is a type error in .plugins().

Hooks

Routes and requests:

  • routes adds API routes and views.
  • deriveRoutes adds routes made from the final list of page routes of a language, see Derived Routes.
  • middleware handles every request before the routes and pages, see Middleware.
  • build runs once when the site is built, see Build Hook.

Pages and layouts:

  • head adds tags to the <head> of a page, sent with the page.
  • layoutProps adds navbar links and other props of the layouts, per language.
  • transformPage changes the data of a page that the browser receives, like its title or noindex.

A plugin with components ships them in a theme, and names it in theme: see Plugins with UI.

Content hooks, which render the pages of a content source:

  • getPageBody gives the content of a page.
  • getPageToc gives its table of contents.
  • getPageText gives its Markdown, for llms-full.txt.
  • getPageStructuredData gives its headings and text, for search.
  • getPageLastModified gives the date it last changed, for the sitemap and the page.
  • getPageCreatedAt gives the date it was written, for feeds and blogs.
  • getPageFile gives the path of its file, for the link to edit it.

Startup hooks:

  • init runs when the site starts, before the content loads.
  • configureLoader changes the options of the Fumadocs content loader.
  • configure runs when the site starts, after the content loads.

head and layoutProps take the same values as the head and ui.layoutProps options of your config:

vuesho.config.ts
createSite(docs.toFumadocsSource()).plugins({
  name: "site:extras",
  head: () => [{ tag: "meta", attrs: { name: "theme-color", content: "#0ea5e9" } }],
  layoutProps({ lang }) {
    return { links: [{ text: "Blog", url: this.localizePath(lang, "/blog") }] };
  },
});

Plugin Order

Plugins run in this order:

  1. Your plugins, in the order of .plugins().
  2. The plugins of the preset.
  3. The built-in plugins, which you can't remove: core:markdown renders your Markdown collections, core:pages serves the data of each page to the browser, and core:site adds the head tags of each page from its page data and your site config.

When the site starts, each of these steps runs for every plugin before the next step: init, configureLoader, loading the content, configure, routes, then deriveRoutes. middleware and build run in plugin order too.

Merging Results

When several plugins return a value for the same hook, the results combine by hook:

  • head: tags with a key, like title, a meta by its name or property, and the canonical link, are unique, and the attributes of html and body merge one by one. Your head option wins over plugins, and an earlier plugin wins over a later one. Other tags are all kept.
  • layoutProps: your own options come first, then plugins in order. Objects merge deeply and lists concatenate, so every plugin can add links. For other values, the first defined value wins.
  • transformPage and configureLoader: every plugin receives the same data and returns what it changes, so a field has one writer. Two plugins that change the same field fail with an error that names both. The options you pass to createSite() stay as you set them, and the plugins of the loader are combined.
  • Content hooks, like getPageBody: the first result that isn't undefined wins, so a plugin returns undefined for a page it doesn't render.

core:site runs last, so a title or description tag from any plugin replaces its own.

Conditional Plugins

.plugins() skips false, null and undefined, and flattens lists:

vuesho.config.ts
createSite(docs.toFumadocsSource()).plugins(process.env.ANALYTICS === "1" && analyticsPlugin(), [
  statusPlugin(),
  changelogPlugin,
]);

Default Plugins

The default plugins come from recommendedPreset(), in the preset option of .config(). Each has a key in its options:

  • sitemap, the core:sitemap plugin, adds /sitemap.xml, on a site with site.baseUrl.
  • robots, the core:robots plugin, adds /robots.txt, with a link to the sitemap when there is one.
  • llms, the core:llms plugin, adds /llms.txt and /llms-full.txt, in each language.
  • search, the core:search plugin, adds a search index per language, searched in the browser.

Default Plugins of the config lists their options, and how to remove them.

Replacing a Default Plugin

Set the default plugin to false, then list your own:

vuesho.config.ts
import { createSite, recommendedPreset } from "vuesho/config";
import { defineDocs } from "vuesho/content";
import { mySearchPlugin } from "./search-plugin";

const docs = defineDocs();

export default createSite(docs.toFumadocsSource())
  .plugins(mySearchPlugin())
  .config({ preset: recommendedPreset({ search: false }) });

The default plugins are exported too, as sitemapPlugin, robotsPlugin, llmsPlugin and searchPlugin. To list one yourself, like to run it before another plugin, set it to false in the preset first. Otherwise the site has the same plugin twice and fails to start.

Plugins from Fumapress for React

The hooks have the names and signatures of @fumapress/core, which Fumapress on Waku and Astro use. A plugin that uses only server-side hooks, like routes, middleware, content hooks and build, works on both.

The UI is different: the views of a plugin render with components of the theme, and every value sent to the browser is serializable.

Testing Plugins

createFetchHandler() of vuesho/server is the server of a site, without Vite. A test creates a site with your plugin and a custom source, and requests its routes. The handler needs a render function for pages, which a test of routes can stub:

status-plugin.test.ts
import { createSite } from "vuesho/config";
import { createFetchHandler } from "vuesho/server";
import { expect, test } from "vitest";
import { statusPlugin } from "./status-plugin";

test("answers the status route", async () => {
  const site = createSite({
    files: [{ type: "page", path: "index.md", data: { title: "Home" } }],
  }).plugins(statusPlugin());
  const fetch = createFetchHandler({
    site,
    assets: { css: [], js: [] },
    render: async () => ({ html: "" }),
  });

  const response = await fetch(new Request("http://localhost/api/status"));
  expect(await response.json()).toEqual({ ok: true });
});

The macros of vuesho/content are compiled by the Vite plugin, so a test lists its files instead of calling defineDocs().