tinytrack-cloudflare-worker

TinyTrack analytics worker for Cloudflare based deployments.

A transparent proxy that counts pageviews server-side, auto-injects the TinyTrack script, and serves the tracker and beacons first-party.

Install

Cloudflare clones this repo and sets up the worker.

Setup:

1. Set your website id.
   1. Go to: Workers & Pages
   2. Open: tinytrack-cloudflare-worker -> Settings -> Variables: set TINYTRACK_WEBSITE_ID (TinyTrack Settings → Tracking)
2. Route it over your site: Domains → Add Route, e.g. example.com/* (see Cloudflare configuration).

You can reduce the number of requests to your worker by excluding assets, see Reducing Worker invocations.

Install (manual)

Prerequisites:

• Requires a Cloudflare account with your site's DNS proxied
• Node.js 18+
• TinyTrack website ID

1. Setup

git clone https://github.com/tinytrack-io/cloudflare-worker
cd tinytrack-cloudflare-worker
npm install
npx wrangler login

2. Add tinytrack websiteId secret

npx wrangler secret put TINYTRACK_WEBSITE_ID

3. Deploy

npm run deploy

4. Cloudflare configuration

Workers & Pages → tinytrack-cloudflare-worker → Domains → Add Route, e.g. example.com/*, covering the whole site.

Use Worker Routes, not Custom Domains: a Custom Domain replaces your origin and breaks the proxy.

Reducing Worker invocations

A example.com/* route sends every request through the worker, including assets it just passes through. The worker only needs to see HTML document requests and /_tinytrack/*. To stop paying invocations for the rest, add routes with the Worker set to None for your high-volume static prefixes:

To add exclusions:

1. Go to Cloudflare -> Domains
2. Go to your domain example.com
3. Go to Workers routes
4. Add routes you want to exclude with Add Route
5. Worker should be None

Route patterns match path prefixes only (no file extensions) and a route without a Worker negates broader patterns, see the Workers routes docs.

Example exclusions:

• example.com/_app/immutable/* (SvelteKit)
• example.com/_next/static/* (Next.js)
• example.com/assets/*
• example.com/static/*
• example.com/images/*
• example.com/api/*

Route patterns cannot match file extensions (*.jpg is invalid), only path prefixes.

Configuration

| Var | Default | Notes | |---|---|---| | TINYTRACK_WEBSITE_ID | (none) | Required. Public by design. | | TINYTRACK_DOMAIN | request hostname minus www. | Set explicitly when your route spans multiple subdomains, or sessions split. | | INJECT_SCRIPT | "true" | "false" = server-side pageviews only. | | TINYTRACK_PATH_PREFIX | /_tinytrack | First-party paths the worker serves itself. | | TINYTRACK_DEBUG | "false" | "true" = step-by-step debug logs for HTML document requests. |

Only TINYTRACK_WEBSITE_ID is declared in wrangler.jsonc, so it is the only field shown on the one-click deploy setup page. The optional vars fall back to the defaults above; to override one, add it in Workers & Pages → Settings → Variables (kept across deploys, the config sets keep_vars) or to the vars block in wrangler.jsonc.

What gets tracked

• Server-side: one page_view per HTML request (any status). Static assets, /api/-style paths, prefetches, and non-GET requests are skipped.
• Client-side: SPA navigations, outbound clicks, goals, scroll depth, session pings, custom events. The injected script skips the initial pageview, so there is no double counting.
• Bots are recorded for crawler/AI analytics

Troubleshooting

• npx wrangler tail shows live logs; pageview failures log as [TinyTrack] pageview tracking failed.
• No data? Check the route covers the page and TINYTRACK_WEBSITE_ID is set.
• Client events missing? Check the browser console for /_tinytrack/tracker.js (usually CSP or a leftover manual snippet).

Uninstall

Remove the Worker Route and your site instantly serves direct from origin. Then npx wrangler delete when done. Roll back a bad deploy from Workers & Pages → Deployments → Rollback.