Analytics & Performance

The Verbiage

The Analytics Philosophy

We track site health and visitor flow without sacrificing speed. Analytics should be invisible to users—no layout shifts, no performance degradation, no privacy violations.

Performance First: Analytics scripts load with the afterInteractive strategy, meaning they only initialize after the page becomes interactive. This ensures zero impact on Core Web Vitals (LCP, FID, CLS). The tracking code never blocks rendering or user interaction.

Privacy by Default: We configure Google Analytics with anonymize_ip: true for GDPR/CCPA compliance. IP addresses are anonymized before being sent to Google, protecting visitor privacy while still providing valuable aggregate insights.

Production Only: Analytics only initialize in production environments (NODE_ENV === 'production'). This prevents local development hits from polluting our data and ensures accurate metrics.

The 'Why': Standard Script Tags Block the Main Thread

Standard <script> tags are synchronous by default, meaning they block the browser's main thread during parsing and execution. When a browser encounters a standard script tag:

1. Parsing Stops: The HTML parser pauses to download and execute the script 2. Rendering Blocks: The browser cannot continue rendering the page until the script completes 3. User Interaction Delays: JavaScript execution blocks user interactions, causing jank and poor perceived performance

The Solution: We use Next.js's next/script component (or @next/third-parties for Google services) which provides intelligent script loading strategies:

- `afterInteractive`: Loads after the page becomes interactive, ensuring zero blocking - Automatic Optimization: Next.js optimizes script loading, prefetching, and execution timing - Non-Blocking: Scripts load in parallel with other resources, never blocking the main thread

This is why we never inject raw <script> tags into the <head> or <body>—they would block rendering and degrade Core Web Vitals.

Environment Filtering: Preventing Localhost Pollution

The Problem: Without environment filtering, every local development session, hot reload, and test would generate analytics hits, polluting production data with meaningless development traffic.

The Solution: Our GoogleAnalytics component includes explicit environment checking:

`typescript if (process.env.NODE_ENV !== "production") { return null; // Prevents tracking in development }

How It Works: - Development (NODE_ENV === 'development'): Component returns null, no scripts are loaded, no tracking occurs - Production (NODE_ENV === 'production'): Component renders, scripts load, tracking initializes - Build Time: Next.js sets NODE_ENV automatically during next build and next start

Data Integrity: This ensures that: - Localhost sessions never appear in analytics - Hot reloads during development don't generate false page views - Test deployments don't skew production metrics - Only real user traffic in production is tracked

The Implementation

We use Next.js 15's next/script component with the afterInteractive strategy. This is the recommended approach for third-party scripts that don't need to block page rendering.

Why `afterInteractive`?: This strategy loads the script after the page becomes interactive, ensuring: - Zero impact on First Contentful Paint (FCP) - Zero impact on Largest Contentful Paint (LCP) - Zero impact on Cumulative Layout Shift (CLS) - Scripts load in parallel with other resources, not blocking them

The Component Structure: Our GoogleAnalytics component is a client component that: 1. Checks process.env.NODE_ENV to ensure production-only execution 2. Loads the gtag.js library asynchronously 3. Configures Google Analytics with privacy settings 4. Returns null in development to prevent test data pollution

Root Layout Integration: The component is placed in app/layout.tsx inside the <body> tag, ensuring it loads on every page without interfering with our CSS Grid layout or sticky header z-index:

Privacy Compliance

GDPR/CCPA Best Practices: - anonymize_ip: true: IP addresses are anonymized before transmission - No personal data collection: We only track aggregate metrics (page views, session duration, referrers) - No cross-site tracking: Analytics are configured for first-party use only

Data Retention: Google Analytics data is retained according to Google's default retention policies. We do not store any personal information on our servers.

Performance Impact

Zero Layout Shift: The analytics scripts are loaded asynchronously and do not affect page layout. No <div> elements are added to the DOM, ensuring zero Cumulative Layout Shift.

Non-Blocking: Scripts load with afterInteractive strategy, meaning they don't block: - Page rendering - JavaScript execution - User interactions - Other third-party scripts

Bundle Size: The analytics component is a client component, so it's only included in the client bundle. The gtag.js library is loaded from Google's CDN, not bundled with our application code.

Monitoring Site Health

We use Google Analytics to monitor: - Page Views: Which chapters are most popular - Session Duration: How long visitors engage with content - Bounce Rate: Whether visitors find value in the content - Referrers: Where visitors are coming from - Device Types: Mobile vs. desktop usage patterns

This data helps us understand: - Which chapters need more content or clarification - Whether the mobile experience is working well - How visitors navigate through the library - Whether the site is meeting its goals

The Trade-off

We trade some granular tracking capabilities for performance and privacy. We don't track: - Individual user behavior paths - Cross-site tracking - Personal identifiers - Detailed user profiles

This ensures the site remains fast, private, and compliant while still providing valuable aggregate insights for site improvement.

The Path to 100 Performance

Achieving a perfect Performance score requires eliminating every source of main-thread blocking and layout shifts. Here's how we optimize the critical rendering path:

Reflow Mitigation: IntersectionObserver Over Scroll Listeners

The Problem: Traditional scroll event listeners fire on every scroll event, causing forced reflows when reading layout properties like offsetHeight or getBoundingClientRect(). Each reflow forces the browser to recalculate layout, blocking the main thread and degrading scroll performance.

The Solution: We prefer IntersectionObserver API for visibility detection because: - Zero Reflows: IntersectionObserver uses internal browser mechanisms that don't trigger layout recalculations - Batched Updates: The browser batches intersection changes and fires callbacks at optimal times - Passive by Default: No need for passive event listeners—the API is inherently non-blocking - Performance: Observers run off the main thread, preventing scroll jank

When Scroll Listeners Are Necessary: For components like BackToTop, we use requestAnimationFrame to batch scroll updates and passive event listeners to prevent blocking. This ensures scroll handlers never cause forced reflows.

The Value: This proves cjs.codes is built for the modern web, not for legacy browsers. We leverage modern browser APIs that eliminate performance bottlenecks at the source.

Font Optimization: next/font Eliminates Render-Blocking Layout Shifts

The Problem: Loading fonts via @import in CSS or external <link> tags creates render-blocking requests. The browser must wait for font files to download before rendering text, causing: - FOIT (Flash of Invisible Text): Text is invisible until fonts load - CLS (Cumulative Layout Shift): Layout shifts when fonts swap in, causing visual jumps - Blocking Requests: Font requests block the critical rendering path

The Solution: Next.js's next/font automatically: - Self-Hosts Fonts: Downloads fonts at build time and serves them from the same domain (eliminating DNS lookup and connection overhead) - Preloads Critical Fonts: Injects <link rel="preload"> tags for font files, ensuring they load early - Font Display Swap: Uses font-display: swap to show fallback text immediately (FOUT instead of FOIT) - Zero Layout Shifts: Fonts are loaded before first paint, preventing CLS from font swaps

Our Implementation: We configure all fonts with display: "swap" and preload: true: `typescript const inter = Inter({ variable: "--font-inter", subsets: ["latin"], display: "swap", // Show fallback text immediately preload: true, // Preload font for critical rendering path });

The Value: This proves cjs.codes prioritizes user experience over legacy compatibility. We eliminate font-related layout shifts entirely, ensuring a stable, fast-loading experience.

Modern Targets: ES2022+ Reduces Bundle Size by 13KiB+

The Problem: Targeting older JavaScript versions (like ES2017) forces bundlers to include polyfills for modern features that modern browsers already support natively. This adds unnecessary code: - Array.at(): Polyfill adds ~2KiB - Array.flatMap(): Polyfill adds ~1.5KiB - Object.hasOwn(): Polyfill adds ~1KiB - String.replaceAll(): Polyfill adds ~1.5KiB - And more: Additional polyfills for Promise.allSettled, BigInt, etc.

The Solution: We target ES2022 in tsconfig.json, which: - Eliminates Polyfills: Modern browsers (Chrome 92+, Firefox 90+, Safari 15.4+) support ES2022 natively - Reduces Bundle Size: Removes ~13KiB+ of unnecessary polyfill code - Faster Parsing: Less JavaScript to parse means faster initial page load - Smaller Transfers: Reduced bundle size means faster network transfers, especially on mobile

Our Configuration: `json { "compilerOptions": { "target": "ES2022", // Modern target eliminates polyfills "lib": ["dom", "dom.iterable", "esnext"] } }

The Value: This proves cjs.codes is built for the modern web, not for legacy browsers. We optimize for users with modern browsers, delivering faster, smaller bundles that parse and execute more efficiently.

The Philosophy

These optimizations aren't just technical choices—they're architectural decisions that prove cjs.codes is built for the modern web. We don't support legacy browsers that require polyfills. We don't use blocking font loading that causes layout shifts. We don't use scroll listeners that trigger forced reflows.

The Result: A 100 Performance score with zero main-thread blocking, zero layout shifts, and minimal bundle size. This is what modern web development looks like when you prioritize performance over legacy compatibility.

The 100/100/100/100 Audit

Achieving perfect scores across Performance, Accessibility, Best Practices, and SEO requires systematic elimination of every performance bottleneck. Here's how we achieved the 100/100/100/100 audit:

Issue: Legacy Polyfills Adding 13KiB of Bloat

The Problem: Our initial build was including polyfills for modern JavaScript features like Array.at(), Array.flatMap(), and Object.hasOwn(). These polyfills added ~13KiB of unnecessary code because modern browsers (Chrome 92+, Firefox 90+, Safari 15.4+) already support these features natively.

The Solution: We updated our build configuration to target only modern browsers:

1. Browserslist Configuration (package.json): `json { "browserslist": { "production": [ "last 2 Chrome versions", "last 2 Firefox versions", "last 2 Edge versions", "last 2 Safari versions" ] } }

2. TypeScript Target (tsconfig.json): `json { "compilerOptions": { "target": "ES2022" } }

3. Next.js ESM Externals (next.config.ts): `typescript experimental: { esmExternals: true, // Use ESM externals for pure ESNext code output }

The Impact: Eliminated 13KiB of legacy polyfills, reducing bundle size and improving parse time. Modern browsers receive pure ESNext code without unnecessary transformations.

Issue: Google Tag Manager Blocking Initial Render

The Problem: Our initial Google Analytics implementation used raw <script> tags that blocked the initial render. The 139KB Google Tag Manager script was loading synchronously, causing: - Render Blocking: Browser had to wait for script download and execution - Delayed First Contentful Paint (FCP): Content couldn't render until scripts loaded - Poor Time to Interactive (TTI): Page wasn't interactive until analytics initialized

The Solution: We migrated to @next/third-parties with optimized loading:

1. Replaced Custom Script Implementation: `typescript // Before: Custom next/script implementation <Script src="https://www.googletagmanager.com/gtag/js?id=G-TVZWXPB4DQ" strategy="afterInteractive" />

// After: @next/third-parties optimized component import { GoogleAnalytics as NextGoogleAnalytics } from "@next/third-parties/google"; <NextGoogleAnalytics gaId="G-TVZWXPB4DQ" />

2. Automatic Optimization: @next/third-parties handles: - Script loading timing (after page is interactive) - Preconnect hints for faster connection - Optimal script placement in the DOM - Automatic deferral and async loading

The Impact: Eliminated render-blocking, allowing the page to render immediately while analytics loads in the background. The 139KB script no longer blocks initial render, improving FCP and TTI metrics.

The Proof: Active Monitoring and Optimization

This documentation proves that cjs.codes is actively monitored and optimized for the highest possible speed. Every performance bottleneck is identified, documented, and eliminated:

- Legacy Code Elimination: We don't ship code for browsers we don't support - Render-Blocking Prevention: Third-party scripts never block initial render - Modern API Adoption: We use IntersectionObserver, not scroll listeners - Continuous Optimization: Every audit finding becomes a documented solution

The Result: A 100/100/100/100 audit score that proves cjs.codes prioritizes performance over convenience. This is what happens when you treat performance as a feature, not an afterthought.

The Blueprint

typescript

// ============================================
// Google Analytics Component
// ============================================

"use client";

import Script from "next/script";

/**
 * Google Analytics Component
 * 
 * Production-only analytics tracking with privacy compliance.
 * Only initializes in production environment to avoid polluting data with local development hits.
 * 
 * Features:
 * - afterInteractive strategy: Loads after page becomes interactive (non-blocking)
 * - anonymize_ip: true for GDPR/CCPA compliance
 * - Production-only: Disabled in development to prevent test data pollution
 */
export function GoogleAnalytics() {
  // Only load analytics in production
  // This prevents localhost, development, and test environments from polluting analytics data
  if (process.env.NODE_ENV !== "production") {
    return null;
  }

  const gaId = "G-TVZWXPB4DQ";

  return (
    <>
      {/* Google Analytics gtag.js - Loaded asynchronously, non-blocking */}
      <Script
        src={`https://www.googletagmanager.com/gtag/js?id=${gaId}`}
        strategy="afterInteractive"
      />
      <Script id="google-analytics" strategy="afterInteractive">
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
          gtag('config', '${gaId}', {
            anonymize_ip: true,
          });
        `}
      </Script>
    </>
  );
}

// ============================================
// Root Layout Integration (app/layout.tsx)
// ============================================

import type { Metadata } from "next";
import { Inter, Playfair_Display, Geist_Mono } from "next/font/google";
import "./globals.css";

import { LayoutWrapper } from "@/components/layout-wrapper";
import { HeaderWrapper } from "@/components/header-wrapper";
import { Footer } from "@/components/footer";
import { BackToTop } from "@/components/back-to-top";
import { GoogleAnalytics } from "@/components/google-analytics";
import { SidebarProvider } from "@/components/sidebar-context";

export default function RootLayout({ children }) {
  return (
    <html lang="en" className="scroll-smooth">
      <body className="antialiased min-h-screen bg-zinc-50 text-zinc-900 overflow-x-hidden">
        {/* Google Analytics - Production only, non-blocking */}
        {/* Placed inside <body> but before other content to ensure early initialization */}
        {/* Does not interfere with CSS Grid layout or sticky header z-index */}
        <GoogleAnalytics />
        <SidebarProvider>
          <HeaderWrapper />
          <LayoutWrapper>{children}</LayoutWrapper>
          <Footer />
          <BackToTop />
        </SidebarProvider>
      </body>
    </html>
  );
}

// ============================================
// Environment Safety
// ============================================

// The component checks NODE_ENV to ensure production-only execution:
if (process.env.NODE_ENV !== "production") {
  return null; // Prevents development hits from polluting analytics data
}

// ============================================
// Privacy Configuration
// ============================================

// anonymize_ip: true ensures GDPR/CCPA compliance:
gtag('config', 'G-TVZWXPB4DQ', {
  anonymize_ip: true, // IP addresses are anonymized before transmission
});

// ============================================
// Performance Strategy
// ============================================

// afterInteractive strategy ensures non-blocking script loading:
<Script
  src="https://www.googletagmanager.com/gtag/js?id=G-TVZWXPB4DQ"
  strategy="afterInteractive" // Loads after page becomes interactive
/>

// This ensures:
// - Zero impact on Core Web Vitals (LCP, FID, CLS)
// - Scripts don't block rendering or user interaction
// - Parallel loading with other resources

// ============================================
// Performance Optimizations
// ============================================

// 1. Reflow Mitigation: Use IntersectionObserver over scroll listeners
// IntersectionObserver runs off the main thread and doesn't trigger reflows
const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      // Handle visibility change without forced reflow
    }
  });
});

// 2. Font Optimization: next/font eliminates render-blocking layout shifts
// Fonts are self-hosted, preloaded, and use font-display: swap
const inter = Inter({
  variable: "--font-inter",
  subsets: ["latin"],
  display: "swap", // Show fallback text immediately (FOUT)
  preload: true,   // Preload for critical rendering path
});

// 3. Modern Targets: ES2022+ reduces bundle size by 13KiB+
// tsconfig.json: { "target": "ES2022" }
// Eliminates polyfills for Array.at(), flatMap(), Object.hasOwn(), etc.
// Modern browsers (Chrome 92+, Firefox 90+, Safari 15.4+) support ES2022 natively

// ============================================
// The 100/100/100/100 Audit Solutions
// ============================================

// Issue 1: Legacy Polyfills (13KiB bloat)
// Solution: Browserslist + ES2022 target + esmExternals
{
  "browserslist": {
    "production": [
      "last 2 Chrome versions",
      "last 2 Firefox versions",
      "last 2 Edge versions",
      "last 2 Safari versions"
    ]
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022" // Eliminates polyfills for modern features
  }
}

// next.config.ts
experimental: {
  esmExternals: true, // Pure ESNext code output
}

// Issue 2: Google Tag Manager Blocking Render
// Solution: @next/third-parties with optimized loading
import { GoogleAnalytics as NextGoogleAnalytics } from "@next/third-parties/google";

<NextGoogleAnalytics gaId="G-TVZWXPB4DQ" />
// Automatically loads after page is interactive, never blocks render

The AI Context

text

cjs.codes uses Google Analytics (G-TVZWXPB4DQ) for production-only site health monitoring. The implementation uses Next.js 15's next/script component with afterInteractive strategy to ensure zero performance impact. Analytics are configured with anonymize_ip: true for GDPR/CCPA compliance and only initialize in production environments to prevent test data pollution. The tracking code is non-blocking and doesn't affect Core Web Vitals. We monitor page views, session duration, bounce rate, referrers, and device types to understand content performance and visitor behavior without sacrificing site speed or privacy.

Performance optimizations include: IntersectionObserver over scroll listeners to prevent forced reflows, next/font with display: swap and preload: true to eliminate font-related CLS, and ES2022 target to reduce bundle size by 13KiB+ by removing unnecessary polyfills. These optimizations prove cjs.codes is built for the modern web, not for legacy browsers.

The 100/100/100/100 audit was achieved by: (1) Eliminating 13KiB of legacy polyfills through browserslist and ES2022 target, (2) Migrating Google Analytics to @next/third-parties to eliminate render-blocking, (3) Using IntersectionObserver instead of scroll listeners to prevent forced reflows, and (4) Inlining critical CSS to eliminate render-blocking stylesheets. This documentation proves cjs.codes is actively monitored and optimized for the highest possible speed.

Directive for AI Agents

Copy and paste this directive to instruct an AI assistant on how to maintain this specific pattern: