SEO and Analytics

Configure search/share metadata at build time, then optionally load one third-party analytics provider. StarryBio publishes a static site: no analytics setting is secret, and no provider receives a server-side event stream from StarryBio.

Search and sharing metadata

seo: {
  title: 'Morgan Lee — Design and writing',
  description: 'Projects, notes, and ways to get in touch.',
  image: '/og.png',
  canonicalUrl: 'https://links.example.com',
  themeColor: '#6ee7b7',
},

Field	When to set it	Fallback
title	Use a concise public site title.	pageTitle
description	Describe the page for search/share previews.	profile.description
image	Use a public image for Open Graph and Twitter cards.	No image metadata
canonicalUrl	Set the final HTTPS URL after connecting your domain.	No canonical URL metadata
themeColor	Set browser UI color when relevant.	Current theme accent

The page emits title, description, theme-color, Open Graph, and Twitter metadata. A configured canonicalUrl adds canonical/Open Graph URL metadata; a configured image adds Open Graph image metadata and uses the summary_large_image Twitter card.

An HTTP(S) seo.image is used as-is. A root-relative or local image becomes an absolute sharing URL only when canonicalUrl is configured. Set both before asking a social platform to refresh a preview. Assets and Generated Downloads explains the matching ogImage generator.

Choose an analytics provider

The default is no analytics:

analytics: { provider: 'none' },

StarryBio supports exactly one configured provider at a time: cloudflare, google, plausible, umami, or custom. It emits the provider’s external script in the document head; it does not create a private analytics backend, a consent banner, or link-click events of its own.

Provider	Choose it when	Observability	Privacy and operating trade-off
Cloudflare Web Analytics	You are already deploying StarryBio on Cloudflare and want the simplest default recommendation.	Privacy-first real-user monitoring, traffic dimensions, page-load timing, and Core Web Vitals.	Cloudflare says it does not collect or use visitor personal data. It has no custom events or UTM/query-string tracking, and long-range reporting is aggregated/sampled.
Plausible	You want a deliberately simple, privacy-first traffic dashboard.	Aggregate traffic, referrers, pages, devices, countries, plus provider-side goals/extensions where configured.	Plausible states it uses no cookies, persistent identifiers, or cross-site tracking; visitor analytics data is processed in the EU. It is a paid/hosted service unless you choose its separate self-hosted offering.
Umami	You want privacy-first analytics with optional self-hosting and a path to richer product/performance analysis.	Core traffic reports, custom events, goals/funnels, performance monitoring, and other platform features.	Umami says its normal tracker uses no cookies, fingerprinting, or personal data; self-hosting keeps analytics data on your infrastructure. Optional replay/heatmap capabilities deserve separate privacy review.
Google Analytics 4	A GA4 property, Google reporting workflows, or Google marketing measurement is an explicit requirement.	Broad Google Analytics reporting and a mature measurement ecosystem. StarryBio itself only installs the tag and page-view behavior; it does not add custom link-click events.	GA4 uses a first-party _ga cookie by default and collects user/session, approximate location, browser, and device information. Plan disclosures and consent before enabling it.
Custom HTTPS script	Your provider is not listed or you need supported data-* attributes not available in a built-in shape.	Entirely provider-specific.	You must verify the script, collection endpoint, CSP, and privacy posture yourself.

These are practical recommendations, not legal advice. Provider privacy claims and local legal requirements can change; decide what to collect, review the provider’s current terms, and obtain any notice/consent your situation requires before deploying.

Quick recommendation

1. Choose none if you do not have a concrete use for metrics.
2. Choose Cloudflare Web Analytics for a low-friction StarryBio deployment that needs page and real-user performance insight without individual tracking.
3. Choose Plausible for a simple, privacy-first traffic dashboard, especially when EU processing and no-cookie operation are important.
4. Choose Umami when data ownership, self-hosting, custom events, or richer operational insight outweigh the added platform administration.
5. Choose GA4 only when its Google ecosystem/reporting value justifies its greater privacy and consent obligations.

Before enabling any provider

1. Set seo.canonicalUrl to the final HTTPS hostname. Register the same hostname with the provider.
2. Use only one StarryBio analytics provider. Do not paste the vendor’s whole snippet into a component or add a second dashboard-managed snippet; duplicate scripts can double-count visits.
3. Treat IDs and browser tokens as public identifiers. Never put Cloudflare API tokens, Google credentials, API keys, passwords, or private customer data in analytics.
4. Run pnpm headers, deploy a preview, then check the browser Console and Network panel. A successful build proves configuration validity, not successful external collection.
5. Review Security and Privacy, including the CSP guidance, before publishing.

Cloudflare Web Analytics

Best fit: Most StarryBio operators who want privacy-first traffic and performance data while already using Cloudflare.

