Configuration

Configure named inputs, image dimensions, formats, and generated types.

og() requires at least one named input. A static input is a route string; a dynamic input pairs a route pattern with an entries function.

vite.config.ts 
import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig } from "vite";
import { include_og_types, og } from "svelte-build-og/vite";

export default defineConfig({
	plugins: [
		sveltekit({
			typescript: { config: include_og_types },
		}),
		og({
			input: {
				home: "/og/home",
				docs: {
					link: "/og/docs/[category]/[slug]",
					entries: () => [
						{ category: "ser", slug: "introduction" },
						{ category: "ser", slug: "installation" },
					],
				},
			},
			format: { file: "png", opts: { compressionLevel: 9 } },
			size: { x: 1200, y: 630 },
		}),
	],
});
OptionDefaultPurpose
inputRequiredNamed static routes or dynamic route-and-entry definitions.
size{ x: 1200, y: 630 }Chromium viewport and captured image dimensions in CSS pixels.
format{ file: "png" }PNG, WebP, or AVIF output with format-specific Sharp options.
browserPlaywright ChromiumBrowser provider used to launch Chromium.
capture{ concurrency: 1 }Number of reusable pages allowed to capture concurrently.
sveltekit_out_dir.svelte-kitSvelteKit output directory where generated types are stored.

Serverless Chromium

Read-only and serverless environments need an explicit browser provider. Install @sparticuz/chromium, then pass it through the official adapter:

vite.config.ts 
import chromium from "@sparticuz/chromium";
import { og, serverless_chromium } from "svelte-build-og/vite";

og({
	browser: serverless_chromium(chromium),
	input: { home: "/og/home" },
});

The default concurrency is one because Chromium memory is usually the limiting resource in CI and serverless builds. Raise it only when the build environment has enough memory for multiple pages in the shared browser context:

og({
	capture: { concurrency: 2 },
	input: { home: "/og/home" },
});

Image formats

PNG captures can be returned directly or passed through Sharp with PNG options. WebP and AVIF always use Sharp after Chromium captures the page as PNG.

og({
	input: { home: "/og/home" },
	format: { file: "webp", opts: { quality: 84, effort: 5 } },
});

The opts object is discriminated by file, so TypeScript exposes the matching Sharp PngOptions, WebpOptions, or AvifOptions fields.

Generated types

The generated declaration lives at .svelte-kit/svelte-build-og/generated.d.ts. The include_og_types hook in the Vite config above registers it through SvelteKit's generated TypeScript configuration, so input names and route parameters remain typed without putting generated files in application source.

If the application changes SvelteKit's kit.outDir, pass the same directory to sveltekit_out_dir:

export default defineConfig({
	plugins: [
		sveltekit({
			outDir: ".generated/svelte-kit",
			typescript: { config: include_og_types },
		}),
		og({
			input: { home: "/og/home" },
			sveltekit_out_dir: ".generated/svelte-kit",
		}),
	],
});

The directory is resolved from the Vite root and should remain excluded from version control with the rest of SvelteKit's generated output.

When upgrading from 0.2, build-og removes the former default src/.svelte-build-og/generated.d.ts after writing its replacement. If 0.2 used a custom types_file, keep that option for the first successful 0.3 start so build-og can remove the old declaration, then remove the option and its obsolete ignore rule.

On this page