David Dal Busco RSS Feed

Structuring SvelteKit Load Functions

Thu, 16 Jul 2026 00:00:00 GMT

Photo by Jr Korpa on Unsplash

Earlier this year I built a server-side rendered app. I developed it with SvelteKit and dozens of +page.server.ts load functions that run before pages render. They all needed authentication, and keeping things maintainable quickly became a real challenge.

In this post, I'll walk you through the architecture I ended up creating. To keep the examples concrete, let's pretend we're building an online pizza shop. 🍕

The Problem

Packing everything into the load function works fine at first:

// +page.server.ts
export const load: PageServerLoad = async ({ locals, depends }) => {
    depends("app:auth");

    if (!locals.jwt) {
        return { pizzas: undefined };
    }

    const response = await fetch(`${API_URL}/pizzas`, {
        headers: { cookie: `jwt=${locals.jwt}` }
    });

    if (!response.ok) {
        error(500, "Failed to load pizzas");
    }

    return { pizzas: await response.json() };
};

As soon as you have ten pages, this falls apart.

The depends call (which tells SvelteKit to re-run the load function when auth state changes), the JWT guard, and the error handling are copy-pasted everywhere.

The fetching logic lives inside the route files, coupling them together and making each one harder to test in isolation.

On top of that, not all requests are SSR. Some happen on the client side and don't need the JWT forwarded as a header, so you end up with two flavors of the same API call with nothing enforcing the difference.

And when you need to change your auth logic or error handling, you likely have to touch every single load file.

The Architecture

The solution I suggest is a layered structure with clear, distinct responsibilities:

src/
  lib/
    api/
      _api.ts             ← base class for all API calls
      _api.ssr.ts         ← SSR-specific base (JWT forwarding)
      pizzas.api.ts      ← browser API
      pizzas.api.ssr.ts  ← SSR API
    services/
      pizzas.services.ts
  main/
    server/
      _server.ts          ← ServerLoader abstract base class
      pizzas.server.ts
  routes/
    pizzas/
      +page.server.ts     ← one-liner

The one rule that holds the whole thing together: route files contain no logic. They delegate entirely to a server class.

The second: lib contains nothing SvelteKit-specific. Keeping it that way makes your business logic agnostic of the presentation layer and potentially allows you to switch your UI, design or even framework without too much pain in the future.

The Foundation: hooks.server.ts

