Installation

ogygia is an islands runtime and docs kit for SvelteKit. It renders your pages on the server as plain HTML, then wakes only the interactive parts on the client. This page walks you from an empty project to a running island in about five minutes.

Prerequisites

ogygia builds directly on SvelteKit and Vite, so the requirements are the same versions those projects support today. If your app already runs on a recent Kit release, you are ready.

Runes only. ogygia targets Svelte 5 in runes mode. Legacy reactive statements ($:) are not supported inside islands. If you are migrating an older app, convert your interactive components to $state and $derived first.

Install the package

Add ogygia with your package manager of choice. The runtime, the Vite plugin, and the docs kit all ship in a single package.

npm install ogygia

pnpm add ogygia

yarn add ogygia

bun add ogygia

There are no peer packages to install by hand. ogygia declares SvelteKit and Svelte as peers and will warn if the installed versions fall outside the supported range.

Add the Vite plugin

The plugin is what turns an ordinary import into an island. It rewrites imports that carry a wake hint, splits each island into its own client chunk, and leaves everything else as server-only HTML. Register it before the SvelteKit plugin in your config.

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { ogygia } from 'ogygia/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		ogygia({
			// Directory that holds your content collections.
			content: 'src/content',
			// Wake strategy used when an import omits an explicit hint.
			defaultWake: 'visible'
		}),
		sveltekit()
	]
});

The order matters. ogygia needs to see the raw module graph before Kit’s own transforms run, so it must sit earlier in the array.

Enable Markdown

ogygia reads .svx files as Svelte-flavored Markdown. Point the preprocessor at your file extensions in svelte.config.js so Kit knows how to compile them.

// svelte.config.js
import adapter from '@sveltejs/adapter-auto';
import { markdown } from 'ogygia/markdown';
import { vitePreprocess } from '@sveltejs/kit/vite';

export default {
	extensions: ['.svelte', '.svx'],
	preprocess: [vitePreprocess(), markdown()],
	kit: {
		adapter: adapter()
	}
};

With this in place, any .svx file becomes a normal Svelte component. Frontmatter is parsed into metadata, headings feed the on-this-page rail, and fenced code blocks are highlighted at build time.

Your first page

Create a content file and give it frontmatter. The body starts at a level-two heading; the title comes from the frontmatter, not from an # H1.

---
title: Hello islands
summary: The smallest possible ogygia page.
---

Everything on this page is static HTML until an island wakes up.

## A live counter

<script>
	import Counter from '$lib/playground/demos/Counter.svelte' with { wake: 'visible' };
</script>

<Counter />

Start your dev server and open the page. The prose renders instantly from the server. When the counter scrolls into view, its chunk loads and it comes alive.

pnpm dev

Next steps

• Read the quick start to build a real content collection and route.
• Learn how islands wake in islands.
• Explore the full render model in regions.

Tip. If an island never wakes, check that its import carries a with { wake: '...' } attribute. Without a wake hint the plugin treats the component as server-only and ships no client chunk for it.