Skip to content
ogygia Docs
Search docs ⌘K

@ogygia/core

Overview

The core of ogygia, for plugin authors. Apps install ogygia, which re-exports @ogygia/core subpath for subpath; every other ogygia package builds on @ogygia/core and its plugin API.

On this page

@ogygia/core is the code behind ogygia: the region compiler, the runtime, the server handle and the plugin API. Apps don’t install it themselves. They install ogygia, which depends on it and re-exports it subpath for subpath, so ogygia/server and @ogygia/core/server are the same module.

The other packages (content, flags, postrender, federation, the server router, devtools, testing) take @ogygia/core as a peer dependency and build on its plugin API. This section is for people who write or read those packages.

Install

In a plugin package, list it as a peer dependency, so the app’s own copy (brought in by ogygia) is the one your code runs against:

{
  "name": "my-ogygia-plugin",
  "type": "module",
  "exports": { "./vite": "./src/vite.ts" },
  "peerDependencies": { "@ogygia/core": "^0.11.0" }
}

First-party, not stable

The plugin API is public so that you can read how the packages work, but it is first-party only for now, and its shape can change in any release.

A first plugin

A plugin is a Vite plugin made with definePlugin, and the server half it names runs inside the app’s ogygia.handle(). Its name is the package name, and it must resolve from the app:

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

export function poweredBy() {
  return definePlugin({
    name: 'my-ogygia-plugin',
    server: import.meta.resolve('./server.ts')
  });
}
import { defineServer } from '@ogygia/core/plugin';

export default defineServer({
  // A returned Response replaces the page's.
  async response(ctx, res) {
    const headers = new Headers(res.headers);
    headers.set('x-powered-by', 'ogygia');
    return new Response(res.body, { status: res.status, headers });
  }
});

The app lists it like any other package, beside ogygia():

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

A server half can be run in a unit test without a server, through startPlugin from @ogygia/core/plugin/testing.

With ogygia’s regions

A plugin can mint regions on the server. region, htmlRegion and deferredRegion from @ogygia/core/plugin are the same values an app renders with <Region>, which is how federation turns another app’s page into a region on yours. Shared hooks (app.notify.invalidate(tags)) and request facts (perVisitor, storable) are how packages cooperate: a flag read sets perVisitor, and postrender reads it before it stores a page.

Where to go next