lossless-monorepo/agent-skills/openpanel-analytics/skill

Adds and verifies OpenPanel analytics on Lossless Astro sites and splash pages, deployed on Vercel, GitHub Pages, or both. Covers the production-only Analytics.astro component, the OPENPANEL_CLIENT_ID variable on each host, the OpenPanel "supported domains" setting whose absence silently 401s every event, and a curl-plus-DevTools verification. Use when adding analytics to a site or splash, when a site deployed to a new host or domain, when OpenPanel shows no data, or when the user mentions OpenPanel, analytics, tracking, traffic, or "is anyone visiting".

Path
agent-skills/openpanel-analytics/SKILL.md

OpenPanel analytics

Most Lossless Astro sites and every splash page should carry OpenPanel. It’s the default analytics for low-traffic sites: one account covers many sites, behavior tracking is richer than a plain page counter, and self-hosting stays an option later. The pattern is the same everywhere, and nearly every failure so far has been configuration, not code.

Contents

  • The component · Environment variable · Per host · OpenPanel dashboard · Verify · Gotchas · Reference

The component

src/components/Analytics.astro, included once in the layout’s <head>. exact: copy it as-is.

---
// Analytics: OpenPanel, production-only.
const isProd = import.meta.env.PROD;
const openPanelClientId = import.meta.env.OPENPANEL_CLIENT_ID;
---

{isProd && openPanelClientId && (
  <>
    <script is:inline define:vars={{ openPanelClientId }}>
      window.op=window.op||function(){var n=[];return new Proxy(function(){arguments.length&&n.push([].slice.call(arguments))},{get:function(t,r){return"q"===r?n:function(){n.push([r].concat([].slice.call(arguments)))}} ,has:function(t,r){return"q"===r}}) }();
      window.op('init', {
        clientId: openPanelClientId,
        trackScreenViews: true,
        trackOutgoingLinks: true,
        trackAttributes: true,
      });
    </script>
    <script is:inline src="https://openpanel.dev/op1.js" defer async></script>
  </>
)}
  • Production-only. pnpm dev and local previews never send events, so they never pollute the dashboard.
  • Inert without a client ID. No variable means no script: a site can ship the component before its OpenPanel client exists.
  • If the site already layers other trackers (Umami, Fathom), keep them in the same component.

Environment variable

  • OPENPANEL_CLIENT_ID is the only value the browser needs. It’s public by design: it appears in the HTML.
  • Never put OPENPANEL_CLIENT_SECRET in a site. Browser tracking doesn’t use it. If a repo holds one as a Secret for a site, it’s unused and can go.
  • Locally: OPENPANEL_CLIENT_ID= in .env.example, with the value only in a gitignored .env.

Per host

One OpenPanel client per site. Name it so it’s findable: splash_<repo> for splashes, the domain for sites.

Host Where the client ID goes Then
GitHub Pages Repo Settings → Secrets and variables → Actions → Variables (not Secrets) → OPENPANEL_CLIENT_ID The workflow’s build step must expose it: env: OPENPANEL_CLIENT_ID: ${{ vars.OPENPANEL_CLIENT_ID }}. Re-run the workflow.
Vercel Project Settings → Environment Variables → OPENPANEL_CLIENT_ID (Production) Redeploy; existing deployments don’t pick it up.
Both Both places, same client ID Add both origins to supported domains (below).

OpenPanel dashboard: supported domains

exact: each client’s supported domains must list every origin the site is served from:

  • GitHub Pages: https://lossless-group.github.io/
  • Vercel: the production domain, e.g. https://<project>.vercel.app
  • Any custom domain

A missing origin makes the API reject every event with 401, while the script loads and runs normally. This is the most common reason a correctly deployed site shows no data. We once lost a night to it across three splashes.

Verify

Copy into your reply and tick:

  • curl -s <site-url> | grep -c 'openpanel.dev/op1.js' returns 1 → 0: the variable didn’t reach the build. Check the host’s variable, the workflow env:, and that you redeployed.
  • The client ID in the HTML matches the dashboard you’re looking at (not a sibling site’s client)
  • In an incognito window with extensions off (uBlock, Brave Shields, and Safari blockers all block OpenPanel), DevTools → Network → api.openpanel.dev/track returns 200 → 401: add the origin to the client’s supported domains; no redeploy needed
  • The visit appears in the OpenPanel dashboard within a minute

Gotchas

  • Don’t pin packageManager in a Vercel site’s package.json. It switches Vercel to a newer pnpm whose build-script gate breaks installs (“Ignored build scripts: esbuild, sharp”).
  • A login-aware header doesn’t hide analytics. The component lives in <head>; anonymous visitors get it.
  • Vercel deployment thumbnails can show 403 from an old protection setting while the site is fine. Not an analytics problem.
  • The custom-domain move: add the new origin to supported domains before switching DNS, or the first days of real traffic vanish.

Reference

  • Rollout history and per-site status: context-v/prompts/Setup-Analytics-Across-Sites.md at the anchor monorepo root.
  • Custom events and deeper tracking: context-v/prompts/Implement-Deeper-Analytics-Tracking.md, same place.
  • Sites already wired (copy from any of them): the splashes of context-vigilance-kit, context-v-corpus, content-farm, lfm, and ai-labs, plus mpstaton-site, twf_site, fullstack-vc, and hypernova-site under astro-knots/sites/.
  • Composes with maintain-splash-pages (every splash gets this) and astro-knots.