sv-router 0.0.8 → 0.2.0

package/README.md

@@ -18,11 +18,14 @@ A feature-rich yet intuitive routing library for Svelte single-page apps.
 ## Features
 
 - 🔒 **Typesafe navigation**: Get autocomplete and type checking for your routes.
-- 🗂️ **File-based routing (optional)**: Enjoy the DX of a meta-framework-like approach.
+- 🔄 **Flexibility**: Choose between code-based or file-based routing approaches.
 - 🌿 **Nested routes**: Create complex layouts with ease.
+- 🔍 **Reactive search params**: For simpler state management in the URL.
+- 🛡️ **Hooks**: For navigation guards, data loading, or analytics tracking.
 - ⚡ **Performance**: Optimized for speed with built-in code splitting and preloading.
-- 🧩 **Familiar API**: Follows established conventions from popular meta frameworks
-- 🚀 **Made for Svelte 5**: Benefit from faster performance and smaller bundle size.
+- 🧩 **Familiar API**: Follows established conventions from popular meta frameworks.
+- 🪶 **Lightweight**: Minimal impact on your bundle size.
+- 🚀 **Made for Svelte 5**: True Svelte 5 implementation with the latest features.
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sv-router",
-  "version": "0.0.8",
+  "version": "0.2.0",
   "description": "Modern Svelte Routing",
   "keywords": [
     "svelte",
@@ -37,23 +37,23 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.28.1",
-    "@eslint/js": "^9.21.0",
-    "@types/node": "^22.13.8",
-    "eslint": "^9.21.0",
-    "eslint-config-prettier": "^10.0.2",
+    "@eslint/js": "^9.23.0",
+    "@types/node": "^22.13.14",
+    "eslint": "^9.23.0",
+    "eslint-config-prettier": "^10.1.1",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-svelte": "^3.0.2",
-    "eslint-plugin-unicorn": "^57.0.0",
+    "eslint-plugin-svelte": "^3.3.3",
+    "eslint-plugin-unicorn": "^58.0.0",
     "globals": "^16.0.0",
-    "prettier": "^3.5.2",
+    "prettier": "^3.5.3",
     "prettier-plugin-jsdoc": "^1.3.2",
     "prettier-plugin-svelte": "^3.3.3",
-    "svelte-check": "^4.1.4",
+    "svelte-check": "^4.1.5",
     "type-testing": "^0.2.0",
     "typescript": "^5.8.2",
-    "typescript-eslint": "^8.25.0",
-    "vite": "^6.2.0",
-    "vitest": "^3.0.7"
+    "typescript-eslint": "^8.28.0",
+    "vite": "^6.2.3",
+    "vitest": "^3.0.9"
   },
   "peerDependencies": {
     "svelte": "^5"
@@ -64,7 +64,7 @@
     "docs:preview": "pnpm --filter docs preview",
     "test": "vitest",
     "check": "svelte-check && pnpm -r check",
-    "lint": "eslint .",
+    "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "format": "prettier . --check",
     "format:fix": "prettier . --write",

package/src/Router.svelte

@@ -1,8 +1,21 @@
 <script>
 	import { on } from 'svelte/events';
-	import { componentTree, onGlobalClick, onNavigate } from './create-router.svelte.js';
+	import { base, componentTree, onGlobalClick, onNavigate } from './create-router.svelte.js';
+	import { join } from './helpers/utils.js';
 	import RecursiveComponentTree from './RecursiveComponentTree.svelte';
 
+	/** @type {{ base?: string }} */
+	let { base: basename } = $props();
+
+	if (basename) {
+		base.name = (basename.startsWith('/') ? '' : '/') + basename;
+		const url = new URL(globalThis.location.href);
+		if (!url.pathname.startsWith(base.name)) {
+			url.pathname = join(base.name, url.pathname);
+			history.replaceState(history.state || {}, '', url.href);
+		}
+	}
+
 	onNavigate();
 
 	$effect(() => {

package/src/create-router.svelte.js

@@ -2,11 +2,11 @@ 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 { constructPath, resolveRouteComponents } from './helpers/utils.js';
+import { constructPath, join, resolveRouteComponents } from './helpers/utils.js';
 import { syncSearchParams } from './search-params.svelte.js';
 
 /** @type {import('./index.d.ts').Routes} */
-export let routes;
+let routes;
 
 /** @type {{ value: import('svelte').Component[] }} */
 export let componentTree = $state({ value: [] });
@@ -16,6 +16,11 @@ export let params = $state({ value: {} });
 
 export let location = $state(updatedLocation());
 
+/** @type {{ name?: string }} */
+export const base = {
+	name: undefined,
+};
+
 /**
  * @template {import('./index.d.ts').Routes} T
  * @param {T} r
@@ -85,12 +90,11 @@ export async function onNavigate(path, options = {}) {
 	if (!routes) {
 		throw new Error('Router not initialized: `createRouter` was not called.');
 	}
-	const {
-		match,
-		layouts,
-		hooks,
-		params: newParams,
-	} = matchRoute(path || globalThis.location.pathname, routes);
+	let matchPath = path || globalThis.location.pathname;
+	if (base.name && matchPath.startsWith(base.name)) {
+		matchPath = matchPath.slice(base.name.length) || '/';
+	}
+	const { match, layouts, hooks, params: newParams } = matchRoute(matchPath, routes);
 
 	for (const { beforeLoad } of hooks) {
 		try {
@@ -107,12 +111,17 @@ export async function onNavigate(path, options = {}) {
 		if (options.search) path += options.search;
 		if (options.hash) path += options.hash;
 		const historyMethod = options.replace ? 'replaceState' : 'pushState';
-		globalThis.history[historyMethod](options.state || {}, '', path);
+		const to = base.name ? join(base.name, path) : path;
+		globalThis.history[historyMethod](options.state || {}, '', to);
 	}
 
 	syncSearchParams();
 	Object.assign(location, updatedLocation());
 
+	if (options.scrollToTop !== false) {
+		window.scrollTo({ top: 0, left: 0, behavior: options.scrollToTop });
+	}
+
 	for (const { afterLoad } of hooks) {
 		afterLoad?.();
 	}
@@ -130,12 +139,13 @@ export function onGlobalClick(event) {
 	if (url.origin !== currentOrigin) return;
 
 	event.preventDefault();
-	const { replace, state } = anchor.dataset;
+	const { replace, state, scrollToTop } = anchor.dataset;
 	onNavigate(url.pathname, {
 		replace: replace === '' || replace === 'true',
 		search: url.search,
 		state,
 		hash: url.hash,
+		scrollToTop: scrollToTop === 'false' ? false : /** @type ScrollBehavior */ (scrollToTop),
 	});
 }
 
