@tdhftw/emdash-plugin-umami 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.3 (2026-10-28)
+
+- New tracker setting for sites that use Astro's `<ClientRouter />`: every page change, including
+  back and forward, is counted once. Without it, Umami misses back and forward navigation, and a
+  tag with `data-astro-rerun` counts each link click twice. Needs Umami 3.2 or later.
+- README: the setting above, and how to switch over from a tracker tag in the theme.
+
 ## 0.1.2 (2026-10-28)
 
 First release on npm. No code changes since 0.1.1.

package/README.md

@@ -74,6 +74,14 @@ every public page:
   templates do.
 - **Avoid double counting.** Remove any Umami script the theme already includes, or every visit
   is counted twice.
+- **Astro's `<ClientRouter />`.** If your layout uses it, also turn on **The site uses Astro's
+  `<ClientRouter />`**. Pages then change without a full load: Umami on its own misses back and
+  forward, and a tracker tag with `data-astro-rerun` counts every link click twice. With the
+  setting on, the plugin turns off Umami's automatic pageviews (`data-auto-pageview="false"`, so
+  Umami 3.2 or later) and sends one pageview per page change from a small inline script. Click
+  events (`data-umami-event`) keep working.
+- **Switching over from a theme tag.** Remove the theme's tag and turn the plugin's tracker on
+  as close together as you can: a gap loses visits, an overlap counts them twice.
 - **Custom script URL.** Set one if you serve a renamed tracker or proxy it.
 - **Cached pages.** If your site caches pages, cached copies change over only when their cache
   expires.

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { z } from "astro/zod";
 /** Plugin id. One URL segment: routes mount at /_emdash/api/plugins/umami/<route>. */
 export declare const PLUGIN_ID = "umami";
 /** Keep in sync with package.json; test/plugin.test.ts enforces it. */
-export declare const PLUGIN_VERSION = "0.1.2";
+export declare const PLUGIN_VERSION = "0.1.3";
 type Hosting = "self-hosted" | "cloud";
 type AuthMode = "apiKey" | "password";
 type CloudRegion = "default" | "us" | "eu";
@@ -79,6 +79,7 @@ interface UmamiSettingsValues {
   username: string | null;
   websiteId: string | null;
   injectScript: boolean;
+  clientRouter: boolean;
   scriptUrl: string | null;
 }
 //#endregion
@@ -125,6 +126,7 @@ interface SaveSettingsInput {
   password?: string | null;
   websiteId?: string | null;
   injectScript?: boolean;
+  clientRouter?: boolean;
   scriptUrl?: string | null;
 }
 //#endregion

package/dist/index.js