Cloudflare Web Analytics is real-user monitoring (RUM): its beacon uses browser performance APIs for page-load and Core Web Vitals information. Cloudflare documents page, referrer, browser, device, country, and path dimensions, and states that the product does not collect or use visitors’ personal data. Its current FAQ also says it does not support custom events or UTM/query-string tracking, so it is not the choice for detailed campaign attribution or bespoke conversion events. See Cloudflare’s overview, metrics, and FAQ.

Set it up

1. In the Cloudflare dashboard, open Web Analytics and select Add a site.

2. Enter the final site hostname, such as links.example.com.

3. Open Manage site and use Enable with JS Snippet installation for this StarryBio integration. If Cloudflare’s automatic setup is enabled for a proxied site, turn off automatic injection first; StarryBio will install the beacon so only one copy runs.

4. Copy the token from Cloudflare’s supplied beacon snippet. Do not paste the whole snippet into an Astro component.

5. Set that token in config/starrybio.config.ts:

   analytics: {
     provider: 'cloudflare',
     token: 'your-site-token',
   },

6. Run pnpm build, deploy, then visit the canonical site. Cloudflare says data can take a few minutes to appear.

StarryBio emits the Cloudflare beacon from https://static.cloudflareinsights.com/beacon.min.js and passes the token in data-cf-beacon. Run pnpm headers after enabling it to generate the required script and collection origins.

For a Cloudflare-proxied site, the beacon can send to your own /cdn-cgi/rum endpoint; for a non-proxied site, Cloudflare documents cloudflareinsights.com/cdn-cgi/rum. The existing policy covers both through 'self' and the Cloudflare insights origin. Verify the beacon request in browser developer tools if data does not arrive.

Google Analytics 4

Best fit: An organization that already uses GA4 reports or other Google measurement workflows and has addressed its privacy/consent obligations.

Google documents that the default website implementation stores a client ID in the first-party _ga cookie and collects user/session statistics, approximate geography, browser, and device information. Google also says site operators need to inform users and provide a way to grant or deny consent where applicable. Read Google’s GA4 setup guide, data collection guide, and privacy controls overview before enabling it.

Set it up

1. Sign in at Google Analytics and create or select a GA4 account.

2. In Admin, create a GA4 property. Review its reporting timezone, currency, data-sharing settings, and any advertising-related choices.

3. In the property, open Data streams > Add stream > Web. Enter the canonical site URL and finish creating the web stream.

4. Open that stream and copy its Measurement ID—the value beginning with G-. StarryBio needs this ID, not the complete manual gtag.js code block.

5. Configure StarryBio:

   analytics: {
     provider: 'google',
     measurementId: 'G-XXXXXXXXXX',
     sendPageView: true,
   },

6. Build and deploy. Open the GA4 Realtime report after visiting your production site; Google notes that new collection can take up to 30 minutes to appear.

measurementId must match G- followed by uppercase letters/numbers. sendPageView defaults to true; set it to false only if you are deliberately managing page views in a custom implementation. The optional config object accepts only string, number, or boolean GA configuration values. scriptSrc is optional and should normally be omitted so StarryBio uses the standard Google Tag URL.

StarryBio initializes Google’s gtag once and sends later client-router page views when enabled. It does not instrument individual profile link clicks, copy buttons, downloads, or custom conversion events. Adding those requires source changes described in Architecture and Customization.

Run pnpm headers after enabling Google Analytics or changing scriptSrc. A custom script that uses a non-Google collection origin needs a source-level analytics extension before it can be allowlisted narrowly.

Plausible Analytics

Best fit: A privacy-first traffic dashboard with an uncomplicated operating model.

Plausible describes its service as no-cookie, no-personal-data, no-persistent-identifier, and no-cross-site-tracking analytics; its compliance documentation says visitor analytics data is processed and stored in the EU. Use the provider’s documentation, tracking-script guide, and compliance overview to assess the current product and plan.

Set it up with the current per-site script

1. Create or sign in to Plausible, open Sites, and choose Add a website.

2. Register the same canonical hostname that StarryBio deploys, for example links.example.com.

3. On the site’s Settings page, find General > Site Installation and select Review Installation.

4. Copy the src URL from Plausible’s site-specific snippet. For a current installation it resembles https://plausible.io/js/pa-XXXXXXXX.js.

5. Put that exact URL into StarryBio:

   analytics: {
     provider: 'plausible',
     scriptSrc: 'https://plausible.io/js/pa-XXXXXXXX.js',
   },

6. Build, deploy, and use Plausible’s installation verification tool from the site settings before trusting the dashboard.

Run pnpm headers after configuring Plausible. Do not add a second copy of Plausible’s snippet.

Existing legacy installation

Existing sites using Plausible’s generic script plus a domain attribute can retain the supported legacy form:

analytics: {
  provider: 'plausible',
  domain: 'links.example.com',
},

