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 devand 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_IDis the only value the browser needs. It’s public by design: it appears in the HTML.- Never put
OPENPANEL_CLIENT_SECRETin 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 workflowenv:, 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/trackreturns 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
packageManagerin a Vercel site’spackage.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.mdat 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, andai-labs, plusmpstaton-site,twf_site,fullstack-vc, andhypernova-siteunderastro-knots/sites/. - Composes with
maintain-splash-pages(every splash gets this) andastro-knots.