Skip to content

casoon/astro-webvitals

BranchesTags

Repository files navigation

@casoon/astro-webvitals

npm version License: MIT

A comprehensive Web Vitals & SEO monitoring component for Astro with debug overlay and analytics support.

This component was extracted from the astro-v5-template to be available as a standalone package.

Features

Core Web Vitals Tracking

  • LCP (Largest Contentful Paint) - Loading performance
  • FID (First Input Delay) - Input responsiveness with auto-measurement
  • CLS (Cumulative Layout Shift) - Visual stability
  • FCP (First Contentful Paint) - Initial render
  • TTFB (Time to First Byte) - Server response
  • INP (Interaction to Next Paint) - Overall responsiveness
  • Navigation Timing: DNS, TCP, DOM, LOAD

Debug Overlay

  • Radial gauge visualization with performance score (0-100)
  • Expandable interface with tabbed organization:
    • Core Vitals: All metrics with visual progress bars and descriptions
    • SEO: Title, description, canonical, robots, Open Graph, Twitter Cards, Structured Data (JSON-LD) validation
    • Accessibility: WCAG issue summary with expandable details and quick wins
    • Details: Session info, memory usage, network status
    • Console: Browser console output viewer
  • Responsive mobile design (< 700px):
    • Full-width footer bar that slides up
    • 60vh max height for better mobile viewing
    • Auto-switches on viewport resize
  • Desktop floating box with customizable position
  • Color-coded indicators (Good, Needs Improvement, Poor)
  • Close button to dismiss overlay

SEO Insights

  • Title and meta description analysis with length validation
  • Canonical URL and robots meta detection
  • X-Robots-Tag header check
  • Indexability status badge
  • Open Graph and Twitter Card validation
  • Structured Data (JSON-LD) parsing with warnings
  • Heading outline with H1 count check
  • Images: alt text and dimension checks
  • Copyable SEO report for bug tickets

Analytics Ready

  • Send metrics to your analytics endpoint
  • JSON payload with all metric data
  • Batch reporting to reduce requests
  • Configurable sampling rate

Accessibility Monitoring

  • Automatic WCAG 2.1 checking
  • Detects missing alt texts, labels, heading issues
  • Expandable issue details with element info
  • Learn more links to web.dev documentation
  • Optional on-page highlighting for issues

Console Viewer

  • Displays browser console output (log, info, warn, error)
  • Scrollable message history (last 200 entries)
  • Color-coded log levels
  • Dockable bottom console with draggable height
  • Custom logging API: webVitalsLog.info(), .warn(), .error()

Installation

npm install @casoon/astro-webvitals
pnpm add @casoon/astro-webvitals
yarn add @casoon/astro-webvitals

Usage

Basic Usage

Add the component to your Astro layout or page:

---
import { WebVitals } from '@casoon/astro-webvitals';
---

<!DOCTYPE html>
<html>
  <head>
    <title>My Site</title>
  </head>
  <body>
    <!-- Your content -->
    
    <WebVitals />
  </body>
</html>

Debug Mode

Enable the debug overlay to see metrics in real-time during development:

<WebVitals debug={true} />

Or only in development:

<WebVitals debug={import.meta.env.DEV} />

Custom Position

Choose where the debug overlay appears (desktop only):

<WebVitals 
  debug={true} 
  position="bottom-left" 
/>

Available positions: top-right, top-left, bottom-right, bottom-left

WCAG Highlighting

Highlight elements with WCAG issues directly on the page:

<WebVitals 
  debug={true}
  checkAccessibility={true}
  highlightAccessibility={true}
/>

Console Logging & Dock

Console output is captured automatically and shown in the Console tab. Use the helper for custom messages:

webVitalsLog.info('Info message');
webVitalsLog.warn('Warning message');  
webVitalsLog.error('Error message');

Open a docked console at the bottom of the page:

<WebVitals debug={true} consoleDock={true} />

Analytics Integration

Send metrics to your analytics endpoint:

<WebVitals 
  endpoint="/api/analytics/vitals"
  sampleRate={0.1}
  batchReporting={true}
/>

The component will send POST requests with this payload:

{
  name: string;        // Metric name (LCP, FID, etc.)
  value: number;       // Metric value
  url: string;         // Page URL
  timestamp: number;   // Unix timestamp
  userAgent: string;   // Browser user agent
}

Example Analytics Endpoint

Create src/pages/api/analytics/vitals.ts:

import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  const metric = await request.json();
  
  // Store in your database, send to analytics service, etc.
  console.log('Web Vital:', metric);
  
  return new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' }
  });
};

Production Setup

---
import { WebVitals } from '@casoon/astro-webvitals';
const isDev = import.meta.env.DEV;
---

<!-- Debug overlay in development, analytics in production -->
<WebVitals 
  debug={isDev}
  endpoint={isDev ? undefined : '/api/analytics/vitals'}
  sampleRate={0.1}
/>

Props

Prop Type Default Description
debug boolean false Show debug overlay with metrics
consoleDock boolean false Show dockable console at bottom
endpoint string undefined URL to send metrics to (POST)
position 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' 'bottom-right' Position of debug overlay
trackInDev boolean false Track metrics in development
sampleRate number 1 Percentage of users to track (0-1)
batchReporting boolean true Batch metrics before sending
batchInterval number 5000 Batch interval in milliseconds
checkAccessibility boolean true (when debug) Enable WCAG checking
highlightAccessibility boolean false Highlight elements with WCAG issues
extendedMetrics boolean false Track memory and network metrics
smartDetection boolean false Detect rage/dead clicks
performanceBudget object Default thresholds Custom performance thresholds
headers object {} Custom headers for endpoint requests
sessionId string Auto-generated Session ID for tracking
userId string undefined User ID for tracking

Metrics Thresholds

Metric Good Needs Improvement Poor
LCP < 2.5s 2.5s - 4s > 4s
FID < 100ms 100ms - 300ms > 300ms
CLS < 0.1 0.1 - 0.25 > 0.25
FCP < 1.8s 1.8s - 3s > 3s
TTFB < 800ms 800ms - 1.8s > 1.8s
INP < 200ms 200ms - 500ms > 500ms

Browser Support

Uses the Performance API supported in all modern browsers:

  • Chrome/Edge 77+ (full support)
  • Firefox 89+ (full support)
  • Safari 14+ (limited support)

Safari Limitations

Safari (WebKit) does not support all Web Vitals metrics. The following metrics are not available in Safari:

Metric Safari Support
LCP ❌ Not supported
FID ❌ Not supported
INP ❌ Not supported
CLS ✅ Supported
FCP ✅ Supported
TTFB ✅ Supported

The debug overlay automatically detects browser limitations and displays a warning when metrics are unavailable. For complete Web Vitals measurement, use a Chromium-based browser (Chrome, Edge, Brave, Arc).

Development

# Clone the repository
git clone https://github.com/casoon/astro-webvitals.git
cd astro-webvitals

# Install dependencies
pnpm install

# Type check
pnpm run type-check

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

MIT © CASOON

Related Projects

Support

If you find this package useful, please consider:

  • Starring the repository
  • Reporting bugs
  • Suggesting new features
  • Improving documentation

About

Track Core Web Vitals & accessibility issues in your Astro site - lightweight, privacy-first, production-ready

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

12 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases

4 tags

Packages

 
 
 

Contributors

Languages