Our API (and I'm assuming yours too) requires a JWT to authenticate calls. Once issued after authentication, we can rely on credentials: 'include' on the client side, which instructs the browser to embed the cookie automatically. However, on the server side, there is no such API and the cookie has to be read manually to pass the JWT along as an HTTP header.

That's why, to make the JWT easily accessible across the application via locals (an object specific to a single request which is available to any route), the first step is setting up a hooks.server.ts that runs every time the SvelteKit server receives a request and extracts it.

// hooks.server.ts
import type { Handle } from "@sveltejs/kit";

export const handle: Handle = ({ event, resolve }) => {
    event.locals.jwt = event.cookies.get("jwt");
    return resolve(event);
};

And the type declaration:

// app.d.ts
declare global {
    namespace App {
        interface Locals {
            jwt: string | undefined;
        }
    }
}

Layer 1: The API Split

All APIs generally share common traits. In this case, they all have an apiUrl and a throwError method to handle exceptions, therefore they can live in a base class.

Note: I use the _ prefix for filename as a convention for package-scoped modules that are not meant to be used directly outside their layer.

// lib/api/_api.ts
export abstract class Api {
    protected readonly apiUrl: string;

    protected constructor({ apiUrl }: { apiUrl: string }) {
        this.apiUrl = apiUrl;
    }

    protected async throwError({
        message,
        response
    }: {
        response: Response;
        message: string;
    }): Promise<never> {
        switch (response.status) {
            case 400:
            case 500: {
                const body = await response.json().catch(() => ({}));
                throw new ApiError(`${message} (${response.status}): ${body.message}`, {
                    cause: response
                });
            }
            default:
                throw new ApiError(`${message} (${response.status})`, { cause: response });
        }
    }
}

The throwError method tries to parse the response body as JSON for known error status codes (400, 500) because our API returns a structured error message in those cases. For anything else, it falls back to just the status code.

As for SSR calls, they share one extra trait: the need to pass the JWT as an HTTP header. Another base class, ApiSsr, extends Api and takes the JWT at construction time, exposing a cookieHeader() helper:

// lib/api/_api.ssr.ts
export abstract class ApiSsr extends Api {
    readonly #jwt: string;

    protected constructor({ apiUrl, jwt }: { apiUrl: string; jwt: string }) {
        super({ apiUrl });
        this.#jwt = jwt;
    }

    cookieHeader(): { cookie: `jwt=${string}` } {
        return { cookie: `jwt=${this.#jwt}` };
    }
}

Note: I use .ssr.ts rather than .server.ts - which was my first idea - because it seems that the latter is a globally reserved suffix for SvelteKit.

With those two base classes in place, each resource gets two API classes: one for the browser, one for SSR.

One might argue that a single class could behave differently depending on where it runs. When I implemented the solution, I felt like the explicit separation was cleaner but, fair enough, I would not be opposed to the alternative.

With the base classes in place, the two API classes serve different purposes. The browser API handles mutations — actions triggered by the user, like creating a pizza:

// lib/api/pizzas.api.ts
export class ApiPizzas extends Api {
    create = async ({ body }: { body: CreatePizzaBody }): Promise<CreatePizzaResponse> => {
        const response = await fetch(`${this.apiUrl}/pizzas`, {
            method: "POST",
            credentials: "include",
            headers: {
                "Content-Type": "application/json"
            },
            body: CreatePizzaBodyCodec.decode(body)
        });

        if (!response.ok) {
            return await this.throwError({ response, message: "Cannot post /pizzas" });
        }

        const result = await response.json();

        return CreatePizzaResponse.parse(result);
    };
}

The SSR API handles reads — data fetched in load functions before the page renders. As explained, there is no cookie jar on the server, so the JWT has to be forwarded explicitly via the cookieHeader() helper:

// lib/api/pizzas.api.ssr.ts
export class ApiPizzasSsr extends ApiSsr {
    list = async (): Promise<ListPizzasResponse> => {
        const response = await fetch(`${this.apiUrl}/pizzas`, {
            headers: {
                ...this.cookieHeader() // → { cookie: `jwt=${this.#jwt}` }
            }
        });

        if (!response.ok) {
            return await this.throwError({ response, message: "Cannot get /pizzas" });
        }

        return ApiPizzasSchema.ListPizzasResponse.parse(await response.json());
    };
}

In the above snippets you might have noticed the use of Zod for schema validation. Parsing the response ensures it matches the expected shape at runtime.

Layer 2: Services

Services sit between the API layer and the page and layout servers. Their role is to act as a proxy that never throws. Instead, they catch errors and return a Result, a discriminated union that should be handled by the caller. I find this pattern - really similar to Rust - more expressive and elegant to deal with potential errors.

type Result<T> = { status: "success"; result: T } | { status: "error"; err: unknown };

When there is additional logic to handle, services become more than a proxy, but the contract stays the same.

// lib/services/pizzas.services.ts
export const listPizzas = async (args: { jwt: string }): Promise<Result<{ pizzas: Pizza[] }>> => {
    try {
        const api = ApiPizzasSsr.create(args);
        const { pizzas } = await api.list();
        return { status: "success", result: { pizzas } };
    } catch (err) {
        return { status: "error", err };
    }
};

A service for fetching a single pizza by ID - e.g. getPizza - would follow the same pattern, taking an additional pizzaId parameter alongside jwt.

Layer 3: The ServerLoader

As mentioned in the introduction, the goal is to avoid duplicating logic and repetitive code across every load function used by our routes, respectively the layout and page server. ServerLoader is an abstract base class that centralises all of that in one place:

// main/server/_server.ts
import { error, type ServerLoadEvent } from "@sveltejs/kit";

export abstract class ServerLoader {
    readonly #context: string;

    protected constructor({ context }: { context: string }) {
        this.#context = context;
    }

    protected async _load<T>({
        $event: { depends, locals },
        errorFallbackMsg,
        loaderFn
    }: {
        $event: ServerLoadEvent;
        errorFallbackMsg: string;
        loaderFn: (params: { jwt: string }) => Promise<Result<T>>;
    }): Promise<T | undefined> {
        depends("main:auth");

        if (isNullish(locals.jwt)) {
            return undefined;
        }

        const result = await loaderFn({ jwt: locals.jwt });

        if (result.status === "error") {
            console.error(`[${this.#context}]`, result.err);
            error(500, result.err instanceof Error ? result.err.message : errorFallbackMsg);
        }

        return result.result;
    }

    protected async _loadWithSlug<T>({
        $event: { params, ...eventRest },
        errorFallbackMsgs: { load: errorFallbackMsg, missingSlug: errorMissingSlug },
        loaderWithSlugFn
    }: {
        $event: ServerLoadEvent;
        errorFallbackMsgs: { load: string; missingSlug: string };
        loaderWithSlugFn: (params: { jwt: string; slug: string }) => Promise<Result<T>>;
    }): Promise<T | undefined> {
        const { slug } = params;

        if (isEmptyString(slug)) {
            error(404, errorMissingSlug);
        }

        const loaderFn = async (args: { jwt: string }) => await loaderWithSlugFn({ slug, ...args });

        return await this._load({
            $event: { params, ...eventRest },
            loaderFn,
            errorFallbackMsg
        });
    }
}

The class exposes two protected methods. _load is the general one, meant to be called with a loader function that hooks into the service layer. _loadWithSlug is for dynamic routes where a slug is expected in the URL params.

On error, both rely on SvelteKit's error() function — a function that never returns — to throw a 404 or 500 with a meaningful message.

Since the application has a sign-in and sign-out flow, every load registers a depends('main:auth') dependency. This tells SvelteKit to re-run the load function whenever invalidate('main:auth') is called, for example after a successful login or logout.

Lastly, also related to authentication, the JWT guard returns undefined early if locals.jwt is not set. The UI is responsible for handling the unauthenticated state.

Layer 4: Server Classes

Server classes are the concrete classes that the route files will instantiate. They extend ServerLoader, pass a context string for log tagging, and expose typed public methods:

// main/server/pizzas.server.ts
import type { ServerLoadEvent } from "@sveltejs/kit";
import { listPizzas } from "$lib/services/pizzas.services";

export class PizzasServer extends ServerLoader {
    private constructor(init: { context: string }) {
        super(init);
    }

    static create(): PizzasServer {
        return new PizzasServer({ context: "pizzas" });
    }

    async listPizzas($event: ServerLoadEvent): Promise<{ pizzas: Pizza[] } | undefined> {
        return await this._load({
            $event,
            errorFallbackMsg: "Unexpected error while loading the pizzas",
            loaderFn: listPizzas
        });
    }
}

For slug-based routes:

// main/server/pizza.server.ts
import type { ServerLoadEvent } from "@sveltejs/kit";
import { getPizza } from "$lib/services/pizza.services";

export class PizzaServer extends ServerLoader {
    private constructor(init: { context: string }) {
        super(init);
    }

    static create(): PizzaServer {
        return new PizzaServer({ context: "pizza" });
    }

    async getPizza($event: ServerLoadEvent): Promise<{ pizza: Pizza } | undefined> {
        return await this._loadWithSlug({
            $event,
            errorFallbackMsgs: {
                load: "Unexpected error while loading the pizza",
                missingSlug: "Pizza cannot be fetched, no pizza ID provided."
            },
            loaderWithSlugFn: async ({ slug: pizzaId, ...rest }) => await getPizza({ pizzaId, ...rest })
        });
    }
}

Layer 5: Route Files

With all the logic extracted, route files become one-liners:

// routes/pizzas/+page.server.ts
import type { PageServerLoad } from "./$types";

export const load: PageServerLoad = ($event) => PizzasServer.create().listPizzas($event);

// routes/pizzas/[slug]/+page.server.ts
import type { PageServerLoad } from "./$types";

export const load: PageServerLoad = ($event) => PizzaServer.create().getPizza($event);

With this architecture, a route file is just a declaration of intent.

Note that the same pattern works similarly for LayoutServerLoad.

Testability

Because each layer has no dependency on the others, testing is straightforward. The API layer, services, and server classes can all be tested independently by mocking fetch globally. The route file test is just a spy confirming delegation to the server class.

Summary

Layer	Responsibility	SvelteKit imports?
`_api.ts`	HTTP, error throwing	No
`_api.ssr.ts`	JWT cookie forwarding	No
`pizzas.api.ts`	Browser mutations (`credentials: 'include'`)	No
`pizzas.api.ssr.ts`	SSR reads (JWT header)	No
Services	Proxy API calls, return `Result`	No
`_server.ts`	Auth guard, `depends`, error handling	Yes
Server classes	Concrete load methods	Yes
Route files	One-line delegation	Yes

Conclusion

With this architecture, layers are clearly separated and logic isn't duplicated. Adding a new route means writing one new method and one new line in a route file, which is about as boring as it should be even for your LLM.

Until next time!
David

Seedorf UR - Hinter Jochli - Dallenwil

Fri, 10 Jul 2026 00:00:00 GMT

I did exactly the same trail one year ago, still one of the most pleasant trails in central Switzerland. That said, 31°C is a bit too warm for running 🥵, so I went up at a slower pace this time.

Building a Trails Section With Maps

Thu, 09 Jul 2026 00:00:00 GMT

Photo by Nenad Novaković on Unsplash

I've been running the Alps for a few years now. At some point I wanted my own record of it, not just a Strava feed, but something on my own site. So I started building a Trails section with the GPX tracks and photos of my "adventures".

Building it was also a good excuse to take a look at the map landscape nowadays, and it turned out that "just add a map" was a bit of a bigger question than it sounds. So, I developed it like this.

Finding a map

Whatever library you pick to render a map, Leaflet, MapLibre, or anything else, it draws what you give it. You need your data, but you also need a source of tiles (raster images or vector geometry) to actually see a map, and that's the part that turns "add a map" into a real decision.

The options

I went looking, and from what I understood, those are the options I had to gather the tiles:

Self-hosting

Since I already self-host my website, my analytics, and other tools, checking whether I could self-host the map tiles too was my first instinct. I found Protomaps, which publishes pre-built vector tile archives you can just serve as static files. Minimal setup, exactly my kind of thing. However, looking at the actual rendering, it wasn't quite the look I wanted. Since I'm displaying trails in the mountains, I wanted some relief, not a flat design.

I then came across a project called Mapterhorn, mentioned in Protomaps' blog, meant to provide exactly that kind of elevation data, but I wasn't exactly sure how to put all the pieces together, nor whether it was still in development or production ready. It would have been cool to use, as it seems to be developed in Zurich.

I also looked at serving - and generating - my own tiles with Planetiler plus Martin or TileServer GL, but even if someone more comfortable with DevOps would say it's not that much work, it felt like more overhead and maintenance than I wanted to take on for a personal site.

Long story short, I got lost in limbo.

Regional data

Since I mostly run in Switzerland, I then checked if swisstopo, the national mapping agency, had an API.

Spoiler alert: they do, and it's a really interesting service. They serve their own tiles, satellite imagery included, for free, no signup, no API key, just a fair-use policy.

I was tempted, but since I also wanted to show off (brag 😅) the mountains I ran when I visited Japan, that ruled it out.

Commercial providers

Ultimately I opened up to the idea of using a third-party cloud provider, MapTiler (was pleased to learn they're also based in Switzerland, at least part of it, it seems) and Carto looked like solid options. Both work as a drop-in source for Leaflet or MapLibre, and have a free tier. MapTiler even ships an "Outdoor" style with trails built in, exactly the look I had in mind.

The catch is that free tiers come with quotas, though generous enough for a website like mine. Carto even seems to have an unlimited free tier, but to be honest with you, their tagline "The Agentic GIS Platform" just ruled them out.

There is also Mapbox, which felt too commercial and Google Maps API was not even an option.

While browsing further, I noticed that Wikiloc actually displayed an "Apple" footer in their maps. I told myself: wait, Apple is also a map provider?

What I picked

I ended up going with the last option. Apple has its own closed map renderer, exposed as a JS library for the web, and they'd just released a newest version. If you already have an Apple Developer Program membership ($99/year), it's "free" to use, with a daily quota of 250,000 map views and 25,000 service calls.

That's my case, since I publish a few app updates to their store each year, and it always felt like a bit of a scam to pay for it every year as it does not seem worth the money. So I figured, why not get some value back out of it by actually using it for something. Plus, their free tier should easily cover the little traffic of my website.

Building it

Here's how I actually wired it into the Trails page.

Getting started

To show anything on a map, you need points. In my case, those come from parsing the GPX data of each trail. I'll skip that part here for brevity, but each point ends up looking like this: a coordinate (latitude and longitude) and a unique id.

interface MapGpxPoint {
    id: string;
    lat: number;
    lon: number;
}

The id is optional but useful when you want to manipulate the points on the UI side, for example when hovering a point on the map.

Loading the map

There's an official open source mapkit-loader to bring the library in, though I have to say that even though I used it, I'm not fully sold on it.

The loader injects a script tag into the page. On one hand, I would have preferred an await import() API, arguably a matter of taste, but on the other, injecting a script tag at runtime within my app is never something I'm really a fan of (#paranoid) and could raise some questions around handling the Content-Security-Policy (the library does support a nonce, though it's not the most elegant solution).

It also seems to load the entire MapKit core regardless of what you actually use, which makes me wonder if that couldn't be trimmed down for performance.

Lastly, you end up holding two separate entities in your state if you want to manipulate the map once it's rendered: the MapKit API itself, and the interactive map instance. I would have expected a single reference.

Anyway, I could have rewritten the loader but couldn't really influence the rest, so I just went with it.

import { load, type MapKit as AppleMapKit, type Map } from "@apple/mapkit-loader";

export interface MapKit {
    mapkit: AppleMapKit;
    map: Map;
}

export const loadMap = async ({ anchor }: { anchor: HTMLElement }): Promise<MapKit> => {
    const mapkit = await load({
        libraries: ["map", "annotations", "overlays"],
        token: "YOUR_TOKEN"
    });

    const map = new mapkit.Map(anchor);

    return {
        mapkit,
        map
    };
};

Loading the map requires a token, which you can create in your Apple Developer Dashboard and which can be scoped to a specific domain. For now, we just keep it simple and hardcoded, I'll come back to how I actually handle it in production later on in this blog post.

The libraries are the list of services you need for your map. Since all I'm doing is showing a map, a route, and a couple of markers, map, annotations, and overlays cover it.

Displaying markers

Each trail on the site needs a starting point marked on the map. A visual hint of where the trail begins, but also something a visitor can click to actually open the trail page from the map itself.

A marker is a mapkit.MarkerAnnotation, adding an annotation is what gets a point displayed. The popover, the link, is resolved with a custom callout shown in a bubble:

const markers = annotations.map(
    ({ location: { lat, lon }, title, pathname }) =>
        new mapkit.MarkerAnnotation(new mapkit.Coordinate(lat, lon), {
            title,
            callout: {
                calloutContentForAnnotation: () => {
                    const link = document.createElement("a");
                    link.href = pathname;
                    link.textContent = title;
                    link.setAttribute("aria-label", `View ${title}`);
                    return link;
                }
            }
        })
);

map.addAnnotations(markers);

An annotation is really just a GPS point extended with a bit of metadata, a title, and a link (pathname) to navigate to when clicked:

interface MapAnnotation {
    location: MapGpxPoint;
    title: string;
    pathname: string;
}

There's more to configure than that, colors, custom glyphs, visibility of the title, and so on.

Drawing the route

Displaying a Trails section has two components: a list and a details page. While showing all the trails with markers could be resolved by the previous chapter, on the details page I wanted to go a step further by drawing the route, the actual trace I followed when I ran or biked.

This can be resolved by mapping all the points of a track to coordinates and joining those through an overlay.

const coordinates = points.map(({ lat, lon }) => new mapkit.Coordinate(lat, lon));

const routeOverlay = new mapkit.PolylineOverlay(coordinates, {
    style: new mapkit.Style({
        lineWidth: 4,
        strokeColor: "#ff65a9",
        lineJoin: "round",
        lineCap: "round"
    })
});

map.addOverlay(routeOverlay);

Once both the markers and the route are added, map.showItems([...markers, routeOverlay]) adjusts the camera to fit everything, no manual center/zoom math needed.

Keeping everything in frame

Once all the points and the route are loaded, I show everything on screen. If I added a point in Switzerland and one in Japan, I want the map to show both, not be centered in South America ;)

const focusItems = () => {
    if (kit === undefined) {
        return;
    }

    const { map } = kit;

    const items = [...(map.annotations ?? []), ...(map.overlays ?? [])];

    if (items.length > 0) {
        map.showItems(items);
    }
};

Worth noting my site doesn't load anything in the maps dynamically at runtime, so there's no UX quirk where the map would recenter while the user isn't expecting it.

Syncing a point

On the details page, I also render an elevation chart (maybe a topic for another blog post). Similarly to what Wikiloc and Strava do, I wanted the map to show the point corresponding to the elevation the user is hovering over on the chart.

This can be achieved by getting some metadata through a hover callback on the chart, most charting libraries support this, I used LayerChart. In this case, the metadata is the unique id of the point, and I update the map whenever the value changes.

// Not a state on purpose. Used for logic, not rendering.
let selectedPoint: MarkerAnnotation | undefined | null = undefined;

$effect(() => {
    if (selectedPointId === undefined) {
        if (selectedPoint !== undefined && selectedPoint !== null) {
            map.removeAnnotation(selectedPoint);
            selectedPoint = null;
        }
        return;
    }

    const point = points.find(({ id }) => id === selectedPointId);

    if (point === undefined) {
        return;
    }

    const coordinate = new mapkit.Coordinate(point.lat, point.lon);

    if (selectedPoint === undefined || selectedPoint === null) {
        selectedPoint = new mapkit.MarkerAnnotation(coordinate, {
            color: "#ff65a9",
            glyphText: "●"
        });
        map.addAnnotation(selectedPoint);
        return;
    }

    selectedPoint.coordinate = coordinate;
});

