Plugins

The core package, ogygia, is the region system: islands, lakes, holes, held regions, the client router and the server handle. Every other feature is a separate package, including content collections, flags, postrender, federation, the server router, the devtools dock and the profiler. You install only what you use, so an app that never reads a flag carries none of the flag code.

Turn a feature on

Install the package, then list its plugin once in the plugins array of your Vite config, beside ogygia(). Each plugin is a Vite plugin in its own right, and ogygia() finds it in that list. Each factory is imported from <package>/vite:

npm i @ogygia/flags @ogygia/postrender

pnpm add @ogygia/flags @ogygia/postrender

import { sveltekit } from '@sveltejs/kit/vite';
import { ogygia } from 'ogygia/vite';
import { flags } from '@ogygia/flags/vite';
import { postrender } from '@ogygia/postrender/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    ogygia(),
    flags(),
    postrender({ ttl: 600 }),
    sveltekit()
  ]
});

ogygia() comes first, the feature plugins follow it, and sveltekit() goes last. ogygia.handle() in hooks.server.ts already runs the server half of every listed plugin, and the page runtime boots every browser half. What the Vite config can’t carry is anything live or app-specific: a flag vendor, your federation identity, your route table, a store client. Most packages therefore also ask for a line or two in hooks.server.ts, and each entry below says which.

These rules hold for every plugin:

• Call the factory. Write flags(), not flags; the build tells you if you forget.
• List each plugin once. A plugin listed twice is a build error.
• Only alongside ogygia(). A plugin listed without ogygia() fails the build with an explanation. The old plugins option of ogygia() has been removed, and passing it is a build error that names the new form.
• Options are plain JSON. They reach the plugin’s server half at run time. Live objects (a store client, a vendor SDK) are set up in hooks.server.ts through the package’s own API.
• List it only where you want it. The list is code, so a plugin can depend on the mode: ...(mode !== 'production' ? [devtools()] : []).

The packages

Every package takes ogygia as a peer dependency, and they all release together under one version number, so keep them on the same version as ogygia.

When several packages need a handle, the order in the sequence() is postrender first, then ogygia, then the router:

export const handle = sequence(postrender.handle(), ogygia.handle(), router.handle);

Content: @ogygia/content

pnpm add @ogygia/content

plugins: [ogygia(), content({ markdown: {} }), sveltekit()]

Nothing goes in hooks.server.ts. Markdown also needs extensions() and preprocess() in svelte.config.js, and a second /// <reference types="@ogygia/content/types" /> line in src/ogygia.d.ts; Install shows both. Guide: Content collections.

Flags: @ogygia/flags

pnpm add @ogygia/flags

plugins: [ogygia(), flags(), sveltekit()]

Native flags need nothing in hooks.server.ts. Call decide() there when you connect a vendor source, an exposure sink or a QA override gate. On plain SvelteKit, also import your flags module there, so every flag is registered before the first request:

import { decide } from '@ogygia/flags';
import { openfeature } from '@ogygia/flags/openfeature';
import '$lib/flags';

decide({ source: openfeature(OpenFeature.getClient()), exposure: (events) => analytics.track(events) });

Guide: Flags & experiments.

Postrender: @ogygia/postrender

pnpm add @ogygia/postrender

plugins: [ogygia(), postrender({ ttl: 600 }), sveltekit()]

postrender.handle() holds the live store and CDN edges, and it must come before ogygia.handle(), because a stored page is served before anything renders:

import { sequence } from '@sveltejs/kit/hooks';
import * as ogygia from 'ogygia/server';
import { postrender, valkey } from '@ogygia/postrender';

export const handle = sequence(postrender.handle({ store: valkey(client) }), ogygia.handle());

Guide: Postrender.

Federation: @ogygia/federation

pnpm add @ogygia/federation @ogygia/router

plugins: [ogygia(), federation(), sveltekit()]

The app’s one federate() call lives in a .server.ts module, and hooks.server.ts must import that module, directly or through a router that uses its peers, so it runs on boot. The plugin then serves every /og/ endpoint from ogygia’s handle, with no route files:

import * as ogygia from 'ogygia/server';
import '$lib/federation.server';   // runs federate() on boot

export const handle = ogygia.handle();

Guide: Fragment federation.

Server router: @ogygia/router

pnpm add @ogygia/router

plugins: [ogygia(), router(), sveltekit()]

Your route table serves requests through its own handle, placed after ogygia’s (or from a Kit catch-all route; see Mounting):

import { sequence } from '@sveltejs/kit/hooks';
import * as ogygia from 'ogygia/server';
import { router } from '$lib/router';   // your routes({ … }) table

export const handle = sequence(ogygia.handle(), router.handle);

Guide: Server router.

Devtools and profiler: @ogygia/devtools

pnpm add @ogygia/devtools

plugins: [ogygia(), devtools({ profiler: true }), sveltekit()]

ogygia.handle() mounts the dock and the profiler, so nothing is required in hooks.server.ts. In production the profiler UI needs OGYGIA_PROFILER_SECRET in the environment. To keep profiler reports in a database instead of process memory, set a store once in hooks.server.ts, before the first request:

import { env } from '$env/dynamic/private';
import { setProfilerStore } from '@ogygia/devtools/profiler/storage';
import { postgresStore } from '@ogygia/devtools/profiler/storage/postgres';

setProfilerStore(postgresStore(env.DATABASE_URL!));

sqliteStore and redisStore come from @ogygia/devtools/profiler/storage/sqlite and …/redis. Guides: Devtools and Profiler.

Testing and the CLI

@ogygia/testing and @ogygia/cli have no plugin. Import @ogygia/testing in your Playwright tests (Testing). @ogygia/cli is the ogygia command, which npx ogygia init adds to your devDependencies (CLI).

The plugin API

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/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/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/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/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/plugin' { interface RequestFacts { … } }.

The browser half: defineClient

import { defineClient } from 'ogygia/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/plugin/testing';
import server from '../src/server.ts';

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