Overview

Most pages in a SvelteKit app are content with a few interactive parts on them: a cart button, a search box, a menu. Kit still sends its whole client to the browser and hydrates the entire component tree, so a page that needs JavaScript for one widget pays for all of it. ogygia is an islands architecture for SvelteKit that removes that cost. A page ships as server HTML with no framework on it, and the browser loads only a small shared runtime plus the code for the components you marked as interactive.

<script>
  import Cart from './Cart.svelte' with { wake: 'visible' };
</script>

<h1>Everything here is static HTML.</h1>
<Cart />   <!-- hydrates only when it scrolls into view -->

You turn off Kit’s client for the route with csr = false, and then you mark the imports that should be interactive. In this example the heading is plain HTML and ships no JavaScript, while Cart ships its own code and loads it only when the page needs it.

The island below is real. It lives on this page with the mark wake: 'load', and the text around it is static HTML:

ogygia fits best on pages that are mostly content with small interactive parts, such as marketing pages, docs, blogs, dashboards and storefronts. If a page is one large interactive application, plain SvelteKit with csr = true is the simpler tool, and ogygia works alongside those pages, route by route.

Why you want this

The first gain is in what you ship. Because nothing hydrates the whole page, a static page stays static, and most pages cost only the runtime. Interactive parts add their own code and nothing more.

You also keep writing ordinary Svelte. An island is a normal component, and the import attribute is the only new syntax, so there is no island API to learn. It is still SvelteKit, too: remote functions, form actions, the router and content all work inside islands, and ogygia neither forks the framework nor patches Kit.

Finally, the different kinds of region (client islands, server islands, lakes and held regions) are settings of one small set of ideas rather than four unrelated systems, so what you learn about one carries over to the others.

How it works

A normal SvelteKit page starts the Kit client, which hydrates the full tree, so every page carries the framework. ogygia turns this around. When you set csr = false, the page is only HTML: there is no Kit client and no full-page hydration.

// the whole page opts out of the Kit client
export const csr = false;

In its place ships a runtime of about 7.6 KB, which is a custom element (<ogygia-region>) plus an optional router. It loads code only for the components you marked, and that code attaches to the HTML already on the page instead of replacing it.

When events occur

You configure a marked import with two attributes. wake says whether the component ships client JavaScript and when that JavaScript runs, and render says where the HTML comes from. The timing words are load, idle, visible, interaction and a CSS media query. A server island, which has no JavaScript of its own, uses the same words under a fetch key to say when its HTML arrives. Timing & nesting has the full schedule, the visible margins and the rules for nested regions, and Regions shows how the two dials combine into the four kinds.

How the docs are organized

Each section builds on the one before, so this is a good order to read them in:

1. Regions. Marking a component makes part of the page interactive. Islands, server islands, lakes and held regions are four settings of one primitive.
2. Data and state. Remote functions give islands a server, and shared state lets one live object span many islands.
3. Content. A collection turns markdown, JSON or a CMS into typed entries. site() arranges collections into a nav tree, search, emitted files and a shell. These docs are built with it.
4. The app layer. The router swaps pages without a reload, sends all server islands in one request, and prerenders the page you are about to click.
5. Macros. import.meta.og.* computes at build time any value that does not change between requests.
6. Profiler. The SSR profiler times every request and records CPU profiles on demand, so you can see where a server render spends its time.
7. Devtools. The in-page dock shows each region, its hydration and its timing, and @ogygia/testing turns the same data into test checks.
8. Plugins. The core ogygia package is the region system. Content, the server router, flags, postrender, federation, devtools and the profiler are separate packages: you install the ones you use and list each plugin beside ogygia() and before sveltekit(), as in plugins: [ogygia(), flags(), sveltekit()].
9. Constraints. The rules that keep all of this correct.

Start here

• Install: add the package and the plugin.
• Quickstart: your first island, from start to finish.
• Regions: the primitive that every mark compiles to.