[feat] add an ssr parameter to resolve for better skipping of SSR

.changeset/spicy-moose-relate.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+Remove `config.kit.ssr` and `export const ssr` in favour of `ssr` parameter for `resolve` function in `handle`

documentation/docs/04-hooks.md

@@ -47,11 +47,15 @@ export interface Response {
 	body?: StrictBody;
 }
 
+export interface ResolveOpts {
+	ssr?: boolean;
+}
+
 export interface Handle<Locals = Record<string, any>, Body = unknown> {
 	(input: {
-		request: Request<Locals, Body>;
-		resolve(request: Request<Locals, Body>): Response | Promise<Response>;
-	}): Response | Promise<Response>;
+		request: ServerRequest<Locals, Body>;
+		resolve(request: ServerRequest<Locals, Body>, opts?: ResolveOpts): MaybePromise<ServerResponse>;
+	}): MaybePromise<ServerResponse>;
 }
 ```
 
@@ -76,6 +80,23 @@ export async function handle({ request, resolve }) {
 
 You can add call multiple `handle` functions with [the `sequence` helper function](#modules-sveltejs-kit-hooks).
 
+`resolve` also supports a second, optional parameter that gives you more control over how the response will be rendered. That parameter is an object that can have the following fields:
+
+- `ssr` — specifies whether the page will be loaded and rendered on the server.
+
+```js
+/** @type {import('@sveltejs/kit').Handle} */
+export async function handle({ request, resolve }) {
+	const response = await resolve(request, {
+		ssr: !request.path.startsWith('/admin')
+	});
+
+	return response;
+}
+```
+
+> Disabling [server-side rendering](#appendix-ssr) effectively turns your SvelteKit app into a [**single-page app** or SPA](#appendix-csr-and-spa). In most situations this is not recommended ([see appendix](#appendix-ssr)). Consider whether it's truly appropriate to disable it, and do so selectively rather than for all requests.
+
 ### handleError
 
 If an error is thrown during rendering, this function will be called with the `error` and the `request` that caused it. This allows you to send data to an error tracking service, or to customise the formatting before printing the error to the console.

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

@@ -6,21 +6,7 @@ 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.
-
-### ssr
-
-Disabling [server-side rendering](#appendix-ssr) effectively turns your SvelteKit app into a [**single-page app** or SPA](#appendix-csr-and-spa).
-
-> 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:
-
-```html
-<script context="module">
-	export const ssr = false;
-</script>
-```
+If both are specified, per-page settings override per-app settings in case of conflicts.
 
 ### router
 

documentation/docs/14-configuration.md

@@ -56,7 +56,6 @@ const config = {
 			register: true,
 			files: (filepath) => !/\.DS_STORE/.test(filepath)
 		},
-		ssr: true,
 		target: null,
 		trailingSlash: 'never',
 		vite: () => ({})
@@ -217,10 +216,6 @@ An object containing zero or more of the following values:
 
 - `files` - a function with the type of `(filepath: string) => boolean`. When `true`, the given file will be available in `$service-worker.files`, otherwise it will be excluded.
 
-### ssr
-
-Enables or disables [server-side rendering](#ssr-and-javascript-ssr) app-wide.
-
 ### target
 
 Specifies an element to mount the app to. It must be a DOM selector that identifies an element that exists in your template file. If unspecified, the app will be mounted to `document.body`.

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

@@ -78,7 +78,6 @@ export class App {
 			root,
 			service_worker: ${has_service_worker ? "'/service-worker.js'" : 'null'},
 			router: ${s(config.kit.router)},
-			ssr: ${s(config.kit.ssr)},
 			target: ${s(config.kit.target)},
 			template,
 			trailing_slash: ${s(config.kit.trailingSlash)}

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

@@ -57,7 +57,6 @@ test('fills in defaults', () => {
 			},
 			protocol: null,
 			router: true,
-			ssr: true,
 			target: null,
 			trailingSlash: 'never'
 		}
@@ -164,7 +163,6 @@ test('fills in partial blanks', () => {
 			},
 			protocol: null,
 			router: true,
-			ssr: true,
 			target: null,
 			trailingSlash: 'never'
 		}

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

@@ -171,8 +171,6 @@ const options = object(
 				files: fun((filename) => !/\.DS_STORE/.test(filename))
 			}),
 
-			ssr: boolean(true),
-
 			target: string(null),
 
 			trailingSlash: list(['never', 'always', 'ignore']),

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

@@ -56,7 +56,6 @@ test('load default config (esm)', async () => {
 			},
 			protocol: null,
 			router: true,
-			ssr: true,
 			target: null,
 			trailingSlash: 'never'
 		}

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

@@ -223,7 +223,6 @@ export async function create_plugin(config, output, cwd) {
 								read: (file) => fs.readFileSync(path.join(config.kit.files.assets, file)),
 								root,
 								router: config.kit.router,
-								ssr: config.kit.ssr,
 								target: config.kit.target,
 								template: ({ head, body, assets }) => {
 									let rendered = load_template(cwd, config)

packages/kit/src/runtime/app/stores.js

@@ -1,8 +1,6 @@
 import { getContext } from 'svelte';
 import { browser } from './env.js';
 
-const ssr = !browser;
-
 // TODO remove this (for 1.0? after 1.0?)
 let warned = false;
 export function stores() {
@@ -58,9 +56,9 @@ export const navigating = {
 /** @param {string} verb */
 const throw_error = (verb) => {
 	throw new Error(
-		ssr
-			? `Can only ${verb} session store in browser`
-			: `Cannot ${verb} session store before subscribing`
+		browser
+			? `Cannot ${verb} session store before subscribing`
+			: `Can only ${verb} session store in browser`
 	);
 };
 
@@ -69,7 +67,7 @@ export const session = {
 	subscribe(fn) {
 		const store = getStores().session;
 
-		if (!ssr) {
+		if (browser) {
 			session.set = store.set;
 			session.update = store.update;
 		}

packages/kit/src/runtime/server/index.js

@@ -60,19 +60,24 @@ export async function respond(incoming, options, state = {}) {
 	print_error('path', 'pathname');
 	print_error('query', 'searchParams');
 
+	let ssr = true;
+
 	try {
 		return await options.hooks.handle({
 			request,
-			resolve: async (request) => {
+			resolve: async (request, opts) => {
+				if (opts && 'ssr' in opts) ssr = /** @type {boolean} */ (opts.ssr);
+
 				if (state.prerender && state.prerender.fallback) {
 					return await render_response({
 						url: request.url,
 						params: request.params,
 						options,
 						$session: await options.hooks.getSession(request),
-						page_config: { ssr: false, router: true, hydrate: true },
+						page_config: { router: true, hydrate: true },
 						status: 200,
-						branch: []
+						branch: [],
+						ssr: false
 					});
 				}
 
@@ -85,7 +90,7 @@ export async function respond(incoming, options, state = {}) {
 					const response =
 						route.type === 'endpoint'
 							? await render_endpoint(request, route, match)
-							: await render_page(request, route, match, options, state);
+							: await render_page(request, route, match, options, state, ssr);
 
 					if (response) {
 						// inject ETags for 200 responses
@@ -125,7 +130,8 @@ export async function respond(incoming, options, state = {}) {
 						state,
 						$session,
 						status: 404,
-						error: new Error(`Not found: ${request.url.pathname}`)
+						error: new Error(`Not found: ${request.url.pathname}`),
+						ssr
 					});
 				}
 			}
@@ -143,7 +149,8 @@ export async function respond(incoming, options, state = {}) {
 				state,
 				$session,
 				status: 500,
-				error
+				error,
+				ssr
 			});
 		} catch (/** @type {unknown} */ e) {
 			const error = coalesce_to_error(e);

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

@@ -7,9 +7,10 @@ import { respond } from './respond.js';
  * @param {RegExpExecArray} match
  * @param {import('types/internal').SSRRenderOptions} options
  * @param {import('types/internal').SSRRenderState} state
+ * @param {boolean} ssr
  * @returns {Promise<import('types/hooks').ServerResponse | undefined>}
  */
-export async function render_page(request, route, match, options, state) {
+export async function render_page(request, route, match, options, state, ssr) {
 	if (state.initiator === route) {
 		// infinite request cycle detected
 		return {
@@ -29,7 +30,8 @@ export async function render_page(request, route, match, options, state) {
 		state,
 		$session,
 		route,
-		params
+		params,
+		ssr
 	});
 
 	if (response) {

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

@@ -12,11 +12,12 @@ import { s } from '../../../utils/misc.js';
  *   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 };
  *   status: number;
- *   error?: Error,
+ *   error?: Error;
  *   url: URL;
- *   params: Record<string, string>
+ *   params: Record<string, string>;
+ *   ssr: boolean;
  * }} opts
  */
 export async function render_response({
@@ -27,7 +28,8 @@ export async function render_response({
 	status,
 	error,
 	url,
-	params
+	params,
+	ssr
 }) {
 	const css = new Set(options.manifest._.entry.css);
 	const js = new Set(options.manifest._.entry.js);
@@ -45,7 +47,7 @@ export async function render_response({
 		error.stack = options.get_stack(error);
 	}
 
-	if (page_config.ssr) {
+	if (ssr) {
 		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));
@@ -148,9 +150,9 @@ export async function render_response({
 					throw new Error(`Failed to serialize session data: ${error.message}`);
 				})},
 				route: ${!!page_config.router},
-				spa: ${!page_config.ssr},
+				spa: ${!ssr},
 				trailing_slash: ${s(options.trailing_slash)},
-				hydrate: ${page_config.ssr && page_config.hydrate ? `{
+				hydrate: ${ssr && page_config.hydrate ? `{
 					status: ${status},
 					error: ${serialize_error(error)},
 					nodes: [

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

@@ -19,15 +19,29 @@ import { coalesce_to_error } from '../../../utils/error.js';
  *   $session: any;
  *   route: import('types/internal').SSRPage;
  *   params: Record<string, string>;
+ *   ssr: boolean;
  * }} opts
  * @returns {Promise<ServerResponse | undefined>}
  */
 export async function respond(opts) {
-	const { request, options, state, $session, route } = opts;
+	const { request, options, state, $session, route, ssr } = opts;
 
 	/** @type {Array<SSRNode | undefined>} */
 	let nodes;
 
+	if (!ssr) {
+		return await render_response({
+			...opts,
+			branch: [],
+			page_config: {
+				hydrate: true,
+				router: true
+			},
+			status: 200,
+			url: request.url
+		});
+	}
+
 	try {
 		nodes = await Promise.all(
 			route.a.map((n) => options.manifest._.nodes[n] && options.manifest._.nodes[n]())
@@ -43,7 +57,8 @@ export async function respond(opts) {
 			state,
 			$session,
 			status: 500,
-			error
+			error,
+			ssr
 		});
 	}
 
@@ -73,7 +88,7 @@ export async function respond(opts) {
 	/** @type {string[]} */
 	let set_cookie_headers = [];
 
-	ssr: if (page_config.ssr) {
+	ssr: if (ssr) {
 		let stuff = {};
 
 		for (let i = 0; i < nodes.length; i += 1) {
@@ -179,7 +194,8 @@ export async function respond(opts) {
 							state,
 							$session,
 							status,
-							error
+							error,
+							ssr
 						}),
 						set_cookie_headers
 					);
@@ -228,8 +244,14 @@ export async function respond(opts) {
  * @param {SSRRenderOptions} options
  */
 function get_page_config(leaf, options) {
+	// TODO remove for 1.0
+	if ('ssr' in leaf) {
+		throw new Error(
+			`\`export const ssr\` has been removed — use the handle hook instead: https://kit.svelte.dev/docs#hooks-handle`
+		);
+	}
+
 	return {
-		ssr: 'ssr' in leaf ? !!leaf.ssr : options.ssr,
 		router: 'router' in leaf ? !!leaf.router : options.router,
 		hydrate: 'hydrate' in leaf ? !!leaf.hydrate : options.hydrate
 	};