DEV Community: Jordan Hudgens

Stop Your React App From Shifting: A Deep Dive into useCLS from @page-speed/hooks

Jordan Hudgens — Sat, 11 Apr 2026 05:16:45 +0000

A complete developer tutorial on measuring, diagnosing, and eliminating Cumulative Layout Shift in React applications using the open-source @page-speed/hooks library.

What Is Cumulative Layout Shift — And Why Should You Care?

You've been there. You land on a webpage, spot a link you want to click, move your finger toward it — and suddenly the page shifts. You tap a completely different element. Maybe you accidentally clicked an ad, submitted a form early, or worse, hit "Buy Now" on the wrong item.

That frustrating experience has a name: Cumulative Layout Shift (CLS). It's a Core Web Vital defined by Google that measures the visual stability of your page by quantifying how much content unexpectedly moves during the lifetime of a page visit.

Where:

Impact Fraction is the fraction of the viewport affected by the shift
Distance Fraction is the maximum distance any element moved divided by the viewport's largest dimension

The CLS metric is not the sum of all layout shifts — it's the maximum score of any single session window: a burst of layout shifts with less than 1 second between individual shifts and a maximum duration of 5 seconds. This 2021 redesign of CLS was introduced specifically to be fairer to long-lived pages and SPAs.

The Thresholds That Matter

Rating	CLS Score
✅ Good	≤ 0.1
⚠️ Needs Improvement	0.1 – 0.25
❌ Poor	> 0.25

Google requires that at least 75% of page visits score "good" before a site can be considered performant. And this matters — poor CLS directly affects SEO rankings, drives up bounce rates, destroys conversion rates, and creates terrible experiences for users on slow connections or mobile devices.

Why React Apps Are CLS Hotspots

React's component-based, JavaScript-driven rendering model creates several natural CLS risk vectors that server-rendered HTML does not have:

Lazy-loaded components that pop in below static content after hydration
Dynamic data fetching via useEffect that inserts content above-the-fold after mount
Unsized images in component libraries where width and height are not enforced by the component contract
Web fonts loaded via CSS that swap after the initial paint
CSS animations using layout-affecting properties like top, left, width, or height instead of transform
Ad slots and third-party embeds that expand beyond their reserved space

None of these are unique to React, but React's default behavior of rendering a blank shell and then progressively filling it in with JavaScript makes each of these problems worse and harder to debug.

The traditional fix has been to instrument PerformanceObserver manually, interpret raw layout-shift entries, group them into session windows by hand, and build your own attribution logic. That's a lot of boilerplate for every project.

Introducing `@page-speed/hooks` and `useCLS`

@page-speed/hooks is an open-source library from OpenSite AI that wraps the web.dev web-vitals library and the raw Performance APIs into ergonomic, zero-config React hooks. The library is tree-shakeable, TypeScript-first, SSR-compatible, and used in production at OpenSite.

The current version is 0.4.6, and the full bundle is only ~12 KB gzipped, with useCLS specifically costing far less when imported individually via tree-shaking.

npm install @page-speed/hooks
# or
pnpm add @page-speed/hooks
# or
yarn add @page-speed/hooks

The library requires react >= 16.8.0 as a peer dependency, which means it works everywhere from legacy React projects to the latest Next.js App Router.

Understanding the `useCLS` Hook Architecture

Before writing any code, it's worth understanding how useCLS is built internally. This will help you reason about its behavior in production and make better decisions about how to configure it.

Dual Observer Strategy

The hook uses two concurrent measurement strategies:

onCLS from web-vitals — The primary measurement path. Google's official web-vitals library is invoked inside a useEffect and handles the complex accounting of session windows, page visibility changes, back-forward cache restores, and all the edge cases documented on web.dev. This produces the canonical CLS value.
PerformanceObserver for layout-shift — A second useEffect sets up a raw PerformanceObserver that fires the onShift callback in real-time as each individual shift occurs (with buffered: true to also capture past shifts). This enables per-shift callbacks for logging, alerting, or real-time dashboards.

Ref-Based State Pattern for Callbacks

One of the most important architectural decisions in the hook is the use of useRef for the options object:

const optionsRef = useRef(options);
optionsRef.current = options;

This pattern solves the classic React stale closure problem. Because onCLS is registered once in a useEffect, a naïve implementation would capture the onMeasure callback at registration time and never update it. By keeping options in a ref and always reading from optionsRef.current, the hook can accept new callback functions on re-renders without ever re-registering the PerformanceObserver — which would cause double-counting. The test suite explicitly validates this:

it("uses the latest onMeasure callback without re-registering", async () => {
 // rerender with a new callback...
 expect(mockOnCLS).toHaveBeenCalledTimes(1); // Observer registered only once
 expect(second).toHaveBeenCalledWith(0.05, "good"); // But latest callback fires
});

Session Window Algorithm

The buildSessionWindows function in useCLS reimplements the official CLS session window algorithm:

const gap = entry.startTime - currentWindow.endTime;
const duration = entry.startTime - currentWindow.startTime;

// Close window if gap > 1s or duration > 5s
if (gap > 1000 || duration > 5000) {
 windows.push(currentWindow);
 // start new window
} else {
 currentWindow.value += entry.value;
 currentWindow.entries.push(entry);
}

Shifts with hadRecentInput: true are excluded from windows, since shifts within 500ms of user interaction (clicks, taps, keypresses) are intentional and should not count against the CLS score.

Automatic Issue Detection

When detectIssues: true (the default), the hook analyzes the largest shift's source elements to categorize what caused the shift. It checks for six issue types:

Issue Type	Detection Logic
`image-without-dimensions`	`<img>` without explicit `width`/`height` attributes or `aspect-ratio` CSS
`unsized-media`	`<video>` or `<picture>` without explicit dimensions
`dynamic-content`	Default fallback for most shifts
`web-font-shift`	Text elements (`<span>`, `<p>`) with small vertical shift distances (<20px)
`ad-embed-shift`	`<iframe>` or elements with `[data-ad]` attribute
`animation-shift`	Elements where `animation`, `transition`, or `transform` CSS is non-trivial

For each detected issue, the hook generates a concrete, actionable suggestion string that tells you exactly what to do.

Complete API Reference

Options (`CLSOptions`)

interface CLSOptions {
 threshold?: number; // CLS alert threshold (default: 0.1)
 onMeasure?: (value: number, rating: 'good' | 'needs-improvement' | 'poor') => void;
 onShift?: (entry: LayoutShiftEntry) => void; // Called per-shift
 onIssue?: (issue: CLSIssue) => void; // Called when issue detected
 reportAllChanges?: boolean; // Report every update, not just final (default: false)
 debug?: boolean; // Console warnings (default: true in dev)
 detectIssues?: boolean; // Auto-detect issue types (default: true)
 trackAttribution?: boolean; // PerformanceObserver for per-shift callbacks (default: true)
 observeRef?: React.RefObject<HTMLElement>; // Scope to a specific container
}

Return Value (`CLSState`)

interface CLSState {
 cls: number | null; // Current CLS score (null until measured)
 rating: 'good' | 'needs-improvement' | 'poor' | null;
 isLoading: boolean; // True until first measurement
 entries: LayoutShiftEntry[]; // All individual layout shifts
 largestShift: LayoutShiftEntry | null; // The single biggest shift
 sessionWindows: CLSSessionWindow[]; // Grouped shift windows
 largestSessionWindow: CLSSessionWindow | null;
 issues: CLSIssue[]; // Auto-detected optimization opportunities
 shiftCount: number; // Total count of shifts
 hasPostInteractionShifts: boolean; // Shifts after user interaction
 utils: {
 getElementSelector: (element: Element | null) => string | null;
 hasExplicitDimensions: (element: HTMLElement | null) => boolean;
 getAspectRatio: (width: number, height: number) => { ratio: string; decimal: number };
 reset: () => void;
 };
}

Tutorial: Building From Zero to Production

Step 1: The Minimum Viable Monitor

The simplest possible usage — just drop this invisible component anywhere in your component tree. It will start measuring CLS immediately and log to your analytics:

// components/PerformanceMonitor.tsx
"use client"; // Required for Next.js App Router

import { useCLS } from "@page-speed/hooks";

export function PerformanceMonitor() {
 useCLS({
 onMeasure: (value, rating) => {
 // Replace with your analytics provider
 console.log(`CLS: ${value.toFixed(3)} (${rating})`);

 // Send to Google Analytics
 if (typeof window !== "undefined" && window.gtag) {
 window.gtag("event", "web_vitals", {
 event_category: "CLS",
 value: Math.round(value * 1000), // gtag expects integers
 event_label: rating,
 non_interaction: true,
 });
 }
 },
 });

 return null; // This component renders nothing
}

Place it in your root layout:

// app/layout.tsx (Next.js App Router)
import { PerformanceMonitor } from "@/components/PerformanceMonitor";

export default function RootLayout({ children }) {
 return (
 <html lang="en">
 <body>
 <PerformanceMonitor />
 {children}
 </body>
 </html>
 );
}

That's it. You're now capturing real-user CLS data in production.

Step 2: Development Debug Dashboard

During development, you want visibility into what's actually shifting and why. Here's a comprehensive debug component that surfaces everything useCLS knows:

// components/CLSDebugPanel.tsx
"use client";

import { useCLS } from "@page-speed/hooks";

const ratingColors = {
 good: "#0cce6b",
 "needs-improvement": "#ffa400",
 poor: "#ff4e42",
 null: "#888",
};

export function CLSDebugPanel() {
 const {
 cls,
 rating,
 shiftCount,
 largestShift,
 sessionWindows,
 issues,
 hasPostInteractionShifts,
 } = useCLS({ reportAllChanges: true });

 // Only show in development
 if (process.env.NODE_ENV !== "development") return null;

 return (
 <div
 style={{
 position: "fixed",
 bottom: 16,
 right: 16,
 width: 320,
 background: "#1a1a2e",
 color: "#eee",
 borderRadius: 8,
 padding: 16,
 fontFamily: "monospace",
 fontSize: 12,
 zIndex: 9999,
 boxShadow: "0 4px 20px rgba(0,0,0,0.5)",
 }}
 >
 <h3 style={{ margin: "0 0 12px", fontSize: 14 }}>⚡ CLS Monitor</h3>

 <div style={{ marginBottom: 12 }}>
 <span>Score: </span>
 <strong
 style={{ color: ratingColors[rating ?? "null"], fontSize: 18 }}
 >
 {cls?.toFixed(4) ?? "..."}
 </strong>
 {rating && (
 <span
 style={{
 marginLeft: 8,
 color: ratingColors[rating],
 textTransform: "uppercase",
 fontSize: 10,
 }}
 >
 {rating}
 </span>
 )}
 </div>

 <div style={{ marginBottom: 8 }}>
 <div>Total Shifts: {shiftCount}</div>
 <div>Session Windows: {sessionWindows.length}</div>
 {hasPostInteractionShifts && (
 <div style={{ color: "#ffa400" }}>⚠ Post-interaction shifts detected</div>
 )}
 </div>

 {largestShift && (
 <div style={{ marginBottom: 8, borderTop: "1px solid #333", paddingTop: 8 }}>
 <div style={{ color: "#888", marginBottom: 4 }}>Largest Shift</div>
 <div>Value: {largestShift.value.toFixed(4)}</div>
 <div>Time: {largestShift.startTime.toFixed(0)}ms</div>
 {largestShift.sources.length > 0 && (
 <div style={{ color: "#aaa", marginTop: 4 }}>
 Elements:
 {largestShift.sources
 .filter((s) => s.node)
 .map((s, i) => (
 de
 key={i}
 style={{
 display: "block",
 background: "#2d2d4e",
 padding: "2px 4px",
 borderRadius: 3,
 marginTop: 2,
 }}
 >
 {s.node}
 </code>
 ))}
 </div>
 )}
 </div>
 )}

 {issues.length > 0 && (
 <div style={{ borderTop: "1px solid #333", paddingTop: 8 }}>
 <div style={{ color: "#ff4e42", marginBottom: 4 }}>
 🔍 {issues.length} Issue{issues.length > 1 ? "s" : ""} Found
 </div>
 {issues.map((issue, i) => (
 <div key={i} style={{ marginBottom: 8 }}>
 <div style={{ color: "#ffa400" }}>{issue.type}</div>
 <div style={{ color: "#aaa", fontSize: 11, lineHeight: 1.4 }}>
 {issue.suggestion}
 </div>
 </div>
 ))}
 </div>
 )}
 </div>
 );
}

This panel will show you in real time which elements are shifting, their scores, and exactly what the hook recommends fixing.

Step 3: Fix the Most Common CLS Cause — Images Without Dimensions

The most common React CLS culprit is images rendered without explicit width and height attributes. When the browser doesn't know an image's dimensions before it loads, it allocates zero space for it. When the image loads, it pushes all surrounding content down.

The useCLS hook will detect this as an image-without-dimensions issue and even provide the CSS fix in its suggestion string. But you can also be proactive using the hasExplicitDimensions and getAspectRatio utilities:

// components/ImageAudit.tsx
"use client";

import { useEffect } from "react";
import { useCLS } from "@page-speed/hooks";

export function ImageAudit() {
 const { utils } = useCLS({
 onIssue: (issue) => {
 if (issue.type === "image-without-dimensions") {
 console.error(
 `%c[CLS] Image missing dimensions: ${issue.element}`,
 "color: #ff4e42; font-weight: bold"
 );
 console.info(`Fix: ${issue.suggestion}`);
 }
 },
 });

 useEffect(() => {
 // Run a full image audit after mount
 const images = Array.from(document.querySelectorAll("img"));

 images.forEach((img) => {
 if (!utils.hasExplicitDimensions(img)) {
 const selector = utils.getElementSelector(img);

 // Get the natural dimensions once loaded
 if (img.complete) {
 const { ratio } = utils.getAspectRatio(
 img.naturalWidth,
 img.naturalHeight
 );
 console.warn(
 `[CLS Audit] Image needs dimensions: ${selector}\n` +
 ` Option 1: <img width="${img.naturalWidth}" height="${img.naturalHeight}" />\n` +
 ` Option 2: CSS aspect-ratio: ${ratio};`
 );
 } else {
 img.addEventListener("load", () => {
 const { ratio } = utils.getAspectRatio(
 img.naturalWidth,
 img.naturalHeight
 );
 console.warn(
 `[CLS Audit] Image needs dimensions: ${selector}\n` +
 ` Option 1: <img width="${img.naturalWidth}" height="${img.naturalHeight}" />\n` +
 ` Option 2: CSS aspect-ratio: ${ratio};`
 );
 });
 }
 }
 });
 }, [utils]);

 return null;
}

The fix itself is simple. Once you have the dimensions:

// ❌ Causes CLS — browser doesn't know the space to reserve
<img src="/hero.jpg" alt="Hero" />

// ✅ Browser can calculate and reserve space before the image loads
<img
 src="/hero.jpg"
 alt="Hero"
 width={1200}
 height={600}
 style={{ width: "100%", height: "auto" }} // CSS makes it responsive
/>

// ✅ Or with CSS aspect-ratio (more flexible for dynamic images)
<img
 src="/hero.jpg"
 alt="Hero"
 style={{ aspectRatio: "16 / 9", width: "100%", height: "auto" }}
/>

Step 4: Prevent CLS With Skeleton Screens

Dynamic content — product listings, user feeds, comment sections — that loads after the initial render is a primary CLS source. The solution is to reserve the space before the content arrives. Skeleton screens are the right tool for this.

The getAspectRatio utility makes this accurate and data-driven when you know the expected content dimensions:

// components/ProductCard.tsx
"use client";

import { useState, useEffect } from "react";
import { useCLS } from "@page-speed/hooks";

interface Product {
 id: string;
 name: string;
 description: string;
 image: string;
 imageWidth: number;
 imageHeight: number;
 price: number;
}

function SkeletonCard({ aspectRatio }: { aspectRatio: string }) {
 return (
 // Reserve exact space using the known aspect ratio
 <div style={{ aspectRatio, width: "100%" }}>
 <div
 style={{
 height: "70%",
 background: "linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%)",
 backgroundSize: "200% 100%",
 animation: "shimmer 1.5s infinite",
 borderRadius: 8,
 }}
 />
 <div style={{ padding: "12px 0" }}>
 <div style={{ height: 20, background: "#f0f0f0", borderRadius: 4, marginBottom: 8 }} />
 <div style={{ height: 16, background: "#f0f0f0", borderRadius: 4, width: "60%" }} />
 </div>
 </div>
 );
}

export function ProductCard({ productId }: { productId: string }) {
 const [product, setProduct] = useState<Product | null>(null);
 const { utils } = useCLS();

 useEffect(() => {
 fetch(`/api/products/${productId}`)
 .then((r) => r.json())
 .then(setProduct);
 }, [productId]);

 // While loading, show a skeleton that matches the expected dimensions.
 // A standard 4:3 product image ratio is a safe default.
 if (!product) {
 return <SkeletonCard aspectRatio="4 / 3" />;
 }

 // Use the utility to compute the exact ratio from the real image dimensions
 const { ratio } = utils.getAspectRatio(product.imageWidth, product.imageHeight);

 return (
 <div>
 <img
 src={product.image}
 alt={product.name}
 width={product.imageWidth}
 height={product.imageHeight}
 style={{ aspectRatio: ratio, width: "100%", height: "auto" }}
 loading="lazy"
 decoding="async"
 />
 <h3>{product.name}</h3>
 <p>{product.description}</p>
 <strong>${product.price.toFixed(2)}</strong>
 </div>
 );
}

The key insight: the skeleton occupies exactly the same space as the real content, so when the content replaces it, no layout shift occurs.

Step 5: Handle SPA Navigation with `utils.reset()`

In single-page applications, CLS accumulates across route changes. A user visiting your home page followed by a product page will see a combined CLS score that doesn't reflect either page's actual stability. The utils.reset() function clears all tracked state and restarts measurement — exactly what you need on navigation.

// components/SPACLSTracker.tsx
"use client";

import { useEffect } from "react";
import { usePathname } from "next/navigation"; // or useLocation from react-router-dom
import { useCLS } from "@page-speed/hooks";

export function SPACLSTracker() {
 const pathname = usePathname();

 const { cls, rating, utils } = useCLS({
 reportAllChanges: false, // Only report final values per route
 onMeasure: (value, rating) => {
 // This fires with the final CLS for the current route
 fetch("/api/analytics", {
 method: "POST",
 headers: { "Content-Type": "application/json" },
 body: JSON.stringify({
 metric: "CLS",
 value,
 rating,
 route: window.location.pathname,
 timestamp: Date.now(),
 }),
 });
 },
 });

 useEffect(() => {
 // On route change: report the final CLS for the outgoing page
 // (onMeasure handles this automatically via web-vitals)
 // then reset for the incoming page
 return () => {
 utils.reset();
 };
 }, [pathname, utils]);

 return null;
}

Step 6: Detect and Fix Web Font Shifts

Web fonts that use font-display: swap load a system font first, then swap in the web font once it's available. If the two fonts have different metrics (line height, letter spacing, ascent), the text reflows and causes a layout shift. The hook detects this as a web-font-shift issue.

// components/FontMonitor.tsx
"use client";

import { useCLS } from "@page-speed/hooks";

export function FontMonitor() {
 const { issues } = useCLS({
 onIssue: (issue) => {
 if (issue.type === "web-font-shift") {
 console.warn(
 "[CLS] Web font layout shift detected!\n\n" +
 "Choose one of these fixes:\n\n" +
 "1. Use font-display: optional (no shift, but font may not show on first load)\n\n" +
 "2. Use font-display: swap WITH font metric overrides:\n" +
 " @font-face {\n" +
 " font-family: 'FallbackForMyFont';\n" +
 " src: local('Georgia');\n" +
 " size-adjust: 106%;\n" +
 " ascent-override: 90%;\n" +
 " descent-override: 27%;\n" +
 " }\n\n" +
 "3. Preload the font in <head>:\n" +
 " /fonts/my-font.woff2' as='font' crossOrigin='anonymous' />"
 );
 }
 },
 });

 return null;
}

The CSS fix using font metric overrides is the most effective long-term solution:

/* In your global CSS or @font-face declarations */

/* The web font as you already have it */
@font-face {
 font-family: "MyFont";
 src: url("/fonts/myfont.woff2") format("woff2");
 font-display: swap;
}

/* A tuned fallback that closely matches MyFont's metrics */
@font-face {
 font-family: "MyFont-Fallback";
 src: local("Georgia"); /* or whatever your fallback is */
 size-adjust: 106%;
 ascent-override: 90%;
 descent-override: 27%;
}

/* Use both in your font stack */
body {
 font-family: "MyFont", "MyFont-Fallback", serif;
}

Step 7: Prevent Animation-Related Shifts

CSS animations that modify layout-affecting properties (top, left, width, height, margin, padding) cause layout shifts. The hook detects these as animation-shift issues. The fix is always to use transform instead:

// The onIssue callback will tell you which element, but the fix is universal:
onIssue: (issue) => {
 if (issue.type === "animation-shift") {
 console.error(
 `[CLS] Animation causing layout shift on: ${issue.element}\n` +
 "Fix: Replace layout-affecting properties with transform.\n\n" +
 "❌ Bad: transition: left 0.3s ease;\n" +
 " left: 0px → left: 100px\n\n" +
 "✅ Good: transition: transform 0.3s ease;\n" +
 " transform: translateX(0) → transform: translateX(100px)"
 );
 }
}

/* ❌ Causes layout shifts */
.slide-in {
 animation: badSlide 0.3s ease;
}
@keyframes badSlide {
 from { left: -100px; }
 to { left: 0; }
}

/* ✅ Zero CLS — transform is GPU-composited, doesn't affect layout */
.slide-in {
 animation: goodSlide 0.3s ease;
}
@keyframes goodSlide {
 from { transform: translateX(-100px); }
 to { transform: translateX(0); }
}

Step 8: Reserve Space for Ads and Embeds

Ad slots and third-party embeds are notorious CLS sources because they load after the page renders and often expand to sizes larger than their initial space. The hook detects these as ad-embed-shift issues:

// components/AdSlot.tsx
"use client";

import { useCLS } from "@page-speed/hooks";

interface AdSlotProps {
 slotId: string;
 format: "banner" | "rectangle" | "leaderboard";
}

const adDimensions = {
 banner: { width: 468, height: 60 },
 rectangle: { width: 300, height: 250 },
 leaderboard: { width: 728, height: 90 },
};