In a first approach, I removed and recreated the marker every time the selected point changed, but that turned out to be laggy, what a surprise 😂. I figured out I could just keep a reference to the rendered annotation and update its coordinate instead, which moves the point fast enough.

Putting it all together

That's basically it for rendering a map with some points and routes plus some real time interaction. You'd likely need to tweak it for your needs, but I hope it gives you a quick start.

For the Svelte lovers, here's the full implementation. Not that proud of it, I find it a bit overbloated. If this weren't my website and some more professional work, I would like to split the effects to have better control, but yeah, if it works, it works 😄.

Going to production

I mentioned earlier that loading the map requires a token, and that it can be scoped to a specific domain. So when I was ready to go live, that's exactly what I did, generated a real token. Or rather, tokens, plural, since I actually needed two: my site is reachable both on daviddalbusco.com and www.daviddalbusco.com, and Apple only lets you scope a token to one domain at a time, not both at once.

Once I created those two tokens, I had to integrate them into my website. Since it is prerendered, the simplest approach would have been to use two environment variables and drop the tokens in a .env file. Even if the repo is public, that's not really a big deal, the tokens end up on the frontend anyway, on the client side, and are de facto public regardless.

# .env
PUBLIC_MAPKIT_TOKEN_ROOT=...
PUBLIC_MAPKIT_TOKEN_WWW=...

