Analytics: Serve the Umami tracker first-party so adblockers stop hiding our traffic

gitstrata.com loaded the tracker straight from a third-party analytics domain at the well-known `/script.js` path — both on adblock blocklists, so most visitors went uncounted. A Cloudflare Pages Function now proxies it same-origin under `/u/*`, matching the first-party setup on the other sites.

- Add `functions/u/[[path]].ts`: proxies `/u/mami` → upstream `/script.js` and passes the beacon (`/u/api/send`) plus everything else straight through. Forwards the real visitor IP via `x-forwarded-for` so Umami still counts uniques; caches the script briefly, never the beacon. Upstream host defaults to our Umami instance, overridable with the `ANALYTICS_UPSTREAM` Pages env var for self-hosters.
- `+layout.svelte`: load the tracker from same-origin `/u/mami` (was `{PUBLIC_ANALYTICS_URL}/script.js`). The tracker derives its beacon endpoint from its own script directory, so it posts to `/u/api/send`.
- Gate the tag on `PUBLIC_ANALYTICS_ID` alone; the upstream URL now lives in the Function, so drop `PUBLIC_ANALYTICS_URL` from the frontend and the CI build env.
- Docs: add `functions/CLAUDE.md`; update architecture, deploying, AGENTS, and `.env.example`.
- Ignore the local `.wrangler/` dir that `wrangler pages dev` creates.

Author: vdavid

.env.example

@@ -6,6 +6,7 @@ PUBLIC_CORS_PROXY_URL=https://cors.isomorphic-git.org
 # Shared results cache — set to your CORS proxy URL after enabling R2 (see docs/deploying.md step 3).
 # PUBLIC_SHARED_CACHE_URL=https://your-proxy.workers.dev
 
-# Optional Umami analytics. Both are required to enable tracking.
-# PUBLIC_ANALYTICS_URL=https://umami.yourdomain.com
+# Optional Umami analytics. Set the website ID to enable tracking. The tracker loads first-party
+# through the Pages Function at /u/* (see functions/CLAUDE.md); point that at your Umami host with
+# the ANALYTICS_UPSTREAM environment variable on the Pages project, not here.
 # PUBLIC_ANALYTICS_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

.github/workflows/ci.yml

@@ -28,6 +28,7 @@ jobs:
                       frontend:
                         - 'src/**'
                         - 'static/**'
+                        - 'functions/**'
                         - 'package.json'
                         - 'pnpm-lock.yaml'
                         - 'svelte.config.js'
@@ -153,7 +154,6 @@ jobs:
               env:
                   PUBLIC_CORS_PROXY_URL: https://proxy.gitstrata.com
                   PUBLIC_CACHE_WRITE_TOKEN: 1938d93de2ba8ed03f53069e4216a9ddd90af40b692a4d016b46ec28ecf3f19e
-                  PUBLIC_ANALYTICS_URL: https://anal.veszelovszki.com
                   PUBLIC_ANALYTICS_ID: 9c082669-20f5-486f-85b8-13911ded8e14
 
             - run: npx wrangler pages deploy build/ --project-name=git-strata

.gitignore

@@ -10,6 +10,7 @@ scripts/loc-counter/
 coverage/
 *.log
 .DS_Store
+.wrangler/
 cors-proxy/.wrangler/
 cors-proxy/.dev.vars
 _ignored/

AGENTS.md

@@ -27,6 +27,8 @@ Core structure:
     - `lib/types.ts` - Shared type definitions
     - `app.css` - Tailwind v4 import + CSS custom properties
 - `cors-proxy/` - Cloudflare Worker (Hono) — adds CORS headers, forwards bytes, zero compute
+- `functions/` - Cloudflare Pages Functions (same-origin as the frontend). `u/[[path]]` proxies the Umami tracker
+  first-party (`/u/*`) so adblockers don't strip it. See `functions/CLAUDE.md`.
 - `scripts/` - Go-based check runner (`scripts/check/`) and reference LoC counter (read-only)
 - `static/` - Static assets
 - `tests/` - Unit tests (Vitest) and end-to-end tests (Playwright)

docs/architecture.md

@@ -34,6 +34,14 @@ Details: [`cors-proxy/CLAUDE.md`](../cors-proxy/CLAUDE.md)
 | Ref caching              | Caches v1 `/info/refs` responses at the edge (12 h TTL)                         |
 | Shared results cache     | Optional R2-backed cache for analysis results (`GET`/`PUT /cache/v1/:repoHash`) |
 
+## Pages Functions (`functions/`)
+
+Details: [`functions/CLAUDE.md`](../functions/CLAUDE.md)
+
+| Component    | Purpose                                                                                                   |
+| ------------ | --------------------------------------------------------------------------------------------------------- |
+| `u/[[path]]` | Same-origin proxy for the Umami tracker (`/u/mami` → `/script.js`, beacon → `/api/send`) to dodge adblock |
+
 ## Tooling
 
 | Directory  | Purpose                                                                                                     |

