feat: add reroute hook

.changeset/thin-ears-double.md

@@ -0,0 +1,5 @@
+---
+"@sveltejs/kit": minor
+---
+
+feat: add `rewriteUrl` hook

documentation/docs/30-advanced/20-hooks.md

@@ -4,12 +4,13 @@ title: Hooks
 
 'Hooks' are app-wide functions you declare that SvelteKit will call in response to specific events, giving you fine-grained control over the framework's behaviour.
 
-There are two hooks files, both optional:
+There are three hooks files, all optional:
 
 - `src/hooks.server.js` — your app's server hooks
 - `src/hooks.client.js` — your app's client hooks
+- `src/hooks.js` — your app's hooks that run on both the client and server
 
-Code in these modules will run when the application starts up, making them useful for initializing database clients and so on.
+Code in the client and server modules will run when the application starts up, making them useful for initializing database clients and so on.
 
 > You can configure the location of these files with [`config.kit.files.hooks`](configuration#files).
 
@@ -232,6 +233,36 @@ During development, if an error occurs because of a syntax error in your Svelte
 
 > Make sure that `handleError` _never_ throws an error
 
+## Universal hooks
+
+The following can be added to `src/hooks.js`. Universal hooks share the same implementation on the server and the client. This is not to be confused with shared hooks, which use separate implementations.
+
+### rewriteUrl
+
+This function allows you to rewrite URLs before SvelteKit uses them to determine which route to render. It will not change the URL in the browser's address bar, or the value of `event.url`. Only the route matching logic is affected.
+
+```js
+/// file: src/hooks.router.js
+// @errors: 2345
+// @errors: 2304
+
+/** @type {Record<string, string>} */
+const mapping = {
+	"/en/about": "/en/about",
+	"/de/ueber-uns": "/de/about",
+	"/fr/a-propos": "/fr/about",
+}
+
+/** @type {import('@sveltejs/kit').RewriteUrl} */
+export function rewriteUrl({ url }) {
+	url.pathname = mapping[url.pathname] ?? url.pathname;
+	return url;
+}
+```
+
+> `rewriteUrl` is not applied to the returned URL
+
+
 ## Further reading
 
 - [Tutorial: Hooks](https://learn.svelte.dev/tutorial/handle)

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

@@ -93,6 +93,7 @@ function process_config(config, { cwd = process.cwd() } = {}) {
 		if (key === 'hooks') {
 			validated.kit.files.hooks.client = path.resolve(cwd, validated.kit.files.hooks.client);
 			validated.kit.files.hooks.server = path.resolve(cwd, validated.kit.files.hooks.server);
+			validated.kit.files.hooks.universal = path.resolve(cwd, validated.kit.files.hooks.universal);
 		} else {
 			// @ts-expect-error
 			validated.kit.files[key] = path.resolve(cwd, validated.kit.files[key]);

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

@@ -79,7 +79,8 @@ const get_defaults = (prefix = '') => ({
 			assets: join(prefix, 'static'),
 			hooks: {
 				client: join(prefix, 'src/hooks.client'),
-				server: join(prefix, 'src/hooks.server')
+				server: join(prefix, 'src/hooks.server'),
+				universal: join(prefix, 'src/hooks')
 			},
 			lib: join(prefix, 'src/lib'),
 			params: join(prefix, 'src/params'),

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

@@ -123,7 +123,8 @@ const options = object(
 				assets: string('static'),
 				hooks: object({
 					client: string(join('src', 'hooks.client')),
-					server: string(join('src', 'hooks.server'))
+					server: string(join('src', 'hooks.server')),
+					universal: string(join('src', 'hooks'))
 				}),
 				lib: string(join('src', 'lib')),
 				params: string(join('src', 'params')),

packages/kit/src/core/sync/write_client_manifest.js

@@ -108,7 +108,8 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 		}
 	`;
 
-	const hooks_file = resolve_entry(kit.files.hooks.client);
+	const client_hooks_file = resolve_entry(kit.files.hooks.client);
+	const universal_hooks_file = resolve_entry(kit.files.hooks.universal);
 
 	const typo = resolve_entry('src/+hooks.client');
 	if (typo) {
@@ -125,7 +126,16 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 	write_if_changed(
 		`${output}/app.js`,
 		dedent`
-			${hooks_file ? `import * as client_hooks from '${relative_path(output, hooks_file)}';` : ''}
+			${
+				client_hooks_file
+					? `import * as client_hooks from '${relative_path(output, client_hooks_file)}';`
+					: ''
+			}
+			${
+				universal_hooks_file
+					? `import * as universal_hooks from '${relative_path(output, universal_hooks_file)}';`
+					: ''
+			}
 
 			export { matchers } from './matchers.js';
 
@@ -139,8 +149,10 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 
 			export const hooks = {
 				handleError: ${
-					hooks_file ? 'client_hooks.handleError || ' : ''
+					client_hooks_file ? 'client_hooks.handleError || ' : ''
 				}(({ error }) => { console.error(error) }),
+
+				rewriteUrl: ${universal_hooks_file ? 'universal_hooks.rewriteUrl || ' : ''}(({url}) => url)
 			};
 
 			export { default as root } from '../root.${isSvelte5Plus() ? 'js' : 'svelte'}';

packages/kit/src/core/sync/write_server.js

@@ -9,7 +9,8 @@ import colors from 'kleur';
 
 /**
  * @param {{
- *   hooks: string | null;
+ *   server_hooks: string | null;
+ *   universal_hooks: string | null;
  *   config: import('types').ValidatedConfig;
  *   has_service_worker: boolean;
  *   runtime_directory: string;
@@ -19,7 +20,8 @@ import colors from 'kleur';
  */
 const server_template = ({
 	config,
-	hooks,
+	server_hooks,
+	universal_hooks,
 	has_service_worker,
 	runtime_directory,
 	template,
@@ -59,8 +61,11 @@ export const options = {
 	version_hash: ${s(hash(config.kit.version.name))}
 };
 
-export function get_hooks() {
-	return ${hooks ? `import(${s(hooks)})` : '{}'};
+export async function get_hooks() {
+	return {
+		${server_hooks ? `...(await import(${s(server_hooks)})),` : ''}
+		${universal_hooks ? `...(await import(${s(universal_hooks)})),` : ''}
+	};
 }
 
 export { set_assets, set_building, set_prerendering, set_private_env, set_public_env, set_safe_public_env };
@@ -76,7 +81,8 @@ export { set_assets, set_building, set_prerendering, set_private_env, set_public
  * @param {string} output
  */
 export function write_server(config, output) {
-	const hooks_file = resolve_entry(config.kit.files.hooks.server);
+	const server_hooks_file = resolve_entry(config.kit.files.hooks.server);
+	const universal_hooks_file = resolve_entry(config.kit.files.hooks.universal);
 
 	const typo = resolve_entry('src/+hooks.server');
 	if (typo) {
@@ -99,7 +105,8 @@ export function write_server(config, output) {
 		`${output}/server/internal.js`,
 		server_template({
 			config,
-			hooks: hooks_file ? relative(hooks_file) : null,
+			server_hooks: server_hooks_file ? relative(server_hooks_file) : null,
+			universal_hooks: universal_hooks_file ? relative(universal_hooks_file) : null,
 			has_service_worker:
 				config.kit.serviceWorker.register && !!resolve_entry(config.kit.files.serviceWorker),
 			runtime_directory: relative(runtime_directory),

packages/kit/src/exports/public.d.ts

@@ -392,6 +392,11 @@ export interface KitConfig {
 			 * @default "src/hooks.server"
 			 */
 			server?: string;
+			/**
+			 * The location of your universal [hooks](https://kit.svelte.dev/docs/hooks).
+			 * @default "src/hooks"
+			 */
+			universal?: string;
 		};
 		/**
 		 * your app's internal library, accessible throughout the codebase as `$lib`
@@ -675,6 +680,11 @@ export type HandleFetch = (input: {
 	fetch: typeof fetch;
 }) => MaybePromise<Response>;
 
+/**
+ * The [`rewriteUrl`](#) hook allows you to modify the URL before it is used to determine which route to render.
+ */
+export type RewriteUrl = (event: { url: URL }) => URL;
+
 /**
  * The generic form of `PageLoad` and `LayoutLoad`. You should import those from `./$types` (see [generated types](https://kit.svelte.dev/docs/types#generated-types))
  * rather than using `Load` directly.

packages/kit/src/runtime/client/client.js

@@ -1071,21 +1071,37 @@ async function load_root_error_page({ status, error, url, route }) {
 }
 
 /**
- * @param {URL} url
+ * @param {URL | undefined} original_url
  * @param {boolean} invalidating
  */
-function get_navigation_intent(url, invalidating) {
-	if (is_external_url(url, base)) return;
+function get_navigation_intent(original_url, invalidating) {
+	if (!original_url) return undefined;
+
+	// rewriteUrl could alter the given URL, so we pass a copy
+	let rewritten_url;
+	try {
+		rewritten_url = app.hooks.rewriteUrl({ url: new URL(original_url) });
+	} catch (e) {
+		return undefined;
+	}
 
-	const path = get_url_path(url.pathname);
+	if (is_external_url(rewritten_url, base)) return;
+
+	const path = get_url_path(rewritten_url.pathname);
 
 	for (const route of routes) {
 		const params = route.exec(path);
 
 		if (params) {
-			const id = url.pathname + url.search;
+			const id = original_url.pathname + original_url.search;
 			/** @type {import('./types.js').NavigationIntent} */
-			const intent = { id, invalidating, route, params: decode_params(params), url };
+			const intent = {
+				id,
+				invalidating,
+				route,
+				params: decode_params(params),
+				url: original_url
+			};
 			return intent;
 		}
 	}
@@ -1451,7 +1467,7 @@ function setup_preload() {
 
 		if (!options.reload) {
 			if (priority <= options.preload_data) {
-				const intent = get_navigation_intent(/** @type {URL} */ (url), false);
+				const intent = get_navigation_intent(url, false);
 				if (intent) {
 					if (DEV) {
 						_preload_data(intent).then((result) => {

packages/kit/src/runtime/server/ambient.d.ts

@@ -1,8 +1,4 @@
 declare module '__SERVER__/internal.js' {
 	export const options: import('types').SSROptions;
-	export const get_hooks: () => Promise<{
-		handle?: import('@sveltejs/kit').Handle;
-		handleError?: import('@sveltejs/kit').HandleServerError;
-		handleFetch?: import('@sveltejs/kit').HandleFetch;
-	}>;
+	export const get_hooks: () => Promise<Partial<import('../../types/internal.js').ServerHooks>>;
 }

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

@@ -62,7 +62,8 @@ export class Server {
 				this.#options.hooks = {
 					handle: module.handle || (({ event, resolve }) => resolve(event)),
 					handleError: module.handleError || (({ error }) => console.error(error)),
-					handleFetch: module.handleFetch || (({ request, fetch }) => fetch(request))
+					handleFetch: module.handleFetch || (({ request, fetch }) => fetch(request)),
+					rewriteUrl: module.rewriteUrl || (({ url }) => url)
 				};
 			} catch (error) {
 				if (DEV) {
@@ -71,7 +72,8 @@ export class Server {
 							throw error;
 						},
 						handleError: ({ error }) => console.error(error),
-						handleFetch: ({ request, fetch }) => fetch(request)
+						handleFetch: ({ request, fetch }) => fetch(request),
+						rewriteUrl: ({ url }) => url
 					};
 				} else {
 					throw error;