sv-router 0.16.3 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sv-router",
-  "version": "0.16.3",
+  "version": "0.18.0",
   "description": "Type-safe routing for Svelte SPAs",
   "keywords": [
     "router",
@@ -20,6 +20,7 @@
     "src"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "import": "./src/index.js",
@@ -39,24 +40,24 @@
     "@eslint/js": "^10.0.1",
     "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/svelte": "^5.3.1",
+    "@testing-library/svelte": "^5.4.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^24.12.4",
-    "@vitest/coverage-v8": "^4.1.7",
-    "eslint": "^10.4.0",
+    "@types/node": "^24.13.2",
+    "@vitest/coverage-v8": "^4.1.9",
+    "eslint": "^10.6.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-simple-import-sort": "^13.0.0",
-    "eslint-plugin-svelte": "^3.18.0",
-    "eslint-plugin-unicorn": "^64.0.0",
-    "globals": "^17.6.0",
-    "happy-dom": "^20.9.0",
-    "oxfmt": "^0.52.0",
-    "svelte-check": "^4.4.8",
+    "eslint-plugin-svelte": "^3.20.0",
+    "eslint-plugin-unicorn": "^70.0.0",
+    "globals": "^17.7.0",
+    "happy-dom": "^20.10.6",
+    "oxfmt": "^0.57.0",
+    "svelte-check": "^4.7.1",
     "type-testing": "^0.2.0",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.60.0",
-    "vite": "^8.0.14",
-    "vitest": "^4.1.7"
+    "typescript-eslint": "^8.62.1",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
   },
   "peerDependencies": {
     "svelte": "^5"

package/src/cli/index.js

@@ -23,6 +23,7 @@ function parseViteConfig() {
 	if (!routerConfig) return;
 	console.log('ℹ️ Using router plugin options from Vite config');
 	if (routerConfig.allLazy) genConfig.allLazy = routerConfig.allLazy;
+	if (routerConfig.base) genConfig.base = routerConfig.base;
 	if (routerConfig.js) genConfig.routesInJs = routerConfig.js;
 	if (routerConfig.path) genConfig.routesPath = routerConfig.path;
 	if (routerConfig.ignore) genConfig.ignore = routerConfig.ignore;
@@ -58,6 +59,9 @@ function parseArgs() {
 	const allLazyArg = arg('allLazy');
 	if (allLazyArg) genConfig.allLazy = true;
 
+	const baseArg = arg('base');
+	if (baseArg) genConfig.base = baseArg;
+
 	const jsArg = arg('js');
 	if (jsArg) genConfig.routesInJs = true;
 

package/src/create-router.svelte.js

@@ -12,6 +12,7 @@ import {
 	stripBase,
 	updatedLocation,
 } from './helpers/utils.js';
+import { validateRoutes } from './helpers/validate-routes.js';
 import { Navigation } from './navigation.js';
 import { syncSearchParams } from './search-params.svelte.js';
 
@@ -53,7 +54,7 @@ let meta = $state({ value: {} });
 const navigationBlockers = new Map();
 
 let historyIndex = 0;
-let skipNextPopstate = false;
+let isSkipNextPopstate = false;
 
 /** @type {AbortController | null} */
 let currentNavigationController = null;
@@ -62,30 +63,42 @@ let pendingController = /** @type {AbortController | null} */ (null);
 /** @type {Promise<void | null> | null} */
 let currentNavigationPromise = null;
 
+/** @param {string} basename */
+function setBase(basename) {
+	const url = new URL(globalThis.location.toString());
+	if (basename === '#') {
+		base.name = '#';
+		if (!globalThis.location.href.includes('#')) {
+			url.hash = '/';
+			history.replaceState(
+				{ _routerIndex: historyIndex, _userState: history.state ?? null },
+				'',
+				url.href,
+			);
+		}
+	} else {
+		base.name = (basename.startsWith('/') ? '' : '/') + basename;
+		if (!url.pathname.startsWith(base.name)) {
+			url.pathname = join(base.name, url.pathname);
+			history.replaceState(
+				{ _routerIndex: historyIndex, _userState: history.state ?? null },
+				'',
+				url.href,
+			);
+		}
+	}
+	Object.assign(location, updatedLocation());
+}
+
 /** @param {string | undefined} basename */
 export function init(basename) {
 	if (basename) {
-		const url = new URL(globalThis.location.toString());
-		if (basename === '#') {
-			base.name = '#';
-			if (!globalThis.location.href.includes('#')) {
-				url.hash = '/';
-				history.replaceState(
-					{ _routerIndex: historyIndex, _userState: history.state ?? null },
-					'',
-					url.toString(),
-				);
-			}
-		} else {
-			base.name = (basename.startsWith('/') ? '' : '/') + basename;
-			if (!url.pathname.startsWith(base.name)) {
-				url.pathname = join(base.name, url.pathname);
-				history.replaceState(
-					{ _routerIndex: historyIndex, _userState: history.state ?? null },
-					'',
-					url.toString(),
-				);
-			}
+		if (base.name === undefined) {
+			setBase(basename);
+		} else if (DEV && base.name !== basename && `/${basename}` !== base.name) {
+			console.warn(
+				'sv-router: the `base` prop on `<Router>` is ignored because a base was already set in `createRouter`.',
+			);
 		}
 	}
 	if (history.state?._routerIndex === undefined) {
@@ -103,15 +116,18 @@ export function init(basename) {
 /**
  * @template {import('./index.d.ts').Routes} T
  * @param {T} r
+ * @param {import('./index.d.ts').CreateRouterOptions} [options]
  * @returns {import('./index.d.ts').RouterApi<T>}
  */
-export function createRouter(r) {
+export function createRouter(r, options = {}) {
 	routes = r;
 
+	if (BROWSER && options.base) {
+		setBase(options.base);
+	}
+
 	if (DEV && BROWSER) {
-		import('./helpers/validate-routes.js').then(({ validateRoutes }) => {
-			validateRoutes(routes);
-		});
+		validateRoutes(routes);
 	}
 
 	preloadOnHover(routes);
@@ -123,6 +139,9 @@ export function createRouter(r) {
 		async preload(pathname) {
 			await preload(routes, pathname);
 		},
+		resolveMeta(pathname) {
+			return matchRoute(pathname, routes).meta;
+		},
 		route: {
 			get params() {
 				return params.value;
@@ -161,7 +180,7 @@ export function createRouter(r) {
  */
 async function navigate(path, options = {}) {
 	if (typeof path === 'number') {
-		globalThis.history.go(path);
+		history.go(path);
 		return new Navigation(`History entry: ${path}`);
 	}
 
@@ -196,8 +215,8 @@ export async function onNavigate(path, options = {}) {
 		throw new Error('Router not initialized: `createRouter` was not called.');
 	}
 
-	if (!path && skipNextPopstate) {
-		skipNextPopstate = false;
+	if (!path && isSkipNextPopstate) {
+		isSkipNextPopstate = false;
 		return;
 	}
 
@@ -207,7 +226,7 @@ export async function onNavigate(path, options = {}) {
 			const shouldNavigate = typeof blocker === 'object' ? blocker.onNavigate : blocker;
 			if (!(await shouldNavigate())) {
 				if (!path && popstateDelta !== 0) {
-					skipNextPopstate = true;
+					isSkipNextPopstate = true;
 					history.go(popstateDelta);
 				}
 				return;
@@ -277,10 +296,10 @@ export async function onNavigate(path, options = {}) {
 		}
 		const historyMethod = options.replace ? 'replaceState' : 'pushState';
 		if (historyMethod === 'pushState') historyIndex++;
-		globalThis.history[historyMethod](
+		history[historyMethod](
 			{ _routerIndex: historyIndex, _userState: options.state ?? null },
 			'',
-			url.toString(),
+			url.href,
 		);
 		syncSearchParams(search);
 	} else {
@@ -328,6 +347,17 @@ function getMatchPath(path) {
 
 /** @param {Event} event */
 export function onGlobalClick(event) {
+	const mouseEvent = /** @type {MouseEvent} */ (event);
+	if (
+		mouseEvent.button !== 0 ||
+		mouseEvent.metaKey ||
+		mouseEvent.ctrlKey ||
+		mouseEvent.shiftKey ||
+		mouseEvent.altKey ||
+		mouseEvent.defaultPrevented
+	)
+		return;
+
 	const anchor = /** @type {HTMLElement} */ (event.target).closest('a');
 	if (!anchor) return;
 

package/src/gen/config.js

@@ -1,6 +1,7 @@
 /**
  * @type {{
  * 	allLazy: boolean;
+ * 	base: string | undefined;
  * 	ignore: RegExp[];
  * 	readonly genCodeAlias: string;
  * 	readonly genCodeDirPath: string;
@@ -12,6 +13,7 @@
  */
 export const genConfig = {
 	allLazy: false,
+	base: undefined,
 	genCodeAlias: 'sv-router/generated',
 	genCodeDirPath: '.router',
 	ignore: [],

package/src/gen/generate-router-code.js

@@ -1,3 +1,4 @@
+/* eslint-disable unicorn/no-unsafe-string-replacement */
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -19,7 +20,7 @@ const META_FILENAME_REGEX = /(?<=[/.]|^)(meta)(\.svelte)?\.(js|ts)$/; // meta.js
 
 /**
  * @param {string} routesPath
- * @param {{ allLazy?: boolean; js?: boolean; ignore?: RegExp[] }} [options]
+ * @param {{ allLazy?: boolean; base?: string; js?: boolean; ignore?: RegExp[] }} [options]
  * @returns {string}
  */
 export function generateRouterCode(routesPath, options) {
@@ -149,7 +150,7 @@ function mergeRouteGroup(result, childMap) {
 	const hasRootRoute = '/' in childMap;
 
 	for (const [key, val] of Object.entries(childMap)) {
-		if (key === 'layout' || key === 'hooks' || key === 'meta') {
+		if (['layout', 'hooks', 'meta'].includes(key)) {
 			continue;
 		}
 
@@ -174,7 +175,7 @@ function mergeRouteGroup(result, childMap) {
 		}
 		if (hooks) routeWithGroupFiles.hooks = hooks;
 		if (mergedMeta) routeWithGroupFiles.meta = /** @type {string | string[]} */ (mergedMeta);
-		if (result[key]) {
+		if (Object.hasOwn(result, key)) {
 			throw new Error(`Route conflict at \`${key}\``);
 		}
 
@@ -185,10 +186,10 @@ function mergeRouteGroup(result, childMap) {
 /**
  * @param {GeneratedRoutes} routes
  * @param {string} routesPath
- * @param {{ allLazy?: boolean; js?: boolean }} [options]
+ * @param {{ allLazy?: boolean; base?: string; js?: boolean }} [options]
  * @returns {string}
  */
-export function createRouterCode(routes, routesPath, { allLazy = false, js = false } = {}) {
+export function createRouterCode(routes, routesPath, { allLazy = false, base, js = false } = {}) {
 	if (!routesPath.endsWith('/')) {
 		routesPath += '/';
 	}
@@ -223,7 +224,7 @@ export function createRouterCode(routes, routesPath, { allLazy = false, js = fal
 		return result;
 	})(routes, routesPath);
 
-	const imports = [...importsMap.entries()].map(([key, value]) => {
+	const imports = [...importsMap].map(([key, value]) => {
 		if (value.endsWith('.ts')) {
 			value = value.replace('.ts', '');
 		}
@@ -240,7 +241,9 @@ export function createRouterCode(routes, routesPath, { allLazy = false, js = fal
 		'',
 		`export const routes = ${stringifiedRoutes};`,
 		...(js ? [] : ['export type Routes = typeof routes;']),
-		'export const { p, navigate, isActive, preload, route } = createRouter(routes);',
+		`export const { p, navigate, isActive, preload, resolveMeta, route } = createRouter(routes${
+			base === undefined ? '' : `, { base: '${base}' }`
+		});`,
 		'',
 	].join('\n');
 }

package/src/gen/write-router-code.js

@@ -12,16 +12,16 @@ export function writeRouterCode() {
 
 		// Write `.router/tsconfig.json` file
 		const tsMajor = getTypeScriptMajorVersion();
-		const useBaseUrl = tsMajor === undefined || tsMajor < 6;
+		const isBaseUrl = tsMajor === undefined || tsMajor < 6;
 		let alias = genConfig.routerPath;
-		if (!useBaseUrl) {
+		if (!isBaseUrl) {
 			alias = alias.replace(genConfig.genCodeDirPath, '.');
 		}
 		const tsConfig = {
 			compilerOptions: {
 				module: 'preserve',
 				moduleResolution: 'bundler',
-				...(useBaseUrl ? { baseUrl: '..' } : {}),
+				...(isBaseUrl && { baseUrl: '..' }),
 				paths: { [genConfig.genCodeAlias]: [alias] },
 			},
 			include: [
@@ -39,6 +39,7 @@ export function writeRouterCode() {
 		// Write `.router/router.ts` file
 		const routerCode = generateRouterCode(genConfig.routesPath, {
 			allLazy: genConfig.allLazy,
+			base: genConfig.base,
 			js: genConfig.routesInJs,
 			ignore: genConfig.ignore,
 		});
@@ -62,10 +63,12 @@ export function writeRouterCode() {
  * @param {string} content
  */
 function writeFileIfDifferent(filePath, content) {
-	if (!fs.existsSync(filePath) || fs.readFileSync(filePath, 'utf8') !== content) {
-		fs.writeFileSync(filePath, content);
-		return true;
+	if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === content) {
+		return;
 	}
+
+	fs.writeFileSync(filePath, content);
+	return true;
 }
 
 function getTypeScriptMajorVersion() {
@@ -73,7 +76,7 @@ function getTypeScriptMajorVersion() {
 		const require = createRequire(process.cwd() + '/package.json');
 		const tsPackagePath = require.resolve('typescript/package.json');
 		const tsPackage = JSON.parse(fs.readFileSync(tsPackagePath, 'utf8'));
-		return Number(tsPackage.version.split('.')[0]);
+		return Number(tsPackage.version.split('.', 1)[0]);
 	} catch {
 		return;
 	}

package/src/helpers/is-active.js

@@ -34,9 +34,8 @@ function compare(compareFn, pathname, params) {
 	if (params) {
 		if (base.name === '#') {
 			return compareFn(location.pathname, constructPath(pathname, params).replace('/#', ''));
-		} else {
-			return compareFn(location.pathname, constructPath(pathname, params));
 		}
+		return compareFn(location.pathname, constructPath(pathname, params));
 	}
 
 	const pathParts = pathname.split('/').slice(1);
@@ -45,10 +44,10 @@ function compare(compareFn, pathname, params) {
 		return false;
 	}
 	for (const [index, pathPart] of pathParts.entries()) {
-		const routePart = routeParts[index];
 		if (pathPart.startsWith(':')) {
 			continue;
 		}
+		const routePart = routeParts[index];
 		if (pathPart !== routePart) {
 			return false;
 		}

package/src/helpers/match-route.js

@@ -84,11 +84,9 @@ function tryMatch(route, pathParts, pathname, routes, baseMeta) {
 
 	/** @type {Record<string, string>} */
 	const params = {};
-	/** @type {boolean} */
-	let breakFromLayouts;
 
 	for (let [index, routePart] of routeParts.entries()) {
-		breakFromLayouts = routePart.startsWith('(') && routePart.endsWith(')');
+		const breakFromLayouts = routePart.startsWith('(') && routePart.endsWith(')');
 		if (breakFromLayouts) {
 			routePart = routePart.slice(1, -1);
 		}

package/src/helpers/preload.js

@@ -1,3 +1,4 @@
+/* eslint-disable unicorn/no-break-in-nested-loop */
 import { matchRoute } from './match-route.js';
 import { parseSearch, resolveRouteComponents, stripBase } from './utils.js';
 
@@ -139,10 +140,12 @@ export function preloadOnHover(routes) {
 
 	const intersectionObserver = new IntersectionObserver((entries) => {
 		for (const entry of entries) {
-			if (entry.isIntersecting) {
-				intersectionObserver.unobserve(entry.target);
-				anchorPreload(/** @type {HTMLAnchorElement} */ (entry.target));
+			if (!entry.isIntersecting) {
+				continue;
 			}
+
+			intersectionObserver.unobserve(entry.target);
+			anchorPreload(/** @type {HTMLAnchorElement} */ (entry.target));
 		}
 	});
 

package/src/helpers/utils.js

@@ -8,7 +8,7 @@ import { base } from '../create-router.svelte.js';
 export function constructPath(path, params) {
 	if (params) {
 		for (const key in params) {
-			path = path.replace(`:${key}`, String(params[key]));
+			path = path.replace(`:${key}`, () => encodeURIComponent(params[key]));
 		}
 	}
 
@@ -17,7 +17,8 @@ export function constructPath(path, params) {
 			return '/#/';
 		}
 		return join('#', path);
-	} else if (base.name) {
+	}
+	if (base.name) {
 		return join(base.name, path);
 	}
 
@@ -54,16 +55,15 @@ export function resolveRouteComponents(input) {
  * @param {import('../index.d.ts').RouteComponent} input
  * @returns {Promise<import('svelte').Component>}
  */
-function resolveRouteComponent(input) {
-	return new Promise((resolve) => {
-		if (isLazyImport(input)) {
-			Promise.resolve(input()).then((module) => {
-				resolve(module.default);
-			});
-		} else {
-			resolve(input);
+async function resolveRouteComponent(input) {
+	if (isLazyImport(input)) {
+		const module = await input();
+		if (!module) {
+			throw new Error('Failed to load route component: the lazy import resolved to nothing');
 		}
-	});
+		return module.default;
+	}
+	return input;
 }
 
 /**
@@ -112,12 +112,11 @@ export function getUserState(state) {
 }
 
 export function updatedLocation() {
-	const pathname =
-		base.name === '#' ? globalThis.location.hash.slice(1) : globalThis.location.pathname;
-	const hash = base.name === '#' ? '' : globalThis.location.hash;
+	const pathname = base.name === '#' ? location.hash.slice(1) : location.pathname;
+	const hash = base.name === '#' ? '' : location.hash;
 	return {
 		pathname,
-		search: globalThis.location.search,
+		search: location.search,
 		state: getUserState(history.state),
 		hash,
 	};
@@ -161,7 +160,7 @@ export function parseSearch(value) {
 	if (typeof value === 'string') {
 		const searchParams = new URLSearchParams(value);
 		return Object.fromEntries(
-			[...searchParams.entries()].map(([key, value]) => [key, parseSearchValue(value)]),
+			[...searchParams].map(([key, value]) => [key, parseSearchValue(value)]),
 		);
 	}
 

package/src/index.d.ts

@@ -26,8 +26,19 @@ export function serializeSearch(search: Search): string | undefined;
  *   ...
  * });
  * ```
+ *
+ * A base path can be provided as an option:
+ *
+ * ```js
+ * export const { p, ... } = createRouter({ ... }, { base: 'my-app' });
+ * ```
  */
-export function createRouter<T extends Routes>(r: T): RouterApi<T>;
+export function createRouter<T extends Routes>(r: T, options?: CreateRouterOptions): RouterApi<T>;
+
+export type CreateRouterOptions = {
+	/** The base path that is prepended to every URL. Use `'#'` to enable hash-based routing. */
+	base?: string;
+};
 
 /**
  * Blocks navigation as long as the callback returns `false`.
@@ -66,11 +77,16 @@ export function blockNavigation(
 		| { beforeUnload?(): boolean; onNavigate(): boolean | Promise<boolean> },
 ): () => void;
 
-/**
- * The component that will render the current route. You can pass a `base` prop to set the base path
- * that is prepended to every url.
- */
-export const Router: Component<{ base?: string }>;
+/** The component that will render the current route. */
+export const Router: Component<{
+	/**
+	 * The base path that is prepended to every URL.
+	 *
+	 * @deprecated Use the `base` option of `createRouter` (or of the Vite plugin for file-based
+	 *   routing) instead.
+	 */
+	base?: string;
+}>;
 
 /**
  * The reactive search params of the URL. It is just a wrapper around `SvelteURLSearchParam` that
@@ -211,6 +227,13 @@ export type RouterApi<T extends Routes> = {
 	 */
 	preload<U extends Path<T>>(path: U): Promise<void>;
 
+	/**
+	 * Resolves the metadata for the given route path by merging meta from all ancestor route levels.
+	 *
+	 * @param path The route to resolve meta for.
+	 */
+	resolveMeta<U extends Path<T>>(path: U): RouteMeta;
+
 	route: {
 		/**
 		 * An object containing the parameters of the current route.

package/src/search-params.svelte.js

@@ -1,7 +1,7 @@
 import { SvelteURLSearchParams } from 'svelte/reactivity';
 import { parseSearchValue } from './helpers/utils.js';
 
-let searchParams = new SvelteURLSearchParams(globalThis.location.search);
+let searchParams = new SvelteURLSearchParams(location.search);
 
 /** @type {import('./index.js').SearchParams} */
 const shell = {
@@ -38,6 +38,7 @@ const shell = {
 		updateUrlSearchParams(options);
 	},
 	sort(options) {
+		// eslint-disable-next-line unicorn/require-array-sort-compare
 		searchParams.sort();
 		updateUrlSearchParams(options);
 	},
@@ -82,7 +83,7 @@ export function syncSearchParams(search) {
 
 /** @param {{ replace?: boolean }} [options] */
 function updateUrlSearchParams(options) {
-	const url = new URL(globalThis.location.toString());
+	const url = new URL(location.toString());
 	url.search = searchParams.toString();
-	globalThis.history[options?.replace ? 'replaceState' : 'pushState']({}, '', url);
+	history[options?.replace ? 'replaceState' : 'pushState']({}, '', url);
 }

package/src/vite-plugin/index.d.ts

@@ -7,6 +7,12 @@ export type RouterOptions = {
 	 * @default false
 	 */
 	allLazy?: boolean;
+	/**
+	 * The base path that is prepended to every URL. Use `'#'` to enable hash-based routing.
+	 *
+	 * @default undefined
+	 */
+	base?: string;
 	/**
 	 * If true, generates the routes in a .js file instead of a .ts file.
 	 *

package/src/vite-plugin/plugin.js

@@ -8,6 +8,7 @@ import { writeRouterCode } from '../gen/write-router-code.js';
  */
 export function router(options) {
 	genConfig.allLazy = options?.allLazy || false;
+	genConfig.base = options?.base;
 	genConfig.ignore = options?.ignore || [];
 	genConfig.routesInJs = options?.js || false;
 	genConfig.routesPath = options?.path || 'src/routes';