[feat] SSR never option

.changeset/bright-tips-beam.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+Added a "never" value to the config.kit.ssr option that prevents pages from being evaluated on the server on both ssr and prerendering.

documentation/docs/11-ssr-and-javascript.md

@@ -14,14 +14,16 @@ Disabling [server-side rendering](#appendix-ssr) effectively turns your SvelteKi
 
 > In most situations this is not recommended: see [the discussion in the appendix](#appendix-ssr). Consider whether it's truly appropriate to disable and don't simply disable SSR because you've hit an issue with it.
 
-You can disable SSR app-wide with the [`ssr` config option](#configuration-ssr), or a page-level `ssr` export:
+You can disable SSR on a page-level with a `ssr` export. Page-level `ssr` exports must be boolean values, if another value is provided it will be cast into a boolean.
 
 ```html
 <script context="module">
 	export const ssr = false;
 </script>
 ```
 
+You can also disable SSR app-wide with the [`ssr` config option](#configuration-ssr), using a boolean or `"never"`. In case you use `"never"`, all page-level `ssr` exports will be completely ignored regardless of their value.
+
 ### router
 
 SvelteKit includes a [client-side router](#appendix-routing) that intercepts navigations (from the user clicking on links, or interacting with the back/forward buttons) and updates the page contents, rather than letting the browser handle the navigation by reloading.

documentation/docs/14-configuration.md

@@ -199,7 +199,8 @@ An object containing zero or more of the following values:
 
 ### ssr
 
-Enables or disables [server-side rendering](#ssr-and-javascript-ssr) app-wide.
+- `true` or `false` — Enables or disables [server-side rendering](#ssr-and-javascript-ssr) app-wide and allows pages to override it locally.
+- `"never"` — Prevents all pages from being evaluated on the server, on both [server-side rendering](#ssr-and-javascript-ssr) and [prerendering](#ssr-and-javascript-prerender), can't be overriden by page-level exports. Using this option is recommended when building an SPA.
 
 ### target
 

documentation/faq/80-integrations.md

@@ -85,6 +85,24 @@ onMount(() => {
 });
 ```
 
+But if your app doesn't use SSR, you can set the `ssr` option to `'never'`:
+
+```js
+export default {
+	kit: {
+		// ...
+		ssr: 'never'
+		// ...
+	}
+}
+```
+
+```js
+import { method } from 'some-browser-only-library';
+
+method('hello world!');
+
+```
 ### How do I use Firebase?
 
 Please use SDK v9 which provides a modular SDK approach that's currently in beta. The old versions are very difficult to get working especially with SSR and also resulted in a much larger client download size. Even with v9, most users need to set `kit.ssr: false` until [vite#4425](https://github.com/vitejs/vite/issues/4425) and [firebase-js-sdk#4846](https://github.com/firebase/firebase-js-sdk/issues/4846) are solved.

packages/kit/src/core/adapt/prerender.js

@@ -94,7 +94,7 @@ const REDIRECT = 3;
  * }} opts
  */
 export async function prerender({ cwd, out, log, config, build_data, fallback, all }) {
-	if (!config.kit.prerender.enabled && !fallback) {
+	if (config.kit.ssr === 'never' || (!config.kit.prerender.enabled && !fallback)) {
 		return;
 	}
 

packages/kit/src/core/build/index.js

@@ -259,32 +259,35 @@ async function build_server(
 		}
 	}
 
+	const allow_ssr = config.kit.ssr !== 'never';
+
 	/** @type {Record<string, { entry: string, css: string[], js: string[], styles: string[] }>} */
 	const metadata_lookup = {};
-
-	manifest.components.forEach((file) => {
-		const js_deps = new Set();
-		const css_deps = new Set();
-
-		find_deps(file, js_deps, css_deps);
-
-		const js = Array.from(js_deps);
-		const css = Array.from(css_deps);
-
-		const styles = config.kit.amp
-			? Array.from(css_deps).map((url) => {
-					const resolved = `${output_dir}/client/${config.kit.appDir}/${url}`;
-					return fs.readFileSync(resolved, 'utf-8');
-			  })
-			: [];
-
-		metadata_lookup[file] = {
-			entry: client_manifest[file].file,
-			css,
-			js,
-			styles
-		};
-	});
+	if (allow_ssr) {
+		manifest.components.forEach((file) => {
+			const js_deps = new Set();
+			const css_deps = new Set();
+
+			find_deps(file, js_deps, css_deps);
+
+			const js = Array.from(js_deps);
+			const css = Array.from(css_deps);
+
+			const styles = config.kit.amp
+				? Array.from(css_deps).map((url) => {
+						const resolved = `${output_dir}/client/${config.kit.appDir}/${url}`;
+						return fs.readFileSync(resolved, 'utf-8');
+				  })
+				: [];
+
+			metadata_lookup[file] = {
+				entry: client_manifest[file].file,
+				css,
+				js,
+				styles
+			};
+		});
+	}
 
 	/** @type {Set<string>} */
 	const entry_js = new Set();
@@ -412,21 +415,23 @@ async function build_server(
 				externalFetch: hooks.externalFetch || fetch
 			});
 
-			const module_lookup = {
-				${manifest.components.map(file => `${s(file)}: () => import(${s(app_relative(file))})`)}
-			};
+			${allow_ssr ?
+			`const module_lookup = {
+				${manifest.components.map((file) => `${s(file)}: () => import(${s(app_relative(file))})`)}
+			};` : ''}
 
-			const metadata_lookup = ${s(metadata_lookup)};
+			${allow_ssr ? `const metadata_lookup = ${s(metadata_lookup)};` : ''}
 
 			async function load_component(file) {
-				const { entry, css, js, styles } = metadata_lookup[file];
+				${allow_ssr ?
+				`const { entry, css, js, styles } = metadata_lookup[file];
 				return {
 					module: await module_lookup[file](),
 					entry: assets + ${s(prefix)} + entry,
 					css: css.map(dep => assets + ${s(prefix)} + dep),
 					js: js.map(dep => assets + ${s(prefix)} + dep),
 					styles
-				};
+				};` : 'throw new Error(\'Cannot use ssr when config.kit.ssr is "never"\')'}
 			}
 
 			export function render(request, {

packages/kit/src/core/config/options.js

@@ -165,7 +165,7 @@ const options = object(
 				files: fun((filename) => !/\.DS_STORE/.test(filename))
 			}),
 
-			ssr: boolean(true),
+			ssr: list([true, false, 'never']),
 
 			target: string(null),
 
@@ -275,16 +275,21 @@ function boolean(fallback) {
 }
 
 /**
- * @param {string[]} options
+ * @param {unknown[]} options
  * @returns {Validator}
  */
 function list(options, fallback = options[0]) {
 	return validate(fallback, (input, keypath) => {
+		/** @param  {unknown} i */
+		const stringify = (i) => (typeof i === 'string' ? `"${i}"` : `${i}`);
 		if (!options.includes(input)) {
-			// prettier-ignore
-			const msg = options.length > 2
-				? `${keypath} should be one of ${options.slice(0, -1).map(input => `"${input}"`).join(', ')} or "${options[options.length - 1]}"`
-				: `${keypath} should be either "${options[0]}" or "${options[1]}"`;
+			const msg =
+				options.length > 2
+					? `${keypath} should be one of ${options
+							.slice(0, -1)
+							.map(stringify)
+							.join(', ')} or ${stringify(options[options.length - 1])}`
+					: `${keypath} should be either ${stringify(options[0])} or ${stringify(options[1])}`;
 
 			throw new Error(msg);
 		}

packages/kit/src/runtime/server/page/render.js

@@ -12,7 +12,11 @@ const s = JSON.stringify;
  *   branch: Array<import('./types').Loaded>;
  *   options: import('types/internal').SSRRenderOptions;
  *   $session: any;
- *   page_config: { hydrate: boolean, router: boolean, ssr: boolean };
+ *   page_config: {
+ * 	 		hydrate: boolean,
+ * 			router: boolean,
+ * 			ssr: import('types/internal').SSROption
+ * 	 };
  *   status: number;
  *   error?: Error,
  *   page?: import('types/page').Page
@@ -43,7 +47,8 @@ export async function render_response({
 		error.stack = options.get_stack(error);
 	}
 
-	if (page_config.ssr) {
+	// excludes false and 'never'
+	if (page_config.ssr === true) {
 		branch.forEach(({ node, loaded, fetched, uses_credentials }) => {
 			if (node.css) node.css.forEach((url) => css.add(url));
 			if (node.js) node.js.forEach((url) => js.add(url));
@@ -124,9 +129,9 @@ export async function render_response({
 				})},
 				host: ${page && page.host ? s(page.host) : 'location.host'},
 				route: ${!!page_config.router},
-				spa: ${!page_config.ssr},
+				spa: ${page_config.ssr === 'never' || !page_config.ssr},
 				trailing_slash: ${s(options.trailing_slash)},
-				hydrate: ${page_config.ssr && page_config.hydrate ? `{
+				hydrate: ${page_config.ssr === true && page_config.hydrate ? `{
 					status: ${status},
 					error: ${serialize_error(error)},
 					nodes: [

packages/kit/src/runtime/server/page/respond.js

@@ -24,6 +24,19 @@ import { coalesce_to_error } from '../../../utils/error.js';
  */
 export async function respond(opts) {
 	const { request, options, state, $session, route } = opts;
+	if (options.ssr === 'never') {
+		return await render_response({
+			branch: [],
+			$session,
+			options,
+			page_config: {
+				hydrate: true,
+				router: true,
+				ssr: false
+			},
+			status: 200
+		});
+	}
 
 	/** @type {Array<SSRNode | undefined>} */
 	let nodes;
@@ -227,7 +240,7 @@ export async function respond(opts) {
  */
 function get_page_config(leaf, options) {
 	return {
-		ssr: 'ssr' in leaf ? !!leaf.ssr : options.ssr,
+		ssr: 'ssr' in leaf ? !!leaf.ssr : options.ssr === true,
 		router: 'router' in leaf ? !!leaf.router : options.router,
 		hydrate: 'hydrate' in leaf ? !!leaf.hydrate : options.hydrate
 	};

packages/kit/test/apps/spa/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "test-spa",
+	"private": true,
+	"version": "0.0.1",
+	"scripts": {
+		"dev": "../../../svelte-kit.js dev",
+		"build": "../../../svelte-kit.js build",
+		"preview": "../../../svelte-kit.js preview"
+	},
+	"devDependencies": {
+		"@sveltejs/kit": "workspace:*",
+		"@sveltejs/adapter-node": "workspace:*",
+		"svelte": "^3.43.0"
+	},
+	"type": "module"
+}

packages/kit/test/apps/spa/src/app.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" href="/favicon.png" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+
+		%svelte.head%
+	</head>
+	<body>
+		<div id="svelte">%svelte.body%</div>
+	</body>
+</html>

packages/kit/test/apps/spa/src/routes/client-code/_client_dep.js

@@ -0,0 +1 @@
+export const root = /** @type {HTMLElement}*/ (document.getElementById('svelte'));

packages/kit/test/apps/spa/src/routes/client-code/_tests.js

@@ -0,0 +1,22 @@
+import * as assert from 'uvu/assert';
+
+/** @type {import('test').TestMaker} */
+export default function (test) {
+	test('page with client only code', '/client-code', async ({ page, js }) => {
+		if (js) {
+			await page.waitForSelector('span');
+			assert.equal(await page.textContent('span'), 'App root is div#svelte');
+		} else {
+			assert.ok(await page.evaluate(() => !document.querySelector('span')));
+		}
+	});
+
+	test('page with client only dependency', '/client-code/dep', async ({ page, js }) => {
+		if (js) {
+			await page.waitForSelector('span');
+			assert.equal(await page.textContent('span'), 'App root is div#svelte');
+		} else {
+			assert.ok(await page.evaluate(() => !document.querySelector('span')));
+		}
+	});
+}

packages/kit/test/apps/spa/src/routes/client-code/dep.svelte

@@ -0,0 +1,5 @@
+<script>
+	import { root } from './_client_dep';
+</script>
+
+<span>App root is {root.localName}#{root.id}</span>

packages/kit/test/apps/spa/src/routes/client-code/index.svelte

@@ -0,0 +1,5 @@
+<script context="module">
+	const appRoot = /** @type {HTMLElement}*/ (document.getElementById('svelte'));
+</script>
+
+<span>App root is {appRoot.localName}#{appRoot.id}</span>

packages/kit/test/apps/spa/svelte.config.js

@@ -0,0 +1,9 @@
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	kit: {
+		ssr: 'never',
+		target: '#svelte'
+	}
+};
+
+export default config;

packages/kit/types/config.d.ts

@@ -1,6 +1,6 @@
 import { UserConfig as ViteConfig } from 'vite';
 import { RecursiveRequired } from './helper';
-import { Logger, TrailingSlash } from './internal';
+import { Logger, SSROption, TrailingSlash } from './internal';
 
 export interface AdapterUtils {
 	log: Logger;
@@ -68,7 +68,7 @@ export interface Config {
 		serviceWorker?: {
 			files?(filepath: string): boolean;
 		};
-		ssr?: boolean;
+		ssr?: SSROption;
 		target?: string;
 		trailingSlash?: TrailingSlash;
 		vite?: ViteConfig | (() => ViteConfig);

packages/kit/types/internal.d.ts

@@ -20,6 +20,8 @@ export interface Logger {
 	info(msg: string): void;
 }
 
+export type SSROption = boolean | 'never';
+
 export interface SSRComponent {
 	ssr?: boolean;
 	router?: boolean;
@@ -130,7 +132,7 @@ export interface SSRRenderOptions {
 	root: SSRComponent['default'];
 	router: boolean;
 	service_worker?: string;
-	ssr: boolean;
+	ssr: SSROption;
 	target: string;
 	template({ head, body }: { head: string; body: string }): string;
 	trailing_slash: TrailingSlash;