svelte-crumbs 1.0.0

package/README.md

@@ -0,0 +1,247 @@
+# svelte-crumbs
+
+Automatic, SSR-ready breadcrumbs for SvelteKit via route-level metadata exports. Zero config, fully reactive, server-rendered with top-level await.
+
+**Svelte 5 + SvelteKit 2 only. Data layer only — bring your own rendering.**
+
+**[Documentation & Live Demo](https://svelte-crumbs.vercel.app/)**
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install svelte-crumbs
+```
+
+### 2. Export breadcrumbs from your routes
+
+```svelte
+<!-- src/routes/products/+page.svelte -->
+<script lang="ts" module>
+  import type { BreadcrumbMeta } from 'svelte-crumbs';
+
+  export const breadcrumb: BreadcrumbMeta = async () => ({
+    label: 'Products'
+  });
+</script>
+```
+
+### 3. Render in your layout
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script lang="ts">
+  import { createBreadcrumbs } from 'svelte-crumbs';
+
+  const getBreadcrumbs = createBreadcrumbs();
+  const crumbs = $derived(await getBreadcrumbs());
+</script>
+
+<nav>
+  {#each crumbs as crumb, i}
+    {#if i > 0} / {/if}
+    <a href={crumb.url}>{crumb.label}</a>
+  {/each}
+</nav>
+```
+
+No `{#await}` blocks needed. Breadcrumbs resolve during SSR and update reactively on client navigation.
+
+## Examples
+
+### Static breadcrumb
+
+```svelte
+<script lang="ts" module>
+  import type { BreadcrumbMeta } from 'svelte-crumbs';
+
+  export const breadcrumb: BreadcrumbMeta = async () => ({
+    label: 'Settings'
+  });
+</script>
+```
+
+### From load data
+
+The breadcrumb resolver receives the full `page` object, including `page.data`. Use `+layout.server.ts` (not `+page.server.ts`) so the data is available to child routes' breadcrumbs too:
+
+```ts
+// src/routes/products/[id]/+layout.server.ts
+export async function load({ params }) {
+  const product = await db.products.find(params.id);
+  return { product };
+}
+```
+
+```svelte
+<!-- src/routes/products/[id]/+page.svelte -->
+<script lang="ts" module>
+  import type { BreadcrumbMeta } from 'svelte-crumbs';
+
+  export const breadcrumb: BreadcrumbMeta = async (page) => ({
+    label: page.data.product.name
+  });
+</script>
+
+<script lang="ts">
+  let { data } = $props();
+</script>
+
+<h1>{data.product.name}</h1>
+```
+
+> **Why `+layout.server.ts`?** Breadcrumb resolvers run for every segment of the URL. When visiting `/products/42/edit`, the resolver for `/products/[id]` fires too. If you put the load in `+page.server.ts`, `page.data` on child routes won't have `product` — layout data cascades down, page data doesn't.
+
+### From a remote function
+
+Breadcrumb resolvers can call [remote functions](https://svelte.dev/docs/kit/remote-functions) that run on the server:
+
+```ts
+// src/lib/products.remote.ts
+import { query } from '$app/server';
+
+export const getProductName = query('unchecked', async (id: string) => {
+  const product = await db.products.find(id);
+  return product.name;
+});
+```
+
+```svelte
+<!-- src/routes/products/[id]/+page.svelte -->
+<script lang="ts" module>
+  import type { BreadcrumbMeta } from 'svelte-crumbs';
+  import { getProductName } from '$lib/products.remote';
+
+  export const breadcrumb: BreadcrumbMeta = async (page) => ({
+    label: await getProductName(page.params.id ?? '')
+  });
+</script>
+```
+
+### Multi-route breadcrumb
+
+For dynamic routes that map to known paths:
+
+```svelte
+<script lang="ts" module>
+  import type { BreadcrumbMeta } from 'svelte-crumbs';
+
+  export const breadcrumb: BreadcrumbMeta = {
+    routes: {
+      '/docs/getting-started': async () => ({ label: 'Getting Started' }),
+      '/docs/api-reference': async () => ({ label: 'API Reference' })
+    }
+  };
+</script>
+```
+
+### With icon
+
+```svelte
+<script lang="ts" module>
+  import type { BreadcrumbMeta } from 'svelte-crumbs';
+  import HomeIcon from './HomeIcon.svelte';
+
+  export const breadcrumb: BreadcrumbMeta = async () => ({
+    label: 'Home',
+    icon: HomeIcon
+  });
+</script>
+```
+
+### Custom rendering
+
+Since `svelte-crumbs` only provides data, you render however you want:
+
+```svelte
+<script lang="ts">
+  import { createBreadcrumbs } from 'svelte-crumbs';
+
+  const getBreadcrumbs = createBreadcrumbs();
+  const crumbs = $derived(await getBreadcrumbs());
+</script>
+
+<ol class="breadcrumb-list">
+  {#each crumbs as crumb}
+    <li>
+      {#if crumb.icon}
+        {@const Icon = crumb.icon}
+        <Icon />
+      {/if}
+      <a href={crumb.url}>{crumb.label}</a>
+    </li>
+  {/each}
+</ol>
+```
+
+## API Reference
+
+### `createBreadcrumbs()`
+
+Creates a reactive breadcrumb resolver. Returns a getter function `() => Promise<Breadcrumb[]>`.
+
+Call `createBreadcrumbs()` once to set up the reactive state, then use the returned getter inside `$derived(await ...)` to get breadcrumbs that update on navigation and resolve during SSR.
+
+### Types
+
+```typescript
+// What you export from +page.svelte
+type BreadcrumbMeta = BreadcrumbResolver | { routes: Record<string, BreadcrumbResolver> };
+
+// Resolver function
+type BreadcrumbResolver = (page: Page) => Promise<BreadcrumbData | undefined>;
+
+// Data for one breadcrumb
+type BreadcrumbData = { label: string; icon?: Component<any> };
+
+// Resolved breadcrumb with URL
+type Breadcrumb = BreadcrumbData & { url: string };
+```
+
+### Utility exports
+
+- `buildBreadcrumbMap()` — manually build the route-to-resolver map
+- `filePathToRoute(filePath)` — convert glob file path to route
+- `matchDynamicRoute(map, route)` — match a concrete path against dynamic patterns
+- `getResolversForRoute(map, route)` — collect resolvers for a given route path
+
+## How It Works
+
+1. `import.meta.glob` eagerly imports all `+page.svelte` files at build time
+2. Each file's `breadcrumb` export is collected into a `Map<route, resolver>`
+3. Route groups like `(app)` are stripped from paths
+4. On navigation, the root (`/`) resolver is checked first, then each segment is walked from left to right with dynamic `[param]` matching
+5. Matching resolvers run in parallel, producing the final breadcrumb array
+6. On SSR, top-level `await` ensures breadcrumbs are rendered in the initial HTML
+7. On the client, `$derived` re-evaluates when the route changes
+
+## Requirements
+
+- **SvelteKit 2** — relies on `$app/state` and `import.meta.glob`
+- **Svelte 5** — uses runes (`$derived`)
+- Route groups (`(group)`) are stripped from paths
+
+### Optional: enable async and remote functions
+
+The library works without any experimental flags — you can use load functions or resolve breadcrumbs manually. However, to unlock top-level `await` in components and remote function support, enable these flags:
+
+```js
+// svelte.config.js
+const config = {
+  compilerOptions: {
+    experimental: {
+      async: true // top-level await in components
+    }
+  },
+  kit: {
+    experimental: {
+      remoteFunctions: true // call server functions from breadcrumb resolvers
+    }
+  }
+};
+```
+
+## License
+
+MIT

package/dist/breadcrumbs/create-breadcrumbs.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { Breadcrumb } from '../types.js';
+/**
+ * Creates a reactive breadcrumb resolver that automatically tracks the current route.
+ * Uses top-level await with SvelteKit's async experimental compiler option for SSR support.
+ *
+ * Usage:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createBreadcrumbs } from 'svelte-breadcrumbs';
+ *   const getBreadcrumbs = createBreadcrumbs();
+ *   const crumbs = $derived(await getBreadcrumbs());
+ * </script>
+ *
+ * {#each crumbs as crumb}
+ *   <a href={crumb.url}>{crumb.label}</a>
+ * {/each}
+ * ```
+ */
+export declare function createBreadcrumbs(): () => Promise<Breadcrumb[]>;

package/dist/breadcrumbs/create-breadcrumbs.svelte.js

@@ -0,0 +1,35 @@
+import { page } from '$app/state';
+import { buildBreadcrumbMap } from '../routing/build-breadcrumb-map.js';
+import { getResolversForRoute } from '../routing/get-resolvers-for-route.js';
+async function resolve(resolvers) {
+    const promises = Array.from(resolvers).map(async ([url, resolver]) => {
+        const data = await resolver(page);
+        if (!data)
+            return undefined;
+        return { ...data, url };
+    });
+    const results = await Promise.all(promises);
+    return results.filter((b) => b !== undefined);
+}
+/**
+ * Creates a reactive breadcrumb resolver that automatically tracks the current route.
+ * Uses top-level await with SvelteKit's async experimental compiler option for SSR support.
+ *
+ * Usage:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createBreadcrumbs } from 'svelte-breadcrumbs';
+ *   const getBreadcrumbs = createBreadcrumbs();
+ *   const crumbs = $derived(await getBreadcrumbs());
+ * </script>
+ *
+ * {#each crumbs as crumb}
+ *   <a href={crumb.url}>{crumb.label}</a>
+ * {/each}
+ * ```
+ */
+export function createBreadcrumbs() {
+    const map = buildBreadcrumbMap();
+    const resolversForRoute = $derived(getResolversForRoute(map, page.url.pathname));
+    return () => resolve(resolversForRoute);
+}

package/dist/demo/docs.remote.d.ts

@@ -0,0 +1 @@
+export declare const getDocTitle: import("@sveltejs/kit").RemoteQueryFunction<string, string>;

package/dist/demo/docs.remote.js

@@ -0,0 +1,11 @@
+import { query } from '$app/server';
+const docs = {
+    'getting-started': 'Getting Started',
+    'api-reference': 'API Reference',
+    'migration-guide': 'Migration Guide'
+};
+export const getDocTitle = query('unchecked', async (slug) => {
+    // Simulate database/CMS lookup
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    return docs[slug] ?? slug;
+});

package/dist/demo/greeting.remote.d.ts

@@ -0,0 +1,2 @@
+export declare const getNickname: import("@sveltejs/kit").RemoteQueryFunction<void, string>;
+export declare const setNickname: import("@sveltejs/kit").RemoteCommand<string, Promise<void>>;

package/dist/demo/greeting.remote.js

@@ -0,0 +1,12 @@
+import { command, query } from '$app/server';
+let currentNickname = 'Visitor';
+export const getNickname = query(async () => {
+    // Simulate server-side lookup (e.g. user profile, session, database)
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    return currentNickname;
+});
+export const setNickname = command('unchecked', async (name) => {
+    // Simulate server-side write
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    currentNickname = name.trim() || 'Visitor';
+});

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createBreadcrumbs } from './breadcrumbs/create-breadcrumbs.svelte.js';
+export { buildBreadcrumbMap } from './routing/build-breadcrumb-map.js';
+export { filePathToRoute, matchDynamicRoute } from './routing/match-route.js';
+export { getResolversForRoute } from './routing/get-resolvers-for-route.js';
+export type { Breadcrumb, BreadcrumbData, BreadcrumbMap, BreadcrumbMeta, BreadcrumbResolver } from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createBreadcrumbs } from './breadcrumbs/create-breadcrumbs.svelte.js';
+export { buildBreadcrumbMap } from './routing/build-breadcrumb-map.js';
+export { filePathToRoute, matchDynamicRoute } from './routing/match-route.js';
+export { getResolversForRoute } from './routing/get-resolvers-for-route.js';