@@ -143,7 +153,7 @@ function updatedLocation() {
 	return {
 		pathname: globalThis.location.pathname,
 		search: globalThis.location.search,
-		state: globalThis.history.state,
+		state: history.state,
 		hash: globalThis.location.hash,
 	};
 }

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

@@ -9,11 +9,11 @@ import path from 'node:path';
  * }} GeneratedRoutes
  */
 
-const FILENAME_REGEX = /\(?([\w-]+)\)?(\.lazy)?\.svelte$/; // any.svelte, any.lazy.svelte, (any).svelte
-const PARAM_FILENAME_REGEX = /\(?\[(.*)\]\)?(\.lazy)?\.svelte$/; // [any].svelte, [any].lazy.svelte, ([any]).svelte
-const CATCH_ALL_FILENAME_REGEX = /\(?\[\.\.\.(.*)\]\)?(\.lazy)?\.svelte$/; // [...any].svelte, [...any].lazy.svelte, ([...any]).svelte
-const OUT_OF_LAYOUT_FILENAME_REGEX = /\(\[\.?\.?\.?(.*)\]\)(\.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 FILENAME_REGEX = /(?<=[/.]|^)\(?([\w-]+)\)?(\.lazy)?\.svelte$/; // any.svelte, any.lazy.svelte, (any).svelte
+const PARAM_FILENAME_REGEX = /(?<=[/.]|^)\(?\[([\w-]+)\]\)?(\.lazy)?\.svelte$/; // [any].svelte, [any].lazy.svelte, ([any]).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
 
 /**
  * @param {string} routesPath

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

@@ -9,10 +9,6 @@ export function writeRouterCode() {
 			fs.mkdirSync(genConfig.genCodeDirPath);
 		}
 
-		// Write `.router/router.ts` file
-		const routerCode = generateRouterCode(genConfig.routesPath);
-		writeFileIfDifferent(genConfig.routerPath, routerCode);
-
 		// Write `.router/tsconfig.json` file
 		const tsConfig = {
 			compilerOptions: {
@@ -35,7 +31,15 @@ export function writeRouterCode() {
 		};
 		writeFileIfDifferent(genConfig.tsconfigPath, JSON.stringify(tsConfig, undefined, 2));
 
-		console.log('✅️ Routes generated');
+		// Write `.router/router.ts` file
+		const routerCode = generateRouterCode(genConfig.routesPath);
+		const written = writeFileIfDifferent(genConfig.routerPath, routerCode);
+
+		if (written) {
+			console.log('✅️ Routes generated');
+		} else {
+			console.log('✅️ Routes already up to date');
+		}
 	} catch (error) {
 		console.error(
 			'Error during routes generation:',
@@ -51,5 +55,6 @@ export function writeRouterCode() {
 function writeFileIfDifferent(filePath, content) {
 	if (!fs.existsSync(filePath) || fs.readFileSync(filePath, 'utf8') !== content) {
 		fs.writeFileSync(filePath, content);
+		return true;
 	}
 }

package/src/helpers/utils.js

@@ -44,3 +44,18 @@ export function resolveRouteComponent(input) {
 export function isLazyImport(input) {
 	return typeof input === 'function' && !!/\(\)\s?=>\s?import\(.*\)/.test(String(input));
 }
+
+/** @param {...string} parts */
+export function join(...parts) {
+	let result = '';
+	for (let part of parts) {
+		if (!part.startsWith('/')) {
+			result += '/';
+		}
+		if (part.endsWith('/')) {
+			part = part.slice(0, -1);
+		}
+		result += part;
+	}
+	return result;
+}

package/src/index.d.ts

@@ -23,13 +23,16 @@ export const isActiveLink: IsActiveLink;
  * ```
  */
 export function createRouter<T extends Routes>(r: T): RouterApi<T>;
-/** The component that will render the current route. */
-export const Router: Component;
+/**
+ * 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.
  */
-export const searchParams: URLSearchParams;
+export const searchParams: SearchParams;
 
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 type BaseProps = {};
@@ -162,9 +165,17 @@ export type NavigateOptions =
 			search?: string;
 			state?: string;
 			hash?: string;
+			scrollToTop?: ScrollBehavior | false;
 	  }
 	| undefined;
 
+export type SearchParams = URLSearchParams & {
+	append: (name: string, value: string, options?: { replace?: boolean }) => void;
+	delete: (name: string, value?: string, options?: { replace?: boolean }) => void;
+	set: (name: string, value: string, options?: { replace?: boolean }) => void;
+	sort: (options?: { replace?: boolean }) => void;
+};
+
 type NavigateArgs<T extends string> =
 	| (PathParams<T> extends never
 			? [T] | [T, NavigateOptions]

package/src/search-params.svelte.js

@@ -2,15 +2,15 @@ import { SvelteURLSearchParams } from 'svelte/reactivity';
 
 let searchParams = new SvelteURLSearchParams(globalThis.location.search);
 
-/** @type {URLSearchParams} */
+/** @type {import('./index.js').SearchParams} */
 const shell = {
-	append(...args) {
-		searchParams.append(...args);
-		updateUrlSearchParams();
+	append(name, value, options) {
+		searchParams.append(name, value);
+		updateUrlSearchParams(options);
 	},
-	delete(...args) {
-		searchParams.delete(...args);
-		updateUrlSearchParams();
+	delete(name, value, options) {
+		searchParams.delete(name, value);
+		updateUrlSearchParams(options);
 	},
 	entries() {
 		return searchParams.entries();
@@ -31,13 +31,13 @@ const shell = {
 	keys() {
 		return searchParams.keys();
 	},
-	set(...args) {
-		searchParams.set(...args);
-		updateUrlSearchParams();
+	set(name, value, options) {
+		searchParams.set(name, value);
+		updateUrlSearchParams(options);
 	},
-	sort() {
+	sort(options) {
 		searchParams.sort();
-		updateUrlSearchParams();
+		updateUrlSearchParams(options);
 	},
 	toString() {
 		return searchParams.toString();
@@ -60,19 +60,17 @@ export function syncSearchParams() {
 	if (searchParams.toString() === newSearchParams.toString()) {
 		return;
 	}
-
-	for (const key of searchParams.keys()) {
-		searchParams.delete(key);
-	}
+	searchParams = new SvelteURLSearchParams();
 	for (const [key, value] of newSearchParams.entries()) {
 		searchParams.append(key, value);
 	}
 }
 
-function updateUrlSearchParams() {
+/** @param {{ replace?: boolean }} [options] */
+function updateUrlSearchParams(options) {
 	let url = globalThis.location.origin + globalThis.location.pathname;
 	if (searchParams.size > 0) {
 		url += '?' + searchParams.toString();
 	}
-	globalThis.history.pushState({}, '', url);
+	globalThis.history[options?.replace ? 'replaceState' : 'pushState']({}, '', url);
 }