feat: ability to use manual script injection in hooks (#89)

Co-authored-by: Hunter Johnston <[email protected]>
Co-authored-by: Hunter Johnston <[email protected]>

.changeset/modern-seas-smile.md

@@ -0,0 +1,5 @@
+---
+"mode-watcher": minor
+---
+
+feat: add ability to disable head script injection via the `disableHeadScriptInjection` prop for handling in hooks.server files

packages/mode-watcher/src/lib/index.ts

@@ -1,4 +1,5 @@
 import {
+	generateSetInitialModeExpression,
 	mode,
 	modeStorageKey,
 	resetMode,
@@ -12,6 +13,7 @@ import {
 } from "./mode.js";
 
 export {
+	generateSetInitialModeExpression,
 	setMode,
 	toggleMode,
 	resetMode,

packages/mode-watcher/src/lib/mode-watcher-full.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+	import { setInitialMode } from "./mode.js";
+	import type { ThemeColors } from "./types.js";
+
+	export let trueNonce: string = "";
+	export let initConfig: Parameters<typeof setInitialMode>[0];
+	export let themeColors: ThemeColors = undefined;
+</script>
+
+<svelte:head>
+	{#if themeColors}
+		<!-- default to dark mode for to allow testing -->
+		<!-- this will be overwritten by FOUC prevention snippet below -->
+		<!-- but that snippet does not run in vitest -->
+		<meta name="theme-color" content={themeColors.dark} />
+	{/if}
+	<!-- eslint-disable-next-line svelte/no-at-html-tags, prefer-template -->
+	{@html `<script${trueNonce ? ` nonce=${trueNonce}` : ""}>(` +
+		setInitialMode.toString() +
+		`)(` +
+		JSON.stringify(initConfig) +
+		`);</script>`}
+</svelte:head>

packages/mode-watcher/src/lib/mode-watcher-lite.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+	import type { ThemeColors } from "./types.js";
+
+	export let themeColors: ThemeColors = undefined;
+</script>
+
+{#if themeColors}
+	<!-- default to dark mode for to allow testing -->
+	<!-- this will be overwritten by FOUC prevention snippet below -->
+	<!-- but that snippet does not run in vitest -->
+	<meta name="theme-color" content={themeColors.dark} />
+{/if}

packages/mode-watcher/src/lib/mode-watcher.svelte

@@ -4,7 +4,6 @@
 		defineConfig,
 		disableTransitions as disableTransitionsStore,
 		mode,
-		setInitialMode,
 		setMode,
 		setTheme,
 		systemPrefersMode,
@@ -20,6 +19,8 @@
 		modeStorageKey as modeStorageKeyStore,
 		themeStorageKey as themeStorageKeyStore,
 	} from "./stores.js";
+	import ModeWatcherLite from "./mode-watcher-lite.svelte";
+	import ModeWatcherFull from "./mode-watcher-full.svelte";
 
 	type $$Props = ModeWatcherProps;
 
@@ -33,6 +34,7 @@
 	export let nonce: string = "";
 	export let themeStorageKey: string = "mode-watcher-theme";
 	export let modeStorageKey: string = "mode-watcher-mode";
+	export let disableHeadScriptInjection = false;
 
 	$: disableTransitionsStore.set(disableTransitions);
 	$: themeColorsStore.set(themeColors);
@@ -70,18 +72,8 @@
 	$: trueNonce = typeof window === "undefined" ? nonce : "";
 </script>
 
-<svelte:head>
-	{#if themeColors}
-		<!-- default to dark mode for to allow testing -->
-		<!-- this will be overwritten by FOUC prevention snippet below -->
-		<!-- but that snippet does not run in vitest -->
-		<meta name="theme-color" content={themeColors.dark} />
-	{/if}
-
-	<!-- eslint-disable-next-line svelte/no-at-html-tags, prefer-template -->
-	{@html `<script${trueNonce ? ` nonce=${trueNonce}` : ""}>(` +
-		setInitialMode.toString() +
-		`)(` +
-		JSON.stringify(initConfig) +
-		`);</script>`}
-</svelte:head>
+{#if disableHeadScriptInjection}
+	<ModeWatcherLite {themeColors} />
+{:else}
+	<ModeWatcherFull {trueNonce} {initConfig} {themeColors} />
+{/if}

packages/mode-watcher/src/lib/mode.ts

@@ -37,24 +37,24 @@ export function defineConfig(config: SetInitialModeArgs) {
 }
 
 type SetInitialModeArgs = {
-	defaultMode: Mode;
+	defaultMode?: Mode;
 	themeColors?: ThemeColors;
-	darkClassNames: string[];
-	lightClassNames: string[];
-	defaultTheme: string;
-	modeStorageKey: string;
-	themeStorageKey: string;
+	darkClassNames?: string[];
+	lightClassNames?: string[];
+	defaultTheme?: string;
+	modeStorageKey?: string;
+	themeStorageKey?: string;
 };
 
 /** Used to set the mode on initial page load to prevent FOUC */
 export function setInitialMode({
-	defaultMode,
+	defaultMode = "system",
 	themeColors,
 	darkClassNames = ["dark"],
 	lightClassNames = [],
 	defaultTheme = "",
-	modeStorageKey,
-	themeStorageKey,
+	modeStorageKey = "mode-watcher-mode",
+	themeStorageKey = "mode-watcher-theme",
 }: SetInitialModeArgs) {
 	const rootEl = document.documentElement;
 	const mode = localStorage.getItem(modeStorageKey) || defaultMode;
@@ -89,6 +89,13 @@ export function setInitialMode({
 	localStorage.setItem(modeStorageKey, mode);
 }
 
+/**
+ * A type-safe way to generate the source expression used to set the initial mode and avoid FOUC.
+ */
+export function generateSetInitialModeExpression(config: SetInitialModeArgs = {}): string {
+	return `(${setInitialMode.toString()})(${JSON.stringify(config)});`;
+}
+
 export {
 	modeStorageKey,
 	themeStorageKey,

packages/mode-watcher/src/lib/types.ts

@@ -77,4 +77,12 @@ export type ModeWatcherProps = {
 	 * @defaultValue `undefined`
 	 */
 	nonce?: string;
+
+	/**
+	 * Whether to disable the injected script tag that sets the initial mode.
+	 * Set this if you are manually injecting the script using a hook.
+	 *
+	 * @defaultValue `false`
+	 */
+	disableHeadScriptInjection?: boolean;
 };

sites/docs/content/api-reference/mode-watcher.md

@@ -172,5 +172,13 @@ export type ModeWatcherProps = {
 	 * @defaultValue `undefined`
 	 */
 	nonce?: string;
+
+	/**
+	 * Whether to disable the injected script tag that sets the initial mode.
+	 * Set this if you are manually injecting the script using a hook.
+	 *
+	 * @defaultValue `false`
+	 */
+	disableHeadScriptInjection?: boolean;
 };
 ````