sv-router 0.3.0 → 0.5.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.3.0",
+  "version": "0.5.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.3",
+    "@eslint/js": "^9.26.0",
+    "@types/node": "^22.15.15",
+    "eslint": "^9.26.0",
+    "eslint-config-prettier": "^10.1.3",
     "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.5.1",
+    "eslint-plugin-unicorn": "^59.0.1",
+    "globals": "^16.1.0",
     "prettier": "^3.5.3",
     "prettier-plugin-jsdoc": "^1.3.2",
     "prettier-plugin-svelte": "^3.3.3",
-    "svelte-check": "^4.1.5",
+    "svelte-check": "^4.1.7",
     "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.32.0",
+    "vite": "^6.3.5",
+    "vitest": "^3.1.3"
   },
   "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,9 @@ export let params = $state({ value: {} });
 
 export let location = $state(updatedLocation());
 
+let navigationIndex = 0;
+let pendingNavigationIndex = 0;
+
 /** @type {{ name?: string }} */
 export const base = {
 	name: undefined,
@@ -41,6 +44,9 @@ export function createRouter(r) {
 		p: constructPath,
 		navigate,
 		isActive,
+		async preload(pathname) {
+			await preload(routes, pathname);
+		},
 		route: {
 			get params() {
 				return params.value;
@@ -90,6 +96,10 @@ export async function onNavigate(path, options = {}) {
 	if (!routes) {
 		throw new Error('Router not initialized: `createRouter` was not called.');
 	}
+
+	navigationIndex++;
+	const currentNavigationIndex = navigationIndex;
+
 	let matchPath = path || globalThis.location.pathname;
 	if (base.name && matchPath.startsWith(base.name)) {
 		matchPath = matchPath.slice(base.name.length) || '/';
@@ -98,14 +108,22 @@ export async function onNavigate(path, options = {}) {
 
 	for (const { beforeLoad } of hooks) {
 		try {
+			pendingNavigationIndex = currentNavigationIndex;
 			await beforeLoad?.();
 		} catch {
 			return;
 		}
 	}
 
-	componentTree.value = await resolveRouteComponents(match ? [...layouts, match] : layouts);
-	params.value = newParams || {};
+	const fromBeforeLoadHook = new Error().stack?.includes('beforeLoad');
+
+	const routeComponents = await resolveRouteComponents(match ? [...layouts, match] : layouts);
+	if (
+		navigationIndex !== currentNavigationIndex ||
+		(fromBeforeLoadHook && pendingNavigationIndex + 1 !== currentNavigationIndex)
+	) {
+		return;
+	}
 
 	if (path) {
 		if (options.search) path += options.search;
@@ -115,6 +133,14 @@ export async function onNavigate(path, options = {}) {
 		globalThis.history[historyMethod](options.state || {}, '', to);
 	}
 
+	if (options.viewTransition && document.startViewTransition !== undefined) {
+		document.startViewTransition(() => {
+			componentTree.value = routeComponents;
+		});
+	} else {
+		componentTree.value = routeComponents;
+	}
+	params.value = newParams || {};
 	syncSearchParams();
 	Object.assign(location, updatedLocation());
 
@@ -139,13 +165,14 @@ export function onGlobalClick(event) {
 	if (url.origin !== currentOrigin) return;
 
 	event.preventDefault();
-	const { replace, state, scrollToTop } = anchor.dataset;
+	const { replace, state, scrollToTop, viewTransition } = anchor.dataset;
 	onNavigate(url.pathname, {
 		replace: replace === '' || replace === 'true',
 		search: url.search,
 		state,
 		hash: url.hash,
 		scrollToTop: scrollToTop === 'false' ? false : /** @type ScrollBehavior */ (scrollToTop),
+		viewTransition: viewTransition === '' || viewTransition === 'true',
 	});
 }
 

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

@@ -163,7 +163,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');
 }
 

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/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 = {
@@ -90,8 +95,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 +130,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.
@@ -134,7 +148,7 @@ export type RouterApi<T extends Routes> = {
 		 */
 		params: AllParams<T>;
 		/** 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. */
@@ -144,8 +158,8 @@ export type RouterApi<T extends Routes> = {
 	};
 };
 
-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 +169,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 =
 	| {
@@ -166,6 +184,7 @@ export type NavigateOptions =
 			state?: string;
 			hash?: string;
 			scrollToTop?: ScrollBehavior | false;
+			viewTransition?: boolean;
 	  }
 	| undefined;
 
@@ -194,14 +213,28 @@ type StripNonRoutes<T extends Routes> = {
 					: 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}`
@@ -210,14 +243,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;

package/src/vite-plugin/plugin.js

@@ -7,9 +7,9 @@ import { writeRouterCode } from '../gen/write-router-code.js';
  * @returns {import('vite').Plugin}
  */
 export function router(options) {
-	if (options?.allLazy) genConfig.allLazy = options.allLazy;
-	if (options?.js) genConfig.routesInJs = options.js;
-	if (options?.path) genConfig.routesPath = options.path;
+	genConfig.allLazy = options?.allLazy || false;
+	genConfig.routesInJs = options?.js || false;
+	genConfig.routesPath = options?.path || 'src/routes';
 
 	return {
 		name: 'sv-router',