package/dist/routing/build-breadcrumb-map.d.ts

@@ -0,0 +1,6 @@
+import type { BreadcrumbMap } from '../types.js';
+/**
+ * Scans all +page.svelte files via import.meta.glob for `breadcrumb` exports
+ * and builds a map from route pattern to resolver function.
+ */
+export declare function buildBreadcrumbMap(): BreadcrumbMap;

package/dist/routing/build-breadcrumb-map.js

@@ -0,0 +1,20 @@
+import { filePathToRoute } from './match-route.js';
+/**
+ * Scans all +page.svelte files via import.meta.glob for `breadcrumb` exports
+ * and builds a map from route pattern to resolver function.
+ */
+export function buildBreadcrumbMap() {
+    const map = new Map();
+    const pageModules = import.meta.glob('/src/routes/**/+page.svelte', { eager: true });
+    for (const [filePath, module] of Object.entries(pageModules)) {
+        if (!module?.breadcrumb)
+            continue;
+        const route = filePathToRoute(filePath);
+        const meta = module.breadcrumb;
+        const routes = 'routes' in meta ? meta.routes : { [route]: meta };
+        for (const [routeKey, resolver] of Object.entries(routes)) {
+            map.set(routeKey, resolver);
+        }
+    }
+    return map;
+}

package/dist/routing/get-resolvers-for-route.d.ts

@@ -0,0 +1,6 @@
+import type { BreadcrumbMap } from '../types.js';
+/**
+ * Walks route segments from root to leaf, collecting ordered resolvers.
+ * For `/products/123/edit`, checks `/`, `/products`, `/products/123`, `/products/123/edit`.
+ */
+export declare function getResolversForRoute(map: BreadcrumbMap, route: string): BreadcrumbMap;

package/dist/routing/get-resolvers-for-route.js

@@ -0,0 +1,23 @@
+import { matchDynamicRoute } from './match-route.js';
+/**
+ * Walks route segments from root to leaf, collecting ordered resolvers.
+ * For `/products/123/edit`, checks `/`, `/products`, `/products/123`, `/products/123/edit`.
+ */
+export function getResolversForRoute(map, route) {
+    const resolvers = new Map();
+    // Always check root first
+    const rootResolver = map.get('/');
+    if (rootResolver) {
+        resolvers.set('/', rootResolver);
+    }
+    const segments = route.split('/').filter(Boolean);
+    let currentRoute = '';
+    for (const segment of segments) {
+        currentRoute += `/${segment}`;
+        const resolver = map.get(currentRoute) ?? matchDynamicRoute(map, currentRoute);
+        if (!resolver)
+            continue;
+        resolvers.set(currentRoute, resolver);
+    }
+    return resolvers;
+}