Still, it felt nicer, or cleaner, to keep them out of the repo. Instead, I could have used GitHub Actions secrets and referenced them in the build workflow:

- name: Build
  run: npm run build
  env:
    PUBLIC_MAPKIT_TOKEN_ROOT: ${{ secrets.MAPKIT_TOKEN_ROOT }}
    PUBLIC_MAPKIT_TOKEN_WWW: ${{ secrets.MAPKIT_TOKEN_WWW }}

I was about to do exactly that, but then I thought, why not build something a bit more fun instead 🤪.

Since I self-host the site with Kyushu, I have a backend worker that serves the assets on the web, but it can do more than that. The same function can also act as an API and supports env vars. So why not extend it to also serve the token, by adding a /api/mapkit/token route that responds to GET requests 💡:

export default {
    async fetch(request, env) {
        const { pathname } = URL.parse(request.url) ?? { pathname: undefined };

        if (request.method === "GET" && pathname === "/api/mapkit/token") {
            return; // TODO returning the token
        }

        return await fetchAsset(request, env);
    }
} satisfies ExportedHandler;

Returning the token is relatively straightforward, it's basically just about identifying the GET request and providing back an adequate JSON body, but there were two tricks I had to work out.

Given there are two tokens, one for the root domain and one for www, the function needs to know which domain it's actually being called from, since there's just one function serving both. Locally, reading the Host header would have been enough, but in production I run Caddy as a reverse proxy in front of it, and that value no longer matches. Fortunately, I found out I could use x-forwarded-host, the header that carries the original host that was requested.

Aside from this, my first implementation didn't work either, because I declared the record holding the environment variables globally. Since Kyushu freezes the worker's memory and only evaluates variables at runtime, those ended up undefined. That's why I had to move the reading of those variables inside the function itself, so they're evaluated at request time.

const resolveHost = (request: WorkerRequest): string | undefined =>
    request.headers?.["x-forwarded-host"] ?? request.headers?.host;

const fetchMapkitToken: ExportedHandler["fetch"] = async (request) => {
    const host = resolveHost(request);

    if (host === undefined) {
        return {
            status: 405,
            body: "Method Not Allowed"
        };
    }

    const MAPKIT_TOKENS: Record<string, string | undefined> = {
        "daviddalbusco.com": process.env.MAPKIT_TOKEN_ROOT,
        "www.daviddalbusco.com": process.env.MAPKIT_TOKEN_WWW
    };

    const token = MAPKIT_TOKENS[host];

    if (token === undefined) {
        return {
            status: 403,
            body: "Forbidden"
        };
    }

    return {
        status: 200,
        headers: {
            "content-type": "application/json",
            "cache-control": "no-store"
        },
        body: JSON.stringify({ token })
    };
};

Lastly, on the client side, I modified the loading of the map to pre-fetch the token first before using it to load the map (instead of the plain hardcoded value from the earlier chapter):

export interface MapKit {
    mapkit: AppleMapKit;
    map: Map;
}

export const loadMap = async (args: { anchor: HTMLElement }): Promise<Result<MapKit>> => {
    return await safeExec(async () => {
        const token = await loadToken();
        return await loadMapKit({ ...args, ...token });
    });
};

const loadMapKit = async ({
    anchor,
    token
}: {
    anchor: HTMLElement;
    token: string;
}): Promise<MapKit> => {
    const mapkit = await load({
        libraries: ["map", "annotations", "overlays"],
        token
    });

    const map = new mapkit.Map(anchor);

    return {
        mapkit,
        map
    };
};

const loadToken = async (): Promise<{ token: string }> => {
    const response = await fetch("/api/mapkit/token");

    if (!response.ok) {
        const text = await response.text();
        throw new Error(`${response.status} ${text}`);
    }

    return await response.json();
};

Unrelated but somehow related note, you may notice in the snippet above that I used a safeExec function and a Result type. Those are tiny helpers I use across my projects, as I came to the realization that relying on throwing exceptions results in try/catch scattered everywhere, and can also, to some extent, result in uncaught issues. That's why I prefer to use a pattern like this, likely inherited from my work with Rust 🦀.

export type Result<T> = { status: "success"; result: T } | { status: "error"; err: unknown };

export const safeExec = async <T>(fn: () => Promise<T>): Promise<Result<T>> => {
    try {
        const result = await fn();
        return { status: "success", result };
    } catch (err: unknown) {
        return { status: "error", err };
    }
};

Conclusion

I'm a hobbyist, so don't expect ultra distances, marathon is about as far as I go, but if you are curious about the result you can see them live on the Trails page. Most routes I follow are convenient for day trips from Zürich. If you'd like to follow any of them and have questions, reach out!

Until next time!
David

Lake Zurich

Tue, 07 Jul 2026 00:00:00 GMT

I guess when you live in Zürich and own a bike, riding around the lake is basically mandatory for citizenship. Had to be done ;)

5-lake Pizol+

Fri, 03 Jul 2026 00:00:00 GMT

So, I spent the day in the fog 😄. I might redo it some day, the all view should be amazing, the lake and foggy scenery was already great.

The Pizol 5 lakes (5-Seen-Wanderung Pizol) is super popular, therefore best during the week if you don't want to slalom between hikers.

Passing the summit was alright but snowy. Likely a trail best suited towards the end of summer.

Oh, worth noting, had no phone signal most of the day.

A Progress Bar for Blog Posts

Thu, 02 Jul 2026 00:00:00 GMT

Photo by and machines on Unsplash

This morning, after doing my company's accounting and getting upset again at how garbage that software is, I decided I needed an easy, little coding task to chill 😄. So I added a small progress bar to the top of my blog posts. It's a nice little cosmetic win, and I thought I would follow up with a short post to share a couple of beginner friendly details.

If you scroll this page, you should see a bar at the top fill up as you go, and reach 100% right as you finish reading.

The component

To add this new element to the blog I created a component. I might not reuse it elsewhere, but still, it's always nice to approach composition with agnostic, reusable components. It takes an anchor element (the end of the article) as a property, since we are looking to show the progression of the reading, computes this percentage, and renders it in a element pinned at the top.

