ReviewOS

stacks/paweldregan

Wire up @stacksjs/ts-analytics

#10
Open glennmichael123 opened this 8 days ago ·
8 days ago

Context

paweldregan.com is now deployed and the SEO/contrast layer just landed (#5, #6). Next step from the broader rollout plan: get our own analytics on it via @stacksjs/ts-analytics.

This is the first deployment of ts-analytics on a real public site, so it doubles as the reference impl that the cross-site rollout (stx docs, bunpress docs, ts-images docs, barista docs, …) will copy from.

Scope

  • Add @stacksjs/ts-analytics to dependencies in package.json
  • Initialize the tracker in layouts/default.stx (single load point — every page extends this layout, no per-page wiring needed)
  • Configure via site.config.ts if ts-analytics has a config surface there (preferred), otherwise minimal inline config
  • Respect the existing dark/light theme + i18n behavior (no flash, no analytics call before the active locale is settled)
  • SPA awareness: stx does view transitions on <main> — make sure pageview events fire on stx:navigate, not just initial DOMContentLoaded
  • Verify in bun run build output that the tracker script lands once per page (no duplication from layout + components)

Acceptance

  • One pageview event per route load (initial + each SPA navigation)
  • No console errors in light or dark mode
  • No layout shift / flash from the analytics script
  • Works in en, de, pl
  • Documented in repo README briefly so the next site that adopts ts-analytics can copy the integration
  • Reference impl for the cross-repo rollout tracker (separate issue on stacksjs/ts-analytics)
8 days ago

Triage finding (2026-05-08): `@stacksjs/analytics` (the actual package name; this repo is `stacksjs/ts-analytics`) is server-side / DynamoDB-backed — there's no browser-loaded tracker snippet to drop into `layouts/default.stx` today. Confirmed by reading the README + checking the package exports map (single `./dist/index.js`, no browser entry, no UMD bundle).

Wiring it up requires:

  1. Backend infrastructure — DynamoDB table + ingestion endpoint (Lambda + API Gateway, or a Stacks API route).
  2. Client-side tracker snippet — doesn't exist in `ts-analytics` yet. Would need to be written (hashes visitor + session, POSTs pageview to the ingestion endpoint, hooks `stx:navigate` for SPA pageviews).
  3. Provisioning — table + endpoint deployed in our AWS account before any consumer can use it.

This is the same architectural fork in the road as #11 (subscription) — both require either:

  • A serverless backend alongside the static stx site, OR
  • Converting paweldregan from static stx to a deployed Stacks app.

Suggest pairing this issue with #11 for the decision — once we pick the architecture for #11, #10 falls out of it almost for free (analytics middleware would already be wired by the Stacks app, or the same Lambda surface that handles subscription would handle pageview ingestion).

Cross-cuts to ts-analytics#42 (cross-site rollout): until `@stacksjs/analytics` ships a browser-side tracker (or this issue produces one and contributes it back), the cross-site rollout to bunpress/stx/ts-images/barista docs has the same blocker.

Sign in to comment on this issue.