package/dist/routing/match-route.d.ts

@@ -0,0 +1,11 @@
+import type { BreadcrumbMap, BreadcrumbResolver } from '../types.js';
+/**
+ * Converts a file path from import.meta.glob to a clean route.
+ * `/src/routes/(group)/products/+page.svelte` → `/products`
+ */
+export declare function filePathToRoute(filePath: string): string;
+/**
+ * Matches a concrete route against dynamic patterns in the breadcrumb map.
+ * `/products/123` matches `/products/[id]`
+ */
+export declare function matchDynamicRoute(map: BreadcrumbMap, route: string): BreadcrumbResolver | undefined;

package/dist/routing/match-route.js

@@ -0,0 +1,26 @@
+/**
+ * Converts a file path from import.meta.glob to a clean route.
+ * `/src/routes/(group)/products/+page.svelte` → `/products`
+ */
+export function filePathToRoute(filePath) {
+    return (filePath
+        .replace(/^\/src\/routes/, '')
+        .replace(/\/\+page\.svelte$/, '')
+        .replace(/\/\(.*?\)/g, '') || '/');
+}
+/**
+ * Matches a concrete route against dynamic patterns in the breadcrumb map.
+ * `/products/123` matches `/products/[id]`
+ */
+export function matchDynamicRoute(map, route) {
+    const routeSegments = route.split('/').filter(Boolean);
+    for (const [pattern, resolver] of map) {
+        const patternSegments = pattern.split('/').filter(Boolean);
+        if (routeSegments.length !== patternSegments.length)
+            continue;
+        const isMatch = patternSegments.every((segment, i) => (segment.startsWith('[') && segment.endsWith(']')) || segment === routeSegments[i]);
+        if (isMatch)
+            return resolver;
+    }
+    return undefined;
+}

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+import type { Component } from 'svelte';
+import type { Page } from '@sveltejs/kit';
+/** What users export from +page.svelte as `breadcrumb` */
+export type BreadcrumbMeta = BreadcrumbResolver | {
+    routes: Record<string, BreadcrumbResolver>;
+};
+/** Async resolver function that receives the current page and returns breadcrumb data */
+export type BreadcrumbResolver = (page: Page) => Promise<BreadcrumbData | undefined>;
+/** Resolved data for one breadcrumb */
+export type BreadcrumbData = {
+    label: string;
+    icon?: Component<any>;
+};
+/** Final breadcrumb with its URL */
+export type Breadcrumb = BreadcrumbData & {
+    url: string;
+};
+/** Internal map from route pattern to resolver */
+export type BreadcrumbMap = Map<string, BreadcrumbResolver>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,79 @@
+{
+	"name": "svelte-crumbs",
+	"version": "1.0.0",
+	"description": "Automatic breadcrumbs for SvelteKit via route-level metadata exports",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/focause/svelte-crumbs.git"
+	},
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build && npm run prepack",
+		"preview": "vite preview",
+		"prepare": "svelte-kit sync || echo ''",
+		"prepack": "svelte-kit sync && svelte-package && publint",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"lint": "prettier --check . && eslint .",
+		"format": "prettier --write .",
+		"test:unit": "vitest",
+		"test": "npm run test:unit -- --run"
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	},
+	"peerDependencies": {
+		"@sveltejs/kit": "^2.0.0",
+		"svelte": "^5.0.0"
+	},
+	"devDependencies": {
+		"@changesets/cli": "^2.29.8",
+		"@eslint/compat": "^2.0.2",
+		"@eslint/js": "^9.39.3",
+		"@sveltejs/adapter-auto": "^7.0.1",
+		"@sveltejs/kit": "^2.53.0",
+		"@sveltejs/package": "^2.5.7",
+		"@sveltejs/vite-plugin-svelte": "^6.2.4",
+		"@tailwindcss/vite": "^4.2.0",
+		"@types/node": "^24.10.13",
+		"@vitest/browser-playwright": "^4.0.18",
+		"eslint": "^9.39.3",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-svelte": "^3.15.0",
+		"globals": "^17.3.0",
+		"playwright": "^1.58.2",
+		"prettier": "^3.8.1",
+		"prettier-plugin-svelte": "^3.5.0",
+		"publint": "^0.3.17",
+		"shiki": "^3.22.0",
+		"svelte": "^5.53.2",
+		"svelte-check": "^4.4.3",
+		"tailwindcss": "^4.2.0",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.56.0",
+		"vite": "^7.3.1",
+		"vitest": "^4.0.18",
+		"vitest-browser-svelte": "^2.0.2"
+	},
+	"keywords": [
+		"svelte",
+		"sveltekit",
+		"breadcrumbs",
+		"navigation"
+	]
+}