<script lang="ts">
    let { anchor }: { anchor: HTMLElement } = $props();

    $effect(() => {
        // add and remove scroll listener, see "Why not svelte:window to bind scrollY" below
    });

    let value = $state(0);

    const onscroll = () => {
        // compute % scrolled relative to the anchor, see "The math" below
    };
</script>

<progress {value} max="100"></progress>

<style lang="scss">
    // see "Styling" below
</style>

With the scene set, let's look at a few of the details.

Why not svelte:window to bind scrollY

Svelte has a built-in way to bind to scrollY (doc).

<svelte:window bind:scrollY={y} />

AFAIK it doesn't let you pass passive: true to the underlying listener. I took a quick look at the source and it doesn't seem to use it either, though I'm not entirely sure. What I do know for sure is that using a passive listener for scroll is generally a performance best practice, even if in this particular case one might argue there isn't much to worry about. That's why I went with a custom event listener instead.

Update: turns out passive isn't actually needed here anyway. As pointed out in this thread and confirmed by MDN, the scroll event can't be canceled, so a listener can't block page rendering regardless of passive.

$effect(() => {
    window.addEventListener("scroll", onscroll, { passive: true });

    return () => {
        window.removeEventListener("scroll", onscroll, false);
    };
});

In this effect I add and remove a scroll listener but you might notice a subtlety: removeEventListener doesn't pass the same options as addEventListener, which is generally required to correctly match and remove a listener. That was my assumption too, but TypeScript warned me those options weren't accepted. I looked into why and it turns out that's expected (see this issue). Searching further I figured out MDN's docs explain it well: only capture matters for removal matching, not passive, so passing false here is just being explicit about capture rather than relying on its default.

The math

It's common to see these bars track the full page scroll, but I wanted it to reflect the reading progress instead. Tracking scrollY against the full page height would be wrong here, because my pages have a footer. If I use the full scroll height, the bar never reaches 100% by the time you finish the article, since there's still the footer left to scroll past.

So instead I pass an anchor element (the end of the article), and compute how much of the scroll is "left" once you get there:

const delta = document.documentElement.scrollHeight - anchor.offsetTop;
const scrollLength = anchor.offsetTop - delta;
const y = (window.scrollY * 100) / scrollLength;

delta is everything below the anchor (footer included). Subtracting it from anchor.offsetTop gives the actual scroll distance that corresponds to "reading the article", so the bar hits 100% right when you reach the end, not somewhere before it because of the footer.

Once I got the percentage of the progression (y), I could apply it to the state value of the progress element while capping it to avoid overflow.

value = Math.min(100, Math.floor(y));

Styling

I used a native element instead of a styled div. Free accessibility semantics, and it, well, looks like a progress bar. I would have expected accent-color to be enough to style it, but it wasn't. I found the solution on Stack Overflow, which I tailored for my website:

progress {
    color: var(--color-highlight);
    background: transparent;

    /* Firefox: Filled portion of the progress bar */
    &::-moz-progress-bar {
        background: currentColor;
    }

    /* Chrome & Safari: Unfilled portion of the progress bar */
    &::-webkit-progress-bar {
        background: transparent;
    }

    /* Chrome & Safari: Filled portion of the progress bar */
    &::-webkit-progress-value {
        background: currentColor;
    }
}

I set a base color and a transparent background that the pseudo-elements inherit through currentColor, but I still need an explicit background on the Chrome/Safari specific pseudo-elements, since neither browser applies the fill by default.

Summary

Long story short, here's the full component:

<script lang="ts">
    interface Props {
        anchor: HTMLElement;
    }

    let { anchor }: Props = $props();

    let value = $state(0);

    const onscroll = () => {
        const delta = document.documentElement.scrollHeight - anchor.offsetTop;
        const scrollLength = anchor.offsetTop - delta;

        const y = (window.scrollY * 100) / scrollLength;
        value = Math.min(100, Math.floor(y));
    };

    $effect(() => {
        window.addEventListener("scroll", onscroll, { passive: true });

        return () => {
            // https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener#matching_event_listeners_for_removal
            window.removeEventListener("scroll", onscroll, false);
        };
    });
</script>

<progress {value} max="100"></progress>

<style lang="scss">
    progress {
        position: fixed;
        top: 0;
        left: 0;
        width: 100%;
        height: 0.25rem;

        z-index: 10;

        appearance: none;
        border: none;
    }

    // Color: https://stackoverflow.com/a/76860350/5404186
    progress {
        color: var(--color-highlight);
        background: transparent;

        /* Firefox: Filled portion of the progress bar */
        &::-moz-progress-bar {
            background: currentColor;
        }

        /* Chrome & Safari: Unfilled portion of the progress bar */
        &::-webkit-progress-bar {
            background: transparent;
        }

        /* Chrome & Safari: Filled portion of the progress bar */
        &::-webkit-progress-value {
            background: currentColor;
        }
    }
</style>

Conclusion

Nothing fancy but, it was fun. Feel free to copy/pasta the code or let me know if anything should be improved.

Until next time!
David

Greifensee

Tue, 30 Jun 2026 00:00:00 GMT

A loop around the Greifensee.

Altdorf - Engelberg

Sat, 27 Jun 2026 00:00:00 GMT

Poor performance. Two thirds felt like running in an oven thanks to the heatwave, and the last third was spent hoping not to get caught in the storm.

Around 200m of the pass was covered in snow. July or even August feels like the safer bet if you want to avoid it.

Yet Another Web Analytics

Wed, 24 Jun 2026 00:00:00 GMT

Photo by BoliviaInteligente on Unsplash

I've been building Juno for a few years, a platform I ultimately deprecated recently. As a result, I needed to move my projects away from it, including the analytics of my own website, which were baked into the platform.

So I looked around at what was out there that matched my requirements (privacy-friendly, self-hosted, open-source, not sloppy, etc.), found a few good options, but ultimately thought: why not build my own web analytics, again 😅. After all, I already had the knowledge and could likely reuse some of my code.

I gave it some thought but honestly was still hesitant, until a second motivation came into play: what if I explored a new UX paradigm? What if instead of building a UI, I would solely rely on an LLM (Claude Code or else) to query my analytics in plain language (also known as "frenglish" in my case).

The result is yet another web analytics (shortened yawa by the cool kids, meaning me), a self-hostable, open-source, no cookies, no GDPR consent, web analytics solution.

How it works

Your app or website sends analytics through a lightweight JavaScript library (yawa-tracker) that collects page views, custom events, and Web Vitals.

On your self-hosted server, a Docker container runs an API that receives the events and stores them in an embedded DuckDB database. It also exposes 26+ analytics tools over the Model Context Protocol (MCP).

Finally, connect your MCP client (Claude Code, Codex, or any compatible client) to your endpoint and query your data in plain language.

In practice, that last step looks like this:

❯ What are my top pages this week?

• Fetching your site ID and top pages for this week.

  Called fluster-analytics 2 times

• Here are your top 10 pages on daviddalbusco.com this week (Jun 15–22):

┌───────────────────────────────────────────────────────────────┬──────────┬───────────┐
│                             Page                              │ Visitors │ Pageviews │
├───────────────────────────────────────────────────────────────┼──────────┼───────────┤
│ / (home)                                                      │ 72       │ 84        │
├───────────────────────────────────────────────────────────────┼──────────┼───────────┤
│ /blog/making-your-website-ai-ready                            │ 53       │ 59        │
├───────────────────────────────────────────────────────────────┼──────────┼───────────┤
│ /blog/                                                        │ 14       │ 14        │
├───────────────────────────────────────────────────────────────┼──────────┼───────────┤
│ /blog/automating-newsletter-claude-telegram-cloudflare-worker  │ 10       │ 11        │
├───────────────────────────────────────────────────────────────┼──────────┼───────────┤
│ /blog/making-your-website-ai-ready/                           │ 10       │ 11        │
├───────────────────────────────────────────────────────────────┼──────────┼───────────┤
│ /blog/better-type-safety-in-svelte-guard-components           │ 6        │ 6         │
├───────────────────────────────────────────────────────────────┼──────────┼───────────┤
│ /blog/serving-local-assets-with-bun                           │ 6        │ 6         │
└───────────────────────────────────────────────────────────────┴──────────┴───────────┘

The "Making your website AI-ready" post is clearly the standout this week with 53 visitors — well ahead of everything else after the homepage.

No dashboard. No login (though obviously access is restricted via bearer token). Just a question and an answer (and a few tokens spent, nothing is perfect).

Architecture

One might argue I overengineered it, to which I would answer: I build tools that aim to be maintainable. So even for a side project, I gave the repo a proper structure and split it into focused packages with clear separation of concerns.

For example, the database layer is intentionally isolated. If I ever swap Bun or the Hono API engine, I won't have to rewrite the entire data layer.

