feat: allow async reroute

closes #13176

Author: dummdidumm

.changeset/cool-donkeys-pump.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: allow async `reroute`

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

@@ -299,6 +299,8 @@ The `lang` parameter will be correctly derived from the returned pathname.
 
 Using `reroute` will _not_ change the contents of the browser's address bar, or the value of `event.url`.
 
+Since version 2.18, the `reroute` hook is allowed to be asynchronous, to for example fetch data from your backend to decide where to reroute. Use this carefully and make sure it's fast, as this will delay navigations otherwise.
+
 ### transport
 
 This is a collection of _transporters_, which allow you to pass custom types — returned from `load` and form actions — across the server/client boundary. Each transporter contains an `encode` function, which encodes values on the server (or returns `false` for anything that isn't an instance of the type) and a corresponding `decode` function:

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

@@ -814,7 +814,7 @@ export type ClientInit = () => MaybePromise<void>;
  * The [`reroute`](https://svelte.dev/docs/kit/hooks#Universal-hooks-reroute) hook allows you to modify the URL before it is used to determine which route to render.
  * @since 2.3.0
  */
-export type Reroute = (event: { url: URL }) => void | string;
+export type Reroute = (event: { url: URL }) => MaybePromise<void | string>;
 
 /**
  * The [`transport`](https://svelte.dev/docs/kit/hooks#Universal-hooks-transport) hook allows you to transport custom types across the server/client boundary.

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

@@ -1198,13 +1198,13 @@ async function load_root_error_page({ status, error, url, route }) {
 /**
  * Resolve the relative rerouted URL for a client-side navigation
  * @param {URL} url
- * @returns {URL | undefined}
+ * @returns {Promise<URL | undefined>}
  */
-function get_rerouted_url(url) {
-	// reroute could alter the given URL, so we pass a copy
+async function get_rerouted_url(url) {
 	let rerouted;
 	try {
-		rerouted = app.hooks.reroute({ url: new URL(url) }) ?? url;
+		// reroute could alter the given URL, so we pass a copy
+		rerouted = (await app.hooks.reroute({ url: new URL(url) })) ?? url;
 
 		if (typeof rerouted === 'string') {
 			const tmp = new URL(url); // do not mutate the incoming URL
@@ -1246,7 +1246,7 @@ async function get_navigation_intent(url, invalidating) {
 	if (is_external_url(url, base, app.hash)) return;
 
 	if (__SVELTEKIT_CLIENT_ROUTING__) {
-		const rerouted = get_rerouted_url(url);
+		const rerouted = await get_rerouted_url(url);
 		if (!rerouted) return;
 
 		const path = get_url_path(rerouted);
@@ -1997,7 +1997,7 @@ export async function preloadCode(pathname) {
 		}
 
 		if (__SVELTEKIT_CLIENT_ROUTING__) {
-			const rerouted = get_rerouted_url(url);
+			const rerouted = await get_rerouted_url(url);
 			if (!rerouted || !routes.find((route) => route.exec(get_url_path(rerouted)))) {
 				throw new Error(`'${pathname}' did not match any routes`);
 			}

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

@@ -115,7 +115,7 @@ export async function respond(request, options, manifest, state) {
 
 	try {
 		// reroute could alter the given URL, so we pass a copy
-		resolved_path = options.hooks.reroute({ url: new URL(url) }) ?? url.pathname;
+		resolved_path = (await options.hooks.reroute({ url: new URL(url) })) ?? url.pathname;
 	} catch {
 		return text('Internal Server Error', {
 			status: 500

packages/kit/test/apps/basics/src/hooks.js

@@ -27,6 +27,14 @@ export const reroute = ({ url }) => {
 		throw new Error('Server Error - Should trigger 500 response');
 	}
 
+	if (url.pathname === '/reroute/async/a') {
+		return new Promise((resolve) => {
+			setTimeout(() => {
+				resolve('/reroute/async/b');
+			}, 100);
+		});
+	}
+
 	if (url.pathname in mapping) {
 		return mapping[url.pathname];
 	}

packages/kit/test/apps/basics/src/routes/reroute/async/+page.svelte

@@ -0,0 +1 @@
+<a href="/reroute/async/a">Go to url that should be rewritten</a>

packages/kit/test/apps/basics/src/routes/reroute/async/a/+page.svelte

@@ -0,0 +1 @@
+<h1>Should have been rewritten to <code>/reroute/async/b</code></h1>

packages/kit/test/apps/basics/src/routes/reroute/async/b/+page.svelte

@@ -0,0 +1,5 @@
+<script>
+	import { page } from '$app/state';
+</script>
+
+<h1>Successfully rewritten, URL should still show a: {page.url.pathname}</h1>

packages/kit/test/apps/basics/test/client.test.js

@@ -1402,6 +1402,14 @@ test.describe('reroute', () => {
 		);
 	});
 
+	test('Apply async reroute during client side navigation', async ({ page }) => {
+		await page.goto('/reroute/async');
+		await page.click("a[href='/reroute/async/a']");
+		expect(await page.textContent('h1')).toContain(
+			'Successfully rewritten, URL should still show a: /reroute/async/a'
+		);
+	});
+
 	test('Apply reroute after client-only redirects', async ({ page }) => {
 		await page.goto('/reroute/client-only-redirect');
 		expect(await page.textContent('h1')).toContain('Successfully rewritten');

packages/kit/test/apps/basics/test/server.test.js

@@ -668,6 +668,13 @@ test.describe('reroute', () => {
 		);
 	});
 
+	test('Apply async reroute when directly accessing a page', async ({ page }) => {
+		await page.goto('/reroute/async/a');
+		expect(await page.textContent('h1')).toContain(
+			'Successfully rewritten, URL should still show a: /reroute/async/a'
+		);
+	});
+
 	test('Returns a 500 response if reroute throws an error on the server', async ({ page }) => {
 		const response = await page.goto('/reroute/error-handling/server-error');
 		expect(response?.status()).toBe(500);

packages/kit/types/index.d.ts

@@ -796,7 +796,7 @@ declare module '@sveltejs/kit' {
 	 * The [`reroute`](https://svelte.dev/docs/kit/hooks#Universal-hooks-reroute) hook allows you to modify the URL before it is used to determine which route to render.
 	 * @since 2.3.0
 	 */
-	export type Reroute = (event: { url: URL }) => void | string;
+	export type Reroute = (event: { url: URL }) => MaybePromise<void | string>;
 
 	/**
 	 * The [`transport`](https://svelte.dev/docs/kit/hooks#Universal-hooks-transport) hook allows you to transport custom types across the server/client boundary.