At least one of scriptSrc or domain is required. Prefer the exact current per-site scriptSrc for a new site.

Plausible can provide provider-side goals and enhanced measurements, but the stock StarryBio plausible shape only supplies the script URL and, for legacy installs, the domain. It does not add custom event markup or arbitrary Plausible attributes. If Plausible’s documented snippet requires supported extra data-* attributes, use the carefully reviewed custom configuration below or extend StarryBio—never paste a duplicate vendor snippet.

Umami

Best fit: Privacy-first analytics where self-hosting/data ownership or a path to richer custom-event and performance analysis matters.

Umami describes itself as open source, no-cookie/no-fingerprinting analytics with Cloud and self-hosted deployment options. Its platform supports traffic metrics, custom events, goals/funnels, performance monitoring, and optional session replay/heatmaps. The last two are materially more sensitive than aggregate traffic analysis; enabling them is a separate product/privacy decision and is not configured by stock StarryBio. Consult Umami’s overview, website setup guide, and tracker documentation.

Set up Umami Cloud

1. Sign in to Umami Cloud, open Websites, and choose Add website.

2. Enter a display name and the exact canonical domain, then save it.

3. Edit the new website and open its Tracking code section. Copy the Website ID.

4. Configure the Cloud tracker in StarryBio:

   analytics: {
     provider: 'umami',
     websiteId: 'your-umami-website-id',
     scriptSrc: 'https://cloud.umami.is/script.js',
   },

5. Run pnpm headers. It adds cloud.umami.is for the tracker and gateway.umami.is for Umami Cloud collection without broadening the CSP.

6. Run pnpm preview to confirm no CSP violation, deploy, then visit the production page and check the Umami dashboard. Umami recommends inspecting browser Network requests if data does not appear; ad blockers can block the tracker.

Set up a self-hosted Umami instance

Create the website in your own Umami administration UI, copy its Website ID, and point scriptSrc at the HTTPS tracker script served by that instance:

analytics: {
  provider: 'umami',
  websiteId: 'your-umami-website-id',
  scriptSrc: 'https://analytics.example.com/script.js',
},

Run pnpm headers, then build and preview. A self-hosted instance whose collection endpoint differs from the script origin needs a source-level analytics extension before it can be allowlisted narrowly.

Use supported advanced Umami attributes

The built-in umami provider deliberately accepts only websiteId and scriptSrc. For supported tracker attributes such as data-performance, data-exclude-search, or data-domains, use custom so StarryBio emits the required data-* attributes:

analytics: {
  provider: 'custom',
  scriptSrc: 'https://cloud.umami.is/script.js',
  dataAttributes: {
    'website-id': 'your-umami-website-id',
    performance: 'true',
    'exclude-search': 'true',
  },
},

Attribute keys omit the data- prefix because StarryBio adds it. They must be lowercase and contain only letters, numbers, and hyphens; values must be strings. Run pnpm headers after configuration changes. Verify every optional tracker behavior against Umami’s current tracker-configuration reference.

Custom HTTPS analytics script

Use custom only when the provider cannot be represented by a built-in shape or when the provider’s documented, non-secret snippet needs additional safe data-* attributes:

analytics: {
  provider: 'custom',
  scriptSrc: 'https://analytics.example.com/script.js',
  dataAttributes: {
    site: 'links-example',
    environment: 'production',
  },
},

StarryBio loads the script with defer and renders data-site/data-environment. Do not include data- in the key itself. The reserved keys starrybio-provider, measurement-id, send-page-view, and config are rejected.

Before enabling a custom provider:

1. Read the provider’s official install, privacy, and CSP/network documentation.
2. Confirm the script URL is HTTPS and contains no credential or account-administration secret.
3. Run pnpm headers to generate the script and same-origin collection permissions.
4. Deploy a preview and inspect successful script and collection requests in the browser Network panel.
5. Do not use a custom provider to work around a vendor snippet that needs inline JavaScript; StarryBio intentionally keeps analytics initialization out of inline script blocks.

Content Security Policy and verification

pnpm headers scopes the generated CSP to the selected provider and writes matching Cloudflare/Netlify and Vercel policies. pnpm validate rejects stale generated headers.

After any analytics change:

1. Run pnpm headers, pnpm validate, and pnpm build.
2. Run pnpm preview and inspect Console/CSP errors plus Network requests.
3. Deploy to the canonical hostname, not only a temporary workers.dev URL.
4. Use the provider’s own verification/realtime workflow: Cloudflare dashboard after a few minutes, GA4 Realtime (allowing up to 30 minutes for initial data), Plausible Site Installation verification, or the Umami dashboard/network check.
5. Confirm only one analytics script is present in page source and that no unsupported external origin was broadly allowlisted.

For broader data exposure, cookie, and public-configuration guidance, see Security and Privacy. For CSP failures, see Troubleshooting.