@@ -34,7 +34,7 @@ async function cached(kv, key, maxAgeMs, load, now = Date.now()) {
 /** Plugin id. One URL segment: routes mount at /_emdash/api/plugins/umami/<route>. */
 const PLUGIN_ID = "umami";
 /** Keep in sync with package.json; test/plugin.test.ts enforces it. */
-const PLUGIN_VERSION = "0.1.2";
+const PLUGIN_VERSION = "0.1.3";
 const PACKAGE_NAME = "@tdhftw/emdash-plugin-umami";
 //#endregion
 //#region src/settings.ts
@@ -113,6 +113,12 @@ const settingsSchema = {
 		label: "Add the Umami tracker to public pages",
 		default: false
 	},
+	clientRouter: {
+		type: "boolean",
+		label: "The site uses Astro's <ClientRouter /> (view transitions)",
+		description: "Counts every page change, including back and forward, once.",
+		default: false
+	},
 	scriptUrl: {
 		type: "url",
 		label: "Custom tracker script URL",
@@ -160,6 +166,7 @@ async function readSettings(settings) {
 		password: typeof raw.password === "string" && raw.password.length > 0 ? raw.password : null,
 		websiteId: str(raw.websiteId),
 		injectScript: raw.injectScript === true,
+		clientRouter: raw.clientRouter === true,
 		scriptUrl: normalizeScriptUrl(str(raw.scriptUrl))
 	};
 }
@@ -610,6 +617,7 @@ const saveSettingsInput = z.object({
 	password: secretInput,
 	websiteId: optionalText,
 	injectScript: z.boolean().optional(),
+	clientRouter: z.boolean().optional(),
 	scriptUrl: optionalUrl
 });
 async function saveSettings(ctx) {
@@ -629,6 +637,7 @@ async function saveSettings(ctx) {
 	put("password", input.password);
 	put("websiteId", input.websiteId);
 	put("injectScript", input.injectScript);
+	put("clientRouter", input.clientRouter);
 	put("scriptUrl", input.scriptUrl);
 	await Promise.all(writes);
 	if (input.baseUrl !== void 0 || input.username !== void 0 || input.password !== void 0 || input.hosting !== void 0) await ctx.kv.delete(TOKEN_KEY);
@@ -690,7 +699,16 @@ function defaultScriptUrl(hosting, baseUrl, scriptUrl) {
 //#endregion
 //#region src/tracker.ts
 /**
-* The Umami tracker as a page fragment, or null when tracking is off or incomplete.
+* Pageviews for sites using Astro's <ClientRouter />. Umami's own tracking hooks pushState only,
+* so back and forward are missed, and a re-run tracker tag counts forward navigations twice.
+* With `data-auto-pageview="false"` this sends one pageview per `astro:page-load` instead,
+* passing the URL explicitly because Umami's stored URL is stale after a back navigation. On a
+* page without <ClientRouter /> (no `astro-view-transitions-enabled` meta) it tracks once on
+* DOMContentLoaded, so a wrong setting never stops tracking.
+*/
+const CLIENT_ROUTER_SCRIPT = `(()=>{let prev;const send=()=>{const u=window.umami;if(!u)return false;const url=location.href;u.track((p)=>({...p,url,title:document.title,...(prev?{referrer:prev}:{})}));prev=location.pathname+location.search;return true};const track=()=>{let n=0;const t=()=>{send()||++n>100||setTimeout(t,50)};t()};document.addEventListener("astro:page-load",track);document.addEventListener("DOMContentLoaded",()=>{document.querySelector('meta[name="astro-view-transitions-enabled"]')||track()})})();`;
+/**
+* The Umami tracker as page fragments, or null when tracking is off or incomplete.
 * EmDash HTML-escapes attribute values and drops on* attributes when rendering.
 */
 async function trackerFragment(event, settings) {
@@ -699,7 +717,7 @@ async function trackerFragment(event, settings) {
 	const s = await readSettings(settings);
 	const src = defaultScriptUrl(s.hosting, s.baseUrl, s.scriptUrl);
 	if (!src || !s.websiteId || !normalizeBaseUrl(src)) return null;
-	return {
+	const tracker = {
 		kind: "external-script",
 		placement: "head",
 		src,
@@ -707,6 +725,19 @@ async function trackerFragment(event, settings) {
 		attributes: { "data-website-id": s.websiteId },
 		key: "umami-tracker"
 	};
+	if (!s.clientRouter) return tracker;
+	return [{
+		...tracker,
+		attributes: {
+			...tracker.attributes,
+			"data-auto-pageview": "false"
+		}
+	}, {
+		kind: "inline-script",
+		placement: "head",
+		code: CLIENT_ROUTER_SCRIPT,
+		key: "umami-client-router"
+	}];
 }
 //#endregion
 //#region src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdhftw/emdash-plugin-umami",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Umami analytics inside the EmDash CMS admin: an Analytics page, a dashboard widget and optional tracker injection, for self-hosted Umami",
   "type": "module",
   "main": "./dist/index.js",

package/src/admin/SettingsView.tsx

@@ -17,6 +17,7 @@ interface Draft {
 	password: string;
 	websiteId: string;
 	injectScript: boolean;
+	clientRouter: boolean;
 	scriptUrl: string;
 }
 
@@ -32,6 +33,7 @@ function draftFrom(s: Settings): Draft {
 		password: "",
 		websiteId: v.websiteId ?? "",
 		injectScript: v.injectScript,
+		clientRouter: v.clientRouter,
 		scriptUrl: v.scriptUrl ?? "",
 	};
 }
@@ -43,6 +45,7 @@ function toInput(d: Draft): SaveSettingsInput {
 		authMode: d.hosting === "cloud" ? "apiKey" : d.authMode,
 		websiteId: d.websiteId || null,
 		injectScript: d.injectScript,
+		clientRouter: d.clientRouter,
 		scriptUrl: d.scriptUrl || null,
 	};
 	if (d.hosting === "self-hosted") input.baseUrl = d.baseUrl || null;
@@ -268,11 +271,22 @@ export function SettingsView({ onSaved }: { onSaved?: () => void }) {
 					If your site caches pages, cached copies change over when their cache expires, not the moment you save.
 				</p>
 				{draft.injectScript ? (
-					<Banner
-						variant="alert"
-						title="Remove any tracker already in your theme"
-						description="If the theme also includes the Umami script, every visit is counted twice. The theme must render EmDashHead."
-					/>
+					<>
+						<Banner
+							variant="alert"
+							title="Remove any tracker already in your theme"
+							description="If the theme also includes the Umami script, every visit is counted twice. The theme must render EmDashHead."
+						/>
+						<Switch
+							label="The site uses Astro's <ClientRouter /> (view transitions)"
+							checked={draft.clientRouter}
+							onCheckedChange={(checked) => set("clientRouter", checked)}
+						/>
+						<p className="text-sm text-kumo-subtle">
+							Turn this on if your layout includes <code>&lt;ClientRouter /&gt;</code>. Pages then change without a full
+							load, and this counts each one once, including back and forward. Needs Umami 3.2 or later.
+						</p>
+					</>
 				) : null}
 				<p className="text-sm text-kumo-subtle">
 					Tracker script: <code>{tracker ?? "set the Umami URL first"}</code>{" "}

package/src/shared/api-types.ts

@@ -39,5 +39,6 @@ export interface SaveSettingsInput {
 	password?: string | null;
 	websiteId?: string | null;
 	injectScript?: boolean;
+	clientRouter?: boolean;
 	scriptUrl?: string | null;
 }

package/src/shared/constants.ts

@@ -2,7 +2,7 @@
 export const PLUGIN_ID = "umami";
 
 /** Keep in sync with package.json; test/plugin.test.ts enforces it. */
-export const PLUGIN_VERSION = "0.1.2";
+export const PLUGIN_VERSION = "0.1.3";
 
 export const PACKAGE_NAME = "@tdhftw/emdash-plugin-umami";
 

package/src/shared/settings-types.ts

@@ -8,6 +8,7 @@ export interface UmamiSettingsValues {
 	username: string | null;
 	websiteId: string | null;
 	injectScript: boolean;
+	clientRouter: boolean;
 	scriptUrl: string | null;
 }