sv-router 0.4.0 → 0.6.0

package/README.md

@@ -27,9 +27,15 @@ A feature-rich yet intuitive routing library for Svelte single-page apps.
 - 🪶 **Lightweight**: Minimal impact on your bundle size.
 - 🚀 **Made for Svelte 5**: True Svelte 5 implementation with the latest features.
 
-## Installation
+## Getting Started
 
-Add it to an existing Svelte project:
+Kickstart a new project:
+
+```bash
+npm create sv-router
+```
+
+...or add it to an existing project:
 
 ```bash
 npm install sv-router

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sv-router",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Modern Svelte Routing",
   "keywords": [
     "svelte",
@@ -36,29 +36,31 @@
     "esm-env": "^1.2.2"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.28.1",
-    "@eslint/js": "^9.23.0",
-    "@types/node": "^22.13.14",
-    "eslint": "^9.23.0",
-    "eslint-config-prettier": "^10.1.1",
+    "@changesets/cli": "^2.29.4",
+    "@eslint/js": "^9.28.0",
+    "@types/node": "^22.15.30",
+    "eslint": "^9.28.0",
+    "eslint-config-prettier": "^10.1.5",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-svelte": "^3.3.3",
-    "eslint-plugin-unicorn": "^58.0.0",
-    "globals": "^16.0.0",
+    "eslint-plugin-svelte": "^3.9.1",
+    "eslint-plugin-unicorn": "^59.0.1",
+    "globals": "^16.2.0",
     "prettier": "^3.5.3",
     "prettier-plugin-jsdoc": "^1.3.2",
-    "prettier-plugin-svelte": "^3.3.3",
-    "svelte-check": "^4.1.5",
+    "prettier-plugin-svelte": "^3.4.0",
+    "svelte-check": "^4.2.1",
     "type-testing": "^0.2.0",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.28.0",
-    "vite": "^6.2.3",
-    "vitest": "^3.0.9"
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.33.1",
+    "vite": "^6.3.5",
+    "vitest": "^3.2.2"
   },
   "peerDependencies": {
     "svelte": "^5"
   },
   "scripts": {
+    "create:dev": "pnpm --filter create-sv-router dev",
+    "create:build": "pnpm --filter create-sv-router build",
     "docs:dev": "pnpm --filter docs dev",
     "docs:build": "pnpm --filter docs build",
     "docs:preview": "pnpm --filter docs preview",

package/src/create-router.svelte.js

@@ -1,7 +1,7 @@
 import { BROWSER, DEV } from 'esm-env';
 import { isActive } from './helpers/is-active.js';
 import { matchRoute } from './helpers/match-route.js';
-import { preloadOnHover } from './helpers/preload-on-hover.js';
+import { preload, preloadOnHover } from './helpers/preload.js';
 import { constructPath, join, resolveRouteComponents } from './helpers/utils.js';
 import { syncSearchParams } from './search-params.svelte.js';
 
@@ -16,6 +16,8 @@ export let params = $state({ value: {} });
 
 export let location = $state(updatedLocation());
 
+let meta = $state({ value: {} });
+
 let navigationIndex = 0;
 let pendingNavigationIndex = 0;
 
@@ -44,10 +46,19 @@ export function createRouter(r) {
 		p: constructPath,
 		navigate,
 		isActive,
+		async preload(pathname) {
+			await preload(routes, pathname);
+		},
 		route: {
 			get params() {
 				return params.value;
 			},
+			getParams(pathname) {
+				if (!isActive(pathname)) {
+					throw new Error(`\`${pathname}\` does not match the current route`);
+				}
+				return params.value;
+			},
 			get pathname() {
 				return /** @type {import('./index.d.ts').Path<T>} */ (location.pathname);
 			},
@@ -60,6 +71,9 @@ export function createRouter(r) {
 			get hash() {
 				return location.hash;
 			},
+			get meta() {
+				return meta.value;
+			},
 		},
 	};
 }
