Plugin Recipes

Writing a Plugin builds one plugin from an empty folder to a working directive. This page is the next step: a set of small recipes for the extension points you are likely to need.

Each recipe is independent. Copy the one you need into extensions/, register it in riebeckite.config.ts, and check the result in the browser or build output. The recipes are task-oriented; the exact contracts are in the Plugin API.

Plugins are trusted application code. When a recipe builds HTML, it escapes untrusted values. When it emits URLs, it validates them for the context. Riebeckite does not sanitize plugin-generated HTML. See the Security model.

Before you start

The recipes assume a site created by create-riebeckite and a local plugin in extensions/. A local plugin does not need its own package.

Start with the smallest possible plugin:

import { definePlugin } from "@riebeckite/core";
 
export function example() {
  return definePlugin({
    name: "example",
  });
}

Register it:

import { defineConfig } from "@riebeckite/core";
import { example } from "./extensions/example";
 
export default defineConfig({
  plugins: [example()],
});

Each recipe defines its own factory. Put it in extensions/ and register it instead of example. The name must be unique across enabled plugins, because it owns the plugin cache and generated output namespace.

Recipe map

Check each recipe

Run npm run build for recipes that affect static output. For browser behavior, use npm run dev and check the console and network panel.

The testing levels in Writing a Plugin apply to every recipe. For framework-level test conventions, see Testing.

Common mistakes

• Reading manifest.entries for published output. It includes drafts. Use publicEntries or discoverableEntries.
• Returning an empty string from a renderer for an unsupported target. Return null so another renderer can handle it.
• Forgetting to escape values from frontmatter, files, or remote responses.
• Passing secrets through publicConfig. Only that value is sent to the browser.
• Adding a transform without processedContentCache. The site then cannot reuse processed content.
• Assuming an endpoint becomes a static file. Use generated outputs for static export.
• Emitting a planned output without dependencies. The runtime rejects it.
• Changing a permalink without a redirect. Old links break; add a redirect if the URL was public.
• Using order to override a capability dependency. Providers always run first.

Related

• Writing a Plugin
• Plugin API
• Plugin System
• Testing
• Security model
• Accessibility