Writing a plugin

Every package beside ogygia (content, flags, postrender, federation, the server router, devtools) is a plugin: a Vite plugin the app lists once beside ogygia(), with a server half that runs inside ogygia.handle() and a browser half that boots with the page runtime. This page describes that API. For the app side (installing a package and listing its plugin), see Packages.

The first-party packages import it from @ogygia/core, which they take as a peer dependency. ogygia re-exports the same modules subpath for subpath, so ogygia/plugin and @ogygia/core/plugin are one module, and the examples below work with either.

A plugin consists of three pieces, each in its own file, so that server code never reaches a browser bundle:

The plugin names its halves: server and client hold each module’s location, resolved relative to the plugin’s own file with import.meta.resolve, and either one may be omitted. They are files inside the package itself, so each module exists only once, and they need no entry in the package’s exports, which remain yours to name. The build imports them statically, so nothing is looked up at run time, and a feature whose plugin is not listed costs zero bytes.

The plugin: definePlugin

import { definePlugin, type OgygiaPlugin } from '@ogygia/core/vite';

export function postrender(options: { ttl?: number } = {}): OgygiaPlugin<{ ttl: number }> {
  return definePlugin({
    name: '@ogygia/postrender',        // the package name: its identity
    server: import.meta.resolve('./server.ts'),
    options: { ttl: options.ttl ?? 86400 },
    build(b) {
      b.routeConfig('postrender');     // pages may say `export const config = { postrender: false }`
    }
  });
}

definePlugin returns a Vite plugin that carries the definition under its own symbol (Symbol.for('ogygia.plugin')). That symbol is how ogygia() finds it in the plugins list, so a plugin’s name needs no naming convention beyond its package name.

Vite hooks of its own

A plugin that needs its own Vite hooks returns an array containing its definePlugin(...) and a plain Vite plugin. Vite flattens the array, so the app still lists a single yaml(). content() and devtools() work this way.

import { definePlugin } from '@ogygia/core/vite';

export function yaml() {
  return [
    definePlugin({ name: 'ogygia-yaml', server: import.meta.resolve('./server.ts') }),
    { name: 'ogygia-yaml:transform', transform(code, id) { /* a plain Vite plugin */ } }
  ];
}

The build context: b

build(b) runs once, when Vite loads its config. b.root is the app’s root, and b.dev is true under vite dev.

The server half: defineServer

import { defineServer } from '@ogygia/core/plugin';

export default defineServer<{ ttl: number }, { hit: boolean }>({
  setup(app) { /* once: app.options, app.notify, app.ask */ },
  state: () => ({ hit: false }),                  // fresh per request: ctx.state
  async request(ctx) { /* every request */ },
  async page(ctx) { /* a page request: return a Response to answer it */ },
  async response(ctx, res) { /* return a Response to replace the page's */ },
  done(ctx) { /* the request ended */ },
  async invalidate(tags) { /* a shared hook */ }
});

Each hook has a kind, which determines what its return value does.

Shared hooks are how plugins communicate with each other. A plugin implements one as a method of its server half, and any code can call it through app:

• app.notify.<hook>(…) runs the hook on every plugin that has it and resolves when all of them are done.
• app.ask.<hook>(…) returns the first answer that is not undefined, in plugin order.

Core owns the common names: invalidate(tags) (drop stored pages with these tags), invalidated(tags) (stored pages were dropped) and lastBuild(version). It is normal for no plugin to implement a hook, in which case notify does nothing and ask answers undefined. A plugin’s own hooks carry its name and are typed through declaration merging:

declare module '@ogygia/core/plugin' {
  interface ServerHooks { myPluginReset(path: string): void }
}

The contexts: app and ctx

app is the server process as one plugin sees it. setup receives it, and every ctx.app refers to it.

ctx is one request as one plugin sees it. handle receives a smaller version with only event, options and app.

Request facts

Facts are what a request has learned so far, shared by every plugin and by core. Whichever code learns a fact writes it and whichever code needs it reads it, without either one importing the other.

A plugin adds facts of its own the same way it adds hooks, with declare module '@ogygia/core/plugin' { interface RequestFacts { … } }.

The browser half: defineClient

import { defineClient } from '@ogygia/core/plugin/client';

export default defineClient({
  boot({ kitPage }) { /* once, before the first region wakes */ },
  regionMount(el, { entry, urls }) { /* a region's component started */ },
  regionUnmount(el, { entry }) { /* …and left the page */ }
});

The browser half is part of the boot’s static graph, so it ships to every page. Keep it small and load anything heavy on demand through a dynamic import of its own. When the build contains no browser half, core’s calls into these hooks are removed.

Helpers

import { startPlugin } from '@ogygia/core/plugin/testing';
import server from '../src/server.ts';

const { ctx } = startPlugin(server, { name: '@ogygia/flags' });
await server.request?.(ctx(new Request('http://localhost/')));