@@ -101,7 +115,7 @@ export async function onNavigate(path, options = {}) {
 	if (base.name && matchPath.startsWith(base.name)) {
 		matchPath = matchPath.slice(base.name.length) || '/';
 	}
-	const { match, layouts, hooks, params: newParams } = matchRoute(matchPath, routes);
+	const { match, layouts, hooks, meta: newMeta, params: newParams } = matchRoute(matchPath, routes);
 
 	for (const { beforeLoad } of hooks) {
 		try {
@@ -137,7 +151,8 @@ export async function onNavigate(path, options = {}) {
 	} else {
 		componentTree.value = routeComponents;
 	}
-	params.value = newParams || {};
+	params.value = newParams;
+	meta.value = newMeta;
 	syncSearchParams();
 	Object.assign(location, updatedLocation());
 

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

@@ -14,6 +14,7 @@ const PARAM_FILENAME_REGEX = /(?<=[/.]|^)\(?\[([\w-]+)\]\)?(\.lazy)?\.svelte$/;
 const CATCH_ALL_FILENAME_REGEX = /(?<=[/.]|^)\(?\[\.\.\.([\w-]+)\]\)?(\.lazy)?\.svelte$/; // [...any].svelte, [...any].lazy.svelte, ([...any]).svelte
 const OUT_OF_LAYOUT_FILENAME_REGEX = /(?<=[/.]|^)\(\[\.?\.?\.?([\w-]+)\]\)(\.lazy)?\.svelte$/; // ([any]).svelte, ([...any]).lazy.svelte
 const HOOKS_FILENAME_REGEX = /(?<=[/.]|^)(hooks)(\.svelte)?\.(js|ts)$/; // hooks.js, hooks.svelte.js, hooks.ts, hooks.svelte.ts
+const META_FILENAME_REGEX = /(?<=[/.]|^)(meta)(\.svelte)?\.(js|ts)$/; // meta.js, meta.svelte.js, meta.ts, meta.svelte.ts
 
 /**
  * @param {string} routesPath
@@ -44,7 +45,11 @@ export function buildFileTree(routesPath) {
 			tree.push({ name: entry, tree: buildFileTree(path.join(routesPath, entry)) });
 			continue;
 		}
-		if (!entry.endsWith('.svelte') && !HOOKS_FILENAME_REGEX.test(entry)) {
+		if (
+			!entry.endsWith('.svelte') &&
+			!HOOKS_FILENAME_REGEX.test(entry) &&
+			!META_FILENAME_REGEX.test(entry)
+		) {
 			continue;
 		}
 		tree.push(entry);
@@ -67,6 +72,10 @@ export function createRouteMap(fileTree, prefix = '') {
 					result['hooks'] = prefix + entry;
 					continue;
 				}
+				if (META_FILENAME_REGEX.test(entry)) {
+					result['meta'] = prefix + entry;
+					continue;
+				}
 				continue;
 			}
 
@@ -101,7 +110,8 @@ export function createRouteMap(fileTree, prefix = '') {
 			result['/' + filePathToRoute(entry.replace('.svelte', ''))] = prefix + entry;
 		} else {
 			const entryName = filePathToRoute(entry.name);
-			result['/' + entryName] = createRouteMap(entry.tree, prefix + entryName + '/');
+			const paramFolder = entryName.replace(/^\[(.*)\]$/, ':$1');
+			result['/' + paramFolder] = createRouteMap(entry.tree, prefix + entryName + '/');
 		}
 	}
 	return result;
@@ -137,7 +147,11 @@ export function createRouterCode(routes, routesPath, { allLazy = false } = {}) {
 		for (const [key, value] of Object.entries(routes)) {
 			if (typeof value === 'object') {
 				result[key] = handleImports(value, routesPath);
-			} else if (key === 'hooks' || (!value.endsWith('.lazy.svelte') && !allLazy)) {
+			} else if (
+				key === 'hooks' ||
+				key === 'meta' ||
+				(!value.endsWith('.lazy.svelte') && !allLazy)
+			) {
 				const variableName = pathToCorrectCasing(value);
 				importsMap.set(variableName, routesPath + value);
 				result[key] = variableName;
@@ -163,7 +177,7 @@ export function createRouterCode(routes, routesPath, { allLazy = false } = {}) {
 		`import { createRouter } from 'sv-router';`,
 		...imports,
 		'',
-		`export const { p, navigate, isActive, route } = createRouter(${stringifiedRoutes});`,
+		`export const { p, navigate, isActive, preload, route } = createRouter(${stringifiedRoutes});`,
 	].join('\n');
 }
 
@@ -189,6 +203,7 @@ export function pathToCorrectCasing(value) {
 		extractLastPart(CATCH_ALL_FILENAME_REGEX) ||
 		extractLastPart(PARAM_FILENAME_REGEX) ||
 		extractLastPart(HOOKS_FILENAME_REGEX) ||
+		extractLastPart(META_FILENAME_REGEX) ||
 		extractLastPart(FILENAME_REGEX);
 	if (!lastPart) {
 		throw new Error(`Invalid filename: ${value}`);
@@ -196,7 +211,8 @@ export function pathToCorrectCasing(value) {
 	parts.push(...lastPart.split('-'));
 
 	const uppercased = parts.map((part, index) => {
-		if (index === 0 && lastPart === 'hooks') return part;
+		if (index === 0 && (lastPart === 'hooks' || lastPart === 'meta')) return part;
+		part = part.replace(/^\[(.*)\]$/, '$1');
 		return part.charAt(0).toUpperCase() + part.slice(1);
 	});
 	return uppercased.join('');

package/src/helpers/is-active.js

@@ -38,10 +38,12 @@ function compare(compareFn, pathname, params) {
 	const routeParts = location.pathname.split('/').slice(1);
 	for (const [index, pathPart] of pathParts.entries()) {
 		const routePart = routeParts[index];
-		if (routePart.startsWith(':')) {
+		if (pathPart.startsWith(':')) {
 			continue;
 		}
-		return compareFn(pathPart, routePart);
+		if (pathPart !== routePart) {
+			return false;
+		}
 	}
-	return false;
+	return true;
 }

package/src/helpers/match-route.js

@@ -6,6 +6,8 @@
  * @typedef {import('../index.d.ts').Hooks} Hooks
  *
  * @typedef {import('../index.d.ts').Routes} Routes
+ *
+ * @typedef {import('../index.d.ts').RouteMeta} RouteMeta
  */
 
 /**
@@ -15,6 +17,7 @@
  * 	match: RouteComponent | undefined;
  * 	layouts: LayoutComponent[];
  * 	hooks: Hooks[];
+ * 	meta: RouteMeta;
  * 	params: Record<string, string>;
  * 	breakFromLayouts: boolean;
  * }}
@@ -39,6 +42,9 @@ export function matchRoute(pathname, routes) {
 	/** @type {Record<string, string>} */
 	let params = {};
 
+	/** @type {RouteMeta} */
+	let meta = {};
+
 	let breakFromLayouts = false;
 
 	outer: for (const route of allRoutes) {
@@ -69,7 +75,7 @@ export function matchRoute(pathname, routes) {
 				);
 				match = /** @type {RouteComponent} */ (routes[resolvedPath]);
 				break outer;
-			} else if (routePart !== pathPart) {
+			} else if (routePart !== pathPart?.toLowerCase()) {
 				break;
 			}
 
@@ -89,6 +95,10 @@ export function matchRoute(pathname, routes) {
 				hooks.push(routes.hooks);
 			}
 
+			if ('meta' in routes && routes.meta) {
+				meta = { ...meta, ...routes.meta };
+			}
+
 			if (typeof routeMatch === 'function') {
 				if (routeParts.length === pathParts.length) {
 					match = routeMatch;
@@ -103,6 +113,7 @@ export function matchRoute(pathname, routes) {
 				match = result.match;
 				params = { ...params, ...result.params };
 				hooks.push(...result.hooks);
+				meta = { ...meta, ...result.meta };
 				if (result.breakFromLayouts) {
 					layouts = [];
 				} else {
@@ -113,7 +124,7 @@ export function matchRoute(pathname, routes) {
 		}
 	}
 
-	return { match, layouts, hooks, params, breakFromLayouts };
+	return { match, layouts, hooks, params, meta, breakFromLayouts };
 }
 
 /**

package/src/helpers/{preload-on-hover.js → preload.js}

@@ -1,9 +1,21 @@
 import { matchRoute } from './match-route.js';
 import { resolveRouteComponents } from './utils.js';
 
+/**
+ * @param {import('../index.js').Routes} routes
+ * @param {string} path
+ */
+export async function preload(routes, path) {
+	const { match, layouts, hooks } = matchRoute(path, routes);
+	for (const { onPreload } of hooks) {
+		onPreload?.();
+	}
+	await resolveRouteComponents(match ? [...layouts, match] : layouts);
+}
+
 const linkSet = new Set();
 
-/** @param {import('../index.d.ts').Routes} routes */
+/** @param {import('../index.js').Routes} routes */
 export function preloadOnHover(routes) {
 	const observer = new MutationObserver(() => {
 		const links = document.querySelectorAll('a[data-preload]');
@@ -15,8 +27,7 @@ export function preloadOnHover(routes) {
 				link.removeEventListener('mouseenter', callback);
 				const href = link.getAttribute('href');
 				if (!href) return;
-				const { match, layouts } = matchRoute(href, routes);
-				resolveRouteComponents(match ? [...layouts, match] : layouts);
+				preload(routes, href);
 			});
 		}
 	});

package/src/helpers/utils.js

@@ -25,7 +25,7 @@ export function resolveRouteComponents(input) {
  * @param {import('../index.d.ts').RouteComponent} input
  * @returns {Promise<import('svelte').Component>}
  */
-export function resolveRouteComponent(input) {
+function resolveRouteComponent(input) {
 	return new Promise((resolve) => {
 		if (isLazyImport(input)) {
 			Promise.resolve(input()).then((module) => {

package/src/helpers/validate-routes.js

@@ -26,9 +26,12 @@ export function validateRoutes(routes) {
 export function getRoutePaths(routes) {
 	const paths = [];
 	for (const [key, value] of Object.entries(routes)) {
+		if (['layout', 'hooks', 'meta'].includes(key)) {
+			continue;
+		}
 		if (typeof value === 'object') {
 			paths.push(
-				...getRoutePaths(value).map((path) => {
+				...getRoutePaths(/** @type {import('../index.d.ts').Routes} */ (value)).map((path) => {
 					if (path === '*') {
 						return key + '/*';
 					}

package/src/index.d.ts

@@ -7,10 +7,11 @@ import type { Action } from 'svelte/action';
  * to `is-active`.
  *
  * ```svelte
- * <a href="/about" use:isActiveLink={{ className: 'active-link' }}>
+ * <a href={p('/about')} use:isActiveLink={{ className: 'active-link' }}>
  * ```
  */
 export const isActiveLink: IsActiveLink;
+
 /**
  * Setup a new router instance with the given routes.
  *
@@ -23,11 +24,13 @@ export const isActiveLink: IsActiveLink;
  * ```
  */
 export function createRouter<T extends Routes>(r: T): RouterApi<T>;
+
 /**
  * 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 reactive search params of the URL. It is just a wrapper around `SvelteURLSearchParam` that
  * will update the url on change.
@@ -62,6 +65,8 @@ export type Hooks = {
 	beforeLoad?(): void | Promise<void>;
 	/** A function that will be called after the route is loaded. */
 	afterLoad?(): void;
+	/** A function that will be called when the route is preloaded. */
+	onPreload?(): void;
 };
 
 export type Routes = {
@@ -69,6 +74,7 @@ export type Routes = {
 	[_: `*${string}` | `(*${string})`]: RouteComponent | undefined;
 	layout?: LayoutComponent;
 	hooks?: Hooks;
+	meta?: RouteMeta;
 };
 
 export type IsActiveLink = Action<
@@ -76,6 +82,20 @@ export type IsActiveLink = Action<
 	{ className?: string; startsWith?: boolean } | undefined
 >;
 
+/**
+ * Route metadata that can be extended via module augmentation.
+ *
+ * @example
+ * 	declare module 'sv-router' {
+ * 		interface RouteMeta {
+ * 			public?: boolean;
+ * 			requiresAuth?: boolean;
+ * 		}
+ * 	}
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RouteMeta {}
+
 export type RouterApi<T extends Routes> = {
 	/**
 	 * Construct a path while ensuring type safety.
@@ -90,8 +110,9 @@ export type RouterApi<T extends Routes> = {
 	 * @param params The parameters to replace in the route.
 	 */
 	p<U extends Path<T>>(...args: ConstructPathArgs<U>): string;
+
 	/**
-	 * Navigate programatically to a route.
+	 * Navigate programmatically to a route.
 	 *
 	 * ```js
 	 * navigate('/users');
@@ -124,6 +145,14 @@ export type RouterApi<T extends Routes> = {
 		<U extends Path<T>>(...args: IsActiveArgs<U>): boolean;
 		startsWith<U extends Path<T>>(...args: IsActiveArgs<U>): boolean;
 	};
+
+	/**
+	 * Preloads the given route.
+	 *
+	 * @param path The route to preload.
+	 */
+	preload<U extends Path<T>>(path: U): Promise<void>;
+
 	route: {
 		/**
 		 * An object containing the parameters of the current route.
@@ -133,19 +162,32 @@ export type RouterApi<T extends Routes> = {
 		 * 'hello-world', commentId: '123' }`.
 		 */
 		params: AllParams<T>;
+		/**
+		 * Extract parameters from the given pathname. Will throw if the pathname does not match the
+		 * current route.
+		 *
+		 * ```ts
+		 * route.getParams('/posts/:slug').slug;
+		 * ```
+		 *
+		 * @param pathname
+		 */
+		getParams<U extends Path<T>>(pathname: U): Record<ExtractParams<U>, string>;
 		/** The reactive pathname of the URL. */
-		pathname: Path<T>;
+		pathname: (Path<T, true> & {}) | (string & {});
 		/** The reactive query string part of the URL. */
 		search: string;
 		/** The reactive history state that can be passed to the `navigate` function. */
 		state: unknown;
 		/** The reactive hash part of the URL. */
 		hash: string;
+		/** Arbitrary metadata associated with the route. */
+		meta: RouteMeta;
 	};
 };
 
-export type Path<T extends Routes> = RemoveParenthesis<
-	RemoveLastSlash<RecursiveKeys<StripNonRoutes<T>>>
+export type Path<T extends Routes, AnyParam extends boolean = false> = RemoveParenthesis<
+	RemoveLastSlash<RecursiveKeys<StripNonRoutes<T>, '', AnyParam>>
 >;
 
 export type ConstructPathArgs<T extends string> =
@@ -155,9 +197,13 @@ export type IsActiveArgs<T extends string> =
 	PathParams<T> extends never ? [T] : [T] | [T, PathParams<T>];
 
 export type PathParams<T extends string> =
-	ExtractParams<T> extends never ? never : Record<ExtractParams<T>, string>;
+	ExtractParams<RemoveParenthesis<T>> extends never
+		? never
+		: Record<ExtractParams<RemoveParenthesis<T>>, string>;
 
-export type AllParams<T extends Routes> = Partial<Record<ExtractParams<RecursiveKeys<T>>, string>>;
+export type AllParams<T extends Routes> = Partial<
+	Record<ExtractParams<RemoveParenthesis<RecursiveKeys<T>>>, string>
+>;
 
 export type NavigateOptions =
 	| {
@@ -192,17 +238,33 @@ type StripNonRoutes<T extends Routes> = {
 				? never
 				: K extends 'hooks'
 					? never
-					: K]: T[K] extends Routes ? StripNonRoutes<T[K]> : T[K];
+					: K extends 'meta'
+						? never
+						: K]: T[K] extends Routes ? StripNonRoutes<T[K]> : T[K];
 };
 
-type RecursiveKeys<T extends Routes, Prefix extends string = ''> = {
+type RecursiveKeys<
+	T extends Routes,
+	Prefix extends string = '',
+	AnyParam extends boolean = false,
+> = {
 	[K in keyof T]: K extends string
 		? T[K] extends Routes
-			? RecursiveKeys<T[K], `${Prefix}${K}`>
-			: `${Prefix}${K}`
+			? RecursiveKeys<
+					T[K],
+					`${Prefix}${AnyParam extends true ? ReplaceParamWithString<K> : K}`,
+					AnyParam
+				>
+			: `${Prefix}${AnyParam extends true ? ReplaceParamWithString<K> : K}`
 		: never;
 }[keyof T];
 
+type ReplaceParamWithString<T extends string> = T extends `/:${string}`
+	? `/${string}`
+	: T extends `/(:${string})`
+		? `/${string}`
+		: T;
+
 type RemoveLastSlash<T extends string> = T extends '/' ? T : T extends `${infer R}/` ? R : T;
 
 type RemoveParenthesis<T extends string> = T extends `${infer A}(${infer B})${infer C}`
@@ -211,14 +273,10 @@ type RemoveParenthesis<T extends string> = T extends `${infer A}(${infer B})${in
 
 type ExtractParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}`
 	? Param | ExtractParams<`/${Rest}`>
-	: T extends `${string}(:${infer Param})`
+	: T extends `${string}:${infer Param}`
 		? Param
-		: T extends `${string}:${infer Param}`
-			? Param
-			: T extends `${string}(*${infer Param})`
-				? Param
-				: T extends `${string}*${infer Param}`
-					? Param extends ''
-						? never
-						: Param
-					: never;
+		: T extends `${string}*${infer Param}`
+			? Param extends ''
+				? never
+				: Param
+			: never;