Skip to content

darbymanning/sveltekit-preview-mode

Repository files navigation

SvelteKit Preview Mode

SvelteKit Preview Mode is a library for SvelteKit that helps you easily enable preview mode for content management systems (CMSs). With this library, you can preview draft or unpublished content without any hassle. This is intended to be a SvelteKit equivelant of the Next.js Preview Mode.

Demo (using Hygraph)

Installation

To install SvelteKit Preview Mode, run the following command:

pnpm add sveltekit-preview-mode -D

Usage

To use SvelteKit Preview Mode, simply import it in your SvelteKit application:

// src/hooks.server.ts
import type { Handle } from '@sveltejs/kit';
import { PREVIEW_SECRET } from '$env/static/private';
import previewMode from 'sveltekit-preview-mode';

export const handle: Handle = previewMode({
	previewSecret: PREVIEW_SECRET
});

Don't forget to set the PREVIEW_SECRET environment variable. This can be any string you'd like. If you need to add additional handlers, you can do so using the sequence helper function.

In order to share the preview status in the client, you'll need to add this to +layout.server.ts:

// src/routes/+layout.server.ts
/**
 * Return the `exitPreviewQueryParam` and `isPreview` values so that they can be referenced in client-side code.
 */
export async function load({ locals }) {
	return {
		exitPreviewQueryParam: locals.exitPreviewQueryParam,
		isPreview: locals.isPreview
	};
}

Displaying Preview Status

To display a banner when preview mode is enabled, import the PreviewMode banner component into +layout.svelte:

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import { PreviewBanner } from 'sveltekit-preview-mode';
</script>

<PreviewBanner />

You can retrieve the preview status by checking the global page store. $page.data.isPreview

Enabling Preview Mode

To enable preview mode, add the query parameter ?secret=PREVIEW_SECRET to any route. This will then check for a matching secret, and update the isPreview value, and set a cookie to securely persist preview mode between sessions.

Disabling Preview Mode

To disable preview mode, add the query parameter ?exit-preview to any route. This will then update the isPreview value, and update the cookie value.

Examples

Options

The previewMode handle function has a few options that can be set:

interface PreviewModeOptions {
	previewSecret: string;
	cookieName?: string;
	cookieOpts?: CookieSerializeOptions;
	exitPreviewQueryParam?: string;
	secretTokenQueryParam?: string;
}
Property Type Default Description
previewSecret string N/A This is the query parameter value, which needs to match in order to enable preview mode.
cookieName? string __preview_mode The name of the cookie that is created to store the preview mode state.
cookieOpts? CookieSerializeOptions 🔗 Options for the cookie we create.
exitPreviewQueryParam? string exit-preview The query param that should be present to exit preview mode.
secretTokenQueryParam? string secret The query param that should be used to enter preview mode.

Static Site Generation (SSG)

sveltekit-preview-mode mode is reliant on having a server to analyze the request and serve different content based on query params and cookies of the incoming request. Sveltekit does not support static site generation on pages that access cookies or url query params. Due to this, during build sveltekit-preview-mode is turned off.

If you would like to take advantage of prerendering while still using sveltekit-preview-mode I would suggest creating a copy of the prerendered route with a new routeId /preview/[slug] that is dynamic and redirecting back to the static route if not in preview mode.

// src/routes/preview/[slug]/+page.server.ts
import { redirect } from '@sveltejs/kit';

export const prerender = false;
/**
 * Return the `exitPreviewQueryParam` and `isPreview` values so that they can be referenced in client-side code.
 */
export async function load({ params, locals: { isPreview } }) {
	if (!isPreview) redirect(302, `/${params.slug}`);

	return {
		isPreview
	};
}

Contributing

If you'd like to contribute to SvelteKit Preview Mode, feel free to open an issue or pull request on our GitHub repository.

Credits

This project is inspired by the Vercel Next.js team's approach in providing Preview Mode functionality. Thanks for their hard work! 🖤

License

SvelteKit Preview Mode is released under the ISC License.