app - the server with two sub-apps: a public API (/events/*, /mcp) for collecting events and providing analytics data, and an internal API available solely within the container (see next chapter)
cli - the admin CLI for token and site management
db - DuckDB instance management, queries, and migrations (yes, I had to write that part too)
schema - shared Zod schemas and types
common - shared utilities (Result, Option, error helpers)
tracker - the JavaScript library for your frontend, published to npm

At the root of the repo there is the traditional zillion of configuration files any project requires nowadays, plus the Dockerfile used to bundle and publish the image to Docker Hub.

Interesting bits

Most of the implementation was straightforward, and I'll be honest, I also used an LLM to help generate repetitive patterns under my supervision, I'm not that much of a caveman. But there were a few challenges and interesting gotchas I thought, or I hope, are worth sharing.

The CLI and the internal API

DuckDB allows only one read-write connection at a time (see documentation). Since the CLI and the server run simultaneously (that's just normal usage), having the CLI open the database directly would cause a file lock error. So I had to figure out a way to work around the limitation.

The solution: don't instantiate the database in the CLI at all. Instead, have it talk to the server, which owns the database exclusively.

yawa-cli → POST /tokens → yawa-app → DuckDB

That raised another question though: exposing CLI endpoints in the API would open private features to the world. Not great.

That's where the idea of having an internal API came in, one that shares the same process as the public API and by extension the same database connection.

I set up a second Hono app that runs on port 9999 but bound to 127.0.0.1 via Bun.serve's hostname option. That way, no external requests can reach it. To make this even more explicit, the docs show a docker-compose.yml that never maps the port, and a Caddy config that never proxies it.

public   → https://yourdomain:3000 → yawa-app (public)   ─┐
                                                          ├→ DuckDB
yawa-cli → http://localhost:9999   → yawa-app (internal) ─┘

Since both run together and the CLI accesses it through plain fetch requests, the locking and coordination problem was solved.

Bun.serve({ port: 3000, fetch: appFetch, hostname: "0.0.0.0" }); // public
Bun.serve({ port: 9999, fetch: internalFetch, hostname: "127.0.0.1" }); // internal only

DB migrations

Unfortunately, neither Drizzle nor Prisma support DuckDB yet. Since the schema will obviously evolve over time, I had to write a small migration runner myself, which you can find here.

The script runs each time the app starts and looks for plain SQL files in a directory, files that create schemas, tables, add new columns, etc.

It then sorts and filters out the files that have already been applied by comparing them against those recorded in the database. To keep track of migrations, I created a table that lists the scripts that were used to terraform it.

It applies the remaining scripts and records them.

Nothing fancy, but it does the job.

Session hashing without cookies

For privacy-friendly visitor counting, I looked at how Umami does it (e.g. source). The approach is to hash a combination of site ID, IP address, user agent, and a daily salt into a deterministic session ID. Same visitor, same day, same session. No cookie required.

The IP address is extracted from the request headers, checking a list of known CDN headers and notably x-forwarded-for included by Caddy), the reverse-proxy I used to expose the API with a custom domain.

The session ID itself is computed like this:

import { CryptoHasher } from "bun";

const hash = ({ input }: { input: string }): { hash: string } => ({
    hash: new CryptoHasher("sha256").update(input).digest("hex")
});

const { hash: salt } = hash({ input: startOfDay(new Date()).toISOString() });

const { hash: sessionHash } = hash({
    input: `${site_id}|${ip}|${user_agent}|${salt}|${sessionSecret}`
});

const sessionId = Bun.randomUUIDv5(sessionHash, "dns");

The salt rotates daily so sessions do not persist across days. The secret (YAWA_SESSION_SECRET) adds an extra layer so the hash cannot be reverse-engineered. If not set, it falls back to random UUIDs, which means less accurate visitor counting, but the app still works. Handy for development.

From an architecture point of view, both the IP and session ID are injected into the request context via middlewares, so route handlers never have to extract them manually, and errors are handled before the handler is ever reached.

For example:

export const extractIpMiddleware = createMiddleware<AnalyticsApiEnv>(async (context, next) => {
    const {
        req: {
            raw: { headers }
        }
    } = context;

    context.set("ip", getIp({ headers }));

    await next();
});

Bun and Docker issue with DuckDB bindings

This one took a while to figure out. DuckDB uses native .node bindings, which causes multiple issues when bundling with Bun and run in Docker. I ended up posting my findings on the issue tracker, but here's the summary.

1. Building locally fails because Bun tries to resolve all platform variants at build time, including Windows bindings not installed on my macOS. The fix is to mark every binding that doesn't match the current platform as external.

2. Using --compile fails at runtime in Docker with libduckdb.so: cannot open shared object file. The native .so simply cannot be embedded in the compiled binary. The only solution was to drop --compile entirely.

3. Only marking platform-specific bindings as external is not enough. @duckdb/node-api and @duckdb/node-bindings themselves must also be external, otherwise the bundled output fails to resolve the native module at runtime.

4. In a monorepo, DuckDB must be a root dependency. If it lives only in a workspace package, Docker won't resolve the bindings correctly.

In other words, I needed a custom build script for Bun:

import os from "node:os";

// Building duckdb with Bun does not work.
// see https://github.com/duckdb/duckdb-node-neo/issues/231

const platform = os.platform();
const arch = os.arch();

// https://github.com/duckdb/duckdb-node-neo#documentation
const duckdbPlatformBindings = [
    "@duckdb/node-bindings-darwin-arm64",
    "@duckdb/node-bindings-darwin-x64",
    "@duckdb/node-bindings-linux-arm64",
    "@duckdb/node-bindings-linux-arm64-musl",
    "@duckdb/node-bindings-linux-x64",
    "@duckdb/node-bindings-linux-x64-musl",
    "@duckdb/node-bindings-win32-arm64",
    "@duckdb/node-bindings-win32-x64"
];

// We need to set all bindings as external and Bun should not use the --compile option.
// Furthermore, the node_modules need to be copied in Docker.
const duckdbBindings = ["@duckdb/node-api", "@duckdb/node-bindings"];

// oven/bun is Debian-based so musl is not needed in Docker and I develop on Mac.
// If its support is needed in the future, e.g. detect-libc could be used to detect it.
const current = `@duckdb/node-bindings-${platform === "win32" ? "win32" : platform === "darwin" ? "darwin" : "linux"}-${arch === "x64" ? "x64" : "arm64"}`;

const platformSpecificExternals = duckdbPlatformBindings.filter((binding) => binding !== current);

await Bun.build({
    entrypoints: ["./src/index.ts"],
    outdir: "./build",
    target: "bun",
    minify: true,
    external: [...duckdbBindings, ...platformSpecificExternals]
});

And the relevant Dockerfile snippet:

...
# build final image
FROM base AS release

# We need to copy native bindings (e.g. DuckDB) from prod node_modules
# otherwise we cannot start the db.
# error: libduckdb.so: cannot open shared object file: No such file or directory
COPY --from=install /temp/prod/node_modules ./node_modules

COPY --from=prerelease /usr/src/app/packages/app/build/index.js ./index.js

...

CMD ["bun", "index.js"]

Handler typing

Hono recommends against Rails-style controllers because extracting handlers into separate functions loses type inference - path params, validated body, and env variables all become untyped Context.

For a project with a few routes this is fine, but yawa has two separate apps (public and internal), each with their own middleware-injected env types. Inlining everything would get messy and, generally speaking, I find it cleaner to have separate controllers. Furthermore, it makes testing easier. So I wanted named, importable handlers.

The trick, found via this Stack Overflow answer, is to type the handler with the input schema shape that zValidator produces:

type JsonInputSchema<T extends z.ZodType> = {
    in: { json: z.input<T> };
    out: { json: z.infer<T> };
};

export type DefineHandler<T extends z.ZodType> = (
    context: Context<Env, string, JsonInputSchema<T>>
) => Promise<Option<Response>>;

Given a schema like:

const CreateSiteRequestSchema = z.object({ hostname: z.string() });

A handler becomes:

export const defineCreateSite: DefineHandler<typeof CreateSiteRequestSchema> = async (context) => {
    const {
        req,
        var: {
            db: { connection }
        }
    } = context;

    const { hostname } = req.valid("json"); // fully typed

    // ...
};

Registered as:

app.post("/sites", zValidator("json", CreateSiteRequestSchema), defineCreateSite);

req.valid("json") is fully typed, the env variables are typed, and the handler is cleanly importable. For handlers with no JSON body, DefineHandler works as a fallback.

As for the variables injected by middlewares, they can be declared by extending the environment.

export type ApiEnv = { Variables: { db: { connection: DbConnection } } };

export type DefineHandler<T extends z.ZodType, Env extends ApiEnv = ApiEnv> = (
    context: Context<Env, string, JsonInputSchema<T>>
) => Promise<Option<Response>>;

The tracker script

My first version of the tracker was only available as an npm package, which made sense for apps using a bundler. But when I started writing the yawa docs with Astro, I realized the idiomatic way to add analytics there was a plain