Cloudflare Web Analytics

Cloudflare Web Analytics provides privacy-first tracking for the lukemcdonald.com website. It captures Real User Monitoring (RUM) data to help analyze site performance and visitor behavior without utilizing intrusive tracking cookies.

The system integrates with the Astro-based frontend and relies on Netlify environment variables for configuration. To prevent blocking by browser extensions, the project proxies analytics scripts and data ingestion through first-party paths.

Sources: README.md:10-14, src/configs/analytics.ts:2-7

Architecture and Proxying

The project uses a first-party proxy strategy to load the Cloudflare beacon script and send RUM data. This approach avoids direct calls to Cloudflare domains, which are often flagged by ad-blockers.

Proxy Configuration

The system defines internal paths that map to Cloudflare's official endpoints via Netlify _redirects.

Sources: src/configs/analytics.ts:2-7, src/configs/analytics.test.ts:18-34

Request Flow

The following diagram illustrates how the browser interacts with the local proxy to reach Cloudflare services.

The browser requests the analytics script and sends tracking data through the site's own domain to ensure delivery and privacy.

Sources: src/configs/analytics.ts:2-7, src/configs/analytics.test.ts:18-34

Implementation Details

The implementation consists of static configuration constants and a helper function to generate the beacon configuration object required by the Cloudflare script.

Configuration Helpers

The getCloudflareBeaconConfig function takes a site token and returns a configuration object. This object instructs the Cloudflare beacon to send its data to the internal proxied path rather than the default Cloudflare URL.

export function getCloudflareBeaconConfig(token: string) {
  return {
    send: { to: CLOUDFLARE_WEB_ANALYTICS.rumPath },
    token,
  }
}

Sources: src/configs/analytics.ts:9-14

Environment Variables

The system requires a CLOUDFLARE_ANALYTICS_TOKEN to function. This token is retrieved from the Cloudflare dashboard under Analytics & Logs > Web Analytics. You must set this as a Netlify environment variable.

The analytics beacon only loads when the Netlify CONTEXT environment variable is set to production.

Sources: README.md:12-14

Validation and Testing

The project includes unit tests to verify that the analytics configuration correctly maps to the expected proxy paths defined in the public/_redirects file.

• getCloudflareBeaconConfig test: Ensures the configuration object contains the correct site token and the RUM destination path.
• CLOUDFLARE_WEB_ANALYTICS test: Matches the exported constants against the regex patterns found in the Netlify redirects file to prevent configuration drift.

Sources: src/configs/analytics.test.ts:10-36

Summary

Cloudflare Web Analytics is implemented as a proxied, privacy-respecting monitoring solution. By routing requests through /cf-insights.js and /cf-insights, the site maintains high data integrity while adhering to first-party data collection standards. Configuration is managed through Netlify environment variables and strictly scoped to production environments.

Sources: README.md:12-14, src/configs/analytics.ts:2-14