docs/deploying.md

@@ -134,22 +134,25 @@ Once these are set, every push to `main` that passes CI will auto-deploy both th
 
 ## Environment variables
 
-| Variable                   | Where                        | Default                           | Purpose                                                         |
-| -------------------------- | ---------------------------- | --------------------------------- | --------------------------------------------------------------- |
-| `PUBLIC_CORS_PROXY_URL`    | Frontend (`.env`)            | `https://cors.isomorphic-git.org` | URL of your deployed CORS proxy                                 |
-| `PUBLIC_SHARED_CACHE_URL`  | Frontend (`.env`)            | _(none)_                          | URL of shared cache API (same as CORS proxy when R2 is enabled) |
-| `PUBLIC_CACHE_WRITE_TOKEN` | Frontend (`.env` / `ci.yml`) | _(none)_                          | Bearer token for cache writes (must match worker secret below)  |
-| `ALLOWED_ORIGIN`           | Worker (`wrangler.toml`)     | `https://gitstrata.com`           | CORS origin restriction — override in `.dev.vars` for local dev |
-| `CACHE_WRITE_TOKEN`        | Worker secret / `.dev.vars`  | _(none)_                          | Server-side token that cache PUT requests are checked against   |
-| `PUBLIC_ANALYTICS_URL`     | Frontend (`.env`)            | _(none)_                          | Umami server URL (for example, `https://umami.yourdomain.com`)  |
-| `PUBLIC_ANALYTICS_ID`      | Frontend (`.env`)            | _(none)_                          | Umami website ID (UUID from your Umami dashboard)               |
+| Variable                   | Where                        | Default                           | Purpose                                                                                    |
+| -------------------------- | ---------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------ |
+| `PUBLIC_CORS_PROXY_URL`    | Frontend (`.env`)            | `https://cors.isomorphic-git.org` | URL of your deployed CORS proxy                                                            |
+| `PUBLIC_SHARED_CACHE_URL`  | Frontend (`.env`)            | _(none)_                          | URL of shared cache API (same as CORS proxy when R2 is enabled)                            |
+| `PUBLIC_CACHE_WRITE_TOKEN` | Frontend (`.env` / `ci.yml`) | _(none)_                          | Bearer token for cache writes (must match worker secret below)                             |
+| `ALLOWED_ORIGIN`           | Worker (`wrangler.toml`)     | `https://gitstrata.com`           | CORS origin restriction — override in `.dev.vars` for local dev                            |
+| `CACHE_WRITE_TOKEN`        | Worker secret / `.dev.vars`  | _(none)_                          | Server-side token that cache PUT requests are checked against                              |
+| `PUBLIC_ANALYTICS_ID`      | Frontend (`.env`)            | _(none)_                          | Umami website ID (UUID from your Umami dashboard) — set to enable tracking                 |
+| `ANALYTICS_UPSTREAM`       | Pages Function (runtime var) | git strata's Umami instance       | Your Umami server URL that `/u/*` proxies to (for example, `https://umami.yourdomain.com`) |
 
 `PUBLIC_CACHE_WRITE_TOKEN` and `CACHE_WRITE_TOKEN` must have the same value. The frontend token is hard-coded in
 `ci.yml` for production builds. The worker token is set via `wrangler secret put` (production) or `cors-proxy/.dev.vars`
 (local dev).
 
-Both `PUBLIC_ANALYTICS_URL` and `PUBLIC_ANALYTICS_ID` must be set to enable analytics. When either is missing, no
-tracking script is loaded.
+Set `PUBLIC_ANALYTICS_ID` to enable analytics. When it's missing, no tracking script is loaded. The tracker loads
+first-party from the Pages Function at `/u/*` (see `functions/CLAUDE.md`) so adblockers don't strip it — this dodges the
+third-party analytics domain and the well-known `/script.js` filename, both on adblock blocklists. Set
+`ANALYTICS_UPSTREAM` on the Pages project (Cloudflare dashboard > **Settings > Environment variables**) to point `/u/*`
+at your own Umami host.
 
 Frontend variables are set at build time in CI (see the `deploy-frontend` job in `ci.yml`). For local development,
 create a `.env` file in the repo root:
@@ -159,7 +162,6 @@ PUBLIC_CORS_PROXY_URL=https://your-proxy.workers.dev
 # PUBLIC_SHARED_CACHE_URL=https://your-proxy.workers.dev
 PUBLIC_CACHE_WRITE_TOKEN=your-token-here
 # PUBLIC_ANALYTICS_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-# PUBLIC_ANALYTICS_URL=https://umami.yourdomain.com
 ```
 
 For local proxy dev, create `cors-proxy/.dev.vars`:

functions/CLAUDE.md

@@ -0,0 +1,24 @@
+# Pages Functions
+
+Cloudflare Pages Functions that run alongside the static frontend on the same origin (gitstrata.com). Wrangler discovers
+this `functions/` directory at deploy time (`wrangler pages deploy build/`, run from the repo root) and compiles it into
+a Worker that fronts the static assets. Routes not matched by a function fall through to the static site.
+
+## Analytics proxy (`u/[[path]].ts`)
+
+Same-origin proxy for the Umami analytics tracker, matching `/u/*`.
+
+- **Why it exists**: Loading the tracker directly from a third-party analytics domain at the well-known `/script.js`
+  path gets it blocked by adblockers on both counts, so most visitors go uncounted. Serving it first-party under `/u/*`
+  sidesteps the blocklists.
+- **Path mapping**: `/u/mami` → upstream `/script.js` (the only path Umami serves the tracker at). Everything else maps
+  straight through, notably the beacon: the tracker derives its collect endpoint from its own script directory, so with
+  `src="/u/mami"` it posts to `/u/api/send`, which proxies to upstream `/api/send`. The `data-website-id` on the script
+  tag (`src/routes/+layout.svelte`) is what ties events to the right site.
+- **Upstream host**: defaults to git strata's own Umami instance. Self-hosters override it with the `ANALYTICS_UPSTREAM`
+  environment variable on the Pages project (Cloudflare dashboard > Settings > Environment variables, or a Pages
+  `wrangler.toml` `[vars]`).
+- **Caching**: the tracker script gets `Cache-Control: public, max-age=3600`; the beacon (and any other path) gets
+  `no-store`.
+- **Client IP**: the real visitor IP (`cf-connecting-ip`) is forwarded as `x-forwarded-for` so Umami counts uniques
+  correctly instead of attributing every hit to the proxy.

functions/u/[[path]].ts

@@ -0,0 +1,51 @@
+// Same-origin proxy for the Umami analytics tracker.
+//
+// Loading the tracker first-party under `/u/*` keeps it off adblock blocklists, which flag both
+// third-party analytics domains and the well-known `/script.js` filename — a directly-loaded
+// tracker gets blocked and most visitors go uncounted. `/u/mami` maps to the analytics host's
+// `/script.js` (the only path Umami serves the tracker at); the tracker derives its beacon
+// endpoint from its own directory, so it posts to `/u/api/send`, which maps straight through to
+// the host's `/api/send`.
+//
+// The upstream host defaults to git strata's own Umami instance; self-hosters override it with the
+// `ANALYTICS_UPSTREAM` environment variable on the Pages project (see docs/deploying.md).
+
+interface Env {
+    ANALYTICS_UPSTREAM?: string
+}
+
+const defaultUpstream = 'https://anal.veszelovszki.com'
+
+export const onRequest = async (context: { request: Request; env: Env }): Promise<Response> => {
+    const upstream = (context.env.ANALYTICS_UPSTREAM ?? defaultUpstream).replace(/\/+$/, '')
+    const requestUrl = new URL(context.request.url)
+    const subPath = requestUrl.pathname.replace(/^\/u\//, '')
+    const upstreamPath = subPath === 'mami' ? 'script.js' : subPath
+    const targetUrl = `${upstream}/${upstreamPath}${requestUrl.search}`
+
+    const headers = new Headers(context.request.headers)
+    headers.delete('host')
+    const clientIp = context.request.headers.get('cf-connecting-ip')
+    if (clientIp) {
+        // Preserve the real visitor IP so Umami counts uniques correctly instead of seeing the proxy.
+        headers.set('x-forwarded-for', clientIp)
+    }
+
+    const method = context.request.method
+    const hasBody = method !== 'GET' && method !== 'HEAD'
+    const upstreamResponse = await fetch(targetUrl, {
+        method,
+        headers,
+        body: hasBody ? await context.request.arrayBuffer() : undefined,
+    })
+
+    const responseHeaders = new Headers(upstreamResponse.headers)
+    // The tracker script is safe to cache briefly; the beacon must never be cached.
+    responseHeaders.set('cache-control', upstreamPath === 'script.js' ? 'public, max-age=3600' : 'no-store')
+
+    return new Response(upstreamResponse.body, {
+        status: upstreamResponse.status,
+        statusText: upstreamResponse.statusText,
+        headers: responseHeaders,
+    })
+}

src/routes/+layout.svelte

@@ -10,12 +10,11 @@
     let { children } = $props()
 
     const analyticsId = env.PUBLIC_ANALYTICS_ID
-    const analyticsUrl = env.PUBLIC_ANALYTICS_URL
 </script>
 
 <svelte:head>
-    {#if analyticsId && analyticsUrl}
-        <script defer data-website-id={analyticsId} src="{analyticsUrl}/script.js"></script>
+    {#if analyticsId}
+        <script defer data-website-id={analyticsId} src="/u/mami"></script>
     {/if}
 </svelte:head>