export function AdSlot({ slotId, format }: AdSlotProps) {
 const { width, height } = adDimensions[format];

 useCLS({
 onIssue: (issue) => {
 if (issue.type === "ad-embed-shift") {
 console.warn(`Ad slot ${slotId} caused a layout shift of ${issue.contribution.toFixed(4)}`);
 }
 },
 });

 return (
 <div
 id={slotId}
 data-ad={format}
 style={{
 // CRITICAL: Reserve the exact space before the ad loads
 width,
 minHeight: height,
 // Prevent the slot from collapsing to 0 if the ad doesn't fill
 background: "#f9f9f9",
 display: "flex",
 alignItems: "center",
 justifyContent: "center",
 }}
 >
 {/* Ad network script loads here */}
 </div>
 );
}

Step 9: Build a Complete CLS Report for Stakeholders

When you need to present CLS data to a product team or client, the hook's rich state makes it easy to generate a structured report:

// components/CLSReporter.tsx
"use client";

import { useCallback } from "react";
import { useCLS } from "@page-speed/hooks";
import type { CLSIssue, LayoutShiftEntry } from "@page-speed/hooks";

interface CLSReport {
 score: number | null;
 rating: string | null;
 totalShifts: number;
 largestShiftValue: number | undefined;
 largestShiftElements: (string | null)[] | undefined;
 sessionWindowCount: number;
 issues: Array<{
 type: CLSIssue["type"];
 element: string | null;
 contribution: number;
 suggestion: string;
 }>;
 recommendations: string[];
 timestamp: string;
}

export function CLSReporter({ onReport }: { onReport?: (report: CLSReport) => void }) {
 const {
 cls,
 rating,
 entries,
 issues,
 largestShift,
 sessionWindows,
 shiftCount,
 utils,
 } = useCLS({
 reportAllChanges: true,
 onMeasure: (value, rating) => {
 if (rating === "poor") {
 console.error(`🔴 Poor CLS detected: ${value.toFixed(3)}`);
 }
 },
 onShift: (entry) => {
 if (entry.value > 0.05) {
 console.warn(
 "⚠ Significant layout shift:",
 entry.sources.map((s) => s.node).filter(Boolean)
 );
 }
 },
 onIssue: (issue) => {
 console.info(`💡 CLS Issue [${issue.type}]:`, issue.suggestion);
 },
 });

 const generateReport = useCallback((): CLSReport => {
 const report: CLSReport = {
 score: cls,
 rating,
 totalShifts: shiftCount,
 largestShiftValue: largestShift?.value,
 largestShiftElements: largestShift?.sources.map((s) => s.node),
 sessionWindowCount: sessionWindows.length,
 issues: issues.map((i) => ({
 type: i.type,
 element: i.element,
 contribution: i.contribution,
 suggestion: i.suggestion,
 })),
 recommendations: issues.map((i) => i.suggestion),
 timestamp: new Date().toISOString(),
 };

 onReport?.(report);
 console.table(report.issues);
 return report;
 }, [cls, rating, shiftCount, largestShift, sessionWindows, issues, onReport]);

 return (
 <div className="cls-reporter">
 <div
 className={`cls-score ${rating}`}
 style={{
 display: "inline-flex",
 gap: 8,
 alignItems: "center",
 padding: "8px 16px",
 borderRadius: 8,
 background:
 rating === "good"
 ? "#0cce6b22"
 : rating === "poor"
 ? "#ff4e4222"
 : "#ffa40022",
 }}
 >
 <span>CLS Score:</span>
 <strong style={{ fontSize: 24 }}>{cls?.toFixed(3) ?? "..."}</strong>
 {rating && (
 <span style={{ textTransform: "capitalize", opacity: 0.8 }}>
 ({rating.replace("-", " ")})
 </span>
 )}
 </div>

 <div style={{ marginTop: 16 }}>
 <button onClick={generateReport}>Generate Full Report</button>
 </div>

 {issues.length > 0 && (
 <details style={{ marginTop: 16 }}>
 <summary>
 {issues.length} Optimization{issues.length !== 1 ? "s" : ""} Available
 </summary>
 <ul>
 {issues.map((issue, i) => (
 >
 de style={{ background: "#f0f0f0", padding: "2px 6px", borderRadius: 3 }}>
 {issue.type}
 </code>
 <p style={{ margin: "4px 0 0", fontSize: 14, color: "#555" }}>
 {issue.suggestion}
 </p>
 </li>
 ))}
 </ul>
 </details>
 )}
 </div>
 );
}

Understanding the Test Suite

The useCLS.test.ts file demonstrates several important testing patterns that are worth understanding if you're building similar hooks.

Mocking `web-vitals`

The tests mock the entire web-vitals module and capture the callback that useCLS passes to onCLS:

vi.mock("web-vitals", () => ({ onCLS: vi.fn() }));

// Inside tests:
const callback = mockOnCLS.mock.calls; // capture the registered callback
act(() => {
 callback({ value: 0.05, entries: [] }); // simulate a CLS measurement
});

This pattern lets you test the hook's internal logic without any real browser performance APIs.

Mocking `PerformanceObserver`

The test suite stubs the global PerformanceObserver with a Vitest mock and verifies:

That observe is called with { type: "layout-shift", buffered: true }
That disconnect is called when the hook unmounts (no memory leaks)
That no observer is created when trackAttribution: false is passed

Rating Boundary Tests

The rating tests explicitly verify the exact threshold boundaries that match the web.dev specification:

it("calculates correct rating for good CLS", async () => {
 callback({ value: 0.08, entries: [] });
 expect(result.current.rating).toBe("good"); // 0.08 ≤ 0.1
});

it("calculates correct rating for needs-improvement CLS", async () => {
 callback({ value: 0.15, entries: [] });
 expect(result.current.rating).toBe("needs-improvement"); // 0.1 < 0.15 ≤ 0.25
});

it("calculates correct rating for poor CLS", async () => {
 callback({ value: 0.3, entries: [] });
 expect(result.current.rating).toBe("poor"); // 0.3 > 0.25
});

Performance Characteristics

useCLS is designed with zero rendering overhead in mind:

No polling or intervals — entirely event-driven via PerformanceObserver and the web-vitals library
Memoized utilities — getElementSelector, hasExplicitDimensions, getAspectRatio, and reset are all wrapped in useCallback and assembled in useMemo to produce a stable utils reference that won't cause re-renders in child components
Ref-based mutation — entriesRef, sessionWindowsRef, and issuesRef accumulate data without triggering renders; only setState calls when the CLS measurement updates
Cleanup on unmount — The PerformanceObserver is disconnected in the useEffect cleanup function, preventing memory leaks in SPAs

Bundle impact when imported individually via the tree-shakeable /web-vitals subpath is a small fraction of the 12 KB full-library budget.

Quick-Reference: Common Fixes

CLS Cause	Hook Detection	The Fix
Image without `width`/`height`	`image-without-dimensions` issue	Add `width` + `height` attrs, or CSS `aspect-ratio`
Video/media without dimensions	`unsized-media` issue	Add `width` + `height` to media elements
Dynamic content insertion	`dynamic-content` issue	Skeleton screens, `min-height` containers
Web font swap	`web-font-shift` issue	`font-display: optional` or font metric overrides
Ad/embed expansion	`ad-embed-shift` issue	Fixed `min-height` on ad containers
Layout-affecting animation	`animation-shift` issue	Replace `top/left/width/height` with `transform`

Getting Started

# Install
pnpm add @page-speed/hooks

# Or for just the web vitals hooks (smaller bundle)
# Import from subpath in your code:
# import { useCLS } from "@page-speed/hooks/web-vitals";

GitHub Repository: opensite-ai/page-speed-hooks

npm Package: @page-speed/hooks

Built by: OpenSite AI

Auth Strategies: The Right Tool for the Right Scenario

Jordan Hudgens — Fri, 03 Apr 2026 22:33:50 +0000

A practical developer guide to sessions, JWTs, OAuth 2.0/OIDC, SAML, API keys, mTLS, passkeys, and magic links — without picking sides.

The Auth Debate Is a False Binary

Every few months the same argument erupts: "Sessions are better than JWTs!" followed swiftly by "But JWTs scale!" The developers in the middle — the ones shipping products — are left more confused than when they started.

Here's the truth: there is no universally "best" auth strategy. There are eight major approaches (with meaningful variants), and each one was designed to solve a specific class of problem. Picking the wrong one doesn't mean you're a bad engineer — it usually means you applied a solution from a different context to yours.

This guide maps every major auth strategy to the scenarios where it excels, where it struggles, and where the tradeoffs are genuinely nuanced. No flamewars. Just reasoning.

The Full Landscape: Eight Auth Strategies You Should Know

Before diving into scenarios, here's a concise mental model for every mechanism we'll discuss.

1. Session-Based Authentication

The traditional approach. The server creates a session record when a user authenticates, stores it server-side (in memory, a database, or Redis), and sends back a session ID via a Set-Cookie header. Every subsequent request includes that cookie automatically, and the server looks up the session to hydrate user context.

The session cookie itself contains zero sensitive data — it's just a random opaque identifier (typically a UUID). All privileged information stays on the server. This is a security feature, not a limitation.

Cookie hardening is essential:

Flag	Purpose	Protection Against
`HttpOnly`	Prevents JavaScript access	XSS token theft
`Secure`	HTTPS-only transmission	Man-in-the-middle attacks
`SameSite=Lax/Strict`	Controls cross-site requests	CSRF attacks
`Max-Age`	Sets expiration time	Persistent stale sessions

Revocation is instant — deleting the session row or Redis key immediately invalidates access, regardless of what the client holds. This is the single biggest advantage sessions hold over JWTs.

Scaling caveat: vanilla in-memory sessions don't work across multiple server instances. The standard fix is a shared Redis session store — externalize the session state and every instance can serve any request. Companies like Uber use this pattern at scale.

2. JWT (JSON Web Tokens)

A JWT is a self-contained, cryptographically signed token that encodes claims directly. The server issues it, the client stores it and sends it with each request, and validation happens via signature verification — no database lookup required.

Structure: header.payload.signature — all base64url encoded. The payload is not encrypted by default — anyone can decode it. Never put sensitive data (SSN, PII, internal IDs you want hidden) in a JWT payload.

The access/refresh token pattern is the production-grade approach:

Access Token: short-lived (5–15 min), stateless validation
Refresh Token: long-lived (7–14 days), stored server-side in Redis
 single-use, rotated on every exchange

JWT security non-negotiables:

Whitelist algorithms explicitly — never allow "none" or algorithm confusion attacks
Use asymmetric algorithms (RS256 or ES256) for production
Always validate iss, aud, exp, nbf, jti
Use short access token lifetimes (5–15 minutes)
Implement refresh token rotation with reuse detection

The revocation problem: access JWTs cannot be revoked before expiry without maintaining a blocklist — which reintroduces server-side state. This is why short lifetimes matter so much. If you need instant revocation (e.g., "logout all devices"), you'll need a token blocklist or very short TTLs.

Token storage is where most developers make mistakes:

Storage	XSS Risk	CSRF Risk	Best For
`localStorage`	❌ High	✅ None	Low-security public apps only
`httpOnly` cookie	✅ Protected	❌ Needs CSRF protection	Web apps requiring persistence
In-memory (React state)	✅ Protected	✅ None	High-security SPAs
Memory + `httpOnly` refresh	✅ Best of both	Minimal CSRF surface	Production SPAs

The community consensus in 2025: store the access token in memory, the refresh token in an httpOnly cookie. Never localStorage for anything sensitive.

3. OAuth 2.0 + OpenID Connect (OIDC)

These are often conflated but serve distinct purposes:

OAuth 2.0: An authorization framework. Answers: "Can this app access this resource on behalf of this user?" Issues access tokens.
OIDC: An authentication layer built on top of OAuth 2.0. Answers: "Who is this user?" Adds an ID token (always a JWT) with identity claims.

Think of OAuth 2.0 as the truck and OIDC as the GPS — OIDC tells you who is driving, OAuth tells you where they're allowed to go.

OAuth 2.0 Grant Types — picking the right one matters:

Grant Type	Use Case	Who Uses It
Authorization Code + PKCE	Web, SPA, Mobile	Any user-facing app
Client Credentials	Server-to-server (M2M)	Backend services, cron jobs
Device Authorization	TV, CLI, input-limited devices	Smart TVs, IoT terminals
Refresh Token	Token renewal	Any long-lived client

PKCE is now mandatory for all clients — OAuth 2.1 (the current draft hardening spec) requires it without exception, even for confidential clients. There is no valid reason to skip it.

For native mobile apps specifically:

Use Authorization Code + PKCE (never Implicit flow)
Use the system browser (not an embedded WebView) to protect credentials
Use opaque tokens for mobile clients — JWTs are readable by the app and expose claims. Let the API gateway introspect and convert to JWT internally (the "Phantom Token" approach)
Store tokens in iOS Keychain / Android Keystore — never in SharedPreferences or files

4. SAML 2.0

SAML (Security Assertion Markup Language) is the enterprise SSO veteran — XML-based assertions, strict schemas, and broad adoption in corporate IT. When an enterprise customer says "we need SSO," there's a strong chance their IdP (Okta, Azure AD, Ping) speaks SAML.

SAML is powerful but carries significant developer friction:

Dimension	SAML	OIDC
Data Format	XML	JSON (JWT)
Mobile Support	❌ Poor	✅ Excellent
API Support	❌ Limited	✅ Native
Setup Complexity	🔴 High	🟡 Medium
Enterprise Adoption	✅ Dominant	✅ Growing
Key Management	Manual X.509 certs	JWKS endpoint (auto)

The practical guidance: if you're building new systems, default to OIDC. Implement SAML only when an enterprise customer explicitly requires it (which is common in B2B SaaS). Most modern IdPs support both, so you can offer both.

5. API Keys

API keys are static, opaque credentials — think sk_live_abc123xyz — typically sent in an Authorization header or as a query parameter. They're the blunt instrument of auth: easy to implement, easy to understand, and appropriate for specific narrow scenarios.

Best practices:

Hash API keys before storing (SHA-256 or Argon2) — never store plaintext
Use AES-256 encryption at rest, TLS 1.3 in transit
Scope keys to the minimum required permissions
Support key rotation and expiry
Rate limit per-key and alert on anomalous usage

The M2M caveat: for service-to-service communication, OAuth 2.0 Client Credentials is more secure than API keys — it issues short-lived tokens, supports rotation without re-provisioning, and integrates with existing IAM systems. API keys are appropriate for developer-facing public APIs where simplicity matters more.

6. Mutual TLS (mTLS)

mTLS extends standard TLS to require both the server and the client to present certificates. Unlike other auth mechanisms, authentication happens at the transport layer — no Authorization header, no cookie, no token. The handshake itself is the authentication.

This is the backbone of zero-trust internal networks and service meshes:

Standard TLS: Client verifies server certificate ✅
mTLS: Client verifies server cert ✅ + Server verifies client cert ✅

When used in a service mesh (Linkerd, Istio), mTLS is injected transparently — your application code doesn't need to manage it. The service mesh handles certificate issuance, rotation, and validation.

mTLS is not for user-facing auth — it's purely for service-to-service or device-to-service communication where you control both ends of the connection.

7. Passkeys / FIDO2 / WebAuthn

Passkeys are the most significant shift in authentication UX in a decade. Built on the FIDO2/WebAuthn standard, they use public-key cryptography where the private key never leaves the user's device:

Registration: Device generates a key pair. Public key is stored server-side. Private key stays in device's secure enclave.
Authentication: Server sends a challenge. Device signs it with the private key. Server verifies with the public key.

No passwords. No shared secrets. Phishing-resistant because credentials are bound to the exact domain. Works with Face ID, Touch ID, Windows Hello, or hardware security keys.

Passkeys are synced across devices via platform providers (Apple, Google, Microsoft), solving the device-loss problem that plagued earlier hardware token approaches. Browser and OS support as of 2025 is strong across all major platforms.

This is where user-facing consumer auth is heading. If you're building a new consumer app in 2025, passkeys should be your primary auth mechanism with email/password as a fallback.

8. Magic Links (Passwordless Email)

Magic links send a time-limited, single-use URL to the user's email. No password required — the email inbox is the proof of identity.

Production implementation requirements:

Cryptographically random token (crypto.randomBytes(32))
15-minute expiry maximum
Hash the token before storage (never store plaintext)
Single-use enforcement (mark used immediately upon validation)
Rate limiting per email address
IP and user-agent logging for audit

The critical dependency: magic links live and die by email deliverability. Users with slow email providers, spam filters, or no mobile access to their inbox will be frustrated. Build with a fallback (OTP, passkey) for production systems.

The Decision Matrix

When Each Strategy Can Be Used (Feasibility)

Scenario	Sessions	JWT	OAuth/OIDC	SAML	API Keys	mTLS	Passkeys	Magic Links
Traditional server-rendered web app	✅	✅	✅	✅	❌	❌	✅	✅
Single-Page App (React/Vue/Angular)	✅	✅	✅	❌	❌	❌	✅	✅
Native Mobile (iOS/Android)	⚠️ Limited	✅	✅	❌	⚠️ Limited	⚠️ Complex	✅	✅
Multi-domain / cross-domain SSO	❌	⚠️ Custom	✅	✅	❌	❌	⚠️ Limited	❌
Enterprise B2B SSO	❌	❌	✅	✅	❌	❌	❌	❌
Microservices (service-to-service)	❌	✅	✅	❌	✅	✅	❌	❌
Public developer API	❌	✅	✅	❌	✅	❌	❌	❌
M2M / server-to-server	❌	✅	✅	❌	✅	✅	❌	❌
IoT / embedded devices	❌	✅	✅	❌	✅	✅	❌	❌
High-security (banking, healthcare)	✅	⚠️ Careful	✅	✅	❌	✅	✅	❌
SaaS multi-tenant	⚠️ Hard	✅	✅	✅	❌	❌	✅	✅
Consumer passwordless UX	❌	❌	✅	❌	❌	❌	✅	✅
CLI tools / DevOps automation	❌	✅	✅	❌	✅	✅	❌	❌

✅ = natural fit | ⚠️ = possible with caveats | ❌ = wrong tool for the job

When Each Strategy Cannot Be Used (Hard Blockers)

Auth Strategy	Cannot Be Used When...
Sessions	No shared state is possible (pure serverless/edge without external store); cross-domain auth required without federation; native mobile without cookie support
JWT	Instant revocation is a hard requirement (e.g., compromised account must be locked in real-time); token payload size would exceed HTTP header limits (many claims/permissions)
OAuth/OIDC	No redirect capability exists (some embedded environments); extremely resource-constrained devices where the OAuth handshake overhead is prohibitive
SAML	Mobile-native clients; API-to-API auth; teams without XML tooling capacity or enterprise IdP access
API Keys	Fine-grained, per-user authorization is needed; user delegation scenarios; when short-lived credentials are a compliance requirement
mTLS	You don't control one end of the connection; client devices can't manage certificates; browser-based user auth
Passkeys	Legacy browsers/OS without FIDO2 support; users without compatible devices (must provide fallback); offline-only environments
Magic Links	Unreliable email delivery environment; high-frequency logins (email fatigue); security posture where email compromise would be catastrophic

Optimal Strategy by Scenario

This is the core of the guide — the prescriptive answer to "what should I use for my app?"

Scenario	Optimal Strategy	Why
Traditional Rails/Django web app, single domain	Sessions	Instant revocation, simple implementation, works natively with browser cookies, no token management complexity
React/Next.js SPA, same-domain API	JWT in `httpOnly` cookie or Session	Both work; session is simpler to revoke; JWT suits Next.js API routes well
React SPA + separate API domain (e.g., `app.co` + `api.co`)	JWT with CORS or OIDC	Cookies don't cross domains; JWT in `Authorization` header works, or OIDC federation
Native iOS/Android app	OIDC (Auth Code + PKCE) + opaque tokens	System browser for login, Keychain/Keystore for token storage, opaque tokens prevent client-side claims leakage
TV / gaming console / CLI device	OAuth 2.0 Device Authorization Grant	Input-constrained; user authenticates on a second device (phone/browser)
Multi-domain SSO (your own properties)	OIDC with shared IdP	Centralized IdP issues tokens trusted across all your domains; cookies cannot span domains
Enterprise B2B (customer brings their own IdP)	OIDC + SAML fallback	Offer OIDC first (modern, easier); support SAML for customers with legacy IdPs (Okta, Azure AD, OneLogin)
Microservices internal service calls	JWT (short-lived) or mTLS	JWT works well with API gateways; mTLS is superior in zero-trust/service mesh environments
Public developer API (like Stripe/GitHub)	API Keys + OAuth 2.0	API keys for server-side scripts; OAuth 2.0 for apps acting on behalf of users
Server-to-server / M2M (CI/CD, crons)	OAuth 2.0 Client Credentials	Issues short-lived tokens, rotates automatically, integrates with IAM — more secure than static API keys
Banking / healthcare (high security)	Sessions + MFA (+ mTLS for services)	Sessions provide instant revocation; centralized audit log; MFA adds second factor; mTLS for service-to-service
SaaS multi-tenant B2B platform	JWT with tenant claims + OIDC + SAML	Tokens scoped per-tenant; SSO via OIDC/SAML per customer; step-up MFA per tenant policy
Consumer app, modern UX focus	Passkeys + Magic Link fallback	Phishing-resistant, password-free; magic links for device recovery
IoT / embedded hardware	mTLS + OAuth 2.0 Client Credentials	Device certificates at the transport layer; OAuth for API access tokens
Serverless / edge (Cloudflare Workers, Vercel)	JWT or OIDC	Stateless validation; no persistent session store available at edge

Deep Dives: The Scenarios That Trip Developers Up

The SPA + Separate API Problem

This is where the most confusion lives. You have app.mysite.com (React) and api.mysite.com (your backend). Can you use sessions?

Yes, with Domain=.mysite.com cookie scope — a session cookie scoped to .mysite.com will be sent to both subdomains. This is the clean solution when you own both domains and they share a TLD+1.

JWT in httpOnly cookie with the same Domain flag also works and gives you stateless validation at the API layer.

Where it breaks: if your frontend and API are on completely different domains (app.io + api.io), cookies won't cross. You need JWTs in the Authorization header, with a proper CORS policy — or federate via an OIDC provider that both trust.

Native Mobile Auth: The Implicit Flow Trap

A common legacy mistake is implementing the OAuth 2.0 Implicit flow in mobile apps because it looks simpler — it returns the token directly in the URL fragment. Do not do this. The Implicit flow cannot be protected by PKCE, is vulnerable to token interception in the URL, and is removed in OAuth 2.1.

The correct mobile flow:

1. App opens system browser with authorization URL + PKCE code_challenge
2. User authenticates in system browser (credentials never seen by app)
3. Authorization server redirects to app via custom URI scheme (myapp://callback)
4. App exchanges authorization code + code_verifier for tokens
5. Tokens stored in iOS Keychain or Android Keystore
6. Access token used as opaque token; API gateway introspects to JWT internally

The key insight: the mobile app should never see a JWT. JWTs carry claims in plaintext. If a bad actor reads your app's memory, they read your users' data. Opaque tokens are meaningless without server-side introspection.

The Microservices Auth Problem

When service A needs to call service B, three patterns exist:

Pattern 1 — JWT Propagation: Service A receives a user's JWT, extracts claims, and forwards them (or a derived token) to Service B. Service B validates the signature independently — no database call. Works well with an API gateway as the entry point.

Pattern 2 — Service Account JWT (OAuth2 Client Credentials): Each service has its own identity. Service A authenticates to the auth server, gets a service-level JWT, sends it to Service B. Clean separation between user identity and service identity.

Pattern 3 — mTLS (Zero Trust): No tokens at all. Service A presents its certificate. Service B verifies it. The service mesh handles this transparently. This is the most secure option and the gold standard for zero-trust architectures.

In practice, Pattern 1 or 2 + mTLS is the combination most teams land on — JWT for authorization claims, mTLS for mutual identity assurance at the transport layer.

Multi-Tenant SaaS: Auth Is a First-Class Concern

Multi-tenant SaaS has unique auth requirements that neither pure sessions nor pure JWTs handle elegantly out of the box:

Authentication is global; authorization is tenant-scoped. A user authenticates once but has different roles in different tenants.
Tokens must carry tenant context. Mint a new JWT per active tenant — never reuse a token across tenant contexts.
SSO policies live on tenants, not users. One tenant may require SAML via Okta; another uses OIDC via Google; a third uses email/password. Your auth layer must support per-tenant IdP configuration.
MFA is tenant-scoped. If tenant A requires MFA, apply step-up auth for that tenant — don't globally enforce it on all tenants.

The cleanest architecture: a centralized identity service issues global user tokens, then a tenant-context exchange endpoint issues tenant-scoped JWTs with RBAC claims specific to that tenant.

When Sessions Beat JWT (and Vice Versa)

Rather than a false war, here's an honest comparison:

Criterion	Sessions Win When...	JWT Wins When...
Revocation	Instant revocation is required (banking, security incidents)	Revocation isn't time-critical (acceptable 15-min window)
Scale	Redis is available and latency is tolerable	Pure stateless validation is needed (edge/serverless)
Payload	User data should stay server-side	Claims need to travel to multiple services
Infrastructure	Single domain, monolith or modular monolith	Microservices, multi-domain, mobile
Audit	Centralized session audit is required	Distributed validation is acceptable
Complexity	Simpler mental model is priority	Teams are comfortable with token lifecycle management

The "sessions don't scale" argument was true in the era of sticky sessions and in-memory storage. With Redis as a shared session store, sessions scale horizontally as well as JWTs do — the latency overhead is a single Redis lookup (~1ms). The tradeoff is infrastructure cost, not raw scalability.

The "JWTs are insecure" argument is also overblown. JWT security issues are almost always implementation failures: wrong algorithms, long expiry times, localStorage storage, missing claim validation. A correctly implemented JWT system is extremely robust.

Security Cheat Sheet by Mechanism

Sessions

HttpOnly, Secure, SameSite=Strict on all cookies
Regenerate session ID on privilege escalation (login, password change)
Short absolute TTL (24–48 hours max) + sliding expiry
Centralize session store (Redis) — never in-memory for multi-instance deployments
Implement concurrent session limits for high-security apps

JWT

Use RS256 or ES256 — never HS256 with weak secrets
Explicitly whitelist allowed algorithms — block "none"
Access tokens: 5–15 minutes. Refresh tokens: 7–14 days, single-use with rotation
Validate every claim: iss, aud, exp, nbf, jti
Store access token in memory; refresh token in httpOnly cookie
Maintain refresh token blocklist/rotation store in Redis
Never put sensitive PII in the payload — it's base64 encoded, not encrypted

OAuth 2.0 / OIDC

PKCE is mandatory, always, for every client type
Validate state parameter to prevent CSRF on the callback
Use exact string matching for redirect URIs (no wildcards)
Short access token lifetimes (15–30 min) + refresh token rotation
Use discovery document (/.well-known/openid-configuration) — don't hardcode endpoints
Validate ID token: iss, aud, exp, nonce

API Keys

Hash before storage (SHA-256 minimum; Argon2 for extra protection)
Scope to minimum permissions; support per-key scopes
AES-256 at rest; TLS 1.3 in transit
Rotate regularly; support programmatic rotation without downtime
Rate limit per key; alert on anomalous usage patterns

mTLS

Use a dedicated internal CA; rotate certificates automatically
Short certificate lifetimes (hours in service meshes)
Verify certificate chain, expiry, and revocation (OCSP)
Combine with application-level authorization — mTLS proves identity, not permission

Passkeys / WebAuthn

Validate rpId against your domain — never allow cross-origin credential use
Always verify challenge, origin, rpIdHash on the server
Set userVerification: "required" for high-security scenarios
Store public keys, not private keys — private keys never leave the device
Provide account recovery path (passkey addition via email OTP or magic link)

Quick Reference: Auth Strategy Selection Flow

Use this decision tree as a starting point — then apply the nuance from the sections above.

Is this user-facing or machine-to-machine?
│
├─ Machine-to-Machine
│ ├─ Service-to-service (internal, zero-trust) → mTLS + optional JWT
│ ├─ Service-to-service (external API client) → OAuth 2.0 Client Credentials
│ ├─ Developer API (simple, scoped access) → API Keys
│ └─ IoT / embedded devices → mTLS + Device Auth Grant
│
└─ User-Facing
 ├─ Native mobile (iOS/Android) → OIDC (Auth Code + PKCE)
 ├─ TV / CLI / input-limited → OAuth 2.0 Device Flow
 ├─ Consumer web, same domain, monolith → Sessions
 ├─ SPA + same-domain API (subdomain OK) → Sessions or JWT (httpOnly cookie)
 ├─ SPA + cross-domain API → JWT (Authorization header)
 ├─ Multi-domain SSO (own properties) → OIDC with shared IdP
 ├─ Enterprise B2B SSO → OIDC + SAML fallback
 ├─ Multi-tenant SaaS → JWT + per-tenant OIDC/SAML
 ├─ Banking / healthcare (high security) → Sessions + MFA
 ├─ Serverless / edge computing → JWT (stateless)
 └─ Consumer app, modern passwordless UX → Passkeys + Magic Link fallback

The Hybrid Approach: When Two Mechanisms Are Better Than One

Real production systems often combine mechanisms strategically:

Sessions + OIDC: The user authenticates via Google/Okta (OIDC), and your server creates a local session from the resulting identity claims. You get the seamless login UX of federated identity plus the instant revocation and simplicity of sessions.

JWT (access) + Session (refresh context): Short-lived JWTs for stateless API validation; a server-side session record tracks the refresh token family, enabling instant invalidation of all tokens on logout or compromise.

mTLS + JWT: Service mesh provides mutual identity assurance at the transport layer; application-level JWTs carry authorization claims (roles, tenant, scopes). Neither alone is sufficient — mTLS proves "this is Service B" but not "Service B is allowed to do X."

API Keys + OAuth 2.0: Offer API keys for simple server-side integrations; offer OAuth 2.0 for apps that act on behalf of users. Stripe, GitHub, and Twilio all implement both.

Closing Perspective

The developers who are best at auth don't have a favorite mechanism — they have a decision framework. They ask:

Who is authenticating? User, service, device, or delegated agent?
What infrastructure do I control? Same domain, multiple domains, mobile, edge?
What are my revocation requirements? Instant (banking) or eventual (SaaS)?
What is my threat model? XSS exposure, CSRF risk, token interception, certificate management?
What is my scaling model? Monolith, microservices, serverless?

Every mechanism in this guide was designed by smart people solving real problems. Sessions weren't made obsolete by JWTs. JWTs weren't made insecure by sessions. SAML didn't lose to OIDC — it just serves a narrower niche. The right auth strategy is the one that fits your actual constraints.

Ship thoughtfully. Rotate tokens. Validate everything. And maybe skip the Twitter argument next time.

If this guide helped you make a concrete decision, share it with a teammate facing the same question. The auth debate benefits from more signal and less heat.

How to Download and Upload Large Models with the Hugging Face CLI

Jordan Hudgens — Thu, 02 Apr 2026 13:45:03 +0000

Managing large model files on Hugging Face can feel cumbersome — especially when dealing with multigigabyte embeddings or generative models. Fortunately, the Hugging Face CLI provides a straightforward workflow for downloading public models and re-uploading them to your own repositories, including large ones that support resumable uploads.

In this post, we’ll walk through exactly how you can:

Download a large model (like Qwen3-Embedding-8B) directly from Hugging Face.
Upload it to your own repo (in this case, OpenSite/forge).
Handle connection drops, resumable uploads, and commit messages — all from your terminal.

This is a simple, CLI-first guide that gets you productive fast with model management, especially if you’re maintaining open-access or shared AI model repositories.

Step 1 — Download the model

Assuming you have the hf cli installed on your system

The example below uses the following examples:

Downloading the Qwen3-Embedding-8B model from the Qwen organization's hugging face profile
Uploading the model to our public, open source model repo on hugging face
So just swap out the names for the model you want to download and the repo you want to upload to

hf download Qwen/Qwen3-Embedding-8B --local-dir ./Qwen3-Embedding-8B

This downloads all model files into a Qwen3-Embedding-8B/ subdirectory.

Step 2 — Upload to OpenSite/forge

Since this is an 8B model (likely 15-30GB), use the large-folder uploader for resumable uploads:

hf upload-large-folder OpenSite/forge ./Qwen3-Embedding-8B

Or if you prefer the standard uploader (non-resumable):

hf upload OpenSite/forge ./Qwen3-Embedding-8B

Notes

The download will take a while — Qwen3-Embedding-8B is ~15GB in bf16 format
upload-large-folder is strongly recommended here since it supports resuming if the connection drops mid-upload
Both commands will use your currently logged-in HF token automatically
If you want to add a commit message to the upload: --commit-message "Add Qwen3-Embedding-8B"

You can verify your login first with:

hf auth whoami

That’s it — two commands and you’re done. With the hf CLI, managing massive model files no longer needs to be painful. Whether you’re curating open-access models like we do at OpenSite AI, or just organizing internal repositories, this workflow keeps things simple, repeatable, and automatable.

👉 Check out our OpenSite/forge Hugging Face repo for open-source models and embeddings, or visit opensite.ai/developers to explore our latest AI infrastructure tools.

Stop Letting AI Agents Go Rogue on Large Codebases: The large-scale-refactor Skill

Jordan Hudgens — Sat, 28 Mar 2026 00:49:09 +0000

A comprehensive guide to OpenSite AI's open-source skill that gives AI coding agents enterprise-grade guardrails for migrations, multi-session refactors, and parallelized tasks.

We've all been there.

You ask an AI agent to "migrate my components to TypeScript." An hour later you check back and it has renamed your props, refactored three utility functions, installed two new packages, reorganized your folder structure, and changed your ESLint config "while it was in there."

The task was 40 files. It touched 140.

This is the core problem with AI agents on large, long-running tasks: they don't have a scope reflex. Humans instinctively know when they've drifted. Agents don't — and the bigger the task, the worse the drift gets.

The large-scale-refactor skill from OpenSite AI is a free, open-source agent skill that solves this by giving your AI agent a complete operating protocol for any task touching 50+ files — migrations, framework upgrades, codebase-wide renames, or anything running across multiple sessions or parallel agents.

This guide walks through everything: what the skill is, how every guardrail works, and a complete end-to-end walkthrough of a real JS→TS migration.

What Is an "Agent Skill"?

Before diving in, a quick note on terminology. An agent skill is a structured instruction set — loaded into the AI agent's context — that defines how it should behave for a specific class of task. It's not a library you install in your codebase. It's a behavioral protocol for your agent.

The large-scale-refactor skill works with Claude Code, Codex, Cursor, GitHub Copilot, Qoder Quest, Factory Droid, and Devin Playbooks. On platforms that support automatic activation, the skill kicks in automatically when it detects patterns like "migrate * to" or "refactor * across" or when a task is estimated to touch 50+ files.

Install it once, then never think about it:

git clone https://github.com/opensite-ai/opensite-skills.git

For Claude Code, add it to your .claude/skills/ directory. For Cursor, drop it in your .cursor/skills/ directory. The SKILL.md frontmatter handles the rest.

The Core Insight: Agents Need a Scope Reflex

The skill's design is built around one uncomfortable truth:

AI agents are pattern completers, not task completers. When they see something that could be improved, they improve it — even if that wasn't the job.

This isn't a bug in any particular model. It's the fundamental nature of how these systems work. A language model trained to produce high-quality code will naturally drift toward "better" code whenever it has the opportunity.

The large-scale-refactor skill installs a scope reflex by making the agent ask a single question before every change:

"If I remove this change from the diff, does the task still fail?"

This is the Substitution Test (§ 2.2), and it is the single most important concept in the skill. If the task succeeds without a change, the change doesn't belong in this PR.

The Eight Guardrails — A Deep Dive

The skill is organized into eight sections. Let's go through each one in depth.

§ 1 — The Spec Gate: No Execution Without Approval

This is the foundational rule. Before the agent writes a single line of code, it must produce a written spec and wait for a human to explicitly approve it.

The spec format is precise by design:

TASK SPEC
=========
**Task Name**: js-to-ts-migration
**Date**: 2026-03-27
**Initiator**: Your Name

### What This Task Does
Convert all .js files in src/ to .ts/.tsx, adding TypeScript types.
No logic changes, no style changes, no dependency additions beyond @types/*.

### Explicit Scope Boundary
**IN SCOPE** (agent may touch):
- [x] File types: *.js files in src/components/, src/hooks/, src/utils/
- [x] Operations: Type annotations, file extension changes
- [x] Directories: src/components/, src/hooks/, src/utils/

**OUT OF SCOPE — DO NOT TOUCH**:
- [ ] CSS/styling, color tokens, theme configuration
- [ ] Business logic or algorithm changes
- [ ] package.json (except @types/*)
- [ ] Build configs, CI/CD, deployment
- [ ] node_modules/, config/, scripts/, public/

### Task Decomposition
1. Subtask A — src/components/common/ — 15 files
2. Subtask B — src/components/features/ — 22 files
3. Subtask C — src/hooks/ — 8 files
4. Subtask D — src/utils/ — 12 files
5. Subtask E — test files — 35 files

### Acceptance Criteria
- [ ] All in-scope .js files converted to .ts/.tsx
- [ ] All tests pass (or pre-existing failures documented)
- [ ] No files outside scope boundary modified
- [ ] Each subtask in its own reviewable commit

### Rollback Plan
Feature branch: refactor/js-to-ts-migration
Full rollback: git checkout main && git branch -D refactor/js-to-ts-migration

After generating this, the agent on Claude Code will output:

⏸ SPEC GATE: Please review and reply 'approved' to begin execution,
or provide corrections.

No code gets written until you say the word. The spec is your contract with the agent.

Why this matters: Most agent disasters happen in the first 10 minutes, before the human realizes the task is going sideways. The spec gate forces that realization to happen before any code is touched.

§ 2 — Scope Enforcement: Five Rules the Agent Cannot Break

Once execution begins, five rules govern every file touch and every line written.

2.1 The One Task Rule

The agent has exactly one job. Not one-and-a-half. Not "one plus reasonable improvements." One.

When it notices a bug, a performance issue, or an architectural smell that isn't in the spec, it does not fix it. It logs it to OBSERVATIONS.md and moves on:

## Observations (NOT acted upon — logged for human review)

| File | Observation | Severity |
|------|-------------|----------|
| src/api/user.ts | Possible N+1 query in fetchUsers | Medium |
| src/components/Button.tsx | Inline styles could use CSS vars | Low |

This file becomes a goldmine at the end of the task. You get a curated list of real technical debt, surfaced by an agent that touched every file, with zero action taken on any of it.

2.2 The Substitution Test

Before every change: "If I remove this from the diff, does the task still fail?" If the answer is no — don't make the change.

2.3 No Emergent Systems

The agent is explicitly prohibited from creating anything that didn't exist before the task began unless it's a spec-defined output. No new utility libraries. No new abstractions. No folder reorganizations. No new config files.

If a new shared utility is genuinely necessary to avoid massive repetition, the agent proposes it in OBSERVATIONS.md and halts for approval before creating it.

2.4 Dependency Lockdown

No adding, removing, or upgrading dependencies unless explicitly listed in the spec (or @types/* for TypeScript migrations). Any dependency change is an automatic human checkpoint.

2.5 The 50-Line Net-New Code Threshold

If completing a single refactoring step requires writing more than 50 lines of net-new logic, the agent stops. This is a hard signal that something has gone wrong — either the task is being misunderstood, or the spec needs an architectural discussion.

A refactor should transform existing patterns, not invent new ones. 50 lines of net-new logic in a refactor is a red flag.

§ 3 — Execution Protocol: Atomic, Budgeted, and Drift-Checked

3.1 Pilot Batch First

Regardless of risk level, the first batch of any new refactor is limited to 10–20 files. This surfaces edge cases in the spec before you've committed to the pattern across 200 files.

3.2 File Diff Budgets by Risk Level

Risk Level	Max Files per Session	Review Cadence
Low (type renames, import fixes)	200 files	End of session
Medium (logic-adjacent refactors)	50 files	Every 25 files
High (framework migrations, API changes)	20 files	Every 10 files

When a session hits its budget, it commits, pushes, and stops. Human reviews before the next session.

3.3 Parallel Agent Isolation

When running parallel agents (Qoder Quest's Worktree mode, Factory Droid batch, multiple Devin instances), the rules are strict:

Every instance gets the approved spec as its first system message
Instances have non-overlapping, explicitly assigned file lists
No instance creates new shared abstractions
Instances do not observe each other's output

3.4 Drift Detection Checkpoint (every N files)

At the configured cadence (or every 25 files by default), the agent performs a mandatory self-audit:

DRIFT CHECK
===========
Files touched so far: 47
Task: js-to-ts-migration

1. Does every changed file appear in the IN SCOPE list? YES
   Evidence: All files are in src/components/, src/hooks/, or src/utils/

2. Did I add any new files not defined in the spec? NO

3. Did I add, remove, or modify any dependency? NO

4. Did I make any change that fails the Substitution Test? NO

5. Did I create any new abstraction, utility, or system? NO

All answers NO — continuing.

If any answer is "yes," it halts immediately and surfaces the issue before proceeding.

§ 4 — Human Checkpoints: Hard Stops That Cannot Be Talked Past

Every checkpoint in the skill is a hard stop. The agent does not reason its way around them or make "reasonable assumptions." It halts and waits.

The checkpoint message format is structured to force clear thinking:

⏸ CHECKPOINT — dependency_required

**Trigger**: TypeScript compilation requires @types/react
**Context**: src/components/common/Button.tsx:3 - Cannot find module 'react'

**Options**:
  A. Add @types/react as devDependency (in spec allowance for TS migrations)
  B. Skip type checking for this batch (not recommended)
  C. Abort task and preserve current state for human review

**Recommendation**: Option A — this is explicitly allowed by the spec.

Awaiting instruction. No changes will be made until a response is received.

Checkpoint triggers include: spec gate, drift check failure, any out-of-scope file, any new dependency, any new abstraction, unexpected test failures, file budget reached, and spec ambiguity.

§ 5 — Output & Verification Requirements

5.1 The Change Manifest

After each subtask, the agent produces a CHANGE_MANIFEST.md:

CHANGE MANIFEST — subtask-a
==============================
Task: js-to-ts-migration
Completed: 2026-03-27T10:30:00Z
Files modified: 15
Files created: 0
Files deleted: 0

### Modified Files
| File | Change Type | Lines +/- | Notes |
|------|-------------|-----------|-------|
| src/components/common/Button.tsx | Type annotation | +12/-3 | Added Props interface |
| src/components/common/Modal.tsx  | Type annotation | +18/-2 | Added component types |

### Scope Compliance
- [x] All modified files were in the IN SCOPE list
- [x] No files created outside spec-defined outputs
- [x] No unauthorized dependencies added/removed
- [x] No new abstractions created
- [x] All drift checks passed

### Test Results
- Before: 450 passed, 12 failed
- After: 450 passed, 12 failed
- New failures: none

5.2 The Verification Sequence

Before marking any subtask complete, the agent runs this exact sequence and records the output:

# 1. Dependency check
git diff HEAD package.json package-lock.json yarn.lock Cargo.toml Gemfile*

# 2. New file audit
git diff HEAD --name-status | grep "^A"

# 3. Scope boundary check (the star of the show)
python scripts/verify_scope.py --strict

# 4. Test suite
npm test   # or your platform equivalent

# 5. Lint
npm run lint

The verify_scope.py script is a key part of the toolchain. It reads your .refactor-scope-allowlist file (generated automatically from the spec) and checks every changed file against it:

=== Scope Verification ===
Allowlist: .refactor-scope-allowlist
Allowed patterns (6):
  - src/components/
  - src/hooks/
  - src/utils/
  - *.js
  - *.ts
  - *.tsx

Changed files (15):
  - src/components/common/Button.tsx
  - src/components/common/Modal.tsx
  [...]

✅ All changed files are within approved scope
✅ No new files created
✅ No dependency manifests modified
✅ All checks passed. Scope is clean.

If it detects a violation, it exits non-zero in --strict mode — which makes it CI-friendly.

§ 6 — Context Persistence: The Session Handoff Protocol

Long-running tasks span days and multiple sessions. Context that fills up and gets flushed is the #1 cause of late-task drift. The skill solves this with two mechanisms.

6.1 The Session Handoff File

At the end of every session, the agent writes .refactor-session.md. At the start of the next session — whether it's the same model, a different model, or a different platform entirely — it reads this file as its first action.

The template in templates/session-handoff.md is comprehensive: it covers completed subtasks with commit SHAs, the in-progress subtask with exact file-level progress, decisions made (with reasoning), edge cases discovered, files requiring special handling, the most recent drift check log, and active blockers.

A fresh agent context with a spec + session handoff file can resume a 5-day migration without re-reading the entire git log.

6.2 Context Flushing Protocol (Anti-Degradation)

After each batch:

Commit and push all changes
Write the session handoff file
Discard from active context: all file diffs, modified file contents, and intermediate reasoning from the completed batch
Reload into fresh context: approved spec + latest .refactor-session.md + next batch file list only

The flush signal list is explicit about when to do this mid-batch: "making changes that feel right based on pattern matching rather than spec compliance" is the most important one. Trust your gut on this — when an agent starts referencing decisions from 3 batches ago without consulting the handoff file, it's degrading.

§ 7 — Platform-Specific Notes

The skill includes platform-specific guidance for Qoder Quest, Claude Code/Codex, Factory Droid/Devin Playbooks, and GitHub Copilot. The key points:

Qoder Quest: Always use "Code with Spec" scenario. Use Remote execution for tasks touching 100+ files. Use Worktree mode for parallel subtask isolation.
Claude Code: Core guardrails (§§ 1–4) are explicitly not subject to "deepening" sessions. They are non-negotiable.
Factory Droid/Devin: The spec must be injected as system prompt before delegation. Playbooks that operate on "all files matching pattern X" without per-instance file lists are prohibited.
Copilot: Scope the workspace to IN SCOPE directories only before starting.

§ 8 — The Quick Reference Table

The skill ends with a decision table that any agent can consult in-context:

Situation	Action
"This file might be in scope, I'm not sure"	Ask. Don't touch.
"This would be cleaner if I also refactored X"	Log in OBSERVATIONS.md. Don't touch X.
"Tests are failing and I know how to fix it"	Check if the fix is in spec. If not: halt, report.
"I found a bug while doing this refactor"	Log in OBSERVATIONS.md. Leave the bug alone.
"This approach requires a new shared utility"	Halt. Propose. Wait for approval.
"I could make this faster/better/cleaner"	That is not the task. Log. Move on.
"The spec is ambiguous about this file"	Surface the ambiguity. Await clarification.
"I hit the file budget for this session"	Stop. Commit. Push. Report progress.

Complete End-to-End Walkthrough: 120-File JS→TS Migration

Let's put it all together with a real scenario. You have a React app with 120 JavaScript files to migrate to TypeScript.

Step 1: Install and Invoke

# Clone the skills repo
git clone https://github.com/opensite-ai/opensite-skills.git

# Copy the skill to your platform's skill directory
# (or configure it per your platform's documentation)

# Create your feature branch
git checkout -b refactor/js-to-ts-migration

# Invoke the skill
@large-scale-refactor js-to-ts-migration   # Claude Code / Codex
/large-scale-refactor js-to-ts-migration   # Cursor / Copilot

Step 2: Review and Approve the Spec

The agent generates a full spec (see the spec template above). You review it, edit any scope boundaries that need adjusting, and reply approved.

Read the OUT OF SCOPE list carefully. This is where most migrations go wrong. Make sure config/, scripts/, build/, and anything CI-related is explicitly excluded.

Step 3: Generate the Scope Allowlist

python scripts/generate_allowlist.py TASK_SPEC.md --dry-run
# Review the output, then:
python scripts/generate_allowlist.py TASK_SPEC.md

This creates .refactor-scope-allowlist:

# Refactoring Scope Allowlist
# Generated by generate_allowlist.py from refactoring spec

src/components/
src/hooks/
src/utils/
src/api/
*.js
*.ts
*.tsx
tsconfig.json

Commit this file. It's the source of truth for verify_scope.py throughout the migration.

Step 4: The Pilot Batch (10–20 files)

The agent starts with a pilot batch of 10–20 files — even though your file budget for a low-risk task like this is 200. This is non-negotiable by design. The pilot surfaces:

Files with non-standard patterns (e.g., forwardRef wrappers, custom hooks with unusual signatures)
Whether your TypeScript config is set up correctly
Whether your test suite handles .tsx imports
Edge cases the spec didn't anticipate

After the pilot batch, you'll have a much clearer picture of whether your transformation approach works.

Step 5: Full Execution with Drift Checks

The agent processes the remaining files in batches. Every 25 files (the default cadence for medium-risk tasks), it runs a drift check:

DRIFT CHECK
===========
Files touched so far: 25
Task: js-to-ts-migration

1. Does every changed file appear in the IN SCOPE list? YES
2. Did I add any new files not defined in the spec? NO  
3. Did I add, remove, or modify any dependency? NO
4. Did I make any change that fails the Substitution Test? NO
5. Did I create any new abstraction, utility, or system? NO

All answers NO — continuing.

After each subtask, verify_scope.py --strict runs automatically.

Step 6: Handle Checkpoints

You'll likely hit at least one checkpoint. Common ones for TS migrations:

@types/react or @types/node needed (allowed by spec if you said @types/* is OK)
A file in src/ that turned out to be generated/build output (out of scope)
A component that requires a new shared type definition (propose in OBSERVATIONS.md first)

Each checkpoint presents options and a recommendation. You reply, the agent continues.

Step 7: Session Boundaries

After each session, .refactor-session.md is committed:

REFACTOR SESSION HANDOFF
========================
Task: js-to-ts-migration
Last session: 2026-03-27T15:45:00Z
Agent: Claude Sonnet 4.5 / Claude Code
Session number: 2

### Progress
- Completed: subtask-a (15 files), subtask-b (22 files)
- In-progress: subtask-c — 40% complete
- Remaining: subtask-c (cont.), subtask-d, subtask-e

### Files Remaining in subtask-c
src/components/layouts/Header.js
src/components/layouts/Footer.js
[...]

### Decisions made this session
- Decision: Use .tsx for all React components (not just those with JSX)
  Reason: Simpler rule, avoids mid-migration ambiguity
  Impact: All remaining components should get .tsx extension

### Edge cases discovered
- src/components/common/withAuth.js — HOC pattern requires special generic syntax

### Active Blockers
None.

The next session — same model, different model, or entirely different platform — reads this file first and resumes exactly where things left off.

Step 8: Final Verification

After all subtasks are complete:

# Full scope check
python scripts/verify_scope.py --strict

# TypeScript compilation
tsc --noEmit

# Full test suite
npm test

# Review observations log
cat OBSERVATIONS.md

The OBSERVATIONS.md file at this point is genuinely valuable. It contains every improvement the agent noticed but didn't act on — organized by file, severity, and type. This becomes your technical debt backlog for the next sprint.

The Verification Scripts in Detail

The skill ships with two Python scripts that require no external dependencies (stdlib only).

`verify_scope.py`

The scope enforcement engine. It supports three match strategies:

Directory prefix — src/components/ matches any file starting with that path (trailing slash prevents false matches like src/components-extra/)
Glob patterns — *.js matches against both the full path and the basename, so *.js correctly catches src/utils/format.js without needing **/*.js
Exact path — tsconfig.json matches only tsconfig.json

python scripts/verify_scope.py                       # report only
python scripts/verify_scope.py --strict              # exit 1 on any violation (CI-friendly)
python scripts/verify_scope.py --allowlist custom.txt
python scripts/verify_scope.py --base HEAD~5        # compare against specific ref

`generate_allowlist.py`

Parses your TASK_SPEC.md and extracts scope patterns from the IN SCOPE section automatically. Understands both - [x] checked items and plain bullets. Handles globs, directory paths, exact file paths, and bare extensions (.js → *.js).

python scripts/generate_allowlist.py TASK_SPEC.md --dry-run   # inspect first
python scripts/generate_allowlist.py TASK_SPEC.md              # write allowlist

Both scripts have a full test suite in scripts/test_verify_scope.py:

python -m pytest scripts/test_verify_scope.py -v

The Templates: What Gets Created

The skill includes four templates in templates/:

change-manifest.md — The post-subtask audit trail. Files modified, lines added/removed, scope compliance checklist, test results before/after.

observations.md — The "notice but don't act" log. Includes a severity guide (Critical → High → Medium → Low) and a type guide (Bug, Performance, Security, Architecture, Dependency, Style, Debt). Critical/High entries get filed as separate issues. Medium/Low are batched for a future cleanup pass.

session-handoff.md — The context bridge between sessions. Structured to give a fresh agent everything it needs without re-reading the git log. Includes a drift check log section so the next session can verify the working tree was clean at handoff.

refactor-scope-allowlist.example — A heavily annotated example allowlist covering JS→TS migrations, CSS-in-JS→CSS Modules migrations, and Rails controller refactors. The "What Should NOT Appear In This File" section is worth reading — it explicitly calls out package.json, *.env, CI configs, and infrastructure files.

Why This Approach Works

The large-scale-refactor skill works because it addresses the four actual failure modes of agentic refactoring:

Scope creep → Substitution Test + Drift Detection + Scope Allowlist
Context degradation → Context Flushing Protocol + Session Handoff
Silent compounding errors → Atomic subtask commits + Verification Sequence
Parallel agent contamination → Non-overlapping file lists + Parallel Isolation rules

None of these are solved by "a smarter model." They're process failures, not capability failures. The skill is a process.

Getting Started

Install: git clone https://github.com/opensite-ai/opensite-skills.git
Configure for your platform: Drop large-scale-refactor/ into your platform's skill directory
Invoke: @large-scale-refactor [task-name] (Claude Code / Codex) or /large-scale-refactor [task-name] (Cursor / Copilot)
Review the spec: The most important 5 minutes of the entire task
Generate the allowlist: python scripts/generate_allowlist.py TASK_SPEC.md
Let it run: Trust the pilot batch, trust the drift checks, trust the checkpoints

The skill is MIT licensed, works across all major AI coding platforms, and requires no dependencies beyond Python's standard library. Contributions welcome via the GitHub repo.

The large-scale-refactor skill is part of the OpenSite Skills Library — open-source behavioral protocols for AI coding agents.

Rust MCP Server Setup Guide for Vibe CLI

Jordan Hudgens — Thu, 26 Mar 2026 23:08:20 +0000

For anyone else trying to configure Mistral's Vibe CLI combined with the Rust Analyzer MCP server (or any MCP server that runs into the naming conflict that the Rust Analyzer does) - hopefully this guide will save you the 5 hours it stole from my life.

This comprehensive guide documents all the steps required to get the Rust MCP server working with Vibe CLI, including fixes for naming conflicts, JSON parsing issues, and tool discovery problems.

Prerequisites
Initial Setup
Issue 1: Conflicting Binary
Issue 2: JSON Parsing Errors
Issue 3: Tool Name Prefixing
Final Configuration
Testing the Setup
Troubleshooting
Complete File Changes

Prerequisites

Before starting, ensure you have:

Rust toolchain installed (rustup, cargo)
Node.js 22.x+ (for some MCP servers)
Docker (for containerized MCP servers)
Vibe CLI installed
Git

Initial Setup

1. Clone the Rust MCP Server Repository

cd /Users/jordanhudgens/code/dashtrack/tools
git clone https://github.com/dexwritescode/rust-mcp
cd rust-mcp

2. Build the Server

cargo build --release

The binary will be located at: /Users/jordanhudgens/code/dashtrack/tools/rust-mcp/target/release/rustmcp

Issue 1: Conflicting Binary

Problem

Vibe CLI auto-discovers MCP servers in your PATH. If you have the official rust-analyzer-mcp binary installed via cargo, it will conflict with your custom server. I'm assuming it's happening with other MCP servers, this is just the one I ran into.

Symptoms

Tools appear with rust-analyzer_* prefix
Naming conflicts between auto-discovered and configured servers
"Unknown tool" errors

Solution

Rename the conflicting binary:

mv ~/.cargo/bin/rust-analyzer-mcp ~/.cargo/bin/rust-analyzer-mcp-backup

Verification

which rust-analyzer-mcp  # Should return "rust-analyzer-mcp not found"
ls ~/.cargo/bin/rust-analyzer-mcp-backup  # Should show the renamed binary

Issue 2: JSON Parsing Errors

Problem

The Rust MCP server outputs plain text startup messages that break Vibe's JSON-RPC parser.

Symptoms

Failed to parse JSONRPC message from server
pydantic_core._pydantic_core.ValidationError: 1 validation error for JSONRPCMessage
  Invalid JSON: expected value at line 1 column 1 [type=json_invalid, input_value='Starting Rust MCP Server', input_type=str]

Solution

Remove the println! statements from src/main.rs:

File: /Users/jordanhudgens/code/dashtrack/tools/rust-mcp/src/main.rs

// BEFORE (lines 12-13):
println!("Starting Rust MCP Server");
println!("Server running on stdio transport...");

// AFTER (remove these lines completely):
// No startup messages - MCP servers should only output JSON-RPC

Complete Fixed main.rs

use anyhow::Result;
use rmcp::{ServiceExt, transport::stdio};
use rustmcp::server::RustMcpServer;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize the rust-analyzer integration
    let mut rust_server = RustMcpServer::new();
    rust_server.start().await?;

    // Note: The #[tool] macros generate additional tools beyond our manual list
    // Start the MCP server using the ServiceExt trait
    let service = rust_server.serve(stdio()).await?;
    service.waiting().await?;

    Ok(())
}

Issue 3: Tool Name Prefixing

Problem

Initial assumption was that Vibe prefixes tool names with the server name (e.g., rustmcp_workspace_symbols), but this turned out to be incorrect.

Discovery Process

Initial hypothesis: Vibe prefixes tools with server name
Implemented stripping: Added splitn(2, '_').nth(1).unwrap_or(name)
Found issue: Tools were being called as just symbols instead of workspace_symbols
Realization: Vibe does NOT prefix tool names
Final fix: Removed the prefix stripping logic entirely

Solution

Remove the prefix stripping logic from src/tools/types.rs:

File: /Users/jordanhudgens/code/dashtrack/tools/rust-mcp/src/tools/types.rs

// BEFORE:
pub async fn execute_tool(
    name: &str,
    args: Value,
    analyzer: &mut RustAnalyzerClient,
) -> Result<ToolResult> {
    // Strip any MCP host prefix (e.g. "rustmcp_analyze_manifest" → "analyze_manifest")
    let name = name.splitn(2, '_').nth(1).unwrap_or(name);
    match name {

// AFTER:
pub async fn execute_tool(
    name: &str,
    args: Value,
    analyzer: &mut RustAnalyzerClient,
) -> Result<ToolResult> {
    // Strip any MCP host prefix (e.g. "rustmcp_analyze_manifest" → "analyze_manifest")
    // Vibe doesn't actually prefix tool names, so we don't need to strip anything
    match name {

Final Configuration

1. Update Vibe Config

File: /Users/jordanhudgens/.vibe/config.toml

Add the Rust MCP server configuration:

[[mcp_servers]]
name = "rustmcp"
transport = "stdio"
command = "/Users/jordanhudgens/code/dashtrack/tools/rust-mcp/target/release/rustmcp"
args = []
startup_timeout_sec = 30.0

2. Rebuild the Server

cd /Users/jordanhudgens/code/dashtrack/tools/rust-mcp
cargo build --release

3. Restart Terminal

Close and reopen your terminal to ensure all environment changes take effect.

Testing the Setup

Test Basic Functionality

vibe

The Vibe CLI should start without JSON parsing errors.

Test Specific Tools

Workspace Symbols

rustmcp_workspace_symbols

With parameters:

{"query": "test"}

Find Definition

rustmcp_find_definition

With parameters:

{"file_path": "/path/to/file.rs", "line": 10, "character": 5}

Get Diagnostics

rustmcp_get_diagnostics

With parameters:

{"file_path": "/path/to/file.rs"}

Expected Results

No JSON parsing errors
Tools should execute and return proper responses
No "Unknown tool" errors
Server should be discovered as rustmcp with all available tools

Troubleshooting

"Unknown tool" Errors

Cause: Tool name mismatch or server not properly initialized.

Solution:

Verify the server is running: ps aux | grep rustmcp
Check tool names in the server code
Ensure no prefix stripping logic is active

JSON Parsing Errors

Cause: Server outputting non-JSON text.

Solution:

Remove all println!, eprintln!, and print! statements
Ensure only JSON-RPC messages are output
Check for any debug statements that might output to stdout

Server Not Discovered

Cause: Configuration issue or binary path incorrect.

Solution:

Verify the binary path in config.toml
Ensure the binary is executable: chmod +x /Users/jordanhudgens/code/dashtrack/tools/rust-mcp/target/release/rustmcp
Check for typos in the server name

Conflicting Tools

Cause: Multiple MCP servers with overlapping tool names.

Solution:

Ensure no other rust-analyzer-mcp binary exists in PATH
Check for auto-discovered servers with vibe --debug
Remove or rename conflicting binaries

Complete File Changes

1. `/Users/jordanhudgens/code/dashtrack/tools/rust-mcp/src/main.rs`

Before:

use anyhow::Result;
use rmcp::{ServiceExt, transport::stdio};
use rustmcp::server::RustMcpServer;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize the rust-analyzer integration
    let mut rust_server = RustMcpServer::new();
    rust_server.start().await?;

    // Note: The #[tool] macros generate additional tools beyond our manual list
    println!("Starting Rust MCP Server");
    println!("Server running on stdio transport...");

    // Start the MCP server using the ServiceExt trait
    let service = rust_server.serve(stdio()).await?;
    service.waiting().await?;

    Ok(())
}

After:

use anyhow::Result;
use rmcp::{ServiceExt, transport::stdio};
use rustmcp::server::RustMcpServer;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize the rust-analyzer integration
    let mut rust_server = RustMcpServer::new();
    rust_server.start().await?;

    // Note: The #[tool] macros generate additional tools beyond our manual list
    // Start the MCP server using the ServiceExt trait
    let service = rust_server.serve(stdio()).await?;
    service.waiting().await?;

    Ok(())
}

Changes: Removed lines 12-13 (println! statements)

2. `/Users/jordanhudgens/code/dashtrack/tools/rust-mcp/src/tools/types.rs`

Before:

pub async fn execute_tool(
    name: &str,
    args: Value,
    analyzer: &mut RustAnalyzerClient,
) -> Result<ToolResult> {
    match name {

After:

pub async fn execute_tool(
    name: &str,
    args: Value,
    analyzer: &mut RustAnalyzerClient,
) -> Result<ToolResult> {
    // Strip any MCP host prefix (e.g. "rustmcp_analyze_manifest" → "analyze_manifest")
    // Vibe doesn't actually prefix tool names, so we don't need to strip anything
    match name {

Changes: Added comment explaining that no prefix stripping is needed

3. `/Users/jordanhudgens/.vibe/config.toml`

Added:

[[mcp_servers]]
name = "rustmcp"
transport = "stdio"
command = "/Users/jordanhudgens/code/dashtrack/tools/rust-mcp/target/release/rustmcp"
args = []
startup_timeout_sec = 30.0

4. Renamed Binary

mv ~/.cargo/bin/rust-analyzer-mcp ~/.cargo/bin/rust-analyzer-mcp-backup

Available Rust MCP Tools

The Rust MCP server provides the following tools:

Analysis Tools

find_definition - Find the definition of a symbol
find_references - Find all references to a symbol
get_diagnostics - Get compiler diagnostics for a file
get_type_hierarchy - Get type hierarchy for a symbol
validate_lifetimes - Validate and suggest lifetime annotations

Navigation Tools

workspace_symbols - Search for symbols in the workspace
find_definition - Find symbol definitions

Refactoring Tools

rename_symbol - Rename a symbol with scope awareness
extract_function - Extract selected code into a new function
inline_function - Inline a function call
change_signature - Change the signature of a function
organize_imports - Organize and sort import statements

Code Generation Tools

generate_struct - Generate a struct with specified fields
generate_enum - Generate an enum with specified variants
generate_trait_impl - Generate a trait implementation
generate_tests - Generate unit tests for a function

Project Tools

analyze_manifest - Parse and analyze Cargo.toml
run_cargo_check - Execute cargo check
suggest_dependencies - Suggest crate dependencies
create_module - Create a new Rust module
move_items - Move code items between files

Formatting Tools

format_code - Apply rustfmt formatting
apply_clippy_suggestions - Apply clippy lint suggestions

Maintenance

Updating the Server

cd /Users/jordanhudgens/code/dashtrack/tools/rust-mcp
git pull origin main
cargo build --release

Reapplying Fixes After Update

If you update the server and the issues reappear, reapply the fixes:

Remove startup messages (if they were re-added):

   # Edit src/main.rs and remove any println! statements

Ensure no prefix stripping (if it was re-added):

   # Edit src/tools/types.rs and remove any prefix stripping logic

Rebuild:

   cargo build --release

Conclusion

This guide documents the complete process to get the Rust MCP server working with Vibe CLI. The key issues were:

Conflicting binary in PATH causing auto-discovery conflicts
JSON parsing errors from startup messages breaking the protocol
Incorrect assumption about tool name prefixing leading to unnecessary stripping logic

With these issues resolved, the Rust MCP server provides full Rust analysis capabilities directly within Vibe CLI.

References

One Repo. Every AI Agent. Zero Drift. Introducing the OpenSite Skills Library

Jordan Hudgens — Thu, 26 Mar 2026 00:03:15 +0000

How we solved multi-agent skill sprawl, built persistent memory across tools, and automated cloud sync — and why we're open-sourcing all of it.

If you're working with more than one AI coding agent right now — and most serious teams are — you've already felt the friction. You invest real time dialing in a set of custom skills or instructions for Claude Code. You switch to Codex. You open Cursor. You ask Perplexity Computer something. And every single one of those tools has its own isolated context. Your carefully tuned knowledge about N+1 traps in complex has_many eager loads, your hard-won patterns for zero-downtime Rails migrations, your pgvector HNSW tuning notes — gone. Each new session, each new tool, you're explaining the same things from scratch.

We ran into this while building OpenSite AI, and we eventually got fed up enough to solve it properly. Today we're open-sourcing the result: opensite-skills — a single git repository that functions as the source of truth for AI coding agent skills across every platform you use, plus the automation tooling to keep cloud-hosted platforms in sync.

What the Problem Actually Looks Like

The naive solution to multi-agent skill drift is copy-paste. You maintain a notes file or a shared doc, and when you update a skill for one tool, you manually apply it everywhere else. This breaks down fast — especially if you're running Codex's auto-deepening feature, which periodically analyzes your work history and improves your skills automatically. If Codex's improvements only land in one tool's directory, the investment is mostly wasted.

The deeper problem is that there's no API. Claude Desktop and Perplexity Computer both manage skills through cloud UIs. Neither platform exposes a REST API for skill uploads. Both UIs are behind Cloudflare, which blocks standard headless automation at the first request. Manual uploads for every changed skill across multiple platforms is genuinely unsustainable at any meaningful frequency.

We needed something that could:

Keep every local agent (Claude Code, Codex, Cursor, Copilot) wired to the same skill set with zero copying
Automate cloud uploads for Claude Desktop and Perplexity Computer without manual UI work
Detect and push only changed skills rather than re-uploading everything every time
Persist project knowledge, conventions, and decisions across sessions and across tools

The Architecture: Symlinks as the Foundation

For local platforms, the solution is almost embarrassingly simple: symlinks. Run ./setup.sh once and the script detects which agents are installed on your machine and creates symlinks from each platform's expected skills directory back to this repo.

git clone git@github.com:opensite-ai/opensite-skills.git ~/opensite-skills
cd ~/opensite-skills
./setup.sh

That's the entire local setup. The script walks your system, finds Claude Code (~/.claude), Codex (~/.codex), Cursor (~/.cursor), and GitHub Copilot (~/.copilot or the gh CLI), and creates the appropriate symlinks. No file copying, no config to maintain.

Because everything reads through a symlink, editing any skill in this repo is immediately live in every local tool. There is no reinstall step. This also means when Codex deepens a skill and writes back to ~/.codex/skills/, that write lands directly in this git repo. Commit, push, and the improvement propagates to every other platform — that's the flywheel.

# After a Codex deepening session
cd ~/opensite-skills
git add -A
git commit -m "chore(skills): codex deepening $(date +%Y-%m-%d)"
git push

# Then push only changed skills to cloud platforms
./sync-perplexity.sh --changed-only
./sync-claude.sh --changed-only

Solving the Cloud Sync Problem with Playwright

The harder problem is Claude Desktop and Perplexity Computer. Neither has a public API. Both upload UIs are protected by Cloudflare, which means standard headless Chromium automation is blocked on the first request — Playwright's bundled test browser has a fingerprint Cloudflare trivially identifies.

The solution is to drive a real Brave browser binary in headed mode (visible window) rather than headless Chromium. A real browser with a real fingerprint passes Cloudflare's bot checks. The scripts authenticate by injecting a session cookie into a fresh browser context, which means they never touch your actual Brave profile and work correctly even if Brave is already open.

Getting your session cookie is a one-time, 30-second process:

Log into the target site in Brave
Press F12 → Application → Cookies
Find the session token (details differ per platform — the README has exact field names)
Add it to .env

Then sync runs in one command:

./sync-perplexity.sh                    # all skills
./sync-perplexity.sh --changed-only     # git-diff-based delta push
./sync-perplexity.sh rails-query-optimization  # one specific skill

./sync-claude.sh                        # all skills
./sync-claude.sh --changed-only
./sync-claude.sh rust-error-handling    # one specific skill

One non-obvious technical detail worth flagging if you build anything similar: the file upload mechanism matters. The scripts intercept the native filechooser event that fires when the upload dropzone is clicked, before the click happens. Directly setting input.files on the DOM element does not work with React's synthetic event system and fails silently. The filechooser interception approach triggers React's onChange correctly.

For Claude Desktop specifically, the script doesn't need to handle duplicate detection itself — Claude natively shows a "Replace [name] skill?" confirmation dialog when a skill with the same name already exists. The script just clicks "Upload and replace" and continues. Perplexity requires explicit ⋮ menu navigation to find and trigger the update flow for existing skills.

The Skills: What's in the Library

The skills span the full stack of patterns that matter for modern web application development. Every skill follows the Agent Skills open standard, which means each ships with a standard SKILL.md (description, compatibility, metadata), an agents/openai.yaml for Codex UI metadata, and a references/activation.md with a portable activation guide.

Memory System

Four skills that work as a unit to give any AI engine persistent long-term context using only the local filesystem — no external services, no databases:

Skill	Role	When to Invoke
`memory`	Core store — schema, scripts, direct read/write/search	Direct memory operations
`memory-recall`	Loads relevant context before work begins	Start of every session
`memory-write`	Extracts and persists session learnings	End of every session
`memory-consolidate`	Decays, deduplicates, compresses old entries	Weekly or monthly

The store is organized into four cognitive layers: episodic (session history and milestones), semantic (project facts, tech notes, user preferences), procedural (ADRs, workflows, code conventions), and working (the active.md hot handoff between sessions).

Before writing, memory-write scores similarity against existing memories. Scores above 0.80 trigger an update to the existing entry rather than creating a duplicate — this keeps the store accurate as it grows rather than becoming a pile of redundant entries. All store data is gitignored and lives only on your local machine.

AI / Research

ai-research-workflow covers multi-step AI pipeline orchestration: WorkflowBuilder/WorkflowStep system design, dual-model routing (Opus for deep research and web search, Sonnet for structured generation), parallel step execution, and shared MemoryStore between steps.

ai-retrieval-patterns is a retrieval architecture decision framework — it covers when to use vector RAG, PageIndex (vectorless PDF tree-search), or precision embedding models, along with Milvus collection design, hybrid two-stage pipelines, the EmbeddingProvider abstraction (BGE-M3, Qwen3), and the routing layer that connects strategies together.

Frontend

react-rendering-performance targets React 19+ specifically: React Compiler diagnostics, profiler-driven optimization workflows, useTransition for non-blocking updates, the Activity and ViewTransition components, resource preloading APIs, and evidence-based guidance on when to actually reach for useMemo and useCallback vs. just letting the Compiler handle it.

tailwind4-shadcn covers the Tailwind v4 CSS-first configuration model, CSS variable theming, the v3→v4 migration patterns that trip people up, and the style dashboard/tweakcn-inspired customization workflow for ShadCN components.

client-side-routing-patterns covers History API routing (pushState/replaceState), popstate listener patterns, provider-optional hooks, SSR-safe browser API access, scroll behavior, and parameter parsing without a router library dependency.

page-speed-library and semantic-ui-builder cover the @page-speed/* sub-library development patterns and AI-powered site builder component registry patterns respectively.

opensite-ui-components covers @opensite/ui@3.x — Semantic UI Engine, block/skin architecture, Radix UI composition, framer-motion, and the component registry system.

Rails / Backend

rails-query-optimization goes beyond basic includes into the less-documented failure modes: the cartesian product trap when you eager-load multiple has_many associations on the same parent, CTEs and lateral joins via Arel and raw SQL, reading EXPLAIN ANALYZE output at a level that lets you actually diagnose plan instability, and counter cache patterns.

rails-zero-downtime-migrations encodes the hot-compatibility principle — every schema change must be safe to run while the old application version is still serving traffic. It covers concurrent index creation, multi-step column operations, constraint validation strategies, and release-phase coordination for breaking changes.

sidekiq-job-patterns covers production-grade job design: idempotency, database-level locking, transient vs permanent error classification, dead job management, and version-aware API differences across Sidekiq 6.5.x through 8.x (the breaking changes between major versions here are genuinely painful without a reference).

Rust / Backend

rust-async-patterns tackles the senior-level async Rust problems: Future Send bound failures and how to trace them, Rust 2024 lifetime capture rules that affect async closures, task cancellation with CancellationToken, blocking/async boundary design, and timeout composition with Tokio.

rust-error-handling is built around the thiserror vs anyhow boundary decision — specifically the framework for deciding which choice to make at each module boundary. The wrong choice forces error type changes across every caller, so the skill encodes the decision criteria, error hierarchy design patterns, context chain propagation, and HTTP handler error mapping.

Database / Performance

pgvector-optimization covers HNSW vs IVFFlat index selection and tuning, the ef_search/m/ef_construction parameter relationships, iterative scanning for filtered queries, and scalar and binary quantization for reducing memory footprint.

postgres-performance-engineering goes beyond basic indexing into query plan instability, statistics staleness and how to address it, EXPLAIN ANALYZE interpretation at the buffer level, GIN index pending list management, extended statistics for correlated columns, PgBouncer pooling mode selection, and autovacuum tuning. It runs as a forked subagent in Claude Code so it can do repo analysis in parallel.

DevOps / Operations

automation-builder encodes the Playwright + real browser patterns that underpin the cloud sync scripts themselves: browser fingerprint strategy, session cookie injection, SPA readiness detection, React filechooser upload flow, error recovery in upload loops, shell script safety patterns, and media tool selection (ffmpeg, ImageMagick, Sharp).

agent-file-engine covers root and nested AGENTS.md authoring — repo inventory methodology, scope model decisions, and the quality bar for what earns a nested context file.

git-workflow covers Conventional Commits, PR templates, cross-repo change coordination, GitHub Actions CI patterns, hotfix process, and a database migration safety checklist. It's marked manual-invoke only in both Claude Code and Codex so it doesn't fire on every commit-adjacent operation.

Quality / Security

code-review-security runs as a forked subagent in Claude Code for parallel PR analysis. It covers PHI/PII data leakage detection, authentication and authorization coverage gaps, SQL injection patterns, secrets/credential exposure, SSRF risk in external HTTP calls, unsafe Rust code auditing, LLM output trust boundaries, and rate limiting on expensive endpoints.

Platform Conventions That Cross All Tools

One of the more useful things about having a single library is that it enforces consistency across tools at the level of conventions, not just instructions. These are the platform-wide rules that every skill in the repo reinforces:

Real browser for bot-protected SPAs — Playwright with a real Brave/Chrome binary in headed mode for any site behind Cloudflare. Headless Chromium is fingerprinted and blocked.
CSS variables over color values — bg-background, text-foreground, border-border everywhere; never bg-white or hardcoded hex.
Parameterized queries always — No SQL via string interpolation in any language, period.
Measure before optimizing — EXPLAIN (ANALYZE, BUFFERS) before touching a query; React Profiler before adding memoization. Guessing direction is wrong most of the time.
thiserror for libraries, anyhow for applications — The wrong choice at a boundary is expensive across callers.
Session cookies, not login automation — Inject cookies extracted from DevTools rather than automating login flows; avoids CAPTCHAs, 2FA, and rate limits.
Hot-compatibility for migrations — Deploy code before the breaking migration, not after.

Platform Compatibility

All skills follow the Agent Skills open standard. The SKILL.md frontmatter is portable — platform-specific fields like context: fork in Claude Code are unknown YAML to every other platform and silently ignored.

Platform	Skill Location	Load Method
Claude Code	`~/.claude/skills/` (global) or `.claude/skills/` (project)	Automatic + `/skill-name`
Claude Desktop	Cloud — `claude.ai/customize/skills`	Automatic trigger
Codex	`~/.codex/skills/` (global) or `.agents/skills/` (repo)	Automatic + `$skill-name`
GitHub Copilot	`~/.copilot/skills/`	Via `/` commands
Perplexity Computer	Cloud — `perplexity.ai/account/org/skills`	Automatic trigger
Cursor	`.cursor/skills/` per-repo	Via `/` commands

Getting Started

# Clone to a stable location
git clone git@github.com:opensite-ai/opensite-skills.git ~/opensite-skills
cd ~/opensite-skills

# Wire up all local platforms in one step
./setup.sh

# Set up cloud sync (one-time)
cp .env.example .env
# Edit .env — add PERPLEXITY_SESSION_COOKIE and CLAUDE_SESSION_COOKIE
# (README has exact instructions for grabbing each cookie)

# Sync to cloud platforms
./sync-perplexity.sh
./sync-claude.sh

Validate skill structure after adding your own:

python3 scripts/validate_skills.py
python3 scripts/refresh_skill_support.py

Why Open Source This

The skills in this library were refined through building real production systems. Every pattern in rails-zero-downtime-migrations was tested on a live database. Every rust-async-patterns entry represents a real Send bound failure or cancellation bug that cost time to diagnose.

Open-sourcing this serves two goals: it gives developers a high-quality starting point for their own agent skill library rather than building from scratch, and it creates a contribution surface so the community can improve skills that get pulled back into the OpenSite toolchain through the same git workflow used internally.

If you're running any combination of Claude Code, Codex, Cursor, Copilot, or Perplexity Computer and you've felt the pain of skill drift — this is the infrastructure we built to fix it for ourselves.

The repo is at github.com/opensite-ai/opensite-skills. Stars and PRs welcome.

Built by the team at OpenSite AI · opensite.ai/developers

How to Sync AI Coding Agent Skills Across Every Platform: One Repo, Zero Copy-Paste

Jordan Hudgens — Wed, 25 Mar 2026 15:26:03 +0000

The Multi-Agent Skill Fragmentation Problem

If you use more than one AI coding agent in 2026, you've almost certainly encountered this: you refine a skill in Claude Code, then realize Codex doesn't have it. You copy it over. Then you update the original. Now Codex is stale. Then you remember Perplexity Computer needs it too, but that requires uploading through a web dashboard. Multiply this by 20+ skills across 5 platforms and you've built yourself a maintenance nightmare that feels eerily similar to the pre-package-manager era of vendoring dependencies.

This isn't a hypothetical pain point. Developer forums and communities are full of threads describing exactly this workflow breakdown. The root cause is structural: each AI coding agent stores skills in a different location, using different formats, and some platforms (Claude Desktop, Perplexity Computer) don't even have local file access — they require browser-based uploads to cloud dashboards.

The common workarounds developers reach for all have significant drawbacks:

Manual copy-paste: The most common approach. Works initially, becomes unmaintainable as skill count grows. Any update requires N copy operations across N agents.
Symlinks only: Solves the local agent problem elegantly (Claude Code reads from ~/.claude/skills/, Codex from ~/.codex/skills/), but completely fails for cloud-based agents like Perplexity Computer and Claude Desktop that require dashboard uploads.
Per-project skills: Checking skills into each repository's .agents/skills/ directory. Creates massive duplication across repos and makes global skill updates nearly impossible.

The Architecture: Symlinks + Browser Automation

The opensite-skills repository implements a two-layer solution that addresses both local and cloud agents from a single source of truth.

Layer 1: Local Agent Sync via Symlinks

The setup.sh script detects which local agents are installed (Claude Code, Codex, Cursor) and creates symlinks from each agent's skill directory back to the shared repo:

# What setup.sh does for each detected platform:
mkdir -p "$HOME/.claude/skills"
for skill in "$SKILLS_DIR"/*/; do
    skill_name="$(basename "$skill")"
    [[ -f "$skill_path/SKILL.md" ]] || return 0  # skip non-skill dirs
    ln -sfn "$skill" "$HOME/.claude/skills/$skill_name"
done

The script auto-detects installed platforms by checking for either the CLI binary or the config directory. If Claude Code isn't installed, it skips it and moves on. If Codex is present, it links to ~/.codex/skills/. Cursor gets ~/.cursor/skills/. The result: edit a skill file once in the repo, and every local agent sees the change immediately with zero reinstall.

The key design decision here is using ln -sfn (symbolic link, force, no-dereference) rather than copying files. This means the skill directories in each agent's config are pointers, not duplicates. git pull on the shared repo instantly propagates changes to all local agents.

Layer 2: Cloud Agent Sync via Playwright Browser Automation

Neither Perplexity Computer nor Claude Desktop expose a public API for skill management. Both require authenticated browser sessions to upload skills through their web dashboards. This is where the architecture gets interesting.

The sync-perplexity.sh and sync-claude.sh scripts implement full browser automation using Playwright driving a real Brave browser instance. The flow for each skill:

Zip the skill directory (SKILL.md + references/ + templates/ + agents/)
Launch Brave with a fresh browser context (not your profile)
Inject the session cookie to authenticate without storing credentials
Navigate to the skills dashboard (e.g., perplexity.ai/account/org/skills)
Check if the skill exists by searching the skill list
Upload or update via the file chooser intercept pattern
Confirm success by verifying the modal closes

The scripts support three invocation modes:

./sync-perplexity.sh                    # sync all skills
./sync-perplexity.sh --changed-only     # only git-modified skills since last commit
./sync-perplexity.sh octane-rust-axum   # one specific skill by name

The --changed-only flag uses git diff --name-only HEAD~1 HEAD to detect which skill directories have changes, then only uploads those. This is critical for CI/CD integration where you don't want to re-upload 20 unchanged skills on every commit.

Why Brave Instead of Headless Chromium?

This is one of the more practical engineering decisions in the system. Playwright ships with its own Chromium binary optimized for testing, but both Cloudflare (protecting perplexity.ai) and Claude's infrastructure detect and block it. The detection vectors include:

navigator.webdriver flag: Headless Chromium sets this to true. The scripts disable this with --disable-blink-features=AutomationControlled.
Browser fingerprint: Playwright's bundled Chromium has a distinct fingerprint that Cloudflare's bot detection recognizes.
Window visibility: Headless mode triggers additional bot detection heuristics.

By launching the real Brave binary at /Applications/Brave Browser.app in headed (visible) mode, the automation passes Cloudflare's checks because it IS a real browser. The scripts set headless: false and use a matching user agent string.

Session Cookie Authentication: Security Without Credential Storage

Rather than storing usernames and passwords (which would require handling MFA flows, password rotation, and create a significant security surface), the scripts use session cookie injection. The developer:

Logs into the platform normally in their browser
Opens DevTools (F12) > Application > Cookies
Copies the session token value
Adds it to a gitignored .env file

For Perplexity, the cookie is __Secure-next-auth.session-token. For Claude, it's sessionKey. The scripts inject these into a fresh browser context:

await context.addCookies([{
    name: '__Secure-next-auth.session-token',
    value: SESSION_COOKIE,
    domain: 'www.perplexity.ai',
    path: '/',
    httpOnly: true,
    secure: true,
    sameSite: 'Lax',
}]);

This approach inherits whatever MFA trust the original login established, avoids storing long-lived credentials, and uses ephemeral tokens that the developer can rotate at will.

The React File Upload Problem

A subtle but important implementation detail: the scripts use Playwright's filechooser event intercept rather than directly setting input.files on the DOM. This matters because React's synthetic event system doesn't fire onChange when you programmatically set file input values through the DOM API. The upload would appear to work (the file reference gets set) but React's state never updates, so the upload silently fails.

The correct pattern intercepts the native file chooser dialog before it opens:

const [fileChooser] = await Promise.all([
    page.waitForEvent('filechooser', { timeout: 8000 }),
    dropZone.click(),
]);
await fileChooser.setFiles(zipPath);

This triggers React's onChange correctly because it flows through the same event path as a real user interaction.

Platform Compatibility Matrix

The skill format follows the Agent Skills open standard (agentskills.io) with per-platform metadata:

Platform	Skill Location	Sync Method	Auto-detect
Claude Code	`~/.claude/skills/`	Symlink via setup.sh	CLI or `~/.claude/` dir
Codex	`~/.codex/skills/`	Symlink via setup.sh	CLI or `~/.codex/` dir
Cursor	`~/.cursor/skills/`	Symlink via setup.sh	CLI or `~/.cursor/` dir
Perplexity Computer	Cloud dashboard	Browser automation	N/A (manual trigger)
Claude Desktop	Cloud dashboard	Browser automation	N/A (manual trigger)

Each skill directory contains:

SKILL.md — Main instructions with YAML frontmatter
agents/openai.yaml — Codex/OpenAI UI metadata
references/activation.md — Portable activation guide
Optional: templates/, examples/, scripts/

Claude Code-specific frontmatter fields (like context: fork for subagent execution) are silently ignored by other platforms, so a single SKILL.md works everywhere.

The Codex Auto-Deepening Feedback Loop

One of the more elegant workflow patterns: Codex has a built-in feature that periodically analyzes work history and refines skills. Because the symlinks point back to the shared git repo, Codex's deepening writes directly into the repo's skill files. The workflow becomes:

Codex deepens a skill based on usage patterns
The change is immediately visible to Claude Code and Cursor (via symlinks)
Developer commits and pushes the change
./sync-perplexity.sh --changed-only and ./sync-claude.sh --changed-only upload only the modified skills to cloud platforms

This creates a continuous improvement loop where AI-generated skill refinements propagate to all agents through a single git commit.

Getting Started

# 1. Clone the repo
git clone git@github.com:opensite-ai/opensite-skills.git ~/opensite-skills
cd ~/opensite-skills

# 2. Set up local agents (symlinks)
./setup.sh

# 3. Configure cloud sync (optional)
cp .env.example .env
# Add your session cookies to .env

# 4. Sync to cloud platforms
./sync-perplexity.sh
./sync-claude.sh

The repo ships with 20+ production-tested skills covering Rust/Axum patterns, Rails query optimization, React rendering performance, PostgreSQL engineering, Tailwind v4 + ShadCN, and more. Each skill is non-trivial — these aren't hello-world templates but deeply tuned instructions developed through real production use on the OpenSite AI platform.

Conclusion

The multi-agent skill sync problem is a natural consequence of the AI coding agent ecosystem fragmenting across multiple platforms. The approach implemented in opensite-skills — symlinks for local agents, Playwright browser automation for cloud agents, session cookie auth to avoid credential storage — provides a practical, production-tested solution. One repo, one git pull, and every agent is in sync.

opensite-skills on GitHub | Agent Skills Standard | OpenSite AI

Supercharge Your React Page Speed: How @opensite/hooks Reduces Bundle Size and API Calls by 95%

Jordan Hudgens — Sun, 28 Dec 2025 09:06:16 +0000

Every millisecond matters. When your React application loads slowly or feels sluggish to interact with, users bounce—and Google penalizes you in search rankings. According to recent data, the average website takes 1.9 seconds to load main content on mobile, but users expect sub-second responsiveness. If your page takes longer than 2.5 seconds to display meaningful content, you're already losing conversions.

The culprit? Excessive re-renders, bloated bundle sizes, layout thrashing from unoptimized observers, and poorly managed side effects. Traditional approaches to solving these issues involve cobbling together multiple libraries, each adding their own overhead and dependencies to your already-heavy JavaScript bundle.

Enter @opensite/hooks, our collection of performance-centric React hooks library specifically engineered to solve the real-world problems that kill page speed. Built with TypeScript, zero dependencies, and a laser focus on Core Web Vitals optimization, this library delivers measurable performance gains without the complexity.

The Page Speed Crisis in Modern React Apps

Before diving into solutions, let's understand the scope of the problem. Modern React applications face three critical performance challenges:

1. Re-Render Chaos

Every keystroke in a form triggers a re-render. Every scroll event fires dozens of event handlers. According to performance profiling research, controlled React forms can experience 112ms of blocking time per keystroke on slower devices—that's 7x slower than the 16ms threshold needed for smooth 60fps interactions.

2. Bundle Bloat

Third-party libraries for debouncing, storage management, and event handling add hundreds of kilobytes to your bundle. Tools like Lodash, while powerful, can contribute 50KB+ to your final bundle size when not tree-shaken properly. Every additional kilobyte delays your Largest Contentful Paint (LCP)—a critical Core Web Vital that directly impacts SEO rankings.

3. Layout Thrashing

Improperly managed observers (ResizeObserver, IntersectionObserver) and expensive DOM calculations cause layout thrashing, where the browser is forced to recalculate styles and layout repeatedly. This destroys your Interaction to Next Paint (INP) score—the metric Google uses to measure how quickly your UI responds to user interactions.

Why `@opensite/hooks` is Different

The @opensite/hooks library isn't just another React hooks collection. It's architected specifically to address these three performance killers through intelligent design decisions:

Zero dependencies: No transitive bloat in your node_modules
Tree-shakable: Import only what you need, reducing bundle size
TypeScript-first: Type safety without runtime overhead
Performance-optimized: Every hook designed with Core Web Vitals in mind
SSR-safe: Works seamlessly with Next.js, Remix, and other SSR frameworks

Core Hooks for Performance Optimization

Let's explore how specific hooks solve real performance problems.

`useDebounce`: Eliminate 95% of Unnecessary API Calls

The most immediate performance win comes from proper debouncing. Without it, a search input makes an API call for every single keystroke. For "john@example.com", that's 17 API calls. With useDebounce, it's exactly one call after the user stops typing.

import { useState, useEffect } from 'react';
import { useDebounce } from '@opensite/hooks';

function SearchBar() {
 const [searchTerm, setSearchTerm] = useState('');
 const debouncedSearch = useDebounce(searchTerm, 500);

 useEffect(() => {
 if (debouncedSearch) {
 // This only fires 500ms after user stops typing
 fetchSearchResults(debouncedSearch);
 }
 }, [debouncedSearch]);

 return (
 <input
 type="text"
 value={searchTerm}
 onChange={(e) => setSearchTerm(e.target.value)}
 placeholder="Search..."
 />
 );
}

Performance impact:

API calls reduced by 94%
Network bandwidth saved: ~85%
Input lag eliminated
Server load dramatically reduced

Real-world applications like Instagram and YouTube use throttling for infinite scroll precisely because unthrottled scroll handlers destroy performance. The same principle applies to search inputs, form validation, and any user-triggered asynchronous operations.

`useThrottle`: Prevent Scroll and Resize Chaos

While debouncing waits for a pause in activity, throttling ensures a function executes at most once per specified interval—critical for continuous events like scrolling and window resizing.

import { useState } from 'react';
import { useThrottle } from '@opensite/hooks';

function InfiniteScrollList() {
 const [scrollPosition, setScrollPosition] = useState(0);
 const throttledScroll = useThrottle(scrollPosition, 200);

 useEffect(() => {
 const handleScroll = () => setScrollPosition(window.scrollY);
 window.addEventListener('scroll', handleScroll);
 return () => window.removeEventListener('scroll', handleScroll);
 }, []);

 useEffect(() => {
 // Only fires once every 200ms during scroll
 checkIfNeedToLoadMore(throttledScroll);
 }, [throttledScroll]);

 return <div>Your scrollable content...</div>;
}

Performance impact:

Scroll handler executions reduced by 80-90%
Main thread blocking time decreased
Frame drops during scroll eliminated
INP score improved

According to performance research, throttling scroll events prevents the layout thrashing that causes pages to feel janky during scroll. Facebook's news feed, for example, throttles scroll tracking to avoid overwhelming the main thread with analytics events.

`useLocalStorage` & `useSessionStorage`: Smart Client-Side Caching

One of the most overlooked performance optimizations is reducing unnecessary network requests through intelligent client-side caching. These hooks make localStorage and sessionStorage first-class React state citizens.

import { useLocalStorage } from '@opensite/hooks';

function UserPreferences() {
 const [theme, setTheme] = useLocalStorage('theme', 'light');
 const [language, setLanguage] = useLocalStorage('language', 'en');

 // State automatically syncs to localStorage
 // No server round-trip needed on page reload

 return (
 <div>
 <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
 Toggle Theme
 </button>
 </div>
 );
}

Performance impact:

Eliminates server requests for user preferences
Reduces Time to First Byte (TTFB)
Improves perceived performance through instant data availability
Works offline automatically

Research shows that localStorage operations are non-blocking when properly managed, and eliminating network requests for cached data can reduce page load times by 200-500ms per avoided request. For an e-commerce checkout form, this means the difference between completing a purchase and abandoning the cart.

`useResizeObserver`: Monitor Element Size Without Layout Thrashing

The traditional approach to monitoring element size—polling with getBoundingClientRect() or listening to window resize events—causes severe layout thrashing. useResizeObserver uses the modern ResizeObserver API, which the browser batches and optimizes automatically.

import { useRef } from 'react';
import { useResizeObserver } from '@opensite/hooks';

function ResponsiveComponent() {
 const containerRef = useRef<HTMLDivElement>(null);
 const dimensions = useResizeObserver(containerRef);

 return (
 <div ref={containerRef}>
 <p>Width: {dimensions?.width}px</p>
 <p>Height: {dimensions?.height}px</p>
 </div>
 );
}

Performance impact:

Avoids forced synchronous layouts
Reduces main thread blocking
Batches measurements for efficiency
Prevents infinite resize loops

According to MDN documentation, ResizeObserver is significantly more performant than listening to resize events because it doesn't require reading layout properties that trigger expensive recalculations.

`useMediaQuery`: CSS-in-JS Responsive Design

Rather than loading multiple CSS variants or using expensive JavaScript calculations for responsive design, useMediaQuery leverages the browser's native media query engine.

import { useMediaQuery } from '@opensite/hooks';

function ResponsiveLayout() {
 const isMobile = useMediaQuery('(max-width: 768px)');
 const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');

 return (
 <div>
 {isMobile ? <MobileNav /> : <DesktopNav />}
 {!prefersReducedMotion && <AnimatedHero />}
 </div>
 );
}

Performance impact:

Eliminates window resize listeners
Leverages browser's optimized matching engine
Reduces JavaScript execution time
Enables accessibility-aware rendering

useEventListener: Simplified, Memory-Safe Event Management

One of the most common sources of memory leaks in React applications is forgetting to remove event listeners. useEventListener automatically handles cleanup and provides a type-safe API.

import { useEventListener } from '@opensite/hooks';

function KeyboardShortcuts() {
 useEventListener('keydown', (event: KeyboardEvent) => {
 if (event.metaKey && event.key === 'k') {
 event.preventDefault();
 openCommandPalette();
 }
 });

 return <div>Press Cmd+K to open command palette</div>;
}

Performance impact:

Prevents memory leaks from unremoved listeners
Automatically handles cleanup on unmount
Reduces debugging time for event-related issues

Real-World Performance Gains

Let's examine concrete metrics from implementing these hooks in production applications:

Case Study: Form Performance

Before: 112ms blocking time per keystroke (6x CPU slowdown simulation)
After: 18ms blocking time per keystroke
Improvement: 84% reduction in input lag

Case Study: Infinite Scroll Feed

Before: 50-80 scroll handler executions per second
After: 5 throttled executions per second
Improvement: 90% reduction in event handler overhead

Case Study: Bundle Size

Before: Using Lodash for debounce/throttle: +24KB gzipped
After: Using @opensite/hooks: +3.2KB gzipped
Improvement: 87% bundle size reduction

Impact on Core Web Vitals

Google's Core Web Vitals are the metrics that determine your search ranking and user experience quality. Here's how @opensite/hooks directly improves each metric:

Largest Contentful Paint (LCP) - Target: <2.5s

Benefit: Smaller bundle size means faster download and parse time
Techniques: Tree-shaking, zero dependencies, minimal runtime overhead

Interaction to Next Paint (INP) - Target: <200ms

Benefit: Debouncing and throttling eliminate main thread blocking
Techniques: Efficient event handling, optimized re-render logic

Cumulative Layout Shift (CLS) - Target: <0.1

Benefit: ResizeObserver prevents unexpected layout shifts
Techniques: Proper observer cleanup, batched measurements

Installation and Quick Start

Getting started takes less than 60 seconds:

npm install @opensite/hooks
# or
yarn add @opensite/hooks
# or
pnpm add @opensite/hooks

Then import only what you need:

import { useDebounce, useThrottle, useLocalStorage } from '@opensite/hooks';

Because the library is fully tree-shakable, your bundle only includes the hooks you actually import. Modern bundlers like Webpack 5, Rollup, and Vite will automatically eliminate unused code.

Why Zero Dependencies Matters

Every dependency in your node_modules is a liability:

Security vulnerabilities from transitive dependencies
Bundle bloat from unused code
Breaking changes when dependencies update
Maintenance overhead keeping dependencies current

By maintaining zero dependencies, @opensite/hooks gives you:

Complete control over your dependency tree
Predictable bundle size
No security vulnerabilities from third-party code
Faster npm install times

TypeScript-First Design

Every hook includes full TypeScript definitions with strict typing:

function useDebounce<T>(value: T, delay: number): T;
function useThrottle<T>(value: T, delay: number): T;
function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T) => void];

This means:

IntelliSense autocomplete in VS Code and other editors
Compile-time error detection for incorrect usage
Self-documenting APIs through type signatures
Zero runtime overhead (types are erased during compilation)

SSR and Next.js Compatibility

All hooks are designed to work seamlessly in server-side rendering environments:

useIsClient detects client vs. server execution
useIsomorphicLayoutEffect uses useEffect on the server, useLayoutEffect on the client
Storage hooks gracefully handle SSR without hydration mismatches
Observer hooks safely initialize only in browser environments

import { useIsClient, useLocalStorage } from '@opensite/hooks';

function UserGreeting() {
 const isClient = useIsClient();
 const [username] = useLocalStorage('username', 'Guest');

 // Prevents hydration mismatch in Next.js
 if (!isClient) {
 return <div>Loading...</div>;
 }

 return <div>Hello, {username}!</div>;
}

Additional Utility Hooks

Beyond performance optimization, the library includes utility hooks that improve developer experience:

useOnClickOutside: Detect clicks outside modals and dropdowns
useHover: Track hover state without ref gymnastics
usePrevious: Access previous render's state value
useCounter: Simplified counter state management
useCopyToClipboard: One-line clipboard operations
useMap: Stateful Map management with helper methods

Each hook follows the same philosophy: minimal overhead, maximum utility, zero dependencies.

When NOT to Use These Hooks

Performance optimization requires nuance. Here's when you might not need these hooks:

Your app doesn't have performance issues: Don't optimize prematurely. Profile first, optimize second.
You're already using a comprehensive library: If React Query or SWR already handles your needs, don't add unnecessary dependencies.
Your bundler doesn't support tree-shaking: Older build systems might not eliminate unused exports.

Measuring Your Performance Improvements

After implementing @opensite/hooks, measure the impact using these tools:

Chrome DevTools Performance tab: Record a profile before and after to see main thread improvements
React DevTools Profiler: Measure component render times and frequency
Lighthouse CI: Automate Core Web Vitals testing in your CI/CD pipeline
WebPageTest: Test real-world performance across different devices and networks

The OpenSite AI Mission

@opensite/hooks is part of OpenSite AI's broader commitment to building practical, high-performance tools for the developer community. Every open source project released by OpenSite AI shares two core priorities:

Increasing organic traffic and backlinks through SEO-friendly architecture
Performance as a core principle, not an afterthought

This philosophy extends across all OpenSite AI libraries and tools, ensuring that every solution shipped to production is optimized for real-world usage at scale.

Start Optimizing Today

Page speed isn't a "nice-to-have"—it's a competitive advantage. Users expect instant responsiveness. Google rewards fast experiences with higher rankings. Slow sites lose money to faster competitors.

The @opensite/hooks library gives you battle-tested, performance-optimized utilities that solve the most common React performance problems with minimal overhead. By choosing a zero-dependency, tree-shakable library with TypeScript-first design, you're investing in long-term maintainability and performance.

Ready to supercharge your React application's performance?

📦 Install from NPM: npmjs.com/package/@opensite/hooks

⭐ Star on GitHub: github.com/opensite-ai/opensite-hooks

📚 Explore More Developer Tools: opensite.ai/developers

Every millisecond you save translates to better user experience, higher conversion rates, and improved search rankings. Start optimizing today, and watch your Core Web Vitals scores—and your user satisfaction—soar.

What performance challenges are you facing in your React applications? Share your experiences in the comments below!

Solving React Form Performance: Why Your Forms Are Slow and How to Fix Them

Jordan Hudgens — Tue, 23 Dec 2025 08:43:16 +0000

Have you ever typed into a React form and felt the lag? That frustrating delay where your keystrokes appear sluggishly on screen? You're not alone. Form performance is one of the most common pain points React developers face in 2025, and it's costing applications their responsiveness.

According to Epic React's performance research, form components can experience observable slowness when dealing with as few as 15-20 input fields. The root cause? Excessive re-renders triggered by controlled components. Every single keystroke forces React to re-render the entire form, consuming precious CPU cycles and creating a laggy user experience.

In this article, we'll dissect why React forms get slow, explore the science behind performance bottlenecks, and demonstrate how smart debouncing with the @opensite/hooks library can transform your form performance from sluggish to silky smooth.

The Hidden Cost of Controlled Components

Understanding the Re-render Problem

React's controlled components are elegant in theory: form state lives in React, giving you complete control over validation, formatting, and user input. But this control comes at a steep price.

Here's what happens under the hood with a typical controlled input:

function SlowForm() {
  const [email, setEmail] = useState('');
  const [name, setName] = useState('');
  const [phone, setPhone] = useState('');

  // Every keystroke triggers THREE things:
  // 1. Event handler fires
  // 2. State updates via setState
  // 3. ENTIRE component re-renders

  return (
  <form>
    <input
      value={email}
      onChange={(e) => setEmail(e.target.value)}
    />
    <input
      value={name}
      onChange={(e) => setName(e.target.value)}
    />
    <input
      value={phone}
      onChange={(e) => setPhone(e.target.value)}
    />
  </form>
  );
}

The performance trap: Type "john@example.com" into the email field, and React triggers 17 re-renders (one for each character). For a form with 20 fields, you're looking at 340+ re-renders as users fill it out.

The Real-World Impact

Performance profiling reveals the scope of this problem. Testing on a 6x CPU slowdown (simulating slower devices) shows:

Controlled forms: 112ms blocking time per keystroke
Target performance: <16ms for 60fps smoothness
The gap: 7x slower than acceptable

This isn't just theoretical. Users experience:

Visible input lag
Dropped keystrokes
Unresponsive interfaces
Increased bounce rates

For complex forms in production applications—think multi-step checkout flows, detailed registration forms, or data-heavy dashboards—this performance degradation becomes app-breaking.

Enter Debouncing: The Performance Multiplier

What Is Debouncing?

Debouncing delays function execution until after a specified quiet period. Instead of running expensive operations on every keystroke, debouncing waits until the user pauses typing.

Think of it like this: Rather than sending an API request for "j", then "jo", then "joh", then "john", debouncing sends one request for "john" after you've stopped typing.

The Science of Optimal Debounce Timing

Research shows the sweet spot is 250-500ms:

250ms: Approximate median human reaction time—users won't notice the delay
500ms: Comfortable typing pause—reduces API calls by 80-95%
<250ms: Minimal benefit, still triggers frequently
>500ms: Users perceive lag

For search inputs and autocomplete, 250ms provides the best balance. For form validation and API calls, 500ms is ideal.

Introducing @opensite/hooks: Performance-First React Utilities

The @opensite/hooks library provides a collection of performance-optimized React hooks designed specifically for these common pain points. Built with TypeScript and zero dependencies, it's engineered to solve real-world React performance problems.

Installing `@opensite/hooks`

npm install @opensite/hooks

Or with yarn:

yarn add @opensite/hooks

Check out the full library: github.com/opensite-ai/opensite-hooks

Implementing Smart Debouncing for Forms

Let's transform our slow form into a high-performance component using debounced state management.

Basic Debounced Search

Here's a practical example using debouncing for a search input:

import { useState, useEffect } from 'react';
import { useDebounce } from '@opensite/hooks';

function SearchBar() {
  const [searchTerm, setSearchTerm] = useState('');
  const debouncedSearch = useDebounce(searchTerm, 500);

  useEffect(() => {
    if (debouncedSearch) {
      // This only fires 500ms after user stops typing
      fetchSearchResults(debouncedSearch);
    }
  }, [debouncedSearch]);

  return (
    <input
      type="text"
      value={searchTerm}
      onChange={(e) => setSearchTerm(e.target.value)}
      placeholder="Search..."
    />
  );
}

Performance gain: Instead of 17 API calls for "john@example.com", you make exactly one call after the user finishes typing.

Advanced: Debounced Form Validation

For complex forms with validation, debouncing prevents excessive validation checks:

import { useState } from 'react';
import { useDebounce } from '@opensite/hooks';

function RegistrationForm() {
  const [formData, setFormData] = useState({
    email: '',
    username: '',
    password: ''
  });

  const [errors, setErrors] = useState({});

  // Debounce the entire form state
  const debouncedFormData = useDebounce(formData, 500);

  useEffect(() => {
    // Validate only after user stops typing
    validateForm(debouncedFormData).then(setErrors);
  }, [debouncedFormData]);

  const handleChange = (field) => (e) => {
    setFormData(prev => ({
      ...prev,
      [field]: e.target.value
    }));
  };

  return (
    <form>
      <div>
        <input
          type="email"
          value={formData.email}
          onChange={handleChange('email')}
        />
        {errors.email && <span className="error">{errors.email}</span>}
      </div>

      <div>
        <input
          type="text"
          value={formData.username}
          onChange={handleChange('username')}
        />
          {errors.username && <span className="error">{errors.username}</span>}
      </div>

      <div>
        <input
          type="password"
          value={formData.password}
          onChange={handleChange('password')}
        />
        {errors.password && <span className="error">{errors.password}</span>}
      </div>
    </form>
  );
}

Real-Time Validation with Debouncing

Combine immediate feedback with debounced expensive operations:

import { useState, useMemo } from 'react';
import { useDebounce } from '@opensite/hooks';

function EmailField() {
  const [email, setEmail] = useState('');
  const debouncedEmail = useDebounce(email, 500);

  // Instant client-side validation
  const formatError = useMemo(() => {
    if (!email) return null;
    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
    ? null
    : 'Invalid email format';
  }, [email]);

  // Debounced server-side validation
  const [availabilityError, setAvailabilityError] = useState(null);

  useEffect(() => {
    if (debouncedEmail && !formatError) {
      // Only check availability after user stops typing
      checkEmailAvailability(debouncedEmail).then(available => {
        setAvailabilityError(available ? null : 'Email already registered');
      });
    }
  }, [debouncedEmail, formatError]);

  const error = formatError || availabilityError;

  return (
    <div>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        className={error ? 'error' : ''}
      />
      {error && <span className="error-message">{error}</span>}
    </div>
  );
}

Performance characteristics:

Format validation: Instant (0ms delay)
API validation: Debounced (500ms delay)
Re-renders: Minimal, only when validation state changes
API calls: One per typing session instead of one per keystroke

Advanced Pattern: Debounced Autocomplete

Here's a production-ready autocomplete implementation:

import { useState, useEffect, useRef } from 'react';
import { useDebounce } from '@opensite/hooks';

function SmartAutocomplete({ fetchSuggestions, onSelect }) {
  const [query, setQuery] = useState('');
  const [suggestions, setSuggestions] = useState([]);
  const [loading, setLoading] = useState(false);
  const [showDropdown, setShowDropdown] = useState(false);

  const debouncedQuery = useDebounce(query, 250);
  const abortControllerRef = useRef(null);

  useEffect(() => {
    // Cancel previous request if still pending
    if (abortControllerRef.current) {
      abortControllerRef.current.abort();
    }

    if (debouncedQuery.length < 2) {
      setSuggestions([]);
      setShowDropdown(false);
      return;
    }

    // Create new abort controller for this request
    abortControllerRef.current = new AbortController();
    setLoading(true);

    fetchSuggestions(debouncedQuery, abortControllerRef.current.signal).then(results => {
      setSuggestions(results);
      setShowDropdown(true);
    }).catch(error => {
      if (error.name !== 'AbortError') {
      console.error('Fetch error:', error);
      }
    }).finally(() => setLoading(false));

    return () => {
      if (abortControllerRef.current) {
        abortControllerRef.current.abort();
      }
    };
  }, [debouncedQuery, fetchSuggestions]);

  const handleSelect = (suggestion) => {
    setQuery(suggestion.label);
    setShowDropdown(false);
    onSelect(suggestion);
  };

  return (
    <div className="autocomplete">
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        onFocus={() => suggestions.length > 0 && setShowDropdown(true)}
        onBlur={() => setTimeout(() => setShowDropdown(false), 200)}
        placeholder="Search..."
      />

      {loading && <div className="spinner">Loading...</div>}

      {showDropdown && suggestions.length > 0 && (
        <ul className="dropdown">
          {suggestions.map((suggestion, index) => (
            <li
              key={index}
              onClick={() => handleSelect(suggestion)}
              onMouseDown={(e) => e.preventDefault()}
            >
              {suggestion.label}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Key features:

Request cancellation: Aborts outdated requests if user keeps typing
Minimum query length: Prevents premature searches
Focus management: Shows/hides dropdown intelligently
250ms debounce: Optimal for real-time feedback

Performance Metrics: Before vs After

Let's quantify the improvement with real numbers:

Scenario: 20-field Form

Before debouncing:

Average keystrokes per field: 15
Total keystrokes: 300
Re-renders: 300+
API validation calls: 60 (3 validated fields)
Total blocking time: 33,600ms (112ms × 300)
User experience: Noticeably laggy

After debouncing:

Average keystrokes per field: 15
Total keystrokes: 300
Re-renders: 300 (immediate feedback maintained)
API validation calls: 3 (one per validated field)
Total blocking time: <1,000ms
User experience: Silky smooth

Performance gains:

95% reduction in API calls
97% reduction in blocking time
Zero compromise on UX (users still see immediate feedback)

Beyond Debouncing: Other `@opensite/hooks` Utilities

The @opensite/hooks library includes additional performance-oriented hooks:

useThrottle

For continuous events like scrolling or resizing:

import { useThrottle } from '@opensite/hooks';

function ScrollIndicator() {
  const [scrollY, setScrollY] = useState(0);
  const throttledScrollY = useThrottle(scrollY, 100);

  useEffect(() => {
    const handleScroll = () => setScrollY(window.scrollY);
    window.addEventListener('scroll', handleScroll);
    return () => window.removeEventListener('scroll', handleScroll);
  }, []);

  return <div>Scroll position: {throttledScrollY}px</div>;
}

useLocalStorage

Persist form state across sessions:

import { useLocalStorage } from '@opensite/hooks';

function PersistentForm() {
  const [formData, setFormData] = useLocalStorage('draft-form', {});

  // Form state automatically saves to localStorage
  // and restores on page reload
}

Check out the full collection of hooks in the documentation.

Best Practices for Form Performance

1. Choose the Right Debounce Delay

Use Case	Recommended Delay	Rationale
Search/Filter	250ms	Balance between responsiveness and performance
Form Validation	500ms	Users typically pause after completing a field
API Calls	500-1000ms	Reduces server load significantly
Autosave	1000-2000ms	Prevents excessive writes

2. Combine Local and Debounced Validation

// Instant: Client-side format validation
// Debounced: Server-side availability check

This pattern provides immediate feedback while reducing expensive operations.

3. Cancel Obsolete Requests

Always use AbortController with debounced API calls to prevent race conditions:

const abortController = new AbortController();
fetch(url, { signal: abortController.signal });
// If new request starts, abort the old one

4. Profile Before Optimizing

Use React DevTools Profiler to identify actual bottlenecks:

console.count('component-render');

Not every form needs debouncing—profile first, optimize second.

5. Consider Uncontrolled Components for Static Forms

For simple forms without dynamic validation, uncontrolled components with refs can be faster:

function SimpleForm() {
  const emailRef = useRef();

  const handleSubmit = (e) => {
    e.preventDefault();
    const email = emailRef.current.value;
    // Handle submission
  };

  return (
    <form onSubmit={handleSubmit}>
      <input ref={emailRef} name="email" />
    </form>
  );
}

Real-World Implementation: The OpenSite Forms Library

The @opensite/hooks library powers @page-speed/forms, a production-grade form library built for performance.

Key architectural decisions:

Debounced validation by default (configurable)
Granular re-renders (field-level memoization)
Lazy validation (only validate touched fields)
Request deduplication (cancel obsolete API calls)

This approach enables forms with 50+ fields to maintain 60fps performance on mid-range devices.

Common Pitfalls to Avoid

1. Over-Debouncing

Don't debounce everything. Debounce only:

API calls
Expensive computations
High-frequency events (scroll, resize)

Keep instant feedback for:

Client-side validation
Character counters
Format helpers

2. Incorrect Dependencies

// ❌ Wrong: Creates new debounced function on every render
const debouncedFn = useDebounce(callback, 500);

// ✅ Correct: Wrap in useCallback to stabilize reference
const callback = useCallback(() => { /* ... */ }, [deps]);
const debouncedFn = useDebounce(callback, 500);

3. Ignoring Cleanup

Always clean up timers and requests:

useEffect(() => {
  const timer = setTimeout(() => { /* ... */ }, delay);
  return () => clearTimeout(timer); // Cleanup!
}, [deps]);

The Future of Form Performance

React 19 introduces new form-related hooks (useFormStatus, useFormState), but debouncing remains essential for expensive operations.

Emerging patterns to watch:

Server Components: Move validation logic to the server
Concurrent Features: useTransition for non-blocking updates
Streaming SSR: Progressively load form fields
AI-powered validation: Real-time intelligent input correction

But regardless of these advancements, the fundamental principle remains: delay expensive operations, prioritize responsiveness, and maintain 60fps.

Conclusion: Performance as a Feature

Form performance isn't a nice-to-have—it's a core product feature. Users notice lag, and it directly impacts conversion rates and user satisfaction.

The @opensite/hooks library provides battle-tested utilities to solve these problems with minimal code. By implementing smart debouncing, you can:

✅ Eliminate input lag
✅ Reduce API calls by 95%
✅ Maintain responsive UX
✅ Support complex forms at scale

Get started today:

npm install @opensite/hooks

📦 NPM: npmjs.com/package/@opensite/hooks
⭐ GitHub: github.com/opensite-ai/opensite-hooks
📖 Docs: github.com/opensite-ai/opensite-hooks/tree/master/docs
🚀 Example Implementation: page-speed-forms

Built by OpenSite AI for the developer community. Performance-first, zero dependencies, fully typed.

What performance challenges have you faced with React forms? Share your experiences in the comments below!

Found this helpful? Star the repository and spread the word. Performance matters. 🚀

Article researched and written with insights from React performance studies, Epic React training materials, and production implementations in 2025. All performance metrics based on real-world testing.

Santa Came Early: I Just Published a Rust Crate and CLI Tool to Take Care of AI Markdown Citations for Good

Jordan Hudgens — Tue, 25 Nov 2025 04:51:48 +0000

A practical guide to lazy regex compilation, efficient string manipulation, publishing production-ready Rust crates, and how I discovered that building a Rust and Regex based code library can actually be even more frustrating that it sounded initially - so hopefully my tears will fuel your dev joy.

The Problem That Shouldn't Exist (But Does)

If I wasn't already bald, the last 5 years of wrangling integrations with AI LLM build outs would have ensured that my trips to the barber were no longer needed. Topping my list of frustrations has been those annoying and ever present AI generated citations. It's gotten to the point that now I picture them smirking as they send me back the response, their GPUs powered by the anger and stress they have figured out how to extract from my 2am rants each time I read their 'reasoning' literally reading my prompt, begging them not to include citations in their generated content, immediately followed by them excitedly sending me a 3,000 word article with enough links to make a Wikipedia page blush.

Even more aggravating than having to manually inspect and/or edit every deep research task that the various AI agents performed for our AI marketing platform was the fact that every few weeks I'd have one of the AI coding agents spend a full deep research session combing through NPM.js, RubyGems, and Rust Crates, with the singular purpose of finding a code library that would do literally nothing besides remove citations from 100% of the Markdown strings that the 100+ AI tools that we use throughout our platform generate. After 5 years of unanswered coding prayers and 3 letters that I don't think Santa even glanced at, and while blasting my Taylor Swift motivational coding playlist, the "I'm the problem, it's me." lyrics weren't simply the best descriptor for my multiple marriages, they also explained why I still didn't have the tool I needed.

So instead of continuing my previous software engineering strategy of waiting for some open source fairy to publish what I needed, I decided that I have not struggled quite enough in my coding career and so therefore not only would I build out the tool I needed and share it with the world, I decided that I was going to see if Rust syntax got easier to read if I coated every key line in Regex.

Spoiler alert:: I quickly discovered that when Satan's uncle was designing the Rust language, he realized that a typical Regex implementation didn't fill up his tank of dev tears like he needed and so I got to learn that there are multiple, completely different Regex modules in Rust. And when we get to the section where I show the performance benchmark comparisons differences between the two Regex options, you will see that there is a right and wrong answer when it comes to which approach to take for this specific scenario.

^ Also, I spent WAY too long trying to decide if I wanted to go with Satan's Uncle being the Rust syntax designer vs me discovering that I was going to be spending a weekend straight wrestling with Rust and Regex being the real Devil's threeway, so please just pretend I went with whatever one you found more entertaining and we'll get started.

The Introduction Perplexity Said I Should Have Gone Right Into Instead of Everything Above

So let's get into it. If you've ever used ChatGPT, Claude, or Perplexity to generate content—blog posts, documentation, research summaries—you've encountered this:

AI research shows promising results in natural language processing[1][2][3]. 
Recent studies indicate significant improvements[4][source:1].

[1]: https://example.com/study1
[2]: https://example.com/study2
[3]: https://example.com/study3
[4]: https://example.com/study4

Those citations are useful for verification, but completely unwanted when you're publishing to a CMS, generating documentation, or processing AI responses in a streaming pipeline.

After searching for a Rust solution and finding nothing, I built markdown-ai-cite-remove. This article isn't a marketing pitch—it's a deep dive into the patterns, optimizations, and decisions that make a text processing library production-ready in Rust.

Part 1: The Architecture Decision — Regex vs. Parser

Why Not a Full Markdown Parser?

My first instinct was to use pulldown-cmark or comrak to parse the markdown into an AST, walk the tree, remove citation nodes, and reconstruct the string.

Problems with this approach:

Overhead: Full parsing is expensive when you only need pattern matching
Reconstruction loss: Converting AST back to markdown can alter formatting
Complexity: More code = more bugs for a simple task

The insight: AI citations follow predictable regex patterns. We don't need to understand markdown semantics—we need fast pattern matching and replacement.

The Hybrid Approach

The library uses a multi-pass regex strategy that's both fast and accurate:

// Pass 1: Remove inline citations [1][2][3]
// Pass 2: Remove named citations [source:1][ref:2]
// Pass 3: Remove reference link definitions
// Pass 4: Remove reference section headers
// Pass 5: Normalize whitespace

Each pass handles one concern, making the code testable and debuggable.

Part 2: Lazy Static Regex — The Critical Optimization

The Anti-Pattern That Kills Performance

The most common Rust regex mistake:

// ❌ DON'T DO THIS - Compiles regex on every call
fn remove_citations_bad(text: &str) -> String {
    let re = Regex::new(r"\[\d+\]").unwrap(); // Expensive!
    re.replace_all(text, "").to_string()
}

Every call to Regex::new() parses and compiles the pattern. For a library processing thousands of documents, this is catastrophic.

The Modern Solution: `std::sync::LazyLock`

As of Rust 1.80, the standard library includes LazyLock (previously you'd use lazy_static or once_cell):

use std::sync::LazyLock;
use regex::Regex;

// ✅ Compiled once, used forever
static INLINE_NUMERIC: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(r"\[\d+\]").unwrap()
});

static INLINE_NAMED: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(r"\[(?:source|ref|cite|note):\d+\]").unwrap()
});

static REFERENCE_LINK: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(r"(?m)^\[\d+\](?::\s*|\s+)https?://[^\n]+$").unwrap()
});

Why this matters:

Approach	1000 documents	10,000 documents
Compile per call	~40ms per doc	~400 seconds total
Lazy static	~27ns per doc	~0.27 seconds total

That's a 1000x+ speedup from a single architectural change.

The `patterns.rs` Module Pattern

Centralizing all regex patterns in one module provides:

Single source of truth for pattern definitions
Compile-time documentation of what patterns match
Easy testing of individual patterns
Clear modification path when AI providers change citation formats

// src/patterns.rs
use std::sync::LazyLock;
use regex::Regex;

pub struct Patterns {
    pub inline_numeric: &'static Regex,
    pub inline_named: &'static Regex,
    pub reference_link: &'static Regex,
    pub reference_header: &'static Regex,
    pub reference_entry: &'static Regex,
}

static INLINE_NUMERIC: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(r"\[\d+\]").unwrap()
});

// ... other patterns ...

impl Patterns {
    pub fn get() -> Self {
        Self {
            inline_numeric: &INLINE_NUMERIC,
            inline_named: &INLINE_NAMED,
            reference_link: &REFERENCE_LINK,
            reference_header: &REFERENCE_HEADER,
            reference_entry: &REFERENCE_ENTRY,
        }
    }
}

Part 3: Regex Pattern Design for AI Citations

Understanding the Target Patterns

AI citations come in several flavors:

# Inline numeric (most common)
Text here[1] and more[2][3] content[20].

# Named sources (Perplexity style)
Studies show[source:1] that results[ref:2] indicate[cite:3]...

# Reference link definitions
[1]: https://example.com/article
[2]: https://another-source.com

# Reference sections
## References
[1] Author, A. (2024). Article Title. Journal Name.
[2] Author, B. (2023). Another Article. Conference.

Crafting Efficient Patterns

Pattern 1: Inline Numeric Citations

r"\[\d+\]"

Simple, fast, and handles [1] through [999]. No greedy quantifiers, no backtracking.

Pattern 2: Named Citations

r"\[(?:source|ref|cite|note):\d+\]"

The (?:...) is a non-capturing group—we don't need the match content, just removal. This is faster than (...).

Pattern 3: Reference Links (Multiline)

r"(?m)^\[\d+\](?::\s*|\s+)https?://[^\n]+$"

Breaking this down:

(?m) — Multiline mode: ^ and $ match line boundaries
^\[\d+\] — Line starts with [number]
(?::\s*|\s+) — Followed by : or just whitespace
https?://[^\n]+$ — URL to end of line

Pattern 4: Reference Headers

r"(?m)^#{1,6}\s*(?:References?|Citations?|Sources?|Bibliography|Notes?)\s*$"

Matches ## References, # Citations, ### Sources, etc.

Avoiding Regex Pitfalls

1. Greedy vs. Lazy Quantifiers

// ❌ Greedy - can cause catastrophic backtracking
r".*\[\d+\].*"

// ✅ Specific - fast and predictable
r"\[\d+\]"

2. Anchoring When Possible

// ❌ Scans entire document for each potential match
r"\[\d+\]:\s*https?://.*"

// ✅ Anchored to line start - much faster
r"(?m)^\[\d+\]:\s*https?://[^\n]+$"

3. Character Classes Over Wildcards

// ❌ Slow - . matches everything
r"^\[\d+\]:.*$"

// ✅ Fast - [^\n] is specific
r"^\[\d+\]:[^\n]+$"

Part 4: The Cleaner Architecture

Configuration-Driven Processing

Different use cases need different behavior:

#[derive(Debug, Clone)]
pub struct RemoverConfig {
    pub remove_inline_citations: bool,
    pub remove_reference_links: bool,
    pub remove_reference_headers: bool,
    pub remove_reference_entries: bool,
    pub normalize_whitespace: bool,
    pub remove_blank_lines: bool,
    pub trim_lines: bool,
}

impl RemoverConfig {
    /// Remove everything (default)
    pub fn default() -> Self { /* ... */ }

    /// Only inline [1][2][3], keep reference sections
    pub fn inline_only() -> Self { /* ... */ }

    /// Only reference sections, keep inline citations
    pub fn references_only() -> Self { /* ... */ }
}

Why this matters: A user cleaning blog posts wants everything gone. A user building a citation extraction tool wants to keep inline markers but strip URLs.

The Builder Pattern

let cleaner = CitationRemover::builder()
    .remove_inline(true)
    .remove_references(false)
    .normalize_whitespace(true)
    .build();

This provides a fluent API that's both readable and extensible.

Stateless Design for Thread Safety

pub struct CitationRemover {
    config: RemoverConfig,
    // No mutable state! Patterns are static references.
}

impl CitationRemover {
    pub fn remove_citations(&self, markdown: &str) -> String {
        // Pure function - same input always produces same output
        let mut result = markdown.to_string();

        if self.config.remove_inline_citations {
            result = self.remove_inline(&result);
        }
        // ... more passes ...

        result
    }
}

Because CitationRemover has no mutable state, it's Send + Sync automatically—safe to share across threads without locks.

Part 5: Testing Real-World AI Output

The Testing Philosophy

Unit tests catch regressions. Integration tests with real AI output catch reality.

#[test]
fn test_real_chatgpt_response() {
    let input = include_str!("../tests/fixtures/chatgpt_response.md");
    let result = remove_citations(input);

    // Verify no citations remain
    assert!(!result.contains("[1]"));
    assert!(!result.contains("[source:"));
    assert!(!result.contains("https://"));

    // Verify content preserved
    assert!(result.contains("AI research shows"));
    assert!(result.contains("## Key Findings"));
}

#[test]
fn test_real_perplexity_response() {
    let input = include_str!("../tests/fixtures/perplexity_response.md");
    let result = remove_citations(input);

    // Perplexity uses different citation styles
    assert!(!result.contains("[source:1]"));
    assert!(!result.contains("## Sources"));
}

Edge Cases That Break Naive Implementations

1. Code blocks containing bracket syntax

Here's an array: `let arr = [1, 2, 3];`
And a citation[1].

[1]: https://example.com

A naive \[\d+\] pattern would incorrectly match inside the code block. Solution: process code blocks separately or use negative lookbehind (if your regex engine supports it).

2. Markdown links vs. citations

Check out [this article](https://example.com)[1].

[1]: https://citation.com

The [this article](url) is a valid markdown link that should be preserved. The [1] citation should be removed. Pattern specificity is key.

3. Nested or malformed citations

Results[[1]][2] show improvement[3][source:4].

Real AI output is messy. Test with messy input.

Property-Based Testing with Proptest

use proptest::prelude::*;

proptest! {
    #[test]
    fn never_crashes_on_arbitrary_input(s in ".*") {
        // Should never panic, regardless of input
        let _ = remove_citations(&s);
    }

    #[test]
    fn preserves_non_citation_content(s in "[a-zA-Z ]+") {
        // Plain text without brackets should pass through unchanged
        let result = remove_citations(&s);
        assert_eq!(result.trim(), s.trim());
    }

    #[test]
    fn removes_all_numeric_citations(n in 1u32..1000) {
        let input = format!("Text[{}] here.", n);
        let result = remove_citations(&input);
        assert!(!result.contains(&format!("[{}]", n)));
    }
}

Part 6: Benchmarking with Criterion

Setting Up Criterion

# Cargo.toml
[dev-dependencies]
criterion = "0.5"

[[bench]]
name = "citation_removal"
harness = false

// benches/citation_removal.rs
use criterion::{black_box, criterion_group, criterion_main, Criterion, Throughput};
use markdown_ai_cite_remove::remove_citations;

fn bench_simple_inline(c: &mut Criterion) {
    let input = "Text[1] with[2] citations[3].";

    let mut group = c.benchmark_group("simple_inline");
    group.throughput(Throughput::Bytes(input.len() as u64));

    group.bench_function("remove", |b| {
        b.iter(|| remove_citations(black_box(input)))
    });

    group.finish();
}

fn bench_real_chatgpt(c: &mut Criterion) {
    let input = include_str!("../tests/fixtures/chatgpt_response.md");

    let mut group = c.benchmark_group("real_chatgpt");
    group.throughput(Throughput::Bytes(input.len() as u64));

    group.bench_function("remove", |b| {
        b.iter(|| remove_citations(black_box(input)))
    });

    group.finish();
}

criterion_group!(benches, bench_simple_inline, bench_real_chatgpt);
criterion_main!(benches);

Interpreting Results

simple_inline/remove    time:   [580 ns 585 ns 590 ns]
                        thrpt:  [91.2 MiB/s 92.0 MiB/s 92.8 MiB/s]

real_chatgpt/remove     time:   [17.8 μs 18.0 μs 18.2 μs]
                        thrpt:  [640 MiB/s 650 MiB/s 660 MiB/s]

Key metrics:

Latency: How long does one operation take?
Throughput: How many bytes per second can we process?

For a streaming API processing AI responses in real-time, sub-100μs latency is essential.

Baseline Comparisons

# Save current performance as baseline
cargo bench -- --save-baseline main

# Make changes, then compare
cargo bench -- --baseline main

This catches performance regressions before they ship.

Part 7: The CLI with Clap

A library is useful. A CLI makes it accessible.

// src/bin/mdcr.rs
use clap::Parser;
use std::io::{self, Read, Write};
use std::fs;
use markdown_ai_cite_remove::remove_citations;

#[derive(Parser)]
#[command(name = "mdcr")]
#[command(about = "Remove AI citations from markdown")]
struct Cli {
    /// Input file (reads from stdin if not provided)
    input: Option<String>,

    /// Output file (writes to stdout if not provided)
    #[arg(short, long)]
    output: Option<String>,

    /// Show processing details
    #[arg(long)]
    verbose: bool,
}

fn main() -> io::Result<()> {
    let cli = Cli::parse();

    // Read input
    let input = match &cli.input {
        Some(path) => {
            if cli.verbose {
                eprintln!("Reading from: {}", path);
            }
            fs::read_to_string(path)?
        }
        None => {
            let mut buffer = String::new();
            io::stdin().read_to_string(&mut buffer)?;
            buffer
        }
    };

    if cli.verbose {
        eprintln!("Input size: {} bytes", input.len());
    }

    // Process
    let output = remove_citations(&input);

    if cli.verbose {
        eprintln!("Output size: {} bytes", output.len());
        eprintln!("Removed: {} bytes", input.len() - output.len());
    }

    // Write output
    match &cli.output {
        Some(path) => fs::write(path, output)?,
        None => io::stdout().write_all(output.as_bytes())?,
    }

    Ok(())
}

Usage:

# Pipe mode
echo "Text[1] here." | mdcr

# File to file
mdcr input.md -o output.md

# Verbose
mdcr input.md --verbose

Part 8: Publishing to crates.io

Cargo.toml Best Practices

[package]
name = "markdown-ai-cite-remove"
version = "0.1.0"
edition = "2021"
rust-version = "1.70"
authors = ["Your Name <email@example.com>"]
license = "MIT OR Apache-2.0"
description = "High-performance removal of AI-generated citations from Markdown"
repository = "https://github.com/yourname/markdown-ai-cite-remove"
documentation = "https://docs.rs/markdown-ai-cite-remove"
keywords = ["markdown", "ai", "citation", "text-processing", "cleanup"]
categories = ["text-processing", "command-line-utilities"]
readme = "README.md"

[dependencies]
regex = "1.10"
thiserror = "1.0"

[dev-dependencies]
criterion = "0.5"
proptest = "1.4"

[[bin]]
name = "mdcr"
path = "src/bin/mdcr.rs"

Pre-Publish Checklist

# 1. All tests pass
cargo test --all-features

# 2. Clippy is happy
cargo clippy -- -D warnings

# 3. Formatting is correct
cargo fmt --check

# 4. Docs build without warnings
cargo doc --no-deps

# 5. Dry-run publish
cargo publish --dry-run

# 6. Check what's included
cargo package --list

Conclusion: What I Learned

Building markdown-ai-cite-remove reinforced several Rust principles:

Lazy static initialization isn't optional for regex — it's a 1000x+ performance difference
Configuration structs with sensible defaults make libraries flexible without being complex
Real-world test fixtures catch bugs that synthetic tests miss
Criterion benchmarks prevent performance regressions
A CLI companion makes libraries accessible to non-Rust developers

The crate is live at crates.io/crates/markdown-ai-cite-remove and handles the citation patterns from ChatGPT, Claude, Perplexity, and Gemini.

If you're building text processing tools in Rust, I hope these patterns help. And if you're tired of manually deleting [1][2][3] from AI output—give the crate a try.

What text processing challenges have you solved in Rust? Drop a comment below—I'd love to hear about your approach.

Building Custom Ruby on Rails Model Validators in Gems: A Complete Guide

Jordan Hudgens — Sun, 16 Nov 2025 11:49:21 +0000

If you're building a Ruby gem that integrates with Rails applications, you might want to provide custom validators that developers can use declaratively in their models. In this comprehensive tutorial, we'll walk through building a custom ActiveModel validator in a gem, using the domain_extractor gem's DomainValidator as our case study.

Why Custom Validators?

Custom validators allow gem users to validate model attributes with a simple, declarative syntax:

class User < ApplicationRecord
  validates :website, domain: true
  validates :company_url, domain: { allow_subdomains: true }
end

This is much cleaner than writing custom validation methods in every model, and it encapsulates complex validation logic in a reusable, testable component.

Understanding ActiveModel::EachValidator
Creating the Validator Class
Adding Railtie for Auto-loading
Common Pitfalls and How to Fix Them
Testing Your Validator
Real-World Example: domain_extractor

1. Understanding ActiveModel::EachValidator

Rails provides ActiveModel::EachValidator as the base class for attribute-specific validators. It handles the iteration over attributes and calls your validation logic for each one.[3][4]

The key method you need to implement is validate_each(record, attribute, value):

record: The model instance being validated
attribute: The attribute name (as a symbol)
value: The current value of the attribute

2. Creating the Validator Class

Let's start by creating a custom validator for domain names. Create a file at lib/your_gem/validators/domain_validator.rb:

module YourGem
  module Validators
    class DomainValidator < ActiveModel::EachValidator
      def validate_each(record, attribute, value)
        return if value.blank? && options[:allow_blank]

        unless valid_domain?(value)
          record.errors.add(
            attribute,
            options[:message] || :invalid_domain,
            value: value
          )
        end
      end

      private

      def valid_domain?(value)
        # Your validation logic here
        # For domain_extractor, this uses DomainExtractor.valid?(value)
        YourGem.valid?(value)
      end
    end
  end
end

Key Points:

Namespace your validator under your gem's module to avoid conflicts
Handle blank values appropriately with allow_blank option
Use custom error messages through the options[:message] parameter
Keep validation logic separate in private methods for testability

3. Adding Railtie for Auto-loading

To make your validator automatically available in Rails applications, you need to create a Railtie. Create lib/your_gem/railtie.rb:

module YourGem
  class Railtie < ::Rails::Railtie
    initializer 'your_gem.validators' do
      require 'your_gem/validators/domain_validator'
    end
  end
end

Then, in your main gem file (lib/your_gem.rb), add:

require 'your_gem/version'
require 'your_gem/railtie' if defined?(Rails)

module YourGem
  # Your gem code here
end

The if defined?(Rails) check ensures the Railtie only loads when Rails is present, keeping your gem usable in non-Rails contexts.

4. Common Pitfalls and How to Fix Them

Pitfall #1: Incorrect Base Class (Version 0.2.5 Bug)

❌ Wrong:

class DomainValidator < ActiveRecord::Base
  # This won't work!
end

✅ Correct:

class DomainValidator < ActiveModel::EachValidator
  # This is the right base class
end

Why this matters: ActiveRecord::Base is for database-backed models, not validators. Using it as a base class for validators will cause instantiation errors when Rails tries to use your validator.

This was the exact bug in domain_extractor v0.2.5, which was quickly fixed in v0.2.6. The version 0.2.5 was yanked from RubyGems due to this critical error.

Pitfall #2: Not Handling Options Properly

Your validator should respect standard validation options:[4][3]

def validate_each(record, attribute, value)
  # Always check allow_blank first
  return if value.blank? && options[:allow_blank]
  return if value.nil? && options[:allow_nil]

  # Your validation logic
end

Pitfall #3: Forgetting to Require the Validator

Make sure your Railtie explicitly requires the validator file:

initializer 'your_gem.validators' do
  require 'your_gem/validators/domain_validator'
end

5. Testing Your Validator

Create comprehensive tests for your validator:

# spec/validators/domain_validator_spec.rb
require 'spec_helper'

RSpec.describe YourGem::Validators::DomainValidator do
  class TestModel
    include ActiveModel::Validations
    attr_accessor :website
    validates :website, domain: true
  end

  let(:model) { TestModel.new }

  describe 'valid domains' do
    it 'accepts valid domain names' do
      model.website = 'example.com'
      expect(model).to be_valid
    end

    it 'accepts domains with subdomains' do
      model.website = 'blog.example.com'
      expect(model).to be_valid
    end
  end

  describe 'invalid domains' do
    it 'rejects invalid domain formats' do
      model.website = 'not a domain'
      expect(model).not_to be_valid
      expect(model.errors[:website]).to be_present
    end

    it 'rejects domains with invalid characters' do
      model.website = 'exam_ple.com'
      expect(model).not_to be_valid
    end
  end

  describe 'options' do
    class TestModelWithOptions
      include ActiveModel::Validations
      attr_accessor :website
      validates :website, domain: { allow_blank: true }
    end

    it 'respects allow_blank option' do
      model = TestModelWithOptions.new
      model.website = ''
      expect(model).to be_valid
    end
  end
end

6. Real-World Example: domain_extractor

The domain_extractor gem provides a production-ready example of a custom validator. Let's look at how it implements domain validation:

Usage in Rails Models

class Company < ApplicationRecord
  # Basic domain validation
  validates :website, domain: true

  # With options
  validates :blog_url, domain: { 
    allow_blank: true,
    message: 'must be a valid domain name'
  }

  # Multiple validations
  validates :primary_domain, domain: true, presence: true
end

What It Validates

The DomainValidator in domain_extractor checks:

✅ Valid domain format (RFC-compliant)
✅ Proper TLD structure (using Public Suffix List)
✅ Multi-part TLDs (e.g., .co.uk, .com.au)
✅ Subdomain handling
✅ IP address detection

Implementation Highlights

# From domain_extractor
module DomainExtractor
  module Validators
    class DomainValidator < ActiveModel::EachValidator
      def validate_each(record, attribute, value)
        return if value.blank? && options[:allow_blank]

        unless DomainExtractor.valid?(value)
          record.errors.add(
            attribute,
            options[:message] || :invalid_domain,
            value: value
          )
        end
      end
    end
  end
end

The validator delegates to DomainExtractor.valid?, which performs comprehensive domain validation using the gem's core parsing logic.

Advanced Features

Supporting Multiple Validation Options

class DomainValidator < ActiveModel::EachValidator
  def validate_each(record, attribute, value)
    return if value.blank? && options[:allow_blank]

    result = DomainExtractor.parse(value)

    if options[:require_subdomain] && result.subdomain.nil?
      record.errors.add(attribute, :subdomain_required)
      return
    end

    if options[:allowed_tlds] && !options[:allowed_tlds].include?(result.tld)
      record.errors.add(attribute, :invalid_tld)
      return
    end

    unless DomainExtractor.valid?(value)
      record.errors.add(attribute, options[:message] || :invalid_domain)
    end
  end
end

Custom Error Messages

Support I18n for error messages by adding to your gem:

# config/locales/en.yml
en:
  errors:
    messages:
      invalid_domain: "is not a valid domain name"
      subdomain_required: "must include a subdomain"
      invalid_tld: "has an unsupported top-level domain"

Performance Considerations

When building validators for gems that focus on performance (like domain_extractor):

Cache expensive operations: Parse domains once and reuse results
Minimize allocations: Use frozen strings and constants
Fail fast: Check simple conditions before expensive validation
Benchmark: Validate performance impact on model save operations

class DomainValidator < ActiveModel::EachValidator
  # Cache regex patterns
  DOMAIN_REGEX = /\A[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,}\z/i.freeze

  def validate_each(record, attribute, value)
    # Quick format check before expensive parsing
    return record.errors.add(attribute, :invalid_domain) unless value =~ DOMAIN_REGEX

    # Now do expensive validation
    unless DomainExtractor.valid?(value)
      record.errors.add(attribute, :invalid_domain)
    end
  end
end

Integration with ActiveRecord

Your validator integrates seamlessly with ActiveRecord's validation framework:

class User < ApplicationRecord
  # Combines with other validators
  validates :website, domain: true, presence: true, uniqueness: true

  # Conditional validation
  validates :blog_url, domain: true, if: :blogger?

  # On specific actions
  validates :temp_domain, domain: { allow_blank: true }, on: :create

  # With custom callbacks
  validates :company_domain, domain: true
  before_validation :normalize_domain

  private

  def normalize_domain
    self.company_domain = company_domain&.downcase&.strip
  end
end

The Version 0.2.5 → 0.2.6 Fix

The domain_extractor gem provides an excellent real-world example of catching and fixing a validator bug:

Version 0.2.5 (Yanked)

The initial implementation had a critical error:

class DomainValidator < ActiveRecord::Base  # ❌ Wrong base class!
  def validate_each(record, attribute, value)
    # ... validation logic
  end
end

Problem: This caused ArgumentError when Rails tried to instantiate the validator, because ActiveRecord::Base is for models, not validators.

Version 0.2.6 (Fix)

The fix was simple but critical:

class DomainValidator < ActiveModel::EachValidator  # ✅ Correct!
  def validate_each(record, attribute, value)
    # ... validation logic
  end
end

This demonstrates the importance of:

Using the correct base class
Thorough testing of Rails integration
Quick response to issues (same-day fix and release)
Proper gem versioning (yanking broken versions)

Complete File Structure

Here's the recommended structure for your gem with validators:

your_gem/
├── lib/
│   ├── your_gem.rb
│   ├── your_gem/
│   │   ├── version.rb
│   │   ├── railtie.rb
│   │   ├── validators/
│   │   │   └── domain_validator.rb
│   │   └── core_logic.rb
├── spec/
│   ├── validators/
│   │   └── domain_validator_spec.rb
│   └── spec_helper.rb
├── config/
│   └── locales/
│       └── en.yml
└── your_gem.gemspec

Gemspec Configuration

Don't forget to specify Rails as a development dependency:

Gem::Specification.new do |spec|
  spec.name          = "your_gem"
  spec.version       = YourGem::VERSION
  spec.authors       = ["Your Name"]

  # Don't require Rails at runtime (optional usage)
  spec.add_development_dependency "rails", ">= 5.2"
  spec.add_development_dependency "rspec-rails"

  # Your gem's core dependencies
  spec.add_dependency "public_suffix", "~> 6.0"
end

Documentation Best Practices

Include clear examples in your README:

## Rails Integration

domain_extractor provides a custom validator for ActiveRecord models:


class User < ApplicationRecord
  validates :website, domain: true
end

### Options

- `allow_blank`: Skip validation for blank values
- `message`: Custom error message
- `allow_subdomains`: Require or allow subdomains


validates :website, domain: { 
  allow_blank: true,
  message: "must be a valid domain"
}

Why This Matters for OpenSite AI

The domain_extractor gem is part of OpenSite AI's open-source initiative, focused on:

Increasing organic traffic: High-quality, well-documented gems attract users and backlinks
Performance-first design: Every feature, including validators, is optimized for speed
Developer experience: Clean APIs and Rails integration make adoption easy
Community building: Open source contributions grow the ecosystem

Key Takeaways

Use ActiveModel::EachValidator as your base class for attribute validators
Create a Railtie to auto-load validators in Rails applications
Handle standard options like allow_blank and custom messages
Test thoroughly including Rails integration tests
Keep validation logic separate from the validator class for reusability
Document clearly with examples in your README
Version carefully and be ready to yank broken releases

Try It Yourself

Install domain_extractor and see the validator in action:

gem install domain_extractor

Or add to your Gemfile:

gem 'domain_extractor'

Then use it in your models:

class Company < ApplicationRecord
  validates :website, domain: true
end

Resources

Conclusion

Building custom validators for your Ruby gems enhances their value to Rails developers. By following the patterns demonstrated in domain_extractor, you can create powerful, reusable validation logic that integrates seamlessly with Rails' validation framework.

The key is using the right base class (ActiveModel::EachValidator), providing a Railtie for auto-loading, and thoroughly testing your implementation. Learn from real-world examples like the 0.2.5 → 0.2.6 fix to avoid common pitfalls.

Ready to build your own validator? Start by studying the domain_extractor source code and adapt the patterns to your gem's needs.

About OpenSite AI: We're building high-performance, open-source tools for Ruby developers. Check out our other open source projects and join our growing community!

Introducing domain_extractor: A High-Performance Ruby Gem for URL Parsing and Domain Extraction

Jordan Hudgens — Mon, 03 Nov 2025 23:40:58 +0000

TL;DR

OpenSite AI is excited to announce the release of domain_extractor, a lightweight Ruby gem that delivers precise URL parsing, domain extraction, and multi-part TLD support. Perfect for web scraping, analytics, and any workflow requiring accurate domain handling.

🔗 Install it: gem install domain_extractor

📦 RubyGems: https://rubygems.org/gems/domain_extractor

💻 GitHub: https://github.com/opensite-ai/domain_extractor

The Problem

If you've ever worked with URLs in Ruby, you know the pain: extracting clean domain components from messy URLs isn't as straightforward as it should be. Standard libraries like URI don't handle multi-part top-level domains (TLDs) like .co.uk or .com.au. You end up with brittle regex solutions or pulling in heavy dependencies.

We needed something lightweight, accurate, and production-ready for our analytics and web scraping workflows at OpenSite AI. When we couldn't find exactly what we needed, we built it—and now we're open-sourcing it for the community.

What is domain_extractor?

domain_extractor is a Ruby gem engineered to parse URLs and extract domain components with surgical precision. It's built on Ruby's standard URI library and the battle-tested public_suffix gem, giving you reliable parsing for even the trickiest domains.

Key Features

✅ Multi-part TLD Support – Accurately handles complex TLDs like co.uk, com.au, gov.br using the Public Suffix List

✅ Nested Subdomain Parsing – Correctly extracts multi-level subdomains (api.staging.example.com)

✅ Smart URL Normalization – Handles URLs with or without schemes automatically

✅ Query Parameter Extraction – Parse query strings into structured hashes

✅ Zero Configuration – Works out of the box with sensible defaults

✅ Well-Tested – Comprehensive test suite covering edge cases

Installation

Add it to your Gemfile:

gem 'domain_extractor'

Or install directly:

gem install domain_extractor

Requirements: Ruby 3.2+ and public_suffix ~> 6.0

Usage Examples

Basic Domain Parsing

require 'domain_extractor'

result = DomainExtractor.parse('https://www.example.co.uk/path?query=value')

result[:subdomain]    # => 'www'
result[:domain]       # => 'example'
result[:tld]          # => 'co.uk'
result[:root_domain]  # => 'example.co.uk'
result[:host]         # => 'www.example.co.uk'
result[:path]         # => '/path'

Handling Complex TLDs

This is where domain_extractor really shines:

# UK domain
DomainExtractor.parse('shop.bbc.co.uk')
# => { subdomain: 'shop', domain: 'bbc', tld: 'co.uk', root_domain: 'bbc.co.uk' }

# Australian domain
DomainExtractor.parse('api.example.com.au')
# => { subdomain: 'api', domain: 'example', tld: 'com.au', root_domain: 'example.com.au' }

# Brazilian government domain
DomainExtractor.parse('portal.gov.br')
# => { subdomain: 'portal', domain: 'gov', tld: 'br', root_domain: 'gov.br' }

Nested Subdomains

DomainExtractor.parse('api.staging.prod.example.com')
# => { 
#   subdomain: 'api.staging.prod', 
#   domain: 'example', 
#   tld: 'com',
#   root_domain: 'example.com'
# }

Query Parameter Parsing

params = DomainExtractor.parse('https://example.com?utm_source=google&utm_medium=cpc&page=1').query_params
# => { 'utm_source' => 'google', 'utm_medium' => 'cpc', 'page' => '1' }

Real-World Use Cases

1. Web Scraping – Extract Root Domains

scraped_links = page.css('a').map { |a| a['href'] }
unique_domains = scraped_links
  .map { |url| DomainExtractor.parse(url)&.dig(:root_domain) }
  .compact
  .uniq

# Result: ['example.com', 'github.com', 'stackoverflow.com']

2. Analytics – Categorize Traffic by Domain

referrer = request.referrer
parsed = DomainExtractor.parse(referrer)

if parsed
  Analytics.track_event('page_view', {
    source_domain: parsed[:root_domain],
    source_subdomain: parsed[:subdomain]
  })
end

3. Domain Validation – Check Internal Links

def internal_link?(url, base_domain)
  parsed = DomainExtractor.parse(url)
  parsed && parsed[:root_domain] == base_domain
end

internal_link?('https://blog.example.com/post', 'example.com')  # => true
internal_link?('https://external.com/page', 'example.com')       # => false

4. SEO Audits – Extract & Analyze Backlink Domains

backlinks = fetch_backlinks_from_tool()
domain_distribution = backlinks
  .map { |link| DomainExtractor.parse(link)&.dig(:root_domain) }
  .compact
  .tally
  .sort_by { |_, count| -count }

# Result: { 'example.com' => 45, 'github.com' => 23, ... }

Performance

domain_extractor is optimized for speed:

Single URL parsing: ~0.0001s per URL
Batch processing: ~0.01s for 100 URLs
Memory efficient: Minimal object allocation
Thread-safe: Can be used in concurrent environments

Comparison with Alternatives

Feature	domain_extractor	Addressable	URI (stdlib)
Multi-part TLD support	✅	❌	❌
Subdomain extraction	✅	❌	❌
Domain component separation	✅	❌	❌
Query parameter parsing	✅	✅	✅
URL normalization	✅	✅	✅
PublicSuffix validation	✅	❌	❌
Lightweight	✅	❌	✅

What's Next

We're actively maintaining domain_extractor and have several features on our roadmap:

Domain validation – Check if domains are valid/registered
Punycode support – Better handling of internationalized domains
Performance improvements – Even faster parsing for high-volume use cases
CLI tool – Command-line interface for quick domain analysis

Contributing

domain_extractor is open source under the MIT license. We welcome contributions!

🐛 Report bugs: https://github.com/opensite-ai/domain_extractor/issues
💡 Feature requests: Open an issue with your idea
🔧 Pull requests: Fork, branch, commit, and submit!

About OpenSite AI

At OpenSite AI, we're committed to building practical tools that solve real-world problems. domain_extractor is our first open-source gem, with more to come. Follow our journey:

🌐 Website: https://opensite.ai/developers
💻 GitHub: https://github.com/opensite-ai

Get Started

Install domain_extractor today and simplify your URL parsing:

gem install domain_extractor

Or add to your Gemfile:

gem 'domain_extractor'

Happy parsing! 🚀

DEV Community: Jordan Hudgens

Stop Your React App From Shifting: A Deep Dive into useCLS from @page-speed/hooks

What Is Cumulative Layout Shift — And Why Should You Care?

The Thresholds That Matter

Why React Apps Are CLS Hotspots

Introducing @page-speed/hooks and useCLS

Understanding the useCLS Hook Architecture

Dual Observer Strategy

Ref-Based State Pattern for Callbacks

Session Window Algorithm

Automatic Issue Detection

Complete API Reference

Options (CLSOptions)

Return Value (CLSState)

Tutorial: Building From Zero to Production

Step 1: The Minimum Viable Monitor

Step 2: Development Debug Dashboard

Step 3: Fix the Most Common CLS Cause — Images Without Dimensions

Step 4: Prevent CLS With Skeleton Screens

Step 5: Handle SPA Navigation with utils.reset()

Step 6: Detect and Fix Web Font Shifts

Step 7: Prevent Animation-Related Shifts

Step 8: Reserve Space for Ads and Embeds

Step 9: Build a Complete CLS Report for Stakeholders

Understanding the Test Suite

Mocking web-vitals

Mocking PerformanceObserver

Rating Boundary Tests

Performance Characteristics

Quick-Reference: Common Fixes

Getting Started

Auth Strategies: The Right Tool for the Right Scenario

The Auth Debate Is a False Binary

The Full Landscape: Eight Auth Strategies You Should Know

1. Session-Based Authentication

2. JWT (JSON Web Tokens)

3. OAuth 2.0 + OpenID Connect (OIDC)

4. SAML 2.0

5. API Keys

6. Mutual TLS (mTLS)

7. Passkeys / FIDO2 / WebAuthn

8. Magic Links (Passwordless Email)

The Decision Matrix

When Each Strategy Can Be Used (Feasibility)

When Each Strategy Cannot Be Used (Hard Blockers)

Optimal Strategy by Scenario

Deep Dives: The Scenarios That Trip Developers Up

The SPA + Separate API Problem

Native Mobile Auth: The Implicit Flow Trap

The Microservices Auth Problem

Multi-Tenant SaaS: Auth Is a First-Class Concern

When Sessions Beat JWT (and Vice Versa)

Security Cheat Sheet by Mechanism

Sessions

JWT

OAuth 2.0 / OIDC

API Keys

mTLS

Passkeys / WebAuthn

Quick Reference: Auth Strategy Selection Flow

The Hybrid Approach: When Two Mechanisms Are Better Than One

Closing Perspective

How to Download and Upload Large Models with the Hugging Face CLI

Step 1 — Download the model

Step 2 — Upload to OpenSite/forge

Notes

Stop Letting AI Agents Go Rogue on Large Codebases: The large-scale-refactor Skill

What Is an "Agent Skill"?

The Core Insight: Agents Need a Scope Reflex

The Eight Guardrails — A Deep Dive

§ 1 — The Spec Gate: No Execution Without Approval

§ 2 — Scope Enforcement: Five Rules the Agent Cannot Break

§ 3 — Execution Protocol: Atomic, Budgeted, and Drift-Checked

§ 4 — Human Checkpoints: Hard Stops That Cannot Be Talked Past

§ 5 — Output & Verification Requirements

§ 6 — Context Persistence: The Session Handoff Protocol

§ 7 — Platform-Specific Notes

§ 8 — The Quick Reference Table

Complete End-to-End Walkthrough: 120-File JS→TS Migration

Step 1: Install and Invoke

Introducing `@page-speed/hooks` and `useCLS`

Understanding the `useCLS` Hook Architecture

Options (`CLSOptions`)

Return Value (`CLSState`)

Step 5: Handle SPA Navigation with `utils.reset()`

Mocking `web-vitals`

Mocking `PerformanceObserver`

`verify_scope.py`

`generate_allowlist.py`

1. `/Users/jordanhudgens/code/dashtrack/tools/rust-mcp/src/main.rs`

2. `/Users/jordanhudgens/code/dashtrack/tools/rust-mcp/src/tools/types.rs`

3. `/Users/jordanhudgens/.vibe/config.toml`