[feat] More powerful and configurable rendering options

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

@@ -6,15 +6,17 @@ By default, SvelteKit will render any component first on the server and send it
 
 You can control each of these on a per-app or per-page basis. Note that each of the per-page settings use [`context="module"`](https://svelte.dev/docs#script_context_module), and only apply to page components, _not_ [layout](#layouts) components.
 
-If both are specified, per-page settings override per-app settings in case of conflicts. Each setting can be controlled independently, but `ssr` and `hydrate` cannot both be `false` since that would result in nothing being rendered at all.
+The app-wide config options take a function, which lets you set configure the option in an advanced manner on a per-request and per-page basis. E.g. you could disable SSR for `/admin` or enable SSR only for search engine crawlers (aka [dynamic rendering](https://developers.google.com/search/docs/advanced/javascript/dynamic-rendering)).
+
+ Each setting can be controlled independently, but `ssr` and `hydrate` cannot both be `false` since that would result in nothing being rendered at all.
 
 ### ssr
 
-Disabling [server-side rendering](#appendix-ssr) effectively turns your SvelteKit app into a [**single-page app** or SPA](#appendix-csr-and-spa).
+Disabling [server-side rendering](#appendix-ssr) effectively turns your SvelteKit app into a [**single-page app** or SPA](#appendix-csr-and-spa). The default app-wide config option value is a function which reads the page value. Reading the page value causes the page to be loaded on the server. If you'd like to avoid this because you're building a SPA, you will need to set a value such as a boolean for each of the four rendering options which does not access the page-level settings.
 
 > 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:
+SSR can be configured with app-wide [`ssr` config option](#configuration-ssr), or a page-level `ssr` export:
 
 ```html
 <script context="module">
@@ -26,7 +28,7 @@ You can disable SSR app-wide with the [`ssr` config option](#configuration-ssr),
 
 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.
 
-In certain circumstances you might need to disable [client-side routing](#appendix-routing) with the app-wide [`router` config option](#configuration-router) or the page-level `router` export:
+In certain circumstances you might need to configure [client-side routing](#appendix-routing) with the app-wide [`router` config option](#configuration-router) or the page-level `router` export:
 
 ```html
 <script context="module">

documentation/docs/14-configuration.md

@@ -28,7 +28,11 @@ const config = {
 		floc: false,
 		host: null,
 		hostHeader: null,
-		hydrate: true,
+		// hydrate unless disabled on page
+		hydrate: async ({ page }) => {
+			const leaf = await page;
+			return 'hydrate' in leaf ? !!leaf.hydrate : true;
+		},
 		package: {
 			dir: 'package',
 			emitTypes: true,
@@ -47,15 +51,26 @@ const config = {
 		},
 		prerender: {
 			crawl: true,
-			enabled: true,
-			force: false,
+			// prerender unless disabled on page
+			enabled: async ({ page }) => {
+				const leaf = await page;
+				return 'prerender' in leaf ? !!leaf.prerender : true;
+			},
 			pages: ['*']
 		},
-		router: true,
+		// route unless disabled on page
+		router: async ({ page }) => {
+			const leaf = await page;
+			return 'router' in leaf ? !!leaf.router : true;
+		},
 		serviceWorker: {
 			exclude: []
 		},
-		ssr: true,
+		// do SSR unless disabled on page
+		ssr: async ({ page }) => {
+			const leaf = await page;
+			return 'ssr' in leaf ? !!leaf.ssr : true;
+		},
 		target: null,
 		trailingSlash: 'never',
 		vite: () => ({})

documentation/faq/80-integrations.md

@@ -18,7 +18,7 @@ Please use SDK v9 which provides a modular SDK approach that's currently in beta
 
 ### How do I use a client-side only library that depends on `document` or `window`?
 
-Vite will attempt to process all imported libraries and may fail when encountering a library that is not compatible with SSR. [This currently occurs even when SSR is disabled](https://github.com/sveltejs/kit/issues/754).
+Vite will attempt to process all imported libraries and may fail when encountering a library that is not compatible with SSR. This occurs even when SSR is disabled unless you also override the default values for `hydrate`, `router`, and `prerender.enabled` [as mentioned in the docs](docs#ssr-and-javascript-ssr).
 
 If you need access to the `document` or `window` variables or otherwise need it to run only on the client-side you can wrap it in a `browser` check:
 
@@ -30,20 +30,17 @@ if (browser) {
 }
 ```
 
-You can also run code in `onMount` if you'd like to run it after the component has been first rendered to the DOM. In this case, you may still find a benefit of including a `browser` check as shown below because Vite may otherwise attempt to optimize the dependency and fail on it. [We hope to make this unnecessary in the future](https://github.com/sveltejs/svelte/issues/6372).
+You can also run code in `onMount` if you'd like to run it after the component has been first rendered to the DOM.
 
 ```html
 <script>
 	import { onMount } from 'svelte';
-	import { browser } from '$app/env';
 
 	let lib;
 
-	if (browser) {
-		onMount(async () => {
-			lib = (await import('some-browser-only-library')).default;
-		});
-	}
+	onMount(async () => {
+		lib = (await import('some-browser-only-library')).default;
+	});
 </script>
 ```
 

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

@@ -76,13 +76,14 @@ export async function prerender({ cwd, out, log, config, build_data, fallback, a
 	});
 
 	/** @type {(status: number, path: string, parent: string | null, verb: string) => void} */
-	const error = config.kit.prerender.force
-		? (status, path, parent, verb) => {
-				log.error(`${status} ${path}${parent ? ` (${verb} from ${parent})` : ''}`);
-		  }
-		: (status, path, parent, verb) => {
-				throw new Error(`${status} ${path}${parent ? ` (${verb} from ${parent})` : ''}`);
-		  };
+	const error =
+		config.kit.prerender.enabled === true
+			? (status, path, parent, verb) => {
+					log.error(`${status} ${path}${parent ? ` (${verb} from ${parent})` : ''}`);
+			  }
+			: (status, path, parent, verb) => {
+					throw new Error(`${status} ${path}${parent ? ` (${verb} from ${parent})` : ''}`);
+			  };
 
 	const files = new Set([...build_data.static, ...build_data.client]);
 

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

@@ -312,16 +312,17 @@ async function build_server(
 				set_paths(settings.paths);
 				set_prerendering(settings.prerendering || false);
 
+				const config = settings.config;
 				options = {
-					amp: ${config.kit.amp},
+					amp: config.kit.amp,
 					dev: false,
 					entry: {
 						file: ${s(prefix + client_manifest[client_entry_file].file)},
 						css: ${s(Array.from(entry_css).map(dep => prefix + dep))},
 						js: ${s(Array.from(entry_js).map(dep => prefix + dep))}
 					},
 					fetched: undefined,
-					floc: ${config.kit.floc},
+					floc: config.kit.floc,
 					get_component_path: id => ${s(`${config.kit.paths.assets}/${config.kit.appDir}/`)} + entry_lookup[id],
 					get_stack: error => String(error), // for security
 					handle_error: /** @param {Error & {frame?: string}} error */ (error) => {
@@ -332,19 +333,20 @@ async function build_server(
 						error.stack = options.get_stack(error);
 					},
 					hooks: get_hooks(user_hooks),
-					hydrate: ${s(config.kit.hydrate)},
+					hydrate: config.kit.hydrate,
 					initiator: undefined,
 					load_component,
 					manifest,
 					paths: settings.paths,
+					prerender: config.kit.prerender && config.kit.prerender.enabled,
 					read: settings.read,
 					root,
 					service_worker: ${service_worker_entry_file ? "'/service-worker.js'" : 'null'},
-					router: ${s(config.kit.router)},
-					ssr: ${s(config.kit.ssr)},
-					target: ${s(config.kit.target)},
+					router: config.kit.router,
+					ssr: config.kit.ssr,
+					target: config.kit.target,
 					template,
-					trailing_slash: ${s(config.kit.trailingSlash)}
+					trailing_slash: config.kit.trailingSlash
 				};
 			}
 

packages/kit/src/core/config/index.spec.js

@@ -4,9 +4,7 @@ import { deep_merge, validate_config } from './index.js';
 
 test('fills in defaults', () => {
 	const validated = validate_config({});
-
-	// @ts-expect-error
-	delete validated.kit.vite;
+	delete_complex_opts(validated);
 
 	assert.equal(validated, {
 		compilerOptions: null,
@@ -27,7 +25,6 @@ test('fills in defaults', () => {
 			floc: false,
 			host: null,
 			hostHeader: null,
-			hydrate: true,
 			package: {
 				dir: 'package',
 				exports: {
@@ -49,12 +46,8 @@ test('fills in defaults', () => {
 			},
 			prerender: {
 				crawl: true,
-				enabled: true,
-				force: false,
 				pages: ['*']
 			},
-			router: true,
-			ssr: true,
 			target: null,
 			trailingSlash: 'never'
 		},
@@ -105,8 +98,7 @@ test('fills in partial blanks', () => {
 
 	assert.equal(validated.kit.vite(), {});
 
-	// @ts-expect-error
-	delete validated.kit.vite;
+	delete_complex_opts(validated);
 
 	assert.equal(validated, {
 		compilerOptions: null,
@@ -127,7 +119,6 @@ test('fills in partial blanks', () => {
 			floc: false,
 			host: null,
 			hostHeader: null,
-			hydrate: true,
 			package: {
 				dir: 'package',
 				exports: {
@@ -149,12 +140,8 @@ test('fills in partial blanks', () => {
 			},
 			prerender: {
 				crawl: true,
-				enabled: true,
-				force: false,
 				pages: ['*']
 			},
-			router: true,
-			ssr: true,
 			target: null,
 			trailingSlash: 'never'
 		},
@@ -513,3 +500,17 @@ deepMergeSuite('merge including toString', () => {
 });
 
 deepMergeSuite.run();
+
+/** @param {import('types/config').ValidatedConfig} validated */
+function delete_complex_opts(validated) {
+	// @ts-expect-error
+	delete validated.kit.vite;
+	// @ts-expect-error
+	delete validated.kit.hydrate;
+	// @ts-expect-error
+	delete validated.kit.prerender.enabled;
+	// @ts-expect-error
+	delete validated.kit.router;
+	// @ts-expect-error
+	delete validated.kit.ssr;
+}

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

@@ -78,7 +78,10 @@ const options = {
 
 			hostHeader: expect_string(null),
 
-			hydrate: expect_boolean(true),
+			hydrate: expect_page_scriptable(async ({ page }) => {
+				const leaf = await page;
+				return 'hydrate' in leaf ? !!leaf.hydrate : true;
+			}),
 			serviceWorker: {
 				type: 'branch',
 				children: {
@@ -120,8 +123,10 @@ const options = {
 				type: 'branch',
 				children: {
 					crawl: expect_boolean(true),
-					enabled: expect_boolean(true),
-					force: expect_boolean(false),
+					enabled: expect_page_scriptable(async ({ page }) => {
+						const leaf = await page;
+						return 'prerender' in leaf ? !!leaf.prerender : true;
+					}),
 					pages: {
 						type: 'leaf',
 						default: ['*'],
@@ -144,9 +149,15 @@ const options = {
 				}
 			},
 
-			router: expect_boolean(true),
+			router: expect_page_scriptable(async ({ page }) => {
+				const leaf = await page;
+				return 'router' in leaf ? !!leaf.router : true;
+			}),
 
-			ssr: expect_boolean(true),
+			ssr: expect_page_scriptable(async ({ page }) => {
+				const leaf = await page;
+				return 'ssr' in leaf ? !!leaf.ssr : true;
+			}),
 
 			target: expect_string(null),
 
@@ -233,6 +244,23 @@ function expect_boolean(boolean) {
 	};
 }
 
+/**
+ * @param {import('types/config').ScriptablePageOpt<boolean>} value
+ * @returns {ConfigDefinition}
+ */
+function expect_page_scriptable(value) {
+	return {
+		type: 'leaf',
+		default: value,
+		validate: (option, keypath) => {
+			if (typeof option !== 'boolean' && typeof option !== 'function') {
+				throw new Error(`${keypath} should be a boolean or function that returns one`);
+			}
+			return option;
+		}
+	};
+}
+
 /**
  * @param {string[]} options
  * @returns {ConfigDefinition}

packages/kit/src/core/config/test/index.js

@@ -14,9 +14,7 @@ async function testLoadDefaultConfig(path) {
 	const cwd = join(__dirname, 'fixtures', path);
 
 	const config = await load_config({ cwd });
-
-	// @ts-expect-error
-	delete config.kit.vite; // can't test equality of a function
+	delete_complex_opts(config);
 
 	assert.equal(config, {
 		compilerOptions: null,
@@ -37,7 +35,6 @@ async function testLoadDefaultConfig(path) {
 			floc: false,
 			host: null,
 			hostHeader: null,
-			hydrate: true,
 			package: {
 				dir: 'package',
 				exports: {
@@ -54,9 +51,7 @@ async function testLoadDefaultConfig(path) {
 				exclude: []
 			},
 			paths: { base: '', assets: '/.' },
-			prerender: { crawl: true, enabled: true, force: false, pages: ['*'] },
-			router: true,
-			ssr: true,
+			prerender: { crawl: true, pages: ['*'] },
 			target: null,
 			trailingSlash: 'never'
 		},
@@ -103,3 +98,17 @@ test('errors on loading config with incorrect default export', async () => {
 });
 
 test.run();
+
+/** @param {import('types/config').ValidatedConfig} validated */
+function delete_complex_opts(validated) {
+	// @ts-expect-error
+	delete validated.kit.vite;
+	// @ts-expect-error
+	delete validated.kit.hydrate;
+	// @ts-expect-error
+	delete validated.kit.prerender.enabled;
+	// @ts-expect-error
+	delete validated.kit.router;
+	// @ts-expect-error
+	delete validated.kit.ssr;
+}

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

@@ -392,6 +392,7 @@ async function create_handler(vite, config, dir, cwd, manifest) {
 							};
 						},
 						manifest,
+						prerender: config.kit.prerender.enabled,
 						read: (file) => fs.readFileSync(path.join(config.kit.files.assets, file)),
 						root,
 						router: config.kit.router,