feat: hash based routing (#13191)

* hash based routing

* tests

* fix test

* fml this took me 40 minutes to figure out

* for push/replaceState, too

* more robust tests

* please?

* change approach: make hash visible in page.url etc, require user to pass in hash links

* lint, fix test

* Apply suggestions from code review

* hashchange handling

* rename 'history' to 'pathname', update docs

* update internal jsdoc

* disable SSR and server-only files

* disallow page options at build time

* oops

* allow access to event.url.hash in hash mode

* prerender shell

* add failing reroute test

* fix

* make hash trackable

* skip test for now

* don't normalise

* lint

* i don't understand this code — even with the prior normalization it's unclear what it would do. no tests fail without it so for now i'm just gonna remove to shut typescript up

* get_route_id -> get_page_key

* detect hash changes via URL bar

---------

Co-authored-by: Rich Harris <[email protected]>

Author: dummdidumm

.changeset/thirty-wasps-itch.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: add hash-based routing option

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

@@ -94,6 +94,9 @@ const get_defaults = (prefix = '') => ({
 		moduleExtensions: ['.js', '.ts'],
 		output: { preloadStrategy: 'modulepreload', bundleStrategy: 'split' },
 		outDir: join(prefix, '.svelte-kit'),
+		router: {
+			type: 'pathname'
+		},
 		serviceWorker: {
 			register: true
 		},

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

@@ -260,6 +260,10 @@ const options = object(
 				})
 			}),
 
+			router: object({
+				type: list(['pathname', 'hash'])
+			}),
+
 			serviceWorker: object({
 				register: boolean(true),
 				files: fun((filename) => !/\.DS_Store/.test(filename))

packages/kit/src/core/postbuild/analyse.js

@@ -22,14 +22,22 @@ export default forked(import.meta.url, analyse);
 
 /**
  * @param {{
+ *   hash: boolean;
  *   manifest_path: string;
  *   manifest_data: import('types').ManifestData;
  *   server_manifest: import('vite').Manifest;
  *   tracked_features: Record<string, string[]>;
  *   env: Record<string, string>
  * }} opts
  */
-async function analyse({ manifest_path, manifest_data, server_manifest, tracked_features, env }) {
+async function analyse({
+	hash,
+	manifest_path,
+	manifest_data,
+	server_manifest,
+	tracked_features,
+	env
+}) {
 	/** @type {import('@sveltejs/kit').SSRManifest} */
 	const manifest = (await import(pathToFileURL(manifest_path).href)).manifest;
 
@@ -67,6 +75,18 @@ async function analyse({ manifest_path, manifest_data, server_manifest, tracked_
 
 	// analyse nodes
 	for (const node of nodes) {
+		if (hash && node.universal) {
+			const options = Object.keys(node.universal).filter((o) => o !== 'load');
+			if (options.length > 0) {
+				throw new Error(
+					`Page options are ignored when \`router.type === 'hash'\` (${node.universal_id} has ${options
+						.filter((o) => o !== 'load')
+						.map((o) => `'${o}'`)
+						.join(', ')})`
+				);
+			}
+		}
+
 		metadata.nodes[node.index] = {
 			has_server_load: node.server?.load !== undefined || node.server?.trailingSlash !== undefined
 		};

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

@@ -13,6 +13,7 @@ import { crawl } from './crawl.js';
 import { forked } from '../../utils/fork.js';
 import * as devalue from 'devalue';
 import { createReadableStream } from '@sveltejs/kit/node';
+import generate_fallback from './fallback.js';
 
 export default forked(import.meta.url, prerender);
 
@@ -24,14 +25,15 @@ const SPECIAL_HASHLINKS = new Set(['', 'top']);
 
 /**
  * @param {{
+ *   hash: boolean;
  *   out: string;
  *   manifest_path: string;
  *   metadata: import('types').ServerMetadata;
  *   verbose: boolean;
  *   env: Record<string, string>
  * }} opts
  */
-async function prerender({ out, manifest_path, metadata, verbose, env }) {
+async function prerender({ hash, out, manifest_path, metadata, verbose, env }) {
 	/** @type {import('@sveltejs/kit').SSRManifest} */
 	const manifest = (await import(pathToFileURL(manifest_path).href)).manifest;
 
@@ -98,6 +100,23 @@ async function prerender({ out, manifest_path, metadata, verbose, env }) {
 	/** @type {import('types').ValidatedKitConfig} */
 	const config = (await load_config()).kit;
 
+	if (hash) {
+		const fallback = await generate_fallback({
+			manifest_path,
+			env
+		});
+
+		const file = output_filename('/', true);
+		const dest = `${config.outDir}/output/prerendered/pages/${file}`;
+
+		mkdirp(dirname(dest));
+		writeFileSync(dest, fallback);
+
+		prerendered.pages.set('/', { file });
+
+		return { prerendered, prerender_map };
+	}
+
 	const emulator = await config.adapter?.emulate?.();
 
 	/** @type {import('types').Logger} */

packages/kit/src/core/sync/create_manifest_data/index.js

@@ -271,6 +271,12 @@ function create_routes_and_nodes(cwd, config, fallback) {
 					config.kit.moduleExtensions
 				);
 
+				if (config.kit.router.type === 'hash' && item.kind === 'server') {
+					throw new Error(
+						`Cannot use server-only files in an app with \`router.type === 'hash': ${project_relative}`
+					);
+				}
+
 				/**
 				 * @param {string} type
 				 * @param {string} existing_file

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

@@ -158,6 +158,8 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 
 			export const decoders = Object.fromEntries(Object.entries(hooks.transport).map(([k, v]) => [k, v.decode]));
 
+			export const hash = ${JSON.stringify(kit.router.type === 'hash')};
+
 			export const decode = (type, value) => decoders[type](value);
 
 			export { default as root } from '../root.${isSvelte5Plus() ? 'js' : 'svelte'}';

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

@@ -42,6 +42,7 @@ export const options = {
 	embedded: ${config.kit.embedded},
 	env_public_prefix: '${config.kit.env.publicPrefix}',
 	env_private_prefix: '${config.kit.env.privatePrefix}',
+	hash_routing: ${s(config.kit.router.type === 'hash')},
 	hooks: null, // added lazily, via \`get_hooks\`
 	preload_strategy: ${s(config.kit.output.preloadStrategy)},
 	root,

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

@@ -617,6 +617,16 @@ export interface KitConfig {
 		 */
 		origin?: string;
 	};
+	router?: {
+		/**
+		 * What type of client-side router to use.
+		 * - `'pathname'` is the default and means the current URL pathname determines the route
+		 * - `'hash'` means the route is determined by `location.hash`. In this case, SSR and prerendering are disabled. This is only recommended if `pathname` is not an option, for example because you don't control the webserver where your app is deployed.
+		 *
+		 * @default "pathname"
+		 */
+		type?: 'pathname' | 'hash';
+	};
 	serviceWorker?: {
 		/**
 		 * Whether to automatically register the service worker, if it exists.

packages/kit/src/exports/vite/index.js

@@ -793,6 +793,7 @@ async function kit({ svelte_config }) {
 				);
 
 				const metadata = await analyse({
+					hash: kit.router.type === 'hash',
 					manifest_path,
 					manifest_data,
 					server_manifest,
@@ -897,6 +898,7 @@ async function kit({ svelte_config }) {
 
 				// ...and prerender
 				const { prerendered, prerender_map } = await prerender({
+					hash: kit.router.type === 'hash',
 					out,
 					manifest_path,
 					metadata,