React - freeCodeCamp.org

How to Create a Scalable KYC Onboarding Flow in React with Shadcn UI

Vaibhav Gupta — Thu, 13 Aug 2026 18:10:52 +0000

Every B2B SaaS product with a compliance requirement (like banking, lending, payroll, or crypto) hits the same wall early on: before you can let a business use your platform, you need to verify who they are.

That means collecting a business type, pulling in registration documents, and showing the user where their verification stands, all without making onboarding feel like a customs form.

This article breaks down a working three step KYC (Know Your Customer) flow built with Shadcn UI: a stepper for progress, a radio group for account type, a file upload zone for documents, and an alert for verification status. You'll see the actual component code, not a simplified stand-in, along with the reasoning behind each decision.

You can try the finished flow at onboarding-kyc-flow.vercel.app. Click through it once before reading on, as it makes the code below easier to follow. And it also comes in dark and light mode.

Prerequisites
What You're Building
Project Structure
Radix UI vs Base UI: Which Primitives this Flow Uses
Scaffolding the Flow with v0 and an MCP Server
Step 1: Account Type with a Radio Group
Step 2: Document Upload with Drag and Drop
Step 3: Verification Status with an Alert
Adding a Stepper to the Flow
Small Details that Make it Feel Finished
Accessibility notes
Key Concepts Recap
Conclusion
Resources

Prerequisites

Before working through this flow, you should be comfortable with React function components and hooks, specifically useState, useRef, and useEffect.

You should have:

A Next.js project with the App Router and shadcn/ui already initialized, since this article doesn't cover that initial setup.
A v0 account is optional. You can also use Bolt or Lovable, which support the same shadcn MCP prompt feature.

What You're Building

The flow has three steps:

Account type: The user picks Startup, Enterprise, or Government. This decision drives the rest of the experience. It's shown back to the user as a confirmation line, and would typically decide which workspace defaults get applied.
Document upload: The user drags in a business registration document, a tax return, or a company registry export, in PDF or CSV format.
Verification status: The user sees a live status: checking in progress, then either verified or an issue that needs attention.

Project Structure

The project is a standard Next.js app with shadcn/ui already initialized. Here's the top-level layout:

onboarding-kyc-flow/
├── .vercel/
├── app/
├── components/
├── lib/
├── public/
├── .env.development.local
├── .gitignore
├── components.json
├── next-env.d.ts
├── next.config.mjs
├── package.json
├── pnpm-lock.yaml
├── postcss.config.mjs
├── tsconfig.json
└── tsconfig.tsbuildinfo

components.json is the file the shadcn CLI reads to know where your components live and which style and primitives you're using. components/ holds the shared UI pieces (Alert, Badge, Button, Card, Progress, RadioGroup, Separator) that the flow is built from. lib/utils.ts provides the cn helper used throughout the flow to combine conditional class names. app/ holds the page itself, shown in full below.

Radix UI vs Base UI: Which Primitives this Flow Uses

Shadcn components aren't tied to one underlying primitive library. Most of the ecosystem defaults to Radix UI, but Base UI has become a solid alternative, and it's what this flow is built on.

The underlying primitive library can affect how a component behaves and how you work with it in your project. If you're pulling components from a set like Shadcn UI, check which primitive library it targets before mixing components from different sources.

Mixing Radix-based and Base UI-based components generally works, but it means using two different unstyled primitive libraries in the same project. You can compare Radix UI and Base UI here.

Scaffolding the Flow with v0 and an MCP Server

An MCP (Model Context Protocol) server exposes a component library to an AI coding assistant as a set of callable tools. Instead of the assistant guessing at component names and props from training data, it queries the server for the real, current API.

This matters here specifically, since there are now several shadcn-style component sets with similar names and different props.

The Shadcn Components library publishes an MCP server for its free set, connected to v0 by following its getting started guide. The video below covers the connection step by step. The same generated output can also be copied into Lovable or Bolt through their copy prompt feature, so the workflow isn't locked to one AI builder.

The prompt used to scaffold this flow looked like this:

Create an Enterprise SaaS Onboarding & KYC Flow. Use free components of the shadcn space MCP server: shadcn alert, shadcn radio group, shadcn stepper, shadcn file upload. Only use free components, not pro ones, and list which free component was used for each part.

Step 1: Account Type (stepper) - radio group for Startup, Enterprise, or Government

Step 2: Upload Documents (stepper) - file upload for a business registration document

Step 3: Verification (stepper) - alert showing verification status

This produces a working first draft fast. What follows is the result after cleaning that draft up: real state management, real validation, and states that a generated draft tends to skip.

Step 1: Account Type with a Radio Group

Account type is the first decision in the flow because it's the one most likely to affect what comes after it. Asking it early keeps the rest of the flow feeling relevant to the choice the user just made.

const tiers: { id: Tier; name: string; description: string; tag: string }[] = [
  { id: 'startup', name: 'Startup', description: 'For teams building and scaling fast', tag: 'Up to 25 seats' },
  { id: 'enterprise', name: 'Enterprise', description: 'For established teams with advanced needs', tag: 'Unlimited seats' },
  { id: 'government', name: 'Government', description: 'For public sector and regulated teams', tag: 'FedRAMP-ready' },
]

 setTier(value as Tier)} className="grid gap-3">
  
    Account type
    {tiers.map((item) => (
      
        
        
          
            {item.name}
            {item.id === 'enterprise' && Recommended}
          
          {item.description}
          {item.tag}
        
      
    ))}

Two things worth noticing here. The tier data lives in a plain array outside the component, so adding a fourth tier later is a one-line change, not a markup change. And the fieldset with a visually hidden (sr-only) legend groups the three options as one related choice for screen readers. Sighted users never see it, since the card title above already states "Choose your account type" visually.

This step uses a shadcn radio group rather than a select or checkboxes, since account type is a single, mutually exclusive choice, and a radio group is the only one of the three that makes both the options and the current selection visible at a glance.

Live Preview:

Step 2: Document Upload with Drag and Drop

The upload zone needs to handle three states cleanly: nothing selected yet, a file selected and ready, and a rejected file with a specific reason why.

function FileUpload({ file, onFile, onRemove, error }: {
  file: File | null
  onFile: (file: File) => void
  onRemove: () => void
  error: string
}) {
  const inputRef = useRef(null)
  const [dragging, setDragging] = useState(false)

  const accept = (candidate: File) => {
    if (candidate.type !== 'application/pdf' && candidate.type !== 'text/csv' && !candidate.name.toLowerCase().endsWith('.csv')) {
      return 'Upload a PDF or CSV file only.'
    }
    if (candidate.size > 10 * 1024 * 1024) {
      return 'Files must be smaller than 10 MB.'
    }
    onFile(candidate)
    return ''
  }

  return (
    
      {!file ? (
        
      ) : (
        
          
            
          
          
            {file.name}
            {(file.size / 1024 / 1024).toFixed(2)} MB · Ready to verify
          
          Uploaded
          
        
      )}
      {error && (
        
          
          Unsupported document
          {error}
        
      )}
    
  )
}

The accept function is the whole validation layer, and it runs from two different places: the change handler on the hidden file input, and the drop handler on the drag zone.

Both paths call the same function, so a file dragged in gets the same validation checks as a file selected by clicking browse. It ensures that only PDF or CSV files are allowed, regardless of how the file is added.

This is where shadcn file upload earns its place over a plain : the drag zone, the selected state, and the rejected state are all handled as one component instead of three separate pieces wired together by hand.

Live Preview:

Step 3: Verification Status with an Alert

Verification isn't instant, so the interface needs to say clearly what's happening and what happens next, rather than showing a spinner with no explanation.

{verified ? (
  
    
    Verification complete
    
      Your {selectedTier.name.toLowerCase()} workspace is ready to configure.
    
  
) : (
  <>
    
      
      Verification in progress
      
        This usually takes a few moments. You can keep this tab open while we finish.
      
    
    
      
        Checking business registry
        {checking ? '68%' : '100%'}
      
      
      
         Matching company details and tax identifiers
      
    
  
)}

Pairing the shadcn alert with a progress bar does two jobs at once: the alert states the current status in words, while the progress bar gives a rough sense of how much is left, without promising a specific time. Neither one alone tells the full story, the alert alone feels static, and a progress bar alone doesn't explain what's actually being checked.

Worth adding here, and easy to skip when a demo only shows the success path: a mismatch state, where the tax ID on the document doesn't match the company registry, deserves its own alert with a clear next step: contact support or re-upload a corrected document. It's not shown above, since the flow currently resolves to either checking or verified, but it's the state a production version of this flow would hit the most.

Live Preview:

Adding a Stepper to the Flow

The stepper is the visual anchor of the whole flow. It's the piece that tells the user how much is left before the checking and account-type-selecting are done.

function Stepper({ current }: { current: Step }) {
  return (
    
      {steps.map((step, index) => (
        
          
             step.number
                  ? 'border-primary bg-primary text-primary-foreground'
                  : current === step.number
                  ? 'border-primary bg-primary/10 text-primary'
                  : 'border-border bg-background text-muted-foreground'
              )}
              aria-current={current === step.number ? 'step' : undefined}
            >
              {current > step.number ?  : step.number}
            
            
              = step.number ? 'text-foreground' : 'text-muted-foreground')}>
                {step.label}
              
              {step.caption}
            
          
          {index < steps.length - 1 && (
             step.number ? 'bg-primary' : 'bg-border')} />
          )}
        
      ))}
    
  )
}

The current > step.number check keeps the entire stepper in sync with a single comparison. It determines the circle’s fill color, decides when the step number should be replaced by a checkmark, and controls whether the connecting line to the next step is filled.

This is important because the stepper only needs one piece of state, step, from the parent component. It doesn’t need to know why the user is on step 2, it only needs to know which step is currently active and update its visual state accordingly.

The "continue" logic that actually advances step lives outside the stepper itself:

const continueStep = () => {
  if (step === 1) setStep(2)
  else if (step === 2 && file) {
    setStep(3)
    setChecking(true)
    window.setTimeout(() => {
      setChecking(false)
      setVerified(true)
    }, 1400)
  }
}

Keeping this in the page component, not inside the shadcn stepper itself, is what keeps the stepper reusable. It only renders progress. Whether the user is allowed to move forward, a file is required on step 2, or whether nothing is required on step 1, is a decision for the flow around it to make.

Small Details that Make it Feel Finished

A few things in this build are easy to skip but change how the flow feels in practice:

A dark mode toggle in the header, wired to a darkMode state that toggles a class on document.documentElement. It's small, but it means the flow doesn't fight a user's system theme preference.
A security note in the sidebar, stating documents are encrypted and deleted after verification. This is copy, not code, but it answers the question a corporate user is quietest about and most worried by: what happens to the file after I upload it.
A "Selected" confirmation line under the radio group, restating the chosen tier in plain text. A small detail, but it removes any doubt about what was actually selected before moving on.

If you're looking to wrap a flow like this inside a full application shell, with navigation and a dashboard around it, the Shadcn Dashboard starter uses the same component set. It's a reasonable base to extend from rather than building a shell from scratch.

Live Preview:

https://onboarding-kyc-flow.vercel.app/

This project is open source, and you can easily download the zip and if you like. Please consider giving it a star.

Github Repo

Accessibility notes

The stepper's nav element has an aria-label, and the current step carries aria-current="step", so assistive technology can identify progress without relying on visual position alone.
The radio group sits inside a fieldset with a screen-reader-only legend, grouping the three account types as one decision.
Icons throughout (Check, AlertCircle, UploadCloud, and so on) carry aria-hidden="true", since they're decorative next to text that already states the same information. This stops screen readers from announcing redundant icon labels.
The remove-file button has an explicit aria-label, since its visible content is an icon only, with no text.

Key Concepts Recap

Account type comes first because it's the one decision most likely to affect the rest of the flow, and it's kept in state at the page level, not inside the radio group itself.
File validation runs in a shared function used by both the drag-and-drop path and the click-to-browse path, so both paths apply the same PDF/CSV validation.
Verification status is communicated with both words (the alert) and a rough sense of progress (the progress bar), since either one alone leaves out part of the picture.
The stepper is a pure display component driven by a single step value from its parent. The logic for whether the user can advance lives outside it, not inside it.
Small, non-technical details (like a security note, a confirmation line, or a theme toggle) do as much for how finished a flow feels as any of the four core components.

Conclusion

None of the four components in this flow are complicated individually. What makes a KYC flow work is the decisions around them: which choice comes first, where validation actually runs, and how honestly the interface talks to the user while something outside their control is being checked.

Whether the first draft comes from typing every line by hand or from scaffolding it with an MCP server and v0, that's the part worth spending time getting right before it ships.

Resources

Shadcn Components, the free component set used in this flow
ShadcnSpace, the base library these components extend
MCP server walkthrough
MDN: ARIA current attribute
Model Context Protocol specification

How to Build an Open Source SaaS Landing Page Template with shadcn/ui

Ash — Mon, 03 Aug 2026 18:39:33 +0000

Most SaaS landing pages share the same core sections: a hero, social proof, features, pricing, FAQ, and a footer. And most developers end up building these from scratch on every project. That's repetition, not engineering.

So I built and open-sourced a complete SaaS landing page template called ChatDeck. It runs on Next.js 16, React 19, shadcn/ui with the new base-nova style, Tailwind CSS v4, and TypeScript. The full source is on GitHub under the MIT license. I built and open-sourced this template, and everything here comes from decisions made during that process.

Building it forced me to make real decisions on a stack that moved significantly in the past 12 months. This article is about those decisions: what worked, what didn't, and what I'd do differently if I started today.

Prerequisites: This article assumes you're comfortable with React and TypeScript. Some familiarity with the Next.js App Router is helpful but not required. Each lesson is explained from first principles.

The Stack Choices and Why They Matter
Getting Started
Project Structure
Lesson 1: shadcn/ui's Newbase-novaStyle Changes What "Accessible" Means
Lesson 2: Tailwind CSS v4 Requires a Mental Model Shift
Lesson 3: OKLCH Colors Make Dark Mode Predictable
Lesson 4: Page Architecture — Flat Beats Clever
Lesson 5: Staggered Animations Without Managing Individual Delays
Lesson 6: CSS-Only Infinite Scroll — No Library Needed
Lesson 7: CSS Subgrid Solves Pricing Card Alignment Natively
Lesson 8: Inline SVGs Beat Image Libraries for Simple Logos
What I'd Do Differently
Summary

The Stack Choices and Why They Matter

Before getting into the code, here's what the template runs on. Each choice was deliberate — none of these are defaults you get from create-next-app.

Technology	Version	Why I chose it
Next.js	^16.0.3	App Router gives you React Server Components out of the box. Static sections like Hero and Features render on the server — no client-side JS needed for content that never changes.
React	19.2.0	React 19 stabilises the `use` hook and concurrent features. Staying on the latest version means the template doesn't immediately feel stale.
shadcn/ui	^4.13.0 (CLI)	Components are copied into your codebase, not installed as a package. You own the code. No version lock-in, no fighting library defaults when you need to customize.
Base UI (`@base-ui/react`)	^1.6.0	shadcn/ui's new `base-nova` style uses Base UI instead of Radix as its headless primitive layer. It has a smaller peer dependency footprint and tighter ARIA integration. More on this in Lesson 1.
Tailwind CSS	^4	v4 moves theme configuration from a JavaScript config file into CSS directly. Custom animations, color tokens, and radius scales all live in `globals.css`. More on this in Lesson 2.
Motion (`motion/react`)	^12.23.24	The rebranded Framer Motion. Handles entrance animations on the Hero and scroll-triggered animations on the Features section. Chosen over CSS animations because staggered sequences are much simpler to manage.
TypeScript	^5	Full type safety throughout. Component props, icon maps, pricing plan objects — all typed. Catches errors at build time, not at runtime.
Lucide React	^0.553.0	Consistent, well-maintained icon set that works cleanly with Tailwind's `size-*` utilities. No custom SVG wrangling needed for UI icons.

The most interesting decisions in this list are the ones that reflect how the ecosystem changed in the past year: Base UI replacing Radix inside shadcn/ui, and Tailwind v4's shift to CSS-first configuration. The lessons below walk through each of these in detail, starting with the choices that had the biggest impact on how the code is actually written.

Getting Started

Before diving into the lessons, here's how to get the project running locally. Having it open alongside this article makes the code examples easier to follow.

git clone https://github.com/ShadcnDeck/chatdeck-shadcn-saas-landing-page-template.git
cd chatdeck-shadcn-saas-landing-page-template
pnpm install
pnpm dev

Open http://localhost:3000 and you'll see the full landing page running locally.

All section content lives as plain TypeScript arrays inside each Block component. To change the features, edit the features array in FeatureSection.tsx. To change pricing tiers, edit the plans array in PricingSection.tsx. No CMS, no config files — just TypeScript objects.

To customize colors, update the OKLCH values in app/globals.css under the :root block. Change --primary and every button, link, and accent color updates across the entire template.

Deploy to Vercel with a single vercel command or by pushing to GitHub and connecting the repo. Next.js is detected automatically.

Project Structure

Here's the full directory layout before we go through each part of it:

chatdeck/
├── app/
│   ├── globals.css         # Theme tokens + custom animations (Tailwind v4 @theme)
│   ├── layout.tsx          # Root layout — Navbar, Footer, fonts
│   └── page.tsx            # Section imports — 16 lines
├── components/
│   ├── Blocks/             # Page sections (Hero, Features, Pricing, etc.)
│   ├── ui/                 # shadcn/ui components — base-nova style
│   └── navbar.tsx          # Scroll-aware sticky navbar
└── lib/
    └── utils.ts            # cn() helper (clsx + tailwind-merge)

The key separation is Blocks/ vs ui/. The ui/ folder holds primitive components — Button, Badge, Accordion — that come from shadcn/ui and rarely change. The Blocks/ folder holds page-level sections that are specific to this template and change often. When you're customising, you mostly work in Blocks/. When you upgrade shadcn/ui components, you touch ui/.

The lessons below go through specific files in this structure piece by piece: components.json and ui/accordion.tsx in Lesson 1, app/globals.css in Lessons 2 and 3, app/page.tsx in Lesson 4, and the individual Block components in Lessons 5 through 8.

Lesson 1: shadcn/ui's New `base-nova` Style Changes What "Accessible" Means

If you've used shadcn/ui before, you know the default setup uses Radix UI primitives, headless components that handle focus management, keyboard navigation, and ARIA attributes. Radix has been the default for years.

But shadcn/ui introduced a new style in 2025 called base-nova, which replaces Radix with Base UI, the headless primitive library from MUI.

Based on shadcn's public direction and the components released through 2025, base-nova appears to be the intended default going forward (though shadcn hasn't yet deprecated the Radix style).

In the project's components.json:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "iconLibrary": "lucide"
}

The "style": "base-nova" line means every component the shadcn/ui CLI installs wraps Base UI primitives instead of Radix. To understand what this changes in practice, here's what the same Accordion trigger component looks like in the older Radix-based default style:

// Radix-based default style (the old way)
import * as AccordionPrimitive from "@radix-ui/react-accordion"

const AccordionTrigger = React.forwardRef<
  React.ElementRef,
  React.ComponentPropsWithoutRef
>(({ className, children, ...props }, ref) => {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    
       setIsOpen(!isOpen)}
        {...props}
      >
        {children}
        
        
      
    
  )
})

Notice the useState(false) tracking whether the accordion is open, and the onClick handler that toggles it. This means the component has to manually keep its own isOpen state in sync with what Radix internally knows about the open/closed state.

Now here's the same component using the base-nova style with Base UI:

// components/ui/accordion.tsx — base-nova style (the new way)
import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion"

function AccordionTrigger({ className, children, ...props }: AccordionPrimitive.Trigger.Props) {
  return (
    
      
        {children}
        
        
      
    
  )
}

No useState. No onClick. No isOpen variable. The chevron visibility is controlled entirely by group-aria-expanded/accordion-trigger:hidden — a Tailwind class that reads the aria-expanded attribute Base UI sets automatically on the trigger element.

The lesson here: in the Radix version, you have two parallel systems: the component's own isOpen state, and the ARIA attributes that the library manages separately for screen readers. These can drift out of sync — for example, if the accordion closes via keyboard navigation, the ARIA state updates correctly but your isOpen state doesn't unless you wire up the right callbacks. In the Base UI version, there is only one system. ARIA state IS the state. Tailwind reads it directly. There's nothing to keep in sync and nothing that can drift.

Lesson: use the primitive library's ARIA attributes as your source of truth for visual state. If your headless component library already sets aria-expanded, aria-selected, or aria-checked, Tailwind can respond to those directly with aria-* variant classes — no parallel JavaScript state needed.

So when you install shadcn/ui today, choose base-nova over the default Radix style. You get tighter Base UI integration, a smaller peer dependency footprint, and components that are more aligned with where the ecosystem is moving.

Lesson 2: Tailwind CSS v4 Requires a Mental Model Shift

Tailwind CSS v4 moves primary theme configuration out of the JavaScript config file and into CSS. This sounds small. In practice, it changes how you think about the entire theming system.

In Tailwind v3, you'd extend the theme in tailwind.config.js:

// OLD — tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      animation: {
        marquee: "marquee 40s linear infinite",
      },
      keyframes: {
        marquee: {
          from: { transform: "translateX(0)" },
          to: { transform: "translateX(calc(-100% - var(--gap)))" },
        },
      },
    },
  },
}

In Tailwind v4, that same configuration lives in your CSS file instead:

/* app/globals.css — Tailwind v4 */
@import "tailwindcss";

@theme inline {
  --animate-marquee: marquee var(--duration) infinite linear;
  --animate-marquee-vertical: marquee-vertical var(--duration) linear infinite;

  @keyframes marquee {
    from { transform: translateX(0); }
    to   { transform: translateX(calc(-100% - var(--gap))); }
  }

  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --radius-4xl: calc(var(--radius) * 2.6);
}

The @theme inline block extends Tailwind's design token system. Define --animate-marquee here and you can use className="animate-marquee" anywhere in your components. Tailwind generates the utility class automatically from the CSS variable.

Custom animations, radius scales, and color tokens all live in CSS now. The benefit is that CSS is where styles belong. The config file was always an indirection layer between "what I want my design system to look like" and "where that actually lives." Tailwind v4 removes the indirection.

The friction: if you start a Tailwind v4 project with a v3 mental model, you'll spend time looking for theme config in the wrong place. Read the v4 migration guide before you start, not after you're confused.

Lesson: move your mental model of "theme config" from JavaScript to CSS. In Tailwind v4, if you want a custom animation, a new radius scale, or a color token, define it in @theme inline inside globals.css. That's where it belongs, and that's where every developer on your team will find it.

Lesson 3: OKLCH Colors Make Dark Mode Predictable

The template uses OKLCH color values throughout, not hex or HSL:

:root {
  --background: oklch(1 0 0);        /* white */
  --foreground: oklch(0.145 0 0);    /* near-black */
  --primary: oklch(0.205 0 0);
  --border: oklch(0.922 0 0);
}

.dark {
  --background: oklch(0.145 0 0);    /* near-black */
  --foreground: oklch(0.985 0 0);    /* near-white */
  --primary: oklch(0.922 0 0);
  --border: oklch(1 0 0 / 10%);      /* white at 10% opacity */
}

OKLCH is a perceptually uniform color space. When you increase the lightness value in OKLCH, the color actually looks lighter to human eyes, consistently. Hex and HSL don't guarantee this. You can increase the L in HSL and get a color that looks the same or even darker depending on the hue.

For dark mode specifically, this matters because you're inverting a whole color system. With HSL, you'll often end up manually tweaking individual color values until contrast ratios look right. With OKLCH, increasing or decreasing the lightness value gives you predictable results across all your tokens.

The dark mode switch itself is zero JavaScript. Adding class="dark" to the element swaps every CSS variable. Tailwind reads the updated variables and re-renders every component. There's no context provider and no useTheme hook needed for the CSS layer — just a class toggle on the root element.

Lesson: swap your color tokens to OKLCH. When defining dark mode values, adjust the first OKLCH parameter (lightness) and the result will look predictably lighter or darker. With hex or HSL you're often guessing; with OKLCH you're reasoning.

Lesson 4: Page Architecture — Flat Beats Clever

The main page file is 16 lines:

// app/page.tsx
import Hero from "@/components/Blocks/Hero";
import { LogoCarousel } from "@/components/Blocks/LogoCarousel";
import { FeatureSection } from "@/components/Blocks/FeatureSection";
import { TeamSection } from "@/components/Blocks/TeamSection";
import { TestimonialSection } from "@/components/Blocks/TestimonialSection";
import { PricingSection } from "@/components/Blocks/PricingSection";
import { FaqSection } from "@/components/Blocks/FaqSection";

export default function Home() {
  return (
    
      
        
        
        
        
        
        
        
      
    
  );
}

No dynamic imports, no lazy-loading config, no context providers wrapping everything. Each section is a completely self-contained component in components/Blocks/. None of them import from each other.

This decision came from watching how developers actually use shadcn templates. The first thing anyone does after cloning is delete the sections they don't need and reorder the ones they keep. With flat imports, removing the Team section is one deleted line. Reordering sections is moving one line. Adding a new section is creating a file and adding one import.

The alternative (a sections array, a renderer loop, a config file that controls order) sounds sophisticated. In practice, it adds indirection that makes the template harder to understand and slower to customize. Templates should be obvious, not impressive.

Lesson: in a template context, the simplest architecture is the correct architecture. The developer cloning your template isn't impressed by abstraction. They want to understand the code fast and change it faster.

Lesson 5: Staggered Animations Without Managing Individual Delays

The Hero section uses entrance animations where each element fades up sequentially: badge first, then heading, then subheading, then CTA. The naïve approach sets a different delay prop on each element manually. The correct approach uses staggerChildren:

// components/Blocks/Hero.tsx
"use client"
import { motion, type Variants } from "motion/react"

const containerVariants: Variants = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: {
      staggerChildren: 0.15,  // each child animates 150ms after the previous
      delayChildren: 0.1,
    },
  },
}

const fadeUpVariants: Variants = {
  hidden: { opacity: 0, y: 20 },
  visible: {
    opacity: 1,
    y: 0,
    transition: { duration: 0.5, ease: "easeOut" },
  },
}

const Hero = () => (
  
    
      {/* Badge */}
    
    
      AI Chatbot for Customer Support.
    
    
      {/* Subheading */}
    
    
      {/* CTA */}
    
  
)

The parent defines staggerChildren: 0.15. Every child with variants={fadeUpVariants} automatically inherits a 150ms offset from the previous child. Want to add a new element? Give it variants={fadeUpVariants} and the stagger chain extends automatically. No manually updated delay values.

The Features section uses scroll-triggered animations with a different easing:

// components/Blocks/FeatureSection.tsx

viewport={{ once: true }} fires the animation once when the element enters the viewport, not on every scroll pass. amount: 0.3 starts the animation when 30% of the element is visible, not when the full element is on screen. The cubic bezier [0.22, 1, 0.36, 1] is a fast-out-slow-in curve that feels physical rather than mechanical.

Quick note on the import: most of the core API is compatible, but motion/react isn't a straight drop-in rename of framer-motion. If you're upgrading an existing project, check the official migration guide before swapping the import. Layout animations, AnimatePresence behaviour, and some hooks changed.

Lesson: define animation variants at the parent level and use staggerChildren to orchestrate the sequence. Never set delay manually on individual elements — that creates a brittle list of numbers you have to update every time you add or remove an element. Let the parent handle timing; let children just declare what they animate to.

Lesson 6: CSS-Only Infinite Scroll — No Library Needed

The testimonials use a dual-row auto-scrolling marquee. The second row scrolls in reverse. There's no third-party marquee package. It's a small component built entirely on CSS animations defined in Tailwind v4's @theme block.

// components/ui/marquee.tsx
export function Marquee({
  reverse = false,
  pauseOnHover = false,
  vertical = false,
  children,
  repeat = 4,
  ...props
}) {
  return (
    
      {Array(repeat).fill(0).map((_, i) => (
        
          {children}
        
      ))}
    
  )
}

The repeat={4} prop renders the children 4 times side by side. As the CSS animation scrolls the container left, the repetitions create a seamless loop. By the time the first set has scrolled off screen, the second set is already in position.

group-hover:paused is Tailwind applying animation-play-state: paused when the parent has group class and is hovered. No onMouseEnter/onMouseLeave handlers or state, just pure CSS.

To customize the scroll speed without touching the component source, you override the CSS variable inline:


  {items.map(item => )}

[--duration:20s] is a Tailwind arbitrary property. It sets --duration directly on the element, which the animation reads via var(--duration). Speed customization without a prop, without touching the component.

Lesson: before reaching for a third-party animation package, check whether a CSS keyframe animation and a couple of Tailwind utilities can do the same job. A marquee, a fade loop, a pulsing skeleton — all of these are achievable with native CSS. Fewer dependencies means fewer breaking changes when the ecosystem moves.

Lesson 7: CSS Subgrid Solves Pricing Card Alignment Natively

The pricing section has three cards: Free, Pro, and Business. Each card has four rows: plan name, price, CTA button, and features list. The features list height varies between plans. Without CSS subgrid, the rows don't align across cards.

The common workaround is min-height on each row, or JavaScript that measures each card and sets explicit heights. Both approaches are fragile. Subgrid solves it in CSS:

// components/Blocks/PricingSection.tsx

  {plans.map((plan) => (
    
      {/* Plan name + description */}
      {/* Price */}
      {/* CTA button */}
      {/* Features list */}
    
  ))}

grid-rows-subgrid tells each card to participate in the parent grid's row tracks rather than creating its own. Each card spans 4 rows (row-span-4). The plan name row, price row, CTA row, and features row align across all three cards (regardless of content height) because they're all on the same row tracks.

Each card's row-span-4 reserves four rows in the parent's implicit grid. Because every card spans the same four shared row tracks, their internal rows align automatically even though the parent never declares explicit row heights.

CSS subgrid has been in all modern browsers since late 2023. There's no reason to reach for a JavaScript layout solution when the platform handles it.

Lesson: when you have a grid of cards where each card has multiple internal rows that need to align across columns, reach for grid-rows-subgrid before reaching for min-height or JavaScript. Define the number of rows each card spans with row-span-N, and the browser handles the rest.

Lesson 8: Inline SVGs Beat Image Libraries for Simple Logos

The logo carousel renders 12 brand logos: Shopify, Stripe, GitHub, Google, and others. The first instinct is to use a package like react-icons or simple-icons. I went a different direction: inline SVG paths stored as a plain TypeScript object.

// components/Blocks/LogoCarousel.tsx
const iconMap = {
  stripe: "M13.976 9.15c-2.172-.806...",
  github: "M12 .297c-6.63 0-12...",
  google: "M12.48 10.92v3.28h7.84...",
  // ...
} as const

const SimpleIcon = ({ iconSlug, size = 24 }: { iconSlug: string; size?: number }) => {
  const iconPath = iconMap[iconSlug as keyof typeof iconMap]
  return (
    
  )
}

The fill-black dark:fill-white class means every logo automatically inverts in dark mode: no separate dark mode logo assets, and no conditional rendering based on theme.

The carousel itself duplicates the logo array to create a seamless loop:

{/* First pass */}
{techCompanies.map((company, i) => )}
{/* Second pass — identical, creates the seamless loop */}
{techCompanies.map((company, i) => )}

The CSS animation (animate-logo-scroll) scrolls the container left. When the first pass disappears off the left edge, the second pass is already in position. The loop is seamless.

The trade-off: maintaining SVG paths manually is fine for a fixed set of logos. If you need a large dynamic icon set, reach for simple-icons or a proper icon library. For 12 brand logos that rarely change, this approach ships zero extra dependencies.

Lesson: match your tooling to your actual requirements. A logo carousel with a fixed set of brand logos doesn't need an icon library — it needs a TypeScript object and two Tailwind classes. Installing a package to solve a problem you could solve with 10 lines of code adds maintenance surface for no gain.

What I'd Do Differently

These are the three decisions I'd change if starting the template today.

1. Extract Animation Variants to a Shared File

containerVariants and fadeUpVariants are currently defined locally in both Hero.tsx and FeatureSection.tsx. If you want to change the global animation timing (say, reduce duration from 0.5s to 0.3s) you update two files. A shared lib/animations.ts exporting the standard variants would make global timing changes a one-line edit.

// lib/animations.ts
export const fadeUpVariants: Variants = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0, transition: { duration: 0.5, ease: "easeOut" } },
}

export const containerVariants: Variants = {
  hidden: { opacity: 0 },
  visible: { opacity: 1, transition: { staggerChildren: 0.15, delayChildren: 0.1 } },
}

2. Use Subgrid in the Features Section Too

The Features grid uses a border-based visual separation pattern — borders between cells create the grid appearance. It works, but the hover states have an inconsistency: the gradient hover overlay height varies slightly between cells in the same row because content heights differ. Subgrid would lock those row heights across cards the same way it does in the Pricing section.

3. Use `next/font` More Consistently

The layout loads both Geist and Inter font families. Inter is used via --font-sans. Geist is loaded but the geistSans.variable and geistMono.variable are applied to as className strings while Inter drives the actual font rendering through the CSS variable. The result is that Geist is loaded but not actually displayed. Cleaning this up could shave tens of kilobytes from the font payload — worth verifying in Lighthouse or the Network tab before deploying.

Summary

These are the five things from this build worth taking into your next project:

shadcn/ui's base-nova style runs on Base UI primitives. ARIA state drives visual state — no parallel JavaScript state needed.
Tailwind v4 moves theme config to CSS. All theme tokens, custom animations, and radius scales live in CSS via @theme inline. This is the right place for them.
OKLCH gives predictable dark mode contrast. Adjusting lightness in OKLCH actually changes perceived brightness. Hex and HSL don't guarantee this.
staggerChildren in motion/react eliminates manually managed animation delays. The parent orchestrates while the children just declare their animation variant.
CSS subgrid (grid-rows-subgrid) aligns card rows across columns natively. No JavaScript measurement, no fixed heights.

The full template is MIT-licensed and available at github.com/ShadcnDeck/chatdeck-shadcn-saas-landing-page-template. If it's useful, a star helps others find it.

A Guide to Modern React Form Architecture: TanStack Form + Zod + Shadcn

Tapas Adhikary — Tue, 28 Jul 2026 16:29:03 +0000

Building production-grade forms in React can be a painful experience. It's one of the parts of front-end engineering that most developers are uncomfortable with.

Usually, you'll start with a simple controlled form using the useState hook. But as the form grows, you realise that typing a single character into an input field triggers a re-render of the entire component tree. The application becomes sluggish and ends up creating a terrible user experience.

You might even try mitigating this re-rendering issue by switching to an uncontrolled form using the useRef hook. But this introduces horrible scalability issues, and as the form grows, maintaining the code becomes a nightmare.

Vibe coding might get you to a working demo, but actual engineering gets you to production. To fix these performance and scalability issues in the production apps, we need to rethink how inputs work.

In this article, we'll build a production-ready form architecture. We'll use TanStack Form as a headless state machine to solve the performance and scalability problems, Zod for bulletproof validations, and ShadCN UI for accessible, beautiful components.

If you're a visual learner, I've recorded a full masterclass video covering this exact architecture over on my YouTube channel, tapaScript. You can watch it right here:

The Problem with Traditional Forms
- The Uncontrolled "Ref" Workaround
- Why Not Just Use Native HTML Forms?
Introducing TanStack Form
Fine-Grained Reactivity
Validation with Zod
Headless TanStack Form with ShadCN UI
Handling Nested Dynamic Arrays with TanStack Form
TanStack Form's Granular Reactivity: useSelector vs form.Subscribe
- With useSelector()
- With form.Subscribe()
TanStack Form vs. React Hook Form
Conclusion & Important Resources
If You've Read This Far...

The Problem with Traditional Forms

When developers realize that useState gives them the control to manage forms using React's state, they often create form components like this:

import { useState } from "react";

export function StandardRegistrationForm() {
 
  const [formData, setFormData] = useState({
    firstName: "",
    lastName: "",
    email: "",
    password: "",
  });

  console.log("Form Re-rendered! Current state:", formData.firstName);

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

  return (
    
      
        The Problem
        Standard Controlled Form
      

      
        
          
            First Name
          
          
        

        
          
            Last Name
          
          
        

        
          
            Email
          
          
        

        
      
    
  );
}

The component uses a centralized useState object, which is the standard way most developers are taught to build forms. The moment a value changes for any input fields, the state gets updated.

In React, every time you update a state, the component re-renders to display the current state value. This introduces a performance issue that you need to solve.

The image below shows the exact performance problem of the form component getting re-rendered with every keystroke inside the input elements.

The Uncontrolled "Ref" Workaround

Acknowledging the problem we've seen with the controlled form component, devs found a workaround. Instead of using state, if we use ref, the components don't re-render on ref's current value changes. That sounds like an AHA! moment until we figure out that it introduces completely different architectural headaches.

Here's the same form, but managed using refs instead of states:

import { useRef } from "react";

export function RefRegistrationForm() {
 
  const firstNameRef = useRef(null);
  const lastNameRef = useRef(null);
  const emailRef = useRef(null);

  console.log("Form Rendered (Notice it doesn't log when typing)");

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

    const formData = {
      firstName: firstNameRef.current?.value,
      lastName: lastNameRef.current?.value,
      email: emailRef.current?.value,
    };

    console.log("Submitted Data:", formData);

  };

  return (
    
      
        The Ref Workaround
        Fast, but scales horribly.
      

      
        
          
            First Name
          
          
        

        
          
            Last Name
          
          
        

        
          
            Email
          
          
        

        
      
    
  );
}

Let's talk about the problems with this approach:

The Ref Soup: We've created a separate ref for every single input. Imagine this form grows to 20+ fields, and you have to manage all those refs!
We need to extract the data manually and stitch the object back together. There's no mechanism like setState() that exists here.
How do we do real-time validation? Since the field/component doesn't re-render here as you type, showing a dynamic error message under the inputs becomes incredibly hard without introducing new state variables, and doing that would defeat the whole purpose of refs.

Why Not Just Use Native HTML Forms?

Oh yes! We shouldn't ignore this possibility as well. Why use a library at all? Can't we just use native HTML forms and grab the data with FormData on submit?

If you're building a simple "Contact Us" or "Login Form", the native HTML forms are actually the best tool for the job. They're lean, require zero library knowledge, and are incredibly efficient.

But for complex, production-grade web applications, the native approach quickly hits a wall:

Complex data structures: FormData is a flat object. If you're dealing with deeply nested objects or dynamic arrays, manually parsing speakers[0][firstName] out of a flat FormData object could be messy.
Dynamic UI: If you have a requirement where Field B should appear if Field A is set to "Yes", you need client-side state to track Field A's value anyway. FormData only exists at the exact moment of submission.
UX & Real-time Validations: Native HTML validations are rigid and hard to style cleanly across browsers. If you need complex cross-field validations (like confirming passwords match) or async validations (checking if a username is taken while the user types), you need JavaScript.

When native forms aren't enough, we move to React.

Introducing TanStack Form

TanStack Form is a headless state machine for your inputs. It gives you the strict typing and easy data management of a controlled form, but uses fine-grained reactivity to ensure that only the specific field you're typing in re-renders, and nothing else.

Let's set it up in a modern Vite + TypeScript environment. First, install the TanStack Form using this command:

npm install @tanstack/react-form # Or use, equivallent yarn, pnpm commands

Instead of a massive list of individual state hooks, you just need the useForm hook to spin up the form engine:

import { useForm } from '@tanstack/react-form';

export function SpeakerForm() {
  const form = useForm({
    defaultValues: {
      firstName: '',
      lastName: '',
      twitterHandle: '',
    },
    onSubmit: async ({ value }) => {
      console.log('Form Submitted!', value);
    },
  });

  return (
    
      Add New Speaker
      {/* We will build the fields here */}
    
  );
}

Notice the defaultValues. TanStack Form automatically infers your entire form structure from this object. If you try to reference an invalid field name later, TypeScript will throw an error immediately.

Fine-Grained Reactivity

Let's now connect the form inputs to the engine. To do that, we need to wrap them in TanStack's Field component. This uses the standard JSX render prop pattern to pass the isolated field state directly into our UI.

 {
    e.preventDefault();
    e.stopPropagation();
    form.handleSubmit();
  }}
  className="space-y-4"
>
  
    {(field) => {
      // PROOF: This log will only fire when firstName changes!
      console.log("Rendering First Name Field");
      
      return (
        
          
            First Name
          
           field.handleChange(e.target.value)}
            className="p-2 rounded-md bg-neutral-950 border border-neutral-700 focus:border-emerald-500 outline-none"
          />
        
      );
    }}

If you place a console.log in the parent component and one inside the field, you'll see the magic. When you type in the First Name input, the parent component doesn't re-render. Here's a visual of only the form field re-rendering.

The state update is strictly isolated to the function inside that specific Field component.

Validation with Zod

A form is only useful if it has field validations. In the current ecosystem, Zod is the industry standard. First, install Zod and the zod form adapter.

npm install zod @tanstack/zod-form-adapter # Or use, equivallent yarn, pnpm commands

Then inject the Zod adapter into your form engine:

import { zodValidator } from '@tanstack/zod-form-adapter';
import { z } from 'zod';

// Inside your component...
const form = useForm({
  defaultValues: { firstName: '', lastName: '' },
  validatorAdapter: zodValidator(),
  onSubmit: async ({ value }) => { /* ... */ },
});

Next, we'll update our field to use Zod rules. Here we opted for a rule that the first name must be at least 2 characters. Also, by checking the field.state.meta.isTouched, we ensure the error only shows after the user interacts with the input.



  {(field) => (
    
      
        First Name
      
      
       field.handleChange(e.target.value)}
        className="bg-neutral-950 border-neutral-700 focus-visible:ring-emerald-500"
      />
      {field.state.meta.isTouched && field.state.meta.errors.length ? (
        
        {
           field.state.meta.errors.map((error) =>  error.message)
         }
        ) : null}
    
    
  )}

The image below shows how the error message appears below the field when the First Name field value is changed and it fails validation.

Headless TanStack Form with ShadCN UI

TanStack Form is headless. This means you can map it to any design system seamlessly. Let's take one of the modern design systems available today: ShadCN UI.

If you are using a Vite-TypeScript-based React project, you can integrate the ShadCN UI in a few simple steps:

First, open the tsconfig.json file and add this compiler option:

"compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "./src/*"
      ]
    }
  }

Then open the vite.config.json file and add the mapping for the @ alias:

import react from '@vitejs/plugin-react'
import path from "path"
import { defineConfig } from 'vite'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
})

Install shadcn and its components like label, input, and button:

npx shadcn@latest add input label button

Now, you can import these ShadCN components into your form component and replace the native HTML label, input, and button.

import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";


  {(field) => (
    
      
        First Name
      
      
       field.handleChange(e.target.value)}
        className="bg-neutral-950 border-neutral-700 focus-visible:ring-emerald-500"
      />
      
       {field.state.meta.isTouched && field.state.meta.errors.length ? (
        
        {
           field.state.meta.errors.map((error) =>  error.message)
         }
        ) : null}
    
    
  )}

Handling Nested Dynamic Arrays with TanStack Form

Suppose we're building a speaker form for a meetup. What if we want to feature multiple speakers for a talk in our meetup? Now we need to manage a data structure to hold more than one speaker's details. We'll need an array of objects.

In classic React, managing an array of objects with complex states leads to spaghetti code. TanStack Form treats arrays exactly like a typical form field. We just need to update our defaultValues to an array:

defaultValues: {
  speakers: [ { firstName: '', lastName: '' } ],
},

Now, set the mode to array on your field and map over it:


  {(field) => (
    
      {field.state.value.map((_, index) => (
        
          
          
            {/* Nested Fields use bracket notation! */}
            
              {(subField) => (
                 
                    First Name
                     subField.handleChange(e.target.value)} 
                    />
                 
              )}
            
          

          {/* Remove Button */}
          {field.state.value.length > 1 && (
            
          )}
        
      ))}
      
      {/* Add Button */}
      
    
  )}

To append data, we call field.pushValue() and to remove, we call field.removeValue(index). Typing into the newest row leaves the previous array fields completely static. It's incredibly performant.

The image above shows the multi-speaker form and its output when submitted.

TanStack Form's Granular Reactivity: `useSelector` vs `form.Subscribe`

Sometimes, you need to access form state outside an input. For example, you want to show the "Unsaved Changes!" notification the moment the user changes the value in the input fields.

Notice that here the notification is outside the form, but it solely depends on the form field values.

TanStack gives you two distinct tools for this, and knowing when to use them is the key to mastering this architecture.

With `useSelector()`

If the state change affects the macro-layout of your page (like showing a global "unsaved Changes" banner like the above), you want the parent component to re-render. We'll use the standalone useSelector() hook for this:

import { useForm, useSelector } from "@tanstack/react-form";

export function ReactivityDemo() {
  const form = useForm({ defaultValues: { bio: "" } });

  // This isolates the exact piece of state we want the parent to track
  const isFormDirty = useSelector(form.store, (state) => state.isDirty);

  return (
    
      {isFormDirty && (
        
          Unsaved Changes!
        
      )}
      {/* Form goes here */}
    
  );
}

With `form.Subscribe()`

If the state change only affects a micro-interaction like disabling a submit button while the form is being saved, we don't want the whole form to re-render. In that case, we wrap the button tightly inside .

 [state.canSubmit, state.isSubmitting]}>
  {([canSubmit, isSubmitting]) => (
    
  )}

This isolates the re-render exclusively to the button. The rest of the component stays completely undisturbed.

TanStack Form vs. React Hook Form

If you've been building React applications for a while, you're probably thinking: "Why not just use React Hook Form?"

React Hook Form is an extraordinary library and has been the industry standard for years. It solves the performance problem by leveraging uncontrolled components and useRef under the hood. It isolates re-renders perfectly and handles validation well.

But as applications scale in complexity, the TanStack Form architecture offers three distinct advantages over React Hook Form:

Dynamic Arrays

If you've ever built a complex form with React Hook Form that needs dynamic, nested arrays (like adding multiple speakers in our example above), you probably need a hook like useFieldArray. Managing complex useFieldArray implementations often needs huge boilerplate, careful index tracking, and jumping through to maintain strict TypeScript safety deep within the tree.

TanStack Form eliminates this. It treats arrays the same as a string input. The form is a centralized state machine: you simply inform a field that it has a mode=array, and you instantly get access to pushValue() and removeValue() along with deeply nested type-safety.

Deeply Nested Components

React Hook Form relies on uncontrolled inputs to achieve performance. While this is fast, passing refs around deeply nested component trees can get messy, especially when integrating with complex UI libraries.

TanStack Form gives us the strict, predictable architecture of a controlled component but uses fine-grained reactivity to ensure only the specific parts of the UI that change are re-rendered.

The Ecosystem Sync

If you're moving towards modern, production-ready stacks using TanStack Query (React Query) for data fetching and TanStack Router for navigation, TanStack Form shares the exact same mental model and family. It integrates seamlessly into the ecosystem, providing a unified DX across your entire application architecture.

Conclusion & Important Resources

By combining TanStack Form, Zod, and ShadCN UI, we've created a strictly typed, reactive, production-ready form architecture that handles everything from basic text inputs to complex nested arrays without sacrificing any bit of performance.

You can grab the complete starter code and the final project from my GitHub:

All the source code used in the article and the complete project source code: https://github.com/tapascript/full-stack-vibe-to-prod/tree/main/11-tanstack-form
A code scaffolding repo for React projects using TypeScript, Vite, and TailwindCSS: https://github.com/atapas/code-react19-ts

If you found this helpful, you'll find these two in-depth video tutorials helpful, too:

If You've Read This Far...

Thank You!

I'm thrilled to announce that I've started a Full Stack FREE Course to take developers from vibe coding to a production-ready mental model. I'd be delighted if you check it out and take part.

Subscribe to my YouTube Channel
Follow on LinkedIn and X
Catch up with my React Clean Code Rules Book
All the source code used in this article is on my GitHub Repository.

See you soon with my next article. Until then, please take care of yourself and keep learning.

How to Build a Reusable Date-Time Picker in React with shadcn/ui

Vaibhav Gupta — Wed, 22 Jul 2026 16:47:40 +0000

A date and time picker is one of those components that looks small in a design file and turns into a real time sink once you start building it. You need a calendar, a time selector, a state that keeps both in sync, and usually a range mode and a translated version somewhere down the line, too.

This guide walks through ready-made picker patterns you can drop into a React project today: a combined date and time picker, a date range picker, and a time picker.

Every one of these is available as a Shadcn Date Picker component you can install with a single CLI command instead of building from scratch.

These components are built on both Radix and Base UI primitives, and the versions below use Base UI. They also support copy-prompt functionality, so you can paste them straight into v0, Lovable, or Bolt if that's part of your workflow.

Prerequisites
What You'll Build
How to Install a Shadcn Date Time Picker
How to Build a Date and Time Picker
How to Build a Date Range Picker
How to Build a Time Picker
Live Preview of the components
Key Concepts Recap
Conclusion
Resources

Prerequisites

To follow along, you should know:

The basics of React, including useState and props
How to install components with the shadcn/ui CLI
Basic Tailwind CSS class names

You also need a React project with shadcn/ui already set up. If you haven't done that yet, run the shadcn/ui CLI setup command in your project before continuing.

What You'll Build

A DateTimePicker component that combines a calendar and time slots into one value.
A TimePicker variant that reuses the same time-slot logic without a calendar.
A DateRangePicker that lets a user pick a start and end date.

How to Install a Shadcn Date Time Picker

All the components below install through the same CLI pattern. Pick the package manager you use:

pnpm

pnpm dlx shadcn@latest add @shadcn-space/date-picker-01

npm

npx shadcn@latest add @shadcn-space/date-picker-01

yarn

yarn dlx shadcn@latest add @shadcn-space/date-picker-01

bun

bunx --bun shadcn@latest add @shadcn-space/date-picker-01

Every other component below installs the same way: just swap the package name at the end of the command. If you haven't set up the CLI in your project yet, this getting-started guide covers that first and shows how to integrate these components when you're working through an MCP-connected editor.

How to Build a Date and Time Picker

This is the combined picker: a calendar popover for the date, plus start and end time fields, wrapped around a booking confirmation flow.

Folder structure:

components
└── shadcn-space
    └── date-picker
        └── date-picker-01.tsx

Component code:

"use client";
import { useState } from "react";
import { format } from "date-fns";
import { CalendarIcon, Clock, ChevronDown, Check } from "lucide-react";
import { cn } from "@/lib/utils";

import { Button } from "@/components/ui/button";
import { Calendar } from "@/components/ui/calendar";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover";

const DateAndTimePickerDemo = () => {
  const [open, setOpen] = useState(false);
  const [date, setDate] = useState(undefined);
  const [bookingStatus, setBookingStatus] = useState<
    "idle" | "loading" | "success"
  >("idle");

  const handleBooking = () => {
    setBookingStatus("loading");
    setTimeout(() => setBookingStatus("success"), 1500);
  };

  return (
    <>
      
        
          
            Select Date
          
          
             setBookingStatus("idle")}
              render={
                
              }
            />
            
               {
                  setDate(d);
                  setOpen(false);
                }}
                className="rounded-md border-none"
              />
            
          
        

        
          
            
               Start Time
            
            
          
          
            
               End Time
            
            
          
        

        
      
    
  );
};

export default DateAndTimePickerDemo;

How This Component Works

This component combines three pieces of state into a simple booking flow:

The selected date
Start and end times
The booking status (idle, loading, success)

The date is stored using React state:

const [date, setDate] = useState(undefined);

When a user selects a day from the calendar, the onSelect callback updates the state and closes the popover:

onSelect={(d) => {
  setDate(d);
  setOpen(false);
}}

The calendar itself lives inside a Popover, which keeps the UI compact. Clicking the trigger button opens the calendar panel:

The displayed date uses date-fns formatting:

format(date, "PPP")

This converts a JavaScript Date object into a readable format such as:

July 22, 2026

The time fields use native HTML inputs:

Native time inputs provide built-in browser support, mobile pickers, keyboard accessibility, and locale-aware formatting without additional libraries.

The booking button demonstrates how UI state can change during an async action:

"idle" → "loading" → "success"

In a real application, handleBooking() would typically call an API endpoint instead of using setTimeout.

This pattern works well for:

Meeting schedulers
Appointment systems
Interview booking tools
Event registration forms
SaaS scheduling workflows

How to Build a Date Range Picker

For anything involving a stay, a rental, or a multi-day booking, you need a range instead of a single date. This component pairs a two-month calendar view with a formatted range label and a computed night count.

Folder structure:

components
└── shadcn-space
    └── date-picker
        └── date-picker-02.tsx

Install this Shadcn Date Range Picker with:

npx shadcn@latest add @shadcn-space/date-picker-02

Component code:

"use client";
import * as React from "react";
import { CalendarIcon, ChevronDown } from "lucide-react";
import { addDays, format } from "date-fns";
import { DateRange } from "react-day-picker";

import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";
import { Calendar } from "@/components/ui/calendar";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover";
import { Label } from "@/components/ui/label";

const DateRangePickerDemo = () => {
  const [date, setDate] = React.useState({
    from: new Date(),
    to: addDays(new Date(), 7),
  });

  return (
    
      
        Select Travel Dates
      
      
        
          
                
                {date?.from ? (
                  date.to ? (
                    <>
                      {format(date.from, "LLL dd, y")} -{" "}
                      {format(date.to, "LLL dd, y")}
                    
                  ) : (
                    format(date.from, "LLL dd, y")
                  )
                ) : (
                  Pick a range
                )}
                
              
            }
          />
          
            
          
        
      
      
        {date?.from && date?.to
          ? `Stay duration: ${Math.round((date.to.getTime() - date.from.getTime()) / (1000 * 60 * 60 * 24))} nights`
          : "Please select a valid date range."}
      
    
  );
};

export default DateRangePickerDemo;

How the Date Range Picker Works

This version switches the Calendar component from single-date mode to range mode:

mode="range"

Instead of storing one Date, the component stores a DateRange object:

{
  from: Date,
  to: Date
}

This makes it easy to work with booking systems, hotel stays, travel forms, and rental applications.

The component displays two calendar months:

numberOfMonths={2}

Showing two months reduces navigation and improves the selection experience for longer stays.

The stay duration is calculated directly from the selected dates:

(date.to.getTime() - date.from.getTime())

This avoids additional libraries and keeps the logic simple.

Compared to the first example:

Uses DateRange instead of a single Date
Uses mode="range"
Displays two months
Adds derived data like total nights

How to Build a Time Picker

Not every form needs a calendar. This one wraps the native in an InputGroup with a clock icon that triggers the browser's own time picker UI on click.

Folder structure:

components
└── shadcn-space
    └── date-picker
        └── date-picker-03.tsx

Install this Shadcn Time Picker with:

npx shadcn@latest add @shadcn-space/date-picker-03

Component code:

"use client";
import { useRef } from "react";
import { Label } from "@/components/ui/label";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@/components/ui/input-group";
import { Clock8Icon } from "lucide-react";

const TimePickerWithIconDemo = () => {
  const inputRef = useRef(null);

  const handleShowPicker = () => {
    if (inputRef.current && "showPicker" in inputRef.current) {
      try {
        inputRef.current.showPicker();
      } catch (error) {
        console.error("Failed to open native picker:", error);
      }
    }
  };

  return (
    
      Select Slot
      
        
          
        
        
      
    
  );
};
export default TimePickerWithIconDemo;

How the Time Picker Works

This component uses the browser's native time picker instead of building a custom dropdown.

The input is referenced with useRef:

const inputRef = useRef(null);

This allows the icon button to access the input element directly.

When users click the clock icon, the browser's picker opens programmatically:

inputRef.current.showPicker();

The showPicker() method is a modern browser API that opens the same interface users would see if they clicked the input manually.

The component wraps the input inside an InputGroup:

This creates a cleaner layout where the icon behaves as part of the field rather than a separate button.

The browser's default picker icon is hidden:

[&::-webkit-calendar-picker-indicator]:hidden

This prevents duplicate icons and gives full control over the UI.

The benefit of this approach is that it keeps:

Native accessibility
Mobile keyboard support
Locale-aware formatting
Better browser compatibility

Instead of rebuilding time selection from scratch, the component improves the native experience with custom styling.

Live Preview of the Components

Key Concepts Recap

Pick the pattern that matches the data you're collecting: A single date and time for bookings, a range for stays, a bare time field for slots.
Every component installs the same way: One CLI command per component: pnpm, npm, yarn, and bun. All are supported. Adding a new picker to a project takes one line, not a manual build.
The date and time picker separates date state from time state, then combines them at the confirmation step. This keeps the calendar and the time inputs from getting out of sync.
The range picker leans on the Calendar's built-in mode="range": The two-month view and the night count come from the selection state, not custom range math.
The time picker wraps the native instead of replacing it: This keeps native accessibility and mobile keyboard behavior intact.

Conclusion

You now have working picker patterns for React: a date and time picker for bookings, a date range picker for stays, and a plain time picker for slots.

Each one installs with a single CLI command, so you can pick whichever one matches the form you're building and have it running in minutes.

Resources

shadcn/ui documentation: For the official Popover, Calendar, and Button component APIs
date-fns documentation: For the date helper functions and locale files used in this tutorial
react-day-picker documentation: For the range and multi-date selection modes that power the shadcn/ui Calendar
MDN: ARIA live regions: For more on how role="alert" works
Shadcn Date Time Picker components: If you want more prebuilt date and time picker variants to compare against.
Full Shadcn components library: For other shadcn/ui-compatible components
Guide to free Shadcn date and time pickers

How to Use Apple’s Foundation Models in a Web App with a macOS Companion

Balogun Wahab — Mon, 20 Jul 2026 21:27:11 +0000

Not every AI feature needs a cloud model, with its per-token bills, network round-trips, and private data leaving your machine. If you're on a modern Mac, a capable language model is already on your disk.

Foundation Models is Apple's Swift framework for working with large language models. It's the on-device model behind Apple Intelligence, Apple's Private Cloud Compute, or another provider's server model.

This tutorial targets the on-device model: you send it a prompt and it runs entirely on the Mac's own hardware locally, free-per-call, and offline-friendly.

Paired with Apple Vision for reading images on device, that's enough to build real AI features like summaries, classification, and structured extraction without the data ever leaving your machine.

What You Will Build
Prerequisites
Why a macOS Companion App?
Foundation Models Can't Read Images Directly
Project Structure
Build the React App
Build the macOS Companion App
Check Foundation Models Availability
Extract Text with Apple Vision
Ask Foundation Models to Explain the Vision Output
Return JSON to the Browser
Run the App
Conclusion
Resources

What You Will Build

You'll build Vision Bridge, a web app that sends an image to a local macOS companion. The companion reads the image with Apple Vision, reasons about it with Foundation Models, and returns structured JSON to the browser: private, on-device AI behind a plain web interface.

You can find the complete source code in this GitHub repository: github.com/03balogun/vision-bridge.

The goal isn't to build a giant product but rather to understand the architecture behind how this works.

Vision Bridge has two parts:

A React app with a split-screen interface.
A macOS companion app that exposes a local API.

The React app has:

An image upload area
An image preview
Automatic analysis after upload
A JSON output viewer
A companion health status indicator

The macOS companion app has:

GET /v1/health
POST /v1/analyze-image
Apple Vision OCR
Foundation Models availability checks
Foundation Models reasoning over Vision output

The final response looks like this:

{
  "support": {
    "visionAvailable": true,
    "foundationModelAvailable": true,
    "foundationModelStatus": "available"
  },
  "image": {
    "filename": "screenshot.png",
    "contentType": "image/png",
    "byteCount": 1048576,
    "width": 1440,
    "height": 900
  },
  "vision": {
    "detectedText": [
      {
        "text": "Build failed",
        "confidence": 0.96,
        "boundingBox": {
          "x": 0.12,
          "y": 0.31,
          "width": 0.45,
          "height": 0.08
        }
      }
    ]
  },
  "model": {
    "summary": "The image appears to show a software build failure.",
    "description": "A developer tool window is showing an error state with diagnostic text.",
    "suggestedTags": ["screenshot", "developer-tool", "error"],
    "possibleUses": [
      "Generate alt text",
      "Summarize screenshots",
      "Extract document data"
    ]
  }
}

Prerequisites

To follow along, you need:

macOS 26 or newer
Xcode with the macOS 26 SDK
Node.js 20 or newer
Basic React knowledge
Basic Swift knowledge
A Mac that supports Apple Intelligence

Foundation Models availability depends on the Mac, the OS version, and Apple Intelligence settings. The companion checks this at runtime, which we'll cover below.

Why a macOS Companion App?

You can't write this in a regular React app:

import FoundationModels from "apple-frameworks";

That API doesn't exist in the browser. A native macOS app, however, can use any Apple framework, so the companion acts as a local bridge. The same pattern works for any native capability the web platform doesn't expose.

Foundation Models Can't Read Images Directly

The public Foundation Models framework is a language model interface. It doesn't currently expose direct image input the way a multimodal cloud model might, so this tutorial never sends the image to the model. Instead, the companion feeds the Vision OCR observations and image metadata into the prompt. The model reasons over structured text, never the original pixels.

That split plays to each framework's strength: Vision is excellent at pulling machine-readable information out of images, and Foundation Models turns that information into summaries, labels, explanations, and structured output.

The above diagram shows the round trip that the rest of this tutorial builds. The browser sends the uploaded image as base64 JSON over localhost to the Swift companion. Inside the companion, Apple Vision runs OCR on the image and produces text observations: the recognized strings, their confidence scores, and their bounding boxes.

Those observations, not the image itself, are formatted into a prompt for Foundation Models, which generates a summary, description, and tags. The companion then bundles the Vision output and the model output into one JSON response and returns it to the browser.

Project Structure

Create a project with this structure:

vision-bridge/
  apps/
    web/
      src/
        main.tsx
        styles.css
      package.json
      vite.config.ts
    macos-companion/
      Package.swift
      Sources/
        VisionBridgeCompanion/
          main.swift
  package.json
  README.md

The root package.json gives us a few convenient commands:

{
  "scripts": {
    "dev": "npm --workspace apps/web run dev",
    "build": "npm --workspace apps/web run build",
    "companion": "swift run --package-path apps/macos-companion VisionBridgeCompanion"
  },
  "workspaces": ["apps/web"]
}

Build the React App

The web app is intentionally simple. It has one job: let the user pick an image and show the JSON returned by the companion.

The web app uses Vite, React, Lucide icons, and a JSON viewer:

{
  "dependencies": {
    "@vitejs/plugin-react": "^6.0.3",
    "lucide-react": "^0.468.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-json-view-lite": "^2.5.0",
    "vite": "^8.1.3"
  }
}

After defining the dependencies, install them:

npm install

The API base URL points to the local companion:

const API_BASE_URL = "http://127.0.0.1:43119";

Check Companion Health

The web app pings the companion so the UI can show whether the native bridge is online:

async function checkHealth() {
  setHealthError(null);

  try {
    const response = await fetch(`${API_BASE_URL}/v1/health`);
    if (!response.ok) {
      throw new Error(`Health check failed with ${response.status}`);
    }

    const payload = await response.json();
    setHealth(payload);
  } catch (error) {
    setHealth(null);
    setHealthError(error instanceof Error ? error.message : "Companion unavailable");
  }
}

Convert the Image to Base64

When the user selects a file, the app converts it to base64 so it can be sent as JSON:

function readFileAsBase64(file: File) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => {
      const result = String(reader.result);
      resolve(result.includes(",") ? result.split(",")[1] : result);
    };
    reader.onerror = () => reject(reader.error);
    reader.readAsDataURL(file);
  });
}

This isn't the only way to upload files. You could also use multipart/form-data, but JSON keeps the demo easy to inspect.

Analyze Immediately After Upload

The app starts analysis as soon as an image is uploaded:

async function handleFile(file: File) {
  if (!file.type.startsWith("image/")) {
    setError("Choose a PNG, JPEG, HEIC, or another browser-readable image.");
    return;
  }

  const base64 = await readFileAsBase64(file);
  const nextImage = {
    file,
    previewUrl: URL.createObjectURL(file),
    base64,
  };

  setSelectedImage(nextImage);
  setAnalysis(null);
  setError(null);
  setCopied(false);

  analyzeImage(nextImage);
}

handleFile does the preparation work for every new image. It rejects anything that isn't a browser-readable image, converts the file to base64, and builds a single object holding everything the rest of the flow needs: the original File (for its name and MIME type), an object URL for the preview, and the base64 payload for the API call.

It then clears out the previous run the old analysis, any error message, and the "copied" indicator so the UI never shows results from the last image next to a new one. Finally, it kicks off analyzeImage(nextImage) immediately.

Note that it passes the fresh object directly instead of relying on the selectedImage state: React state updates don't apply until the next render, so reading the state here would still give you the previous image.

The Analyze button still exists in the UI, but it works as a manual rerun button.

Send the Image to the Companion

Here's the core request:

const analysisRequestId = useRef(0);

async function analyzeImage(image = selectedImage) {
  if (!image) {
    setError("Choose an image first.");
    return;
  }

  const requestId = analysisRequestId.current + 1;
  analysisRequestId.current = requestId;

  setRequestState("loading");
  setError(null);
  setCopied(false);

  try {
    const response = await fetch(`${API_BASE_URL}/v1/analyze-image`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        filename: image.file.name,
        mimeType: image.file.type || "application/octet-stream",
        base64: image.base64,
      }),
    });

    const payload = await response.json();

    if (requestId !== analysisRequestId.current) {
      return;
    }

    if (!response.ok) {
      throw new Error(payload.error?.message ?? `Analysis failed with ${response.status}`);
    }

    setAnalysis(payload);
    setRequestState("success");
  } catch (error) {
    if (requestId !== analysisRequestId.current) {
      return;
    }

    setRequestState("error");
    setError(error instanceof Error ? error.message : "Could not analyze image");
  }
}

This function is the entire client side of the bridge. It flips requestState to loading (which drives the spinner and disables the button), then sends a POST to /v1/analyze-image with a JSON body containing three fields: the filename, the MIME type, and the base64 image data. That body maps one-to-one onto the AnalyzeImageRequest struct the Swift companion decodes later.

Notice that the response is parsed as JSON before checking response.ok. That's deliberate: when the companion rejects a request (bad base64, oversized image), it still returns a JSON body with an error.message field, so the UI can show the companion's own explanation instead of a generic status code. On success, the payload goes straight into state, and the JSON viewer re-renders with the result.

The requestId bookkeeping guards against stale responses. If a user uploads a second image while the first is still analyzing, whichever request finishes last would win, and OCR plus model generation takes long enough that responses can genuinely arrive out of order. So every call increments a counter stored in a ref and remembers its own ID.

After the await, it checks whether it's still the newest request; if a newer upload started in the meantime, the older response is silently discarded instead of overwriting the latest image's result. The same check runs in the catch block, so an old failure can't clobber a newer success either. If you also want to cancel the in-flight HTTP request rather than just ignore its result, an AbortController is the natural next step.

Render the JSON Output

The output pane uses react-json-view-lite:

Build the macOS Companion App

The companion is a Swift command-line app. It exposes a small local HTTP API.

If you come from the web side, the mapping is simple: Swift Package Manager is Swift's npm, Package.swift is its package.json, and swift run is its npm start. It ships with Xcode, so there's nothing extra to install.

The Package.swift file looks like this:

// swift-tools-version: 6.0

import PackageDescription

let package = Package(
    name: "VisionBridgeCompanion",
    platforms: [
        .macOS("26.0")
    ],
    products: [
        .executable(
            name: "VisionBridgeCompanion",
            targets: ["VisionBridgeCompanion"]
        )
    ],
    targets: [
        .executableTarget(
            name: "VisionBridgeCompanion"
        )
    ]
)

The companion imports the Apple frameworks it needs:

import Foundation
import FoundationModels
import ImageIO
import Network
import Vision

It listens on 127.0.0.1:43119:

private let defaultPort: UInt16 = 43119

The app exposes two routes:

switch (request.method, request.path) {
case ("GET", "/v1/health"):
    let health = HealthResponse(support: ModelSupport.current)
    return try json(health)

case ("POST", "/v1/analyze-image"):
    let payload = try JSONDecoder().decode(AnalyzeImageRequest.self, from: request.body)
    let response = try await service.analyze(payload)
    return try json(response)

default:
    return try json(
        ErrorResponse(error: APIErrorPayload(message: "Route not found")),
        status: .notFound
    )
}

This switch is the companion's entire routing layer — no web framework, just pattern matching on the method and path.

The two routes split the work cleanly:

GET /v1/health is the cheap, read-only route. It runs no analysis, it just reports whether Vision and Foundation Models are usable on this Mac via ModelSupport.current (covered in the next section). The React app calls it on load to render the online/offline status pill, so the user knows the bridge is up before they upload anything.
POST /v1/analyze-image is where the real work happens. It decodes the request body into an AnalyzeImageRequest (with the same filename, mimeType, and base64 fields the browser sent) and hands it to the analysis service. This validates the image, runs Vision OCR, prompts Foundation Models, and returns the combined result. The try await matters here: analysis is asynchronous, and the route simply waits for it before serializing the response.

Anything else falls through to a JSON 404, so even unknown routes respond in the same format the browser already knows how to parse.

Errors work the same way: thrown errors are caught in one place and converted into JSON error responses with an appropriate status code, which is exactly what the web app's payload.error?.message check reads.

One practical detail: because the browser calls the companion from a different origin (the Vite dev server), every response also carries CORS headers, and the router answers preflight OPTIONS requests with an empty 204. Without that, the browser would block the fetch before it ever reached these routes.

Check Foundation Models Availability

The companion shouldn't assume that the model is available. Check it first:

private struct ModelSupport: Encodable {
    let visionAvailable: Bool
    let foundationModelAvailable: Bool
    let foundationModelStatus: String

    static var current: ModelSupport {
        let model = SystemLanguageModel.default

        switch model.availability {
        case .available:
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: true,
                foundationModelStatus: "available"
            )

        case .unavailable(let reason):
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: false,
                foundationModelStatus: "unavailable.\(reason.description)"
            )

        @unknown default:
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: false,
                foundationModelStatus: "unavailable.unknown"
            )
        }
    }
}

A user might have an unsupported Mac, Apple Intelligence might be disabled, or the model might not be ready yet. The response tells the browser which case it's dealing with.

Extract Text with Apple Vision

The companion decodes the base64 image, checks its metadata, then runs Vision OCR.

Here's the text recognition flow:

private func recognizeText(in imageData: Data) async throws -> [DetectedText] {
    var request = RecognizeTextRequest()
    request.recognitionLevel = .accurate
    request.automaticallyDetectsLanguage = true
    request.usesLanguageCorrection = true

    let observations = try await request.perform(on: imageData)

    var detectedText: [DetectedText] = []

    for observation in observations {
        guard let candidate = observation.topCandidates(1).first else {
            continue
        }

        let bounds = NormalizedBox.from(points: [
            observation.topLeft,
            observation.topRight,
            observation.bottomRight,
            observation.bottomLeft
        ])

        detectedText.append(DetectedText(
            text: candidate.string,
            confidence: Double(candidate.confidence),
            boundingBox: bounds
        ))
    }

    return detectedText
}

Vision gives us structured observations:

recognized text
confidence scores
normalized bounding boxes

Those observations become the model’s context.

Ask Foundation Models to Explain the Vision Output

Now the companion creates a prompt from the image metadata and OCR results.

Notice the instruction:

You cannot see the original image. Use only the metadata and OCR observations below.

That keeps the model honest. It shouldn't pretend to see pixels it never received.

Here's the prompt shape:

let textPreview = detectedText
    .prefix(30)
    .map { "- \($0.text) (confidence: \(String(format: "%.2f", $0.confidence)))" }
    .joined(separator: "\n")

let prompt = """
You are summarizing Apple Vision OCR output for a developer tool named Vision Bridge.
You cannot see the original image. Use only the metadata and OCR observations below.

Image:
- filename: \(image.filename)
- content type: \(image.contentType)
- size: \(image.width ?? 0)x\(image.height ?? 0)

OCR observations:
\(textPreview.isEmpty ? "- No text detected." : textPreview)

Return a compact JSON object with these exact keys:
summary: one sentence
description: one short paragraph
suggestedTags: 3 to 6 short tags
possibleUses: 3 to 5 practical use cases for this kind of image analysis
"""

Then call the model:

let session = LanguageModelSession(
    model: .default,
    instructions: "Return valid JSON only. Do not include Markdown fences."
)

let response = try await session.respond(to: prompt)
let raw = response.content.trimmingCharacters(in: .whitespacesAndNewlines)

Even when you ask for JSON, always validate the output. Models can still return Markdown fences or malformed text. The sample app strips simple Markdown code fences and falls back to a raw response if parsing fails.

Return JSON to the Browser

The companion combines the support state, image metadata, Vision results, and model output:

return AnalyzeImageResponse(
    support: support,
    image: metadata,
    vision: VisionPayload(detectedText: detectedText),
    model: modelInsight
)

The browser doesn't need to know how Vision or Foundation Models work. It just receives JSON. The native app owns the native capabilities, while the web app owns the interface.

It's worth pausing on what each of the four blocks actually gives you, because they're not all the same kind of data:

support tells you what was possible on this Mac. If foundationModelAvailable is false, the model block still exists but contains a fallback message rather than real analysis, and the foundationModelStatus string (for example, unavailable.appleIntelligenceNotEnabled) tells the UI why, so it can explain rather than silently degrade.
image echoes back the file's metadata plus the measured pixel dimensions. It's useful as a sanity check, and you need the width and height to do anything spatial with the Vision results.
vision is the ground truth. Each entry in detectedText is a string Vision actually found, with a confidence score between 0 and 1 and a normalized bounding box: coordinates expressed as fractions of the image size, so x: 0.12, width: 0.45 means "starts 12% from the left and spans 45% of the width." Because the boxes are normalized, you can draw highlight overlays on the preview at any display size by multiplying by the rendered dimensions. Low-confidence entries are worth filtering or flagging before you trust them.
model is interpretation, not observation. The summary, description, suggestedTags, and possibleUses fields are generated by the language model from the OCR text. This is useful as alt text, captions, or tag suggestions, but they inherit whatever the OCR missed and should be treated as a draft, not a fact. When the model's output can't be parsed as JSON, rawResponse carries the unparsed text so nothing is lost.

For a screenshot of a failed build, the model block might come back like this:

{
  "model": {
    "summary": "The image appears to show a software build failure.",
    "description": "A developer tool window is showing an error state with diagnostic text.",
    "suggestedTags": ["screenshot", "developer-tool", "error"],
    "possibleUses": [
      "Generate alt text",
      "Summarize screenshots",
      "Extract document data"
    ]
  }
}

That combination (exact text with positions from Vision, plus a human-readable interpretation from the model) is enough to build real features on top of a searchable screenshot library indexed by detectedText and suggestedTags, automatic alt text for uploaded images, or click-to-highlight overlays powered by the bounding boxes.

And because the prompt lives in the companion, changing what comes back (say, extracting line items from receipts instead of tagging screenshots) is a prompt edit, not an architecture change.

Run the App

Start the companion:

npm run companion

In another terminal, start the web app:

npm run dev

Open the Vite URL:

http://127.0.0.1:5173

If that port is busy, Vite will choose another one.

The companion should be available at:

http://127.0.0.1:43119

You can test it directly:

curl http://127.0.0.1:43119/v1/health

Expected response:

{
  "app": "Vision Bridge Companion",
  "ok": true,
  "support": {
    "foundationModelAvailable": true,
    "foundationModelStatus": "available",
    "visionAvailable": true
  },
  "version": "0.1.0"
}

Conclusion

You now have a React interface that uploads an image, a Swift companion that analyzes it with Apple-native frameworks, and structured JSON flowing between them.

Vision Bridge is intentionally small, but the bridge itself is reusable. Once you have a trusted native companion, a web app can do more than send prompts to a remote model: it can ask the Mac to work with local context, use any Apple framework, and return structured data the browser can render, store, or sync.

Resources

How to Build a Shadcn Sheet Component in React: Cart and Filter Panel Examples

Vaibhav Gupta — Mon, 13 Jul 2026 14:13:49 +0000

A Sheet is a panel that slides in from the edge of the screen instead of popping up in the center like a modal. You've likely used one when you've opened a shopping cart on an e-commerce site or tapped a filter icon and watched options slide in from the side.

Building a Sheet that scrolls correctly with long content, keeps a header and footer fixed in place, and manages form or counter state without bugs takes more than wrapping a

in a slide animation.

In this tutorial, you'll build two production-ready Sheet components using shadcn/ui and Base UI primitives via Shadcn Space:

A Shopping Cart Sheet with quantity controls, item removal, and a live subtotal.
A Filter Panel Sheet with category checkboxes, a price range slider, star ratings, and an active filter count.

By the end, you'll have both components running in your project, and you'll understand the state and layout decisions behind them well enough to build your own Sheet variants from scratch.

Prerequisites
What You'll Build
How to Set Up the CLI Registry
How to Build the Shopping Cart Sheet (sheet-03)
How to Build the Filter Panel Sheet (sheet-04)
Quick Reference Table
Key Concepts Recap
Conclusion
Resources

Prerequisites

Before you start, make sure you have:

Node.js 18 or higher installed
shadcn/ui initialized in your project (npx shadcn@latest init)
Basic knowledge of React and TypeScript

If you haven't initialized shadcn/ui yet, run npx shadcn@latest init in your project root and follow the prompts before continuing.

What You'll Build

This tutorial uses components installed through the Shadcn Space registry, an open-source collection of production-ready components and UI blocks for shadcn/ui.

You can browse the full set in the Shadcn Sheet component library. Each component supports both Radix UI and Base UI primitives and includes a Copy Prompt option, so you can paste the component spec into tools like v0, Lovable, or Bolt if you're prototyping. This tutorial uses the Base UI versions.

Shopping Cart Sheet (sheet-03)

Slide-in panel from the right with a cart icon trigger and item-count badge
Quantity increment, decrement, and removal per item
Live subtotal and total calculated from cart state
Fixed header and footer with a scrollable item list in between

Filter Panel Sheet (sheet-04)

Slide-in panel from the left
Multi-select category checkboxes
Price range slider with live min/max display
Single-select star rating filter
Active filter count badge and a "Clear All" action that doesn't close the panel

How to Set Up the CLI Registry

Before running any install commands, register the Shadcn Space registry in your components.json file.

Open components.json in your project root and add the registries field:

{
  "registries": {
    "@shadcn-space": {
      "url": "https://shadcnspace.com/r/{name}.json"
    }
  }
}

This tells the shadcn CLI where to resolve components prefixed with @shadcn-space/. Without this step, the install commands below will fail.

For a full walkthrough of registry setup, see the getting started guide. Shadcn Space also ships an MCP server, so you can browse and install components straight from your editor if your workflow uses MCP tooling. If you prefer following along visually with a video, here you go:

How to Build the Shopping Cart Sheet (sheet-03)

What the Cart Sheet Does

The cart icon sits in your navbar. Clicking it slides a panel in from the right showing each item's image, name, variant, and price, with controls to change quantity or remove the item entirely. The subtotal updates as you go, and the footer stays pinned at the bottom regardless of how many items are in the list.

How to Install the Cart Sheet

Run one of the following based on your package manager:

npm:

npx shadcn@latest add @shadcn-space/sheet-03

pnpm:

pnpm dlx shadcn@latest add @shadcn-space/sheet-03

Yarn:

yarn dlx shadcn@latest add @shadcn-space/sheet-03

Bun:

bunx --bun shadcn@latest add @shadcn-space/sheet-03

The CLI copies the component into your project at:

components/
  shadcn-space/
    sheet/
      sheet-03.tsx

The Component Code

"use client";
import { useState } from "react";
import { ShoppingCartIcon, PlusIcon, MinusIcon, Trash2Icon } from "lucide-react";
import {
  Sheet,
  SheetTrigger,
  SheetContent,
  SheetHeader,
  SheetTitle,
  SheetDescription,
  SheetFooter,
  SheetClose,
} from "@/components/ui/sheet";
import { Button } from "@/components/ui/button";
import { ButtonGroup, ButtonGroupText } from "@/components/ui/button-group";
import { Badge } from "@/components/ui/badge";
import { Separator } from "@/components/ui/separator";

const initialItems = [
  {
    id: 1,
    name: "Apple Watch S9",
    variant: "Midnight / 41mm",
    price: 684.0,
    qty: 1,
    image: "https://images.shadcnspace.com/assets/ecommerce/product-category/product-category-03-1.webp",
  },
  {
    id: 2,
    name: "Beige Jacket",
    variant: "Size M / Beige",
    price: 479.0,
    qty: 1,
    image: "https://images.shadcnspace.com/assets/ecommerce/product-category/product-category-02-2.webp",
  },
  {
    id: 3,
    name: "Glow Serum",
    variant: "30ml / Vitamin C",
    price: 46.0,
    qty: 2,
    image: "https://images.shadcnspace.com/assets/ecommerce/product-category/product-category-03-3.webp",
  },
];

const ShoppingCartDemo = () => {
  const [items, setItems] = useState(initialItems);

  const updateQty = (id, delta) => {
    setItems((prev) =>
      prev
        .map((item) => (item.id === id ? { ...item, qty: item.qty + delta } : item))
        .filter((item) => item.qty > 0)
    );
  };

  const subtotal = items.reduce((sum, item) => sum + item.price * item.qty, 0);
  const totalCount = items.reduce((sum, item) => sum + item.qty, 0);

  return (
    
      }>
        
        {totalCount > 0 && (
          
            {totalCount}
          
        )}
      

      
        
          Your Cart
          
            {totalCount > 0
              ? `${totalCount} item${totalCount > 1 ? "s" : ""} in your cart`
              : "Your cart is empty"}
          
        

        
          {items.map((item) => (
            
              
                
              
              
                {item.name}
                {item.variant}
                ${item.price.toFixed(2)}
              
              
                
                
                  
                  {item.qty}
                  
                
              
            
          ))}
        

        
          
            
              Subtotal
              ${subtotal.toFixed(2)}
            
            
              Shipping
              Free
            
            
            
              Total
              ${subtotal.toFixed(2)}
            
          
          
          }>
            Continue Shopping
          
        
      
    
  );
};

export default ShoppingCartDemo;

Let's go through how this works.

1. Derived totals instead of tracked state

subtotal and totalCount are calculated from items on every render, not stored in their own useState. If you tracked them separately, they'd drift out of sync the first time you updated items and forgot to update the count alongside them.

2. Removing an item is just zeroing its quantity

const updateQty = (id, delta) => {
  setItems((prev) =>
    prev
      .map((item) => (item.id === id ? { ...item, qty: item.qty + delta } : item))
      .filter((item) => item.qty > 0)
  );
};

The trash icon calls updateQty(item.id, -item.qty), which drops that item's quantity to zero. The .filter() step then removes it from the array. This means you don't need a separate "remove item" function that duplicates logic already living in updateQty.

3. `render` prop instead of `asChild`

SheetTrigger and SheetClose use the render prop (render={}>Apply Filters ); }; export default AdvancedFiltersDemo;

How this component works:

1. Use a separate state for each filter type

Categories and availability use arrays because users can select multiple options. Rating stores a single value (or null) since only one rating can be selected. Price uses a two-value array ([min, max]) to store the selected range. This keeps each filter's state simple and matches how the UI works.

2. `activeCount` is computed, not tracked

Same reasoning as the cart badge above:

const activeCount =
  selectedCategories.length +
  (priceRange[0] !== 0 || priceRange[1] !== 1000 ? 1 : 0) +
  (selectedRating !== null ? 1 : 0) +
  selectedAvailability.length;

If you tracked this count manually, you'd eventually add a new filter, forget to update the count logic, and end up with a badge that lies to the user.

3. "Apply Filters" closes the panel, "Clear All" doesn't

Clear All calls clearAll() directly on a plain Button. Apply Filters is wrapped in SheetClose, so it resets nothing but closes the panel. A user clearing filters usually wants to keep the panel open to pick new ones. Closing on every action would force them to reopen it each time.

4. Toggling a category with `.filter()` and spread

const toggleCategory = (cat) =>
  setSelectedCategories((prev) => (prev.includes(cat) ? prev.filter((c) => c !== cat) : [...prev, cat]));

This one line handles both adding and removing a category from the array, based on whether it's already present. It's a pattern worth reusing anywhere you have a multi-select checkbox list backed by an array of strings.

Live Preview:

Quick Reference Table

Sheet	Identifier	Use Case
Shopping Cart Sheet	sheet-03	Cart drawers, order summaries
Filter Panel Sheet	sheet-04	Product filters, search refinement panels

To install either, swap the identifier in the CLI command:

npx shadcn@latest add @shadcn-space/

Key Concepts for Using Shadcn Sheet

Use a Sheet for secondary workflows: It's ideal for filters, shopping carts, settings, navigation menus, and forms that shouldn't interrupt the main page.
Keep the layout consistent: Use a fixed header, a scrollable content area (flex-1 overflow-y-auto), and a fixed footer so actions remain visible even with long content.
Derive UI values from state: Counts, totals, and badges (such as active filters or cart items) should be calculated from state instead of being stored separately.
Close the Sheet after completing an action: Actions like Apply Filters, Save, or Checkout should close the Sheet. Actions like Clear Filters or Reset should keep it open so users can continue making changes.
Choose the right state structure: Use arrays for multi-select options (such as categories or availability), a single value (or null) for single-select options (such as ratings), and a two-value array ([min, max]) for range filters like price.
Keep actions easy to reach: Place primary actions like Apply, Save, or Checkout in the footer so they remain accessible while the content scrolls.
Avoid overloading the Sheet: If the workflow is long, requires multiple steps, or needs the user's full attention, consider using a dedicated page instead of a Sheet.

Conclusion

In this guide, we built two practical Shadcn Sheet components, a shopping cart and a filter panel, to demonstrate the patterns you'll use most often in React applications. Along the way, we covered layout best practices, state management, derived values, and interaction patterns that make Sheets feel intuitive and reliable.

These examples are more than just demos. They provide a reusable foundation for building settings drawers, mobile navigation, notification panels, and many other side panel experiences. By following these patterns, you can create Shadcn Sheet components that are clean, responsive, and easy to maintain as your application grows.

Resources

Shadcn UI: Component library and documentation home
Shadcn Sheet Components: All Sheet variants are available in Radix and Base UI
Shadcn Components: Full component library with all available categories
Shadcn Dashboard: Ready-to-use admin dashboard built on the same system
Shadcn Sidebar: If you're looking for a shadcn sidebar to pair with these panels, this is where to start
How to Use the Shadcn CLI: Getting started guide for the CLI and registry setup
Shadcn MCP Server: Browse and install components from your editor
Video Walkthrough: How to Use Shadcn Space with MCP Server
Official shadcn/ui Documentation

How to Defend Your JavaScript App Against Unsafe Data with TypeScript Guard Utilities

Kelechi Apugo — Wed, 01 Jul 2026 20:21:18 +0000

Picture this: you hit an API endpoint, and you get an API response back. You pass the data straight into your application, and everything looks fine in development. Your mock data is clean, your types line up, and everything checks out.

Then your code hits production. A field from the API endpoint comes back as null instead of a string. You were expecting an array, and it comes back as undefined, expecting an object and receiving a number. Suddenly, you're faced with an error screen, a crashed UI, or worse, silent data corruption that nobody notices until a user complains.

This is a common and preventable bug in JavaScript development. The fix doesn't require a third-party library or a complete architecture overhaul. It requires a small set of utility functions and the discipline to use them when needed.

This article shows you how to build a resilient application using four TypeScript guard utilities that'll make your codebase more reliable: safeArray, safeString, safeNumber, and safeObject. The utilities are framework-agnostic, so whether you're working in React, plain JavaScript, or anything in between, you can drop them straight into your codebase.

The Problem
Why This Problem Exists
The Solution: Safe Access Utilities
How Each Utility Works
How to Use Them in Practice
Best Practices
Things to Avoid
Bonus: Combine Them into a safeData Helper
Conclusion

Prerequisites

Before diving in, you should have:

A working knowledge of TypeScript. You don't need to be an expert, but you should be comfortable with types, interfaces, and generics
Familiarity with JavaScript and its built-in type-checking methods, like typeof and Array.isArray.

The Problem

JavaScript is a loosely typed language. It will let you call .map() on something that isn't an array, access properties on null, and do arithmetic with NaN. All of this, without throwing an error until it's too late. The language doesn't push back. It just breaks quietly.

TypeScript helps, but only up to a point. It checks types at compile time, not at runtime. So when external data arrives from an API, a form submission, local storage, or a third-party SDK, TypeScript has already left the building. Whatever your interface says, the actual value at runtime is whatever JavaScript received.

Here's what that looks like in practice:

// This looks fine. It is not fine.
type User = {
  id: number;
  name: string;
  tags: string[];
};

function displayUser(user: User) {
  const upperName = user.name.toUpperCase();
  const tagList = user.tags.map((tag) => `#${tag}`);
  return { upperName, tagList };
}

If user.name comes back as null, calling .toUpperCase() crashes your application. If user.tags is undefined, calling .map() crashes your application, too. Both scenarios are entirely possible when you're consuming a real API, and TypeScript won't warn you because you told it to trust the type.

Wait! I hear you saying, "I can use optional chaining to stop my app from crashing". This is correct, like the example below:

// This looks better. But...
type User = {
  id: number;
  name: string;
  tags: string[];
};

function displayUser(user: User) {
  const upperName = user?.name?.toUpperCase?.();
  const tagList = (user?.tags || [])?.map((tag) => `#${tag}`); 
  return { upperName, tagList };
}

But there are issues with the above approach. Firstly, upperName will return undefined if user.name isn't a string. Secondly, the user?.tag || [] guards for undefined and null values alone. What if an object gets returned? {...}?.map(...)? Do you see the real issue now?

So user?.name?.toUpperCase?.() safely handles cases where user, name, or even toUpperCase itself might not exist. This is handy when dealing with uncertain data shapes, but it doesn't handle data mismatch.

Why This Problem Exists

The blame sits squarely with JavaScript's type system, or rather, its lack of one.

JavaScript has a handful of primitive types and a few rules that seem reasonable until you look at them closely. For example, typeof null returns "object", typeof [] also returns "object", and typeof NaN returns "number". These aren't edge cases. They're the language.

Here's a quick illustration of how easily JavaScript misleads you:

typeof null;        // "object" — not "null"
typeof [];          // "object" — not "array"
typeof NaN;         // "number" — NaN is technically a number
Array.isArray([]);  // true — this is the correct check
isNaN("hello");     // true — because "hello" coerces to NaN
Number.isNaN("hello"); // false — this is the correct check

TypeScript layers a static type system on top of this, catching many mistakes before your code runs. But static analysis only works on code you've already written. The moment data crosses the network boundary or comes from localStorage, a URL parameter, a third-party script, or any source outside your codebase, TypeScript's guarantees stop.

When you write something like this:

const data = await response.json() as User;

You're not validating anything. You're telling the TypeScript compiler, "I promise this is a User" . The compiler accepts that promise and stops checking. But if the API returns null for a field, sends a string where you expected a number, or omits a property entirely, JavaScript will proceed anyway and your code will break at the first operation that assumes otherwise.

This gap between "what TypeScript thinks the data is" and "what the data actually is at runtime" is where most production data bugs live. The fix is to stop trusting the type assertion and start validating the data yourself.

The Solution: Safe Access Utilities

The fix is to validate data at the boundary. The moment the expected data enters your application, check it before you pass it anywhere else.

These four functions do exactly that:

export function safeArray(prop: unknown): T[] {
  if (Array.isArray(prop)) {
    return prop as T[];
  } else {
    return [] as T[];
  }
}

export function safeString(prop: unknown, fallback = ""): string {
  if (typeof prop === "string") {
    return prop;
  } else {
    return fallback;
  }
}

export function safeNumber(prop: unknown, fallback = 0): number {
  if (typeof prop === "number" && !isNaN(prop)) {
    return prop;
  } else {
    return fallback;
  }
}

export function safeObject(
  prop: unknown,
  fallback = {} as T,
): T {
  if (prop !== null && typeof prop === "object" && !Array.isArray(prop)) {
    return prop as T;
  }
  return fallback;
}

Each function accepts unknown, which forces you to validate the value before using it. Each one returns a safe default if the input isn't what you expected. No crashes, no silent undefined, and no cryptic runtime errors.

You can drop these into any JavaScript or TypeScript project: React app, a Node.js API, a vanilla TypeScript module, or wherever you're handling external data.

How Each Utility Works

`safeArray`

export function safeArray(prop: unknown): T[] {
  if (Array.isArray(prop)) {
    return prop as T[];
  } else {
    return [] as T[];
  }
}

This checks whether prop is actually an array using Array.isArray. If it is, you get it back typed as T[]. If it's anything other than an array like null, undefined, a string, or whatever, you get back an empty array.

This matters because of the JavaScript quirk you saw above: typeof [] returns "object", which means a naive typeof check wouldn't catch this. Array.isArray handles it correctly.

`safeString`

export function safeString(prop: unknown, fallback = ""): string {
  if (typeof prop === "string") {
    return prop;
  } else {
    return fallback;
  }
}

This function uses typeof to confirm that the value is a string. The optional fallback parameter lets you specify a meaningful default. For example, "Unknown" instead of an empty string, when displaying a user's name.

`safeNumber`

export function safeNumber(prop: unknown, fallback = 0): number {
  if (typeof prop === "number" && !isNaN(prop)) {
    return prop;
  } else {
    return fallback;
  }
}

The key detail here is !isNaN(prop). Because typeof NaN === "number" is true in JavaScript, skipping this check means you could return NaN and cause downstream calculation failures. This function guards against that.

`safeObject`

export function safeObject(
  prop: unknown,
  fallback = {} as T,
): T {
  if (prop !== null && typeof prop === "object" && !Array.isArray(prop)) {
    return prop as T;
  }
  return fallback;
}

This one requires three conditions due to JavaScript's quirks. typeof null === "object" is true. typeof [] === "object" is also true. So this function explicitly excludes both. What you get back is guaranteed to be a plain object and nothing else.

How to Use Them in Practice

Normalising API Responses (Plain TypeScript)

The best place to use these utilities is in the function that processes your API response before the data reaches any other part of your application. This works the same way, whether in a React app, a Node.js service, or a plain TypeScript module.

// lib/users.ts
import { safeArray, safeString, safeNumber, safeObject } from "@/utils/safe";

type User = {
  id: number;
  name: string;
  email: string;
  tags: string[];
};

function normaliseUser(raw: unknown): User {
  const obj = safeObject>(raw);

  return {
    id: safeNumber(obj.id),
    name: safeString(obj.name, "Unknown User"),
    email: safeString(obj.email),
    tags: safeArray(obj.tags),
  };
}

async function fetchUser(id: string): Promise {
  const response = await fetch(`/api/users/${id}`);
  const data = await response.json();
  return normaliseUser(data);
}

By the time your code receives the User object, every field is guaranteed to be the type you declared. Nothing downstream has to wonder whether name might be null or tags might be undefined.

In a React Component (Defensive Rendering)

Sometimes you receive data directly in a component, from props, context, or a query result, and you don't control normalisation upstream. In that case, wrap the values at the point of use.

import { safeArray, safeString, safeNumber, safeObject } from "@/utils/safe";

type ProductProps = {
  product: unknown;
};

function ProductCard({ product }: ProductProps) {
  const p = safeObject>(product);
  const name = safeString(p.name, "Unnamed Product");
  const price = safeNumber(p.price);
  const tags = safeArray(p.tags);

  return (
    
      {name}
      ${price.toFixed(2)}
      
        {tags.map((tag) => (
          {tag}
        ))}
      
    
  );
}

Even if product arrives as null or a completely unexpected shape, this component will render a fallback state instead of crashing.

With React Query

If you're using React Query, you can normalise data inside the select option, which transforms the raw API response before it reaches your component.

import { useQuery } from "@tanstack/react-query";
import { safeArray, safeString, safeNumber, safeObject } from "@/utils/safe";

type Order = {
  id: number;
  status: string;
  total: number;
  items: string[];
};

function normaliseOrder(raw: unknown): Order {
  const obj = safeObject>(raw);
  return {
    id: safeNumber(obj.id),
    status: safeString(obj.status, "pending"),
    total: safeNumber(obj.total),
    items: safeArray(obj.items),
  };
}

function useOrder(orderId: string) {
  return useQuery({
    queryKey: ["order", orderId],
    queryFn: () =>
      fetch(`/api/orders/${orderId}`).then((res) => res.json()),
    select: normaliseOrder,
  });
}

The select callback runs after the query resolves and before the data is cached. Your useOrder hook always returns a properly shaped Order, regardless of what the API actually sent back.

With a React Context Provider

Context is a place where unsafe data can silently propagate through your entire component tree. Normalise it at the provider level so every consumer is protected.

import { createContext, useContext, useEffect, useState } from "react";
import { safeArray, safeString, safeObject } from "@/utils/safe";

type AppConfig = {
  theme: string;
  features: string[];
};

const defaultConfig: AppConfig = {
  theme: "light",
  features: [],
};

const ConfigContext = createContext(defaultConfig);

function ConfigProvider({ children }: { children: React.ReactNode }) {
  const [config, setConfig] = useState(defaultConfig);

  useEffect(() => {
    fetch("/api/config")
      .then((res) => res.json())
      .then((raw: unknown) => {
        const obj = safeObject>(raw);
        setConfig({
          theme: safeString(obj.theme, "light"),
          features: safeArray(obj.features),
        });
      });
  }, []);

  return (
    {children}
  );
}

export function useConfig() {
  return useContext(ConfigContext);
}

One normalisation step at the provider level protects every component that consumes the context.

In a Node.js API Route

These utilities are just as useful on the backend. If your Node.js API receives a request body, you can't trust that the client sent what you expected. Validate it at the point of entry.

// routes/orders.ts (Express)
import { safeArray, safeString, safeNumber, safeObject } from "../utils/safe";

type OrderPayload = {
  userId: number;
  notes: string;
  itemIds: number[];
};

function parseOrderPayload(raw: unknown): OrderPayload {
  const obj = safeObject>(raw);
  return {
    userId: safeNumber(obj.userId),
    notes: safeString(obj.notes),
    itemIds: safeArray(obj.itemIds),
  };
}

app.post("/orders", (req, res) => {
  const payload = parseOrderPayload(req.body);

  if (!payload.userId) {
    return res.status(400).json({ error: "userId is required" });
  }

  // proceed with validated payload
});

The same four utilities, the same pattern. Just a different runtime environment.

Best Practices

As with anything, there are some best practices that'll help you use these utilities well and correctly.

First, normalise at the boundary, not inside every function. The best place to call these utilities is in your data-fetching layer, API handlers, or integration points, just once, before the data spreads. If you're calling safeString in five different places for the same field, that's a sign the normalisation belongs upstream.

Second, use meaningful fallbacks. The default fallbacks (empty string, 0, empty array, and empty object) are safe, but sometimes misleading. For a user's display name, safeString(name, "Anonymous") is more informative than safeString(name). Think about what makes sense for each field in your domain.

Third, keep your type definitions honest. If a field can realistically be null or undefined from your data source, reflect that in your types and use these utilities to handle it. Typing a field as string when it might be null just papers over the problem. These utilities work best when your types reflect the reality of what you receive.

Finally, create a normalisation module. Put all your normaliser functions in one place, for example, src/lib/normalise.ts. This keeps the defensive logic centralised, easy to test, and out of your application logic.

Things to Avoid

Likewise, there are some practices you should avoid.

First, don't use these utilities as a substitute for a proper data contract. If your entire codebase is wrapping every value in safeString because your data sources are wildly inconsistent, the real fix is a contract, an OpenAPI spec, a shared schema, Zod validation, or at minimum, documented response shapes. These utilities handle edge cases and runtime surprises, not systemic chaos.

Second, don't skip the safeObject wrapper. It's tempting to cast straight to any and access properties directly. Avoid this. The as any cast defeats TypeScript entirely, and accessing properties on an unknown value will cause a compile error anyway. Use safeObject to unwrap the value first, then access its fields safely.

Next, don't chain these utilities without extracting intermediate values. Something like safeString(safeArray(raw)[0]) might seem compact, but it's harder to read and debug. Extract intermediate values into clearly named variables instead.

And finally, don't skip validation just because you control the data source. "I wrote the API, so I know what it returns" is a reasonable position right up until a schema migration, a nullable column addition, or an unconsidered edge case proves otherwise. Trust the utilities, not your memory.

Bonus: Combine Them into a `safeData` Helper

If you find yourself calling all four utilities together frequently, which you will once you start normalising API responses consistently, you can compose them into a single fluent helper.

// utils/safeData.ts
import { safeArray, safeString, safeNumber, safeObject } from "./safe";

type SafeDataAccessors = {
  string: (key: string, fallback?: string) => string;
  number: (key: string, fallback?: number) => number;
  array: (key: string) => T[];
  object: (key: string, fallback?: T) => T;
};

export function safeData(raw: unknown): SafeDataAccessors {
  const obj = safeObject>(raw);

  return {
    string: (key, fallback = "") => safeString(obj[key], fallback),
    number: (key, fallback = 0) => safeNumber(obj[key], fallback),
    array: (key: string) => safeArray(obj[key]),
    object: (key: string, fallback = {} as T) =>
      safeObject(obj[key], fallback),
  };
}

Your normalisation functions then read cleanly, whether you're in a React hook, an Express route, or anywhere else:

import { safeData } from "@/utils/safeData";

function normaliseUser(raw: unknown) {
  const d = safeData(raw);
  return {
    id: d.number("id"),
    name: d.string("name", "Unknown User"),
    email: d.string("email"),
    tags: d.array("tags"),
  };
}

This is a thin abstraction: no magic, just less repetition. Use it if your normalisation functions are getting verbose. Skip it if the direct utility calls are clear enough for your team.

Conclusion

JavaScript's loose type system and TypeScript's compile-time-only guarantees leave a gap at every data boundary. External data — from APIs, request bodies, local storage, third-party scripts — arrives at runtime with no guarantee it matches the shape you declared. These four utilities close that gap.

safeArray, safeString, safeNumber, and safeObject each accept unknown, validate the actual type, and return a safe fallback if the value isn't what you expected. They work in React components, Node.js routes, custom hooks, context providers, and any other JavaScript or TypeScript context where data enters your application.

The pattern is simple: validate at the boundary, trust inside. Normalise your data once, at the point it enters your codebase, and everything downstream can focus on its actual job instead of defending against bad inputs.

How to Build a Reliable SSE Client in TypeScript

timothy ogbemudia — Thu, 25 Jun 2026 22:49:09 +0000

When you build a feature that streams data, like an AI chat response or a live notification feed, the network is rarely as cooperative as fetch makes it look.

Connections drop, proxies buffer responses, and mobile networks switch from WiFi to cellular mid-stream. If your streaming code doesn't plan for this, the user sees a response that just stops, with no error and no recovery.

In this article, you'll use an open source TypeScript library called Ore as a practical example of how to build a streaming client that handles real-world network conditions: automatic retries, the official Server-Sent Events (SSE) parsing spec, and clean integration with React and React Server Components.

By the end, you'll understand how async generators, the Fetch API, and the SSE spec fit together to build something far more reliable than a basic fetch and response.body.getReader() loop.

Prerequisites
What You Will Learn
What Is Server-Sent Events?
Why Build a Custom Streaming Client?
How to Stream Raw Chunks with an Async Generator
How to Parse Server-Sent Events by Hand
How to Implement Reconnection with Last-Event-ID
How to Handle Retries with Backoff
How to Use This with React
How to Use This with React Server Components
Conclusion

Prerequisites

To follow along, you should have:

A working understanding of TypeScript
Familiarity with fetch, ReadableStream, and async/await
Basic knowledge of React (for the React-specific sections)

What You Will Learn

How to stream raw text or bytes from a fetch response using async generators
How to parse the Server-Sent Events spec by hand, field by field
How to implement automatic reconnection with Last-Event-ID so you don't lose events
How to handle retries with exponential backoff
How to integrate a streaming client with React state and React Server Components

What Is Server-Sent Events?

Server-Sent Events (SSE) is a web standard for one-way streaming from server to client over a single HTTP connection. Unlike WebSockets, it's plain HTTP, which means it works through existing infrastructure like load balancers and proxies without special configuration.

An SSE response looks like this on the wire:

event: update
id: 42
data: {"status": "processing"}

event: update
id: 43
data: {"status": "complete"}

Each event is separated by a blank line. The data field carries the payload, event names the event type, and id lets the client track its position in the stream for reconnection.

The browser has a built-in EventSource API for this, but it has real limitations: no custom headers, no POST requests, and inconsistent reconnection behavior across browsers. For anything beyond the simplest case, you often need to parse the stream yourself.

Why Build a Custom Streaming Client?

Many streaming use cases, like AI chat responses, don't use the SSE spec at all. They're just raw chunks of text arriving over time. Other cases, like live notifications, genuinely benefit from the structure SSE provides: named events, IDs for resumption, and a server-controlled retry interval.

Ore handles both with two separate functions:

stream() for raw text or byte streaming, with no assumptions about format
streamSSE() for spec-compliant SSE parsing

Both are async generators, so consuming either looks the same from the call site:

for await (const chunk of stream("https://api.example.com/chat")) {
  console.log(chunk);
}

How to Stream Raw Chunks with an Async Generator

The simplest case is streaming raw text. This is useful for AI responses or log tails where there's no event structure, just a sequence of bytes arriving over time.

Here's the core of stream():

export async function* stream(
  url: string,
  options?: StreamOptions
): AsyncGenerator {
  const { headers, retries = 3, signal, decode = true } = options || {};

  let retryCount = 0;

  while (retryCount <= retries) {
    try {
      const response = await fetch(url, { method: "GET", headers, signal });

      if (!response.body) {
        throw new Error("Response body is null");
      }

      const reader = response.body.getReader();
      const decoder = new TextDecoder();

      try {
        while (true) {
          const { done, value } = await reader.read();
          if (done) break;
          yield decode ? decoder.decode(value, { stream: true }) : value;
        }
      } finally {
        reader.releaseLock();
      }

      return;
    } catch (error: any) {
      if (signal?.aborted) throw error;
      retryCount++;
      if (retryCount > retries) {
        throw new Error(`Max retries exceeded. Last error: ${error.message}`);
      }
      await new Promise((r) => setTimeout(r, 1000 * retryCount));
    }
  }
}

A few design decisions are worth calling out.

The function is an async generator (async function*), so the caller can use for await...of instead of managing a reader and a loop manually. That's the difference between exposing a raw ReadableStream and exposing something pleasant to consume.

The finally block always releases the reader lock, even if the loop exits early through a break or an exception. Forgetting this is a common source of stream leaks.

The retry loop only catches errors from the fetch call and the read loop. If the AbortSignal was the cause of the failure, it rethrows immediately rather than retrying, since retrying a deliberate cancellation makes no sense.

How to Parse Server-Sent Events by Hand

The SSE spec is a simple text format, but parsing it correctly means handling several edge cases: events split across multiple data lines, comment lines starting with a colon, fields with no value, and incomplete lines at the end of a chunk.

Here's the core state machine inside streamSSE():

let buffer = "";
let currentEvent: Partial = { data: "", event: null, id: null };
let hasData = false;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split(/\r\n|\r|\n/);
  buffer = lines.pop() || ""; // keep the last incomplete line for the next chunk

  for (const line of lines) {
    if (line === "") {
      if (hasData) {
        const event: SSEEvent = {
          id: currentEvent.id ?? lastEventId,
          event: currentEvent.event ?? null,
          data: currentEvent.data!.endsWith("\n")
            ? currentEvent.data!.slice(0, -1)
            : currentEvent.data!,
          retry: currentEvent.retry,
        };
        if (event.id) lastEventId = event.id;
        yield event;
        currentEvent = { data: "", event: null, id: null };
        hasData = false;
      }
      continue;
    }

    if (line.startsWith(":")) continue; // comment line, ignore

    const colonIndex = line.indexOf(":");
    const field = colonIndex === -1 ? line : line.slice(0, colonIndex);
    let valueStr = colonIndex === -1 ? "" : line.slice(colonIndex + 1);
    if (valueStr.startsWith(" ")) valueStr = valueStr.slice(1);

    switch (field) {
      case "data":
        currentEvent.data += valueStr + "\n";
        hasData = true;
        break;
      case "event":
        currentEvent.event = valueStr;
        break;
      case "id":
        if (valueStr.indexOf("\0") === -1) currentEvent.id = valueStr;
        break;
      case "retry":
        const retry = parseInt(valueStr, 10);
        if (!isNaN(retry)) retryInterval = retry;
        break;
    }
  }
}

A network chunk doesn't respect line boundaries. A single read() call might end mid-line, so the last, possibly incomplete line is held back in buffer and prepended to the next chunk rather than processed early. This is the part of SSE parsing that's easy to get wrong if you reach for a naïve response.text() and a string split.

The blank line is what ends an event. SSE events don't have a fixed-length header. The spec says a blank line marks the boundary, so the parser only yields an event once it has seen one.

The id field is rejected outright if it contains a null byte, per the spec. That's a small detail that almost no hand-rolled implementation gets right on the first try.

How to Implement Reconnection with Last-Event-ID

This is the part of SSE that gives it a real advantage over a plain fetch stream: built-in support for resuming after a disconnect without losing your place.

let lastEventId: string | null = null;

while (retryCount <= retries) {
  const headers = { ...customHeaders };
  if (lastEventId) {
    (headers as any)["Last-Event-ID"] = lastEventId;
  }

  const response = await fetch(url, { method: "GET", headers, signal });
  // ... read and parse events, updating lastEventId as they arrive
}

Every time an event with an id field arrives, lastEventId is updated. If the connection drops and the client reconnects, it sends Last-Event-ID in the request headers. A well-behaved server can use that header to resume the stream from the right point instead of replaying everything or skipping ahead.

This only works if the server actually honors the header, so it's a contract between client and server, not something the client can guarantee alone. But having the client track and send it correctly is the necessary half of that contract.

How to Handle Retries with Backoff

Both stream() and streamSSE() retry on failure, but they do it slightly differently based on what failed.

stream() uses a simple linear backoff tied to the retry count:

await new Promise((resolve) => setTimeout(resolve, 1000 * retryCount));

streamSSE() respects the server-specified retry field from the SSE spec when one is provided, falling back to a default otherwise:

let retryInterval = 1000;
// ... updated from the "retry" field if the server sends one
await new Promise((r) => setTimeout(r, retryInterval));

Letting the server influence the retry interval matters in practice. A server under load can tell clients to back off longer, which is exactly the kind of cooperative behavior the SSE spec was designed to support.

In both functions, an aborted AbortSignal always short-circuits the retry loop. Treating a deliberate cancellation as a retryable failure is a common bug, and the fix is just checking signal?.aborted before deciding to retry.

How to Use This with React

Because both functions are async generators, integrating with React state is a matter of looping and calling setState per chunk:

function ChatComponent() {
  const [messages, setMessages] = useState("");

  useEffect(() => {
    const controller = new AbortController();

    (async () => {
      try {
        for await (const chunk of stream("/api/chat", { signal: controller.signal })) {
          setMessages((prev) => prev + chunk);
        }
      } catch (err: any) {
        if (err.name !== "AbortError") console.error(err);
      }
    })();

    return () => controller.abort();
  }, []);

  return {messages};
}

The cleanup function calling controller.abort() is doing real work here. Without it, navigating away from the component while a stream is still active leaves the fetch running in the background, updating state on an unmounted component.

How to Use This with React Server Components

Because the generator yields values one at a time, you can also drive a recursive Suspense boundary directly from the async iterator, streaming HTML to the client as each chunk arrives:

async function StreamViewer({ iterator }: { iterator: AsyncIterator }) {
  const { value, done } = await iterator.next();
  if (done) return null;

  return (
    
      {value}
      
        
      
    
  );
}

export default function Page() {
  const dataStream = stream("https://api.example.com/stream");
  const iterator = dataStream[Symbol.asyncIterator]();

  return (
    
      
    
  );
}

Each recursive call awaits the next chunk and renders a nested Suspense boundary for the rest. React streams each piece of HTML to the client as it resolves, rather than waiting for the entire response.

Conclusion

A reliable streaming client needs to handle more than the success path. Connections drop, chunks arrive split across line boundaries, and cancellation needs to be distinguished from failure.

Ore's approach to this is built from a small set of ideas:

Expose streams as async generators so consumers can use for await...of
Parse SSE by hand, field by field, respecting the spec's blank-line event boundaries and buffering incomplete lines across chunks
Track Last-Event-ID so reconnection can resume rather than restart
Treat retries and cancellation as separate concerns
Stay framework-agnostic at the core, with thin integration points for React and React Server Components

That combination is what separates a streaming client that works in a demo from one that holds up against real network conditions. You can explore the full source code at github.com/glamboyosa/ore.

How to Build an Animated Badge Component with shadcn/ui

Vaibhav Gupta — Wed, 24 Jun 2026 17:00:48 +0000

Badges are everywhere in modern web apps. You see them on notification counters, status labels, and feature tags.

Most of them are static, though. They sit there doing nothing, blending into the page. But a well-animated badge can tell the user something happened without them having to read a single word.

In this tutorial, you'll build an animated “success” badge using shadcn/ui, Tailwind CSS, and Framer Motion. The badge will have a glowing top light, an animated check icon that bounces into view, and letters that drop in one at a time with a stagger effect.

The component comes from the Shadcn Space badge collection and uses the Base UI primitive version of Badge. You'll install it with a single CLI command, then walk through every piece of code.

By the end, you'll build an animated "Success" badge by:

Installing the badge-07 component from Shadcn Space using the Shadcn CLI
Using motion.create() to wrap the shadcn/ui Badge into an animatable component
Adding layered radial-gradient glow effects as absolutely positioned spans
Animating the check icon with a scale and rotate entrance
Animating each letter of the label individually using staggered variants

Prerequisites
What You'll Build
How to Install the Component
Component Structure
Step 1: Set Up the Imports
Step 2: Define Letter Animation Variants
Step 3: Wrap the Badge with Motion
Step 4: Build the Glow Layers
Step 5: Animate the Icon
Step 6: Animate Each Letter
How to Use It in Your App
How to Customize the Component
Live Preview
Key Concepts Recap
Conclusion
Resources

Prerequisites

You'll need:

A Next.js project with shadcn/ui initialized
Tailwind CSS set up
motion installed: npm install motion
lucide-react installed: npm install lucide-react
Basic TypeScript and React knowledge

What You'll Build

In this tutorial, we'll build a self-contained animated badge with three moving parts:

├── MotionBadge (outline, rounded-full, teal border)
│   ├── Glow layers  → 3 radial gradient spans above the top border
│   ├── CheckCircle  → scale + rotate entrance, easeOutBack
│   └── Letter spans → staggered drop-in, easeOutCubic

After installation, the component file lands here:

components/
└── shadcn-space/
    └── badge/
        └── badge-07.tsx

How to Install the Component

Shadcn UI provides a registry of production-ready components. You pull them into your project with the Shadcn CLI, just like you'd add any standard shadcn/ui component.

Before running any command, check the Getting Started guide or the CLI page for setup details.

You can also follow along with this video walkthrough:

Run the command for your package manager:

pnpm

pnpm dlx shadcn@latest add @shadcn-space/badge-07

npm

npx shadcn@latest add @shadcn-space/badge-07

Yarn

yarn dlx shadcn@latest add @shadcn-space/badge-07

Bun

bunx --bun shadcn@latest add @shadcn-space/badge-07

Note: badge-07 uses the Base UI primitive version of Badge. Both Radix and Base UI versions are available in the registry. This tutorial covers the Base UI version.

Component Structure

Here's the complete component. Read through it once, then each step below breaks down a specific part.

'use client'
import { motion, type Variants } from "motion/react";
import { CheckCircle } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import { cn } from "@/lib/utils";

const LETTER_VARIANTS: Variants = {
  hidden: { y: -14, opacity: 0 },
  visible: (i: number) => ({
    y: 0,
    opacity: 1,
    transition: {
      delay: i * 0.038,
      duration: 0.35,
      ease: [0.215, 0.61, 0.355, 1],
    },
  }),
};

const MotionBadge = motion.create(Badge);

const SuccessBadgeDemo = () => {
  const label = "Success";

  return (
    
      {/* Top glow */}
      
      
      

      {/* Icon */}
      
        
      

      {/* Animated label */}
      
        {label.split("").map((char, i) => (
          
            {char}
          
        ))}
      
    
  );
};

export default SuccessBadgeDemo;

Now let's break it down piece by piece.

Step 1: Set Up the Imports

'use client'
import { motion, type Variants } from "motion/react";
import { CheckCircle } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import { cn } from "@/lib/utils";

'use client' marks this as a Client Component in Next.js App Router. Motion animations run in the browser, not on the server, so this directive is required.

motion/react is the import path for Motion v11 and above. If your project uses an older version, the import is framer-motion. The Variants type is a TypeScript helper for typing named animation state objects.

cn() is the class name utility that ships with every shadcn/ui project. It merges Tailwind classes and handles conditional logic cleanly.

Step 2: Define Letter Animation Variants

const LETTER_VARIANTS: Variants = {
  hidden: { y: -14, opacity: 0 },
  visible: (i: number) => ({
    y: 0,
    opacity: 1,
    transition: {
      delay: i * 0.038,
      duration: 0.35,
      ease: [0.215, 0.61, 0.355, 1],
    },
  }),
};

Each letter starts 14px above its final position and is fully transparent. When the component mounts, it moves to y: 0 at full opacity.

The delay: i * 0.038 formula is the stagger. Letter 0 has no delay, letter 1 waits 38ms, letter 2 waits 76ms, and so on. This makes the letters appear to cascade in from left to right.

The ease value [0.215, 0.61, 0.355, 1] is easeOutCubic. It starts fast and decelerates at the end, giving each letter a natural landing rather than a hard stop.

The visible function accepts a custom value. When you pass custom={i} on the motion.span, Motion calls this function with that index. Each letter calculates its own delay independently.

Accessibility tip: To respect users with reduced motion preferences, import useReducedMotion from motion/react and skip the stagger when it returns true.

Step 3: Wrap the Badge with Motion

const MotionBadge = motion.create(Badge);

The Badge Component from shadcn/ui is a standard React component. You can't apply Motion props like animate or initial to it directly.

motion.create() wraps any React component and returns a new version that accepts all Motion animation props. The result, MotionBadge, behaves exactly like Badge But it's now fully animatable.

Use this pattern any time you want to animate a custom or third-party library component with Motion.

Step 4: Build the Glow Layers

Three spans stack on top of each other above the badge border. Each is narrower and more opaque than the one behind it:

Layer	Position	Width	Blur	Final Opacity
Outer	`-top-2`	80%	`blur`	0.55
Middle	`-top-1`	56%	`blur-sm`	0.75
Inner line	`top-0`	44%	none	0.90

The innermost layer is only 1px tall (h-px) with no blur. This gives the glow a crisp, bright edge right at the badge border. The two outer layers create the soft falloff around it.

All three carry aria-hidden because they're purely decorative. Screen readers skip them. The overflow-visible class on MotionBadge is what allows these spans to render outside the component's boundary without clipping.

Step 5: Animate the Icon

The icon starts at 35% scale, invisible, and rotated 25 degrees counter-clockwise. It animates to full size and zero rotation on mount.

The ease value [0.175, 0.885, 0.32, 1.275] is easeOutBack. Unlike easeOutCubic, this curve overshoots its target slightly before snapping back. The icon appears to spring into place. It is a subtle effect, but it makes the icon feel physical.

shrink-0 on the wrapper prevents the icon from compressing inside the flex container.

Step 6: Animate Each Letter


  {label.split("").map((char, i) => (
    
      {char}
    
  ))}

label.split("") turns "Success" into ["S", "u", "c", "c", "e", "s", "s"]. Each character gets its own motion.span.

variants={LETTER_VARIANTS} connects each span to the animation states from Step 2. custom={i} passes the character's index into the visible resolver so each letter knows its own delay.

Two Tailwind classes matter here:

overflow-hidden on the wrapper clips, each letter as it slides in from above. Without it, letters would be visible outside the badge before they land.
inline-block on each motion.span is required for translateY to work. CSS transforms do not apply to inline elements by default.

How to Use It in Your App

Import and render SuccessBadgeDemo anywhere in your project:

// app/page.tsx
import SuccessBadgeDemo from "@/components/shadcn-space/badge/badge-07";

export default function Page() {
  return (
    
      
    
  );
}

The component is self-contained. It carries its own animation state, theme tokens, and glow layers. No props are required.

How to Customize the Component

You can change the label by replacing "Success" it with any string. The letter animation applies automatically since it splits whatever string you pass.

To build a complete blue "Verified" variant, you just need to change three things: the border color class, the glow gradient color values, and the icon. Here's the full updated component:

'use client'
import { motion, type Variants } from "motion/react";
import { ShieldCheck } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import { cn } from "@/lib/utils";

const LETTER_VARIANTS: Variants = {
  hidden: { y: -14, opacity: 0 },
  visible: (i: number) => ({
    y: 0,
    opacity: 1,
    transition: {
      delay: i * 0.038,
      duration: 0.35,
      ease: [0.215, 0.61, 0.355, 1],
    },
  }),
};

const MotionBadge = motion.create(Badge);

const VerifiedBadgeDemo = () => {
  const label = "Verified";

  return (
    
      
      
      

      
        
      

      
        {label.split("").map((char, i) => (
          
            {char}
          
        ))}
      
    
  );
};

export default VerifiedBadgeDemo;

The only changes from the original: border-blue-400/25 on the badge, rgba(96, 165, 250, ...) in the glow gradients (blue-400 in Tailwind), ShieldCheck for the icon, and text-blue-400 on the icon class.

To adjust stagger speed, just change the delay multiplier in LETTER_VARIANTS:

delay: i * 0.06, // slower stagger
delay: i * 0.02, // faster stagger

You can also explore the Shadcn Blocks collection to see how animated badges fit into full dashboard and card layouts.

Live Preview

Key Concepts Recap

Concept	What It Does
`motion.create(Component)`	Wraps any React component to accept Motion animation props
`Variants`	Named animation states (`hidden`, `visible`) defined outside JSX for reuse
`custom={i}` + variant function	Passes a per-element value into the variant resolver for dynamic transitions
`delay: i * 0.038`	Stagger formula: each element's delay grows by its index
`easeOutCubic` `[0.215, 0.61, 0.355, 1]`	Fast start, smooth deceleration. Letter drop-in.
`easeOutBack` `[0.175, 0.885, 0.32, 1.275]`	Overshoots slightly, snaps back. Icon pop.
Three stacked radial gradients	Wide + soft outer glow, narrow + sharp inner line
`overflow-visible` on the badge	Allows glow spans to extend outside the component's own bounds

Conclusion

In this tutorial, you built a complete animated badge from scratch with a layered glow, bouncing icon, and staggered letter animation. Every part of it uses your existing Shadcn theme tokens, so it drops into any project without extra configuration.

You can browse more Shadcn Components on Shadcn Space to apply the same animation patterns to other UI elements. If you work with external services and tooling in your stack, the Shadcn MCP integration is worth looking at as a next step.

Resources

Shadcn Space Badge Components: with all badge variants, including Pending, Failed, and more
Shadcn Space Getting Started Guide: how to use the Shadcn CLI with third-party registries
Motion Docs: official documentation for motion/react
Lucide React: icon library used in this tutorial
Shadcn/ui Documentation
YouTube: Shadcn Space CLI Walkthrough

How to Build a Scalable Design System in a Monorepo

Vineeth Pawar — Mon, 22 Jun 2026 18:12:27 +0000

When you hear "Scalable Design System with a Monorepo Ecosystem" it might sound like a bunch of jargon glued together. Let's simplify:

Design system: the building blocks of your product (buttons, inputs, styles, tokens, patterns).
Monorepo: one big repo with multiple packages living together, sharing tooling and workflows.

Now here's the magic: when you combine them, you get modularity, consistency, and a faster development cycle. Basically the dream setup for teams working across web, mobile, and beyond.

In this article, you'll learn how to build a modular, scalable design system using React and Turborepo – the same approach used by Microsoft, IBM, and Shopify.

Prerequisites
Who's Already Doing This?
Why it Works
Think of it Like a Ladder
The Same Design System, Everywhere
Should You Go Monorepo?
When a Monorepo Is Not the Right Fit
Let's Build Our Design System
Wrapping Up

Prerequisites

Before you follow along, you'll want to have a few things in place:

Working knowledge of React and TypeScript: You should be comfortable creating components and reading basic type annotations.
Familiarity with the command line: You'll run npx, npm, and similar commands throughout.
Node.js installed (v18 or later): Verify with node -v. If you don't have it, install it from nodejs.org.
A package manager: This guide uses npm, but pnpm or yarn will work with minor command tweaks.
A code editor of your choice (VS Code is a popular fit for TypeScript work).

You don't need any prior experience with monorepos or Turborepo. We'll set everything up from scratch.

Who's Already Doing This?

Turns out, some of the biggest design systems you've heard of run inside monorepos:

Microsoft Fluent UI: lives in a multi-package monorepo that ships React components, Web Components, and even design tokens.
IBM Carbon: multiple packages like @carbon/ibm-products come straight out of their Carbon monorepo.
Shopify Polaris: openly describes itself as a monorepo, packaging React components, docs, and even a VS Code extension.
Atlassian Atlaskit: their public @atlaskit/* packages are published from a large internal monorepo.
MUI (Material UI): maintained as a mono-repository to coordinate React components, tooling, and docs.
Elastic EUI: developed and released from a single repo, with discussions about monorepo publishing flows.

Why it Works

When you put all the pieces of your design system in one repository, you get a few specific advantages that are hard to replicate in a split-repo setup. Each of these reinforces the others, which is why teams that adopt this pattern rarely go back.

Here's what makes it work:

Consistency: tokens, styles, and primitives are defined once and flow everywhere.
Faster iteration: fix a bug in Button and the updates cascade to mobile, desktop, and docs instantly.
Shared tooling: linting, tests, CI pipelines, and release workflows are configured once, and then applied to all packages.
Versioning control: with tools like Changesets or Lerna, you can release packages independently but keep them aligned.
Cross-platform flexibility: the same building blocks can power React web apps, React Native, Electron apps, SDKs, and documentation sites.

Think of it Like a Ladder 🪜

The cleanest way to picture a monorepo design system is as a series of stacked layers. Each layer builds on the one beneath it, and each layer has a clear job.

New contributors find their way around faster because the relationships between packages are predictable: tokens flow up into primitives, primitives compose into layouts, and layouts assemble into screens.

The diagram below shows this stack visually:

At the base, you've got primitives (tokens, styles).

Above that: plugins (utility helpers).

Then come layouts, built from plugins + primitives.

Then screens, built from layouts.

Finally, navigators tie screens together.

At the very top: your app imports just one package, and boom! The UI is environment-agnostic.

The Same Design System, Everywhere

The real payoff of this ladder is that you climb it once, then reuse the whole thing across every platform you ship to.

A button defined in your primitives package can render in a web app, a React Native mobile app, an Electron desktop app, or a documentation site without you rewriting it for each environment.

The diagram below shows the same design system flowing into three different app types, with each environment importing the same package and getting consistent styling, behaviour, and accessibility out of the box:

Whether it's web, desktop, or mobile, the design system climbs that same ladder.

Should You Go Monorepo?

Not every team needs one. But if you're building a design system that's meant to serve multiple apps, stay consistent across platforms, and support lots of contributors, then a monorepo becomes less of a buzzword and more of a sanity-saver.

When a Monorepo Is Not the Right Fit

A quick clarification first, because monorepos sometimes get tangled up with another debate. The "monorepo vs polyrepo" question is not the same as the "monolith vs microservices" question. You can absolutely run microservices out of a monorepo (Google and Facebook do this at massive scale).

The two choices live on different axes: monorepo vs polyrepo is about where the code lives, while monolith vs microservices is about how the runtime is shaped.

With that out of the way, here are a few signs a monorepo may not be the best fit for your situation:

You're a small team shipping a single product. The tooling overhead of a monorepo (workspace config, build pipelines, package boundaries) may slow you down more than it helps. A single React app with no shared libraries probably doesn't need this layer.
Your packages have wildly different release cadences and stakeholders. If two parts of your codebase are owned by teams that need very different deploy pipelines, governance, or security postures, separate repos can reduce friction.
You can't invest in monorepo tooling. Tools like Turborepo, Nx, and Changesets do a lot of heavy lifting, but they have a learning curve. If your team can't dedicate time to set them up and maintain them, you may struggle.
You're using languages or runtimes that don't share well. Monorepos shine when most packages live in the same toolchain. Mixing Node, Go, Rust, and Python in one repo is possible, but the build-tool story gets harder.

For most teams building a serious design system, none of these are dealbreakers. But it's worth checking your situation before committing.

Let's Build Our Design System

Create Your Turborepo Project

Start by creating a new Turborepo project. This gives you the perfect foundation for a scalable monorepo.

# Create a new Turborepo project
npx create-turbo@latest my-design-system

# Navigate to the project
cd my-design-system

# Install dependencies
npm install

Turborepo creates a workspace with apps/ and packages/ folders, shared tooling configuration, and optimized build pipelines.

Design Your Package Structure

Next, create a logical hierarchy for your design system packages. Think of it like a ladder, as I mentioned above: each level builds on the one below.

my-design-system/
├── packages/
│   ├── tokens/          # Design tokens (colors, spacing, typography)
│   ├── primitives/      # Base components (Button, Input, Card)
│   ├── layouts/         # Layout components (Grid, Stack, Container)
├── apps/
│   ├── web/            # Example web app
│   └── docs/           # Documentation site
└── turbo.json          # Turborepo configuration

Detailed file structure

my-design-system/
├── packages/
│   ├── tokens/
│   │   ├── src/
│   │   │   ├── colors.ts
│   │   │   ├── spacing.ts
│   │   │   ├── typography.ts
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── primitives/
│   │   ├── src/
│   │   │   ├── Button/
│   │   │   │   └── Button.tsx
│   │   │   ├── Input/
│   │   │   │   └── Input.tsx
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── layouts/
│   │   ├── src/
│   │   │   ├── Grid/
│   │   │   ├── Stack/
│   │   │   └── index.ts
│   │   └── package.json
├── apps/
│   ├── web/
│   │   ├── src/
│   │   │   ├── App.tsx
│   │   │   └── main.tsx
│   │   ├── index.html
│   │   └── package.json
│   └── docs/
│       ├── src/
│       └── package.json
├── turbo.json
├── package.json
└── README.md

Build Your Design Tokens Package

Start with the foundation: design tokens. Tokens are the smallest, most reusable units of a design system: a color value, a spacing step, a font size, a border radius. Instead of hard-coding padding: 16px or color: #3b82f6 everywhere, you reference a token like spacing.md or colors.primary[500].

The benefits are huge:

One place to change a value: update a token once and every component that uses it updates automatically.
Theming becomes trivial: want a dark mode? Just swap which tokens resolve to which values.
Cross-platform consistency: the same token names work in web CSS, native styles, even Figma.

Tokens are the DNA of your design system. Let's build them.

# Create the tokens package
mkdir -p packages/tokens/src
cd packages/tokens

Update these in your packages/tokens/package.json. This file declares the package name, version, build scripts, and dev dependencies needed to compile the token source files into a publishable package:

{
  "name": "@yourds/tokens",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
  },
  "devDependencies": {
    "tsup": "^8.0.0",
    "typescript": "^5.0.0"
  }
}

Update these in your packages/tokens/src/colors.ts. This file defines the color tokens: a named palette of color values organised by intent (primary, gray) and shade (50 is lightest, 900 is darkest). Components reference these by name rather than hardcoding hex codes:

export const colors = {
  primary: {
    50: '#f0f9ff',
    100: '#e0f2fe',
    500: '#3b82f6',
    600: '#2563eb',
    900: '#1e3a8a'
  },
  gray: {
    50: '#f9fafb',
    100: '#f3f4f6',
    500: '#6b7280',
    900: '#111827'
  }
} as const;

Update these in your packages/tokens/src/spacing.ts. This file defines the spacing scale: a set of standard size steps that components use for padding, margin, and gap values. Using a fixed scale (xs, sm, md, lg, and so on) keeps spacing consistent across the UI:

export const spacing = {
  xs: '0.25rem',    // 4px
  sm: '0.5rem',     // 8px
  md: '1rem',       // 16px
  lg: '1.5rem',     // 24px
  xl: '2rem',       // 32px
  '2xl': '3rem'     // 48px
} as const;

Update these in your packages/tokens/src/typography.ts. This file defines the typography tokens: font sizes and font weights that components use for text. Like spacing, these are named steps rather than arbitrary pixel values:

export const typography = {
  fontSizes: {
    xs: '0.75rem',
    sm: '0.875rem',
    base: '1rem',
    lg: '1.125rem',
    xl: '1.25rem',
    '2xl': '1.5rem'
  },
  fontWeights: {
    normal: 400,
    medium: 500,
    semibold: 600,
    bold: 700
  }
} as const;

Update these in your packages/tokens/src/index.ts. This file is the public entry point of the package: it re-exports everything from the three token files so consumers can do import { colors, spacing, typography } from "@yourds/tokens" in a single line:

export * from './colors';
export * from './spacing';
export * from './typography';

Create Primitive Components

Build your base components that consume the design tokens:

# Create the primitives package
mkdir -p packages/primitives/src
cd packages/primitives

# Install dependencies
npm install react react-dom

Update these in your packages/primitives/package.json:

{
  "name": "@yourds/primitives",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts --external react",
    "dev": "tsup src/index.ts --format cjs,esm --dts --external react --watch"
  },
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.0",
    "tsup": "^8.0.0",
    "typescript": "^5.0.0"
  }
}

Update these in your packages/primitives/src/Button/Button.tsx:

import React from 'react';
import { colors, spacing } from '@yourds/tokens';

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  onClick?: () => void;
  disabled?: boolean;
}

export const Button: React.FC = ({
  variant = 'primary',
  size = 'md',
  children,
  disabled = false,
  ...props
}) => {
  const baseStyles = {
    border: 'none',
    borderRadius: '0.5rem',
    cursor: disabled ? 'not-allowed' : 'pointer',
    fontWeight: 500,
    transition: 'all 0.2s ease',
    opacity: disabled ? 0.6 : 1
  };

  const variants = {
    primary: {
      backgroundColor: colors.primary[500],
      color: 'white',
      ':hover': { backgroundColor: colors.primary[600] }
    },
    secondary: {
      backgroundColor: colors.gray[100],
      color: colors.gray[900],
      ':hover': { backgroundColor: colors.gray[200] }
    },
    outline: {
      backgroundColor: 'transparent',
      color: colors.primary[500],
      border: `1px solid ${colors.primary[500]}`,
      ':hover': { backgroundColor: colors.primary[50] }
    }
  };

  const sizes = {
    sm: { padding: `\({spacing.xs} \){spacing.sm}`, fontSize: '0.875rem' },
    md: { padding: `\({spacing.sm} \){spacing.md}`, fontSize: '1rem' },
    lg: { padding: `\({spacing.md} \){spacing.lg}`, fontSize: '1.125rem' }
  };

  const buttonStyle = {
    ...baseStyles,
    ...variants[variant],
    ...sizes[size]
  };

  return (
    
  );
};

Update these in your packages/primitives/src/index.ts:

export { Button } from './Button/Button';
export type { ButtonProps } from './Button/Button';

Configure the Turborepo Pipeline

Now, set up the build pipeline in turbo.json to ensure packages build in the correct order.

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {},
    "type-check": {
      "dependsOn": ["^build"]
    }
  }
}

Build the @yourds Packages

With the tokens and primitives packages defined, the next step is to compile them so they can be consumed by your apps.

Running npm install at the root resolves all workspace dependencies, including the internal links between @yourds/tokens and @yourds/primitives. Then npm run build walks through every package and runs each one's build script, which Turborepo orders correctly so tokens compiles before primitives (since primitives depend on tokens). The final npm install step then registers the built packages so your apps/web app can import them by name:

# Go to the root of the monorepo
npm install

# Compile every package in the right order
npm run build

# Register the built packages for the apps to use
npm install @yourds/tokens @yourds/primitives

If everything ran successfully, you should see a dist/ folder inside both packages/tokens and packages/primitives, containing compiled JavaScript and TypeScript declaration files.

Use Your Design System in an App

Now you can consume your design system in any React application.

The example below replaces the default content in your apps/web/src/App.tsx file with a small home page that demonstrates two things at once: importing primitives (the Button component) from @yourds/primitives, and importing tokens (colors, spacing) directly from @yourds/tokens to style standard HTML elements like the wrapper

and the

The result is a fully working page that uses your design system end-to-end, with zero hardcoded colors or spacing values:

import { Button } from "@yourds/primitives";
import { colors, spacing } from "@yourds/tokens";

export default function Home() {
  return (
    
      My App with Design System
      
      
    
  );
}

Once you save the file, run the app in development mode:

npx turbo dev --filter=web

You should see your home page render with the primary[500] blue heading, padded by spacing.lg, and two buttons styled by your shared design system. Any change you make to a token (say, swapping the primary color) will flow into this page automatically the next time you rebuild.

Wrapping up

A monorepo won't magically make your design system perfect. But it does give you:

A shared space where everything connects
The agility to publish parts independently
The clarity to scale design across teams and platforms

No wonder the biggest design systems in the world are already doing it.

How to Build an AI-Powered, Local-First Chrome Extension That Turns Your Browsing History into an Intent Map

Shola Jegede — Fri, 19 Jun 2026 17:14:43 +0000

Your browser remembers every page you've ever opened, but it has no idea why you opened any of them.

You might spend three days comparing laptops across a dozen tabs, get distracted, come back a week later, and your history just shows a flat list of timestamps and titles, with no sense that those visits were one thing, a decision you started and never finished.

In this tutorial, you'll build openloops, an open-source, local-first Chrome extension that fixes this by scanning your browsing history and grouping it into "intent threads" – the decisions, research, and open questions you keep coming back to – then scoring each one for how alive it still is. Optionally, it also uses Claude to label those threads in plain language, suggest a concrete next step, and power a chat assistant you can ask "what should I close this week?"

By the end, you'll have built:

A Manifest V3 Chrome extension with a service worker and a full-tab dashboard
A local pipeline that captures, cleans, segments, and clusters browsing history entirely in IndexedDB
A clustering algorithm tuned and debugged on real (messy) browsing data
An AI labeling layer using Claude, with a grounding step that uses brand data from context.dev
A chat assistant that reasons across your threads and tells you what to do next
A polished dashboard with onboarding, a design system, and a working pipeline status machine

Everything runs on-device, and the only network calls are optional and opt-in, made with your own API keys.

What You'll Build
Prerequisites
How openloops Is Structured
- The shared types
- The manifest
How to Scaffold the Extension
How to Capture Your Browsing History
How to Turn Noise into Sessions
How to Cluster Sessions into Intent Threads
How to Clean Up Self-Referential Noise
How to Label Threads with Claude
How to Ground Labels with context.dev
How to Design the Dashboard
How to Build the AI Assistant
What You've Built, and Where to Take It
Resources

What You'll Build

On first run, openloops greets you with a centered welcome screen that walks you through the three pipeline steps:

Once you've scanned your history, built sessions, and built the intent map, your browsing reorganizes into status-grouped threads: active, stalled, and dormant. Each one has a confidence score, a plain-language summary, a concrete next step, and a Resume button that reopens the exact pages you left off on. The right column holds a chat assistant grounded in your own threads:

That assistant response reasons across the user's actual threads, ranking them by how easy they are to close against how much of a real decision they still need. It also explains why, which is the most novel part of this build, and depends on the context.dev grounding step you'll add later in this tutorial.

Prerequisites

To follow along, you'll need:

Node 18+ and a Chromium-based browser (Chrome, Brave, Edge, and so on).
Comfort with TypeScript and React. You don't need to be an expert, but you should be comfortable reading hooks and async/await.
Basic familiarity with IndexedDB is helpful but not required, as you'll learn what you need as you go.

Two parts of this build are optional and require your own API key, each with a free tier:

An Anthropic API key (from platform.claude.com) for AI labeling and the chat assistant
A context.dev API key (from context.dev) for the brand-grounding step

You can build and use the entire core pipeline, capture, clustering, scoring, without either key, since both are additive layers on top of it.

How openloops Is Structured

Before writing any code, it helps to see the whole shape of the thing. Every stage of openloops reads from one IndexedDB store and writes to the next:

chrome.history (backfill) ──┐
chrome.tabs.onUpdated (live)─┴─→ raw_events
                                     │  noise filter
                                     ▼
                                  sessions
                                     │  ambient detection + clustering + scoring
                                     ▼
                               intent_threads
                                     │
                                     ▼
                              React dashboard
                                     │  optional, opt-in
                                     ├──→ brand enrichment   (context.dev)
                                     └──→ AI labeling + next step (Claude)
                                              │
                                              ▼  optional, opt-in
                                        AI assistant chat (Claude)

Each stage is a separate module under src/pipeline/, and each one is independently inspectable: you can open Chrome DevTools, look at raw_events, sessions, or intent_threads directly in the Application tab, and rebuild any single stage without touching the others.

The Shared Types

Every stage consumes and produces the same handful of TypeScript interfaces, defined once in src/types.ts:

// Shared TypeScript interfaces for the openloops pipeline.
// Each stage of the pipeline consumes and produces these types.

export interface RawEvent {
  id: string;
  url: string;
  domain: string;
  title: string;
  visitedAt: number;         // epoch ms
  source: "backfill" | "live";
}

export interface Session {
  id: string;
  events: RawEvent[];
  startedAt: number;
  endedAt: number;
  domains: string[];
  keywords: string[];
}

export interface IntentThread {
  id: string;
  title: string;
  summary?: string;
  nextStep?: string;   // one concrete action to move the thread forward
  sessions: Session[];
  type: "buying" | "research" | "planning" | "learning" | "unclassified";
  confidence: number;        // 0-1
  status: "active" | "stalled" | "dormant";
  firstSeen: number;
  lastSeen: number;
  distinctDays: number;
  signals: string[];
}

export interface Brand {
  domain: string;
  name: string;
  description: string;
  industry: string;
  logoUrl: string;
  brandColor: string;
}

Most fields on IntentThread, confidence, status, signals, and distinctDays get filled in by pure local heuristics later in this guide, when you cluster and score threads. summary and nextStep stay undefined until the optional AI labeling step, covered after that, fills them in.

This is the pattern that makes the whole project work: the core data model functions on its own, and AI makes it richer.

The Manifest

openloops is a Manifest V3 extension with three permissions and three host permissions:

{
  "manifest_version": 3,
  "name": "openloops",
  "version": "0.0.1",
  "description": "Reconstruct your browsing history into an AI-labeled map of intent threads: active decisions, stalled research, open questions. Fully local.",

  "permissions": ["history", "tabs", "storage"],
  "host_permissions": [
    "https://api.anthropic.com/*",
    "https://api.context.dev/*",
    "https://logos.context.dev/*"
  ],

  "background": {
    "service_worker": "src/background.ts",
    "type": "module"
  },

  "options_page": "src/dashboard/index.html",

  "icons": {
    "16": "icons/icon16.png",
    "32": "icons/icon32.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },

  "action": {
    "default_title": "openloops",
    "default_icon": {
      "16": "icons/icon16.png",
      "32": "icons/icon32.png"
    }
  }
}

The permissions, host permissions, and options_page entry each carry specific weight:

permissions: ["history", "tabs", "storage"] are the only permissions the core pipeline needs. history reads your browsing history for the backfill, tabs lets the service worker observe new page loads and lets "Resume" reopen tabs, and storage is where API keys and preferences live.
host_permissions are separate, and only matter if you use the optional AI features. They're what let the dashboard make fetch() calls to Anthropic and context.dev without hitting CORS errors.
options_page points at the dashboard. Setting it this way, instead of a default_popup, means clicking the toolbar icon opens the dashboard as a full browser tab rather than a tiny popup, which matters once you're looking at a multi-column layout with status-grouped cards and a chat panel.

How to Scaffold the Extension

Start with Vite and the CRXJS plugin, which compiles a Manifest V3 extension with hot module reloading:

npm create vite@latest openloops -- --template react-ts
cd openloops
npm install @crxjs/vite-plugin idb react-markdown

Your vite.config.ts wires CRXJS to your manifest.json, and from there, Vite handles compiling src/background.ts to a real .js file that Chrome can load (a raw .ts service worker path in the manifest will fail with a registration error, which we'll debug in the next section).

The dashboard's entry point is a standard React 18 root:



  
    
    
    openloops

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./app.css";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  
    
  
);

Build it, then load it as an unpacked extension:

npm run build

In Chrome, go to chrome://extensions, enable Developer mode, click Load unpacked, and select the dist/ folder. With nothing else built yet, clicking the toolbar icon should open a blank dashboard tab, and the service worker (visible from the extension card's "service worker" link) should log [openloops] Extension installed. on install.

With that foundation in place, it's time to start filling raw_events with your actual browsing history.

How to Capture Your Browsing History

Every record in openloops starts life as a RawEvent, the type you saw earlier: a URL, a domain, a title, a timestamp, and a source of either "backfill" or "live".

Two pipelines populate it:

A one-time backfill that reads your last 14 days of chrome.history on demand
Live capture, which listens for new page loads from this point forward

Both paths share a handful of small helpers and write through the same IndexedDB layer, so it's worth building those first.

A Few Shared Helpers

Create src/lib/util.ts:

export function isHttpUrl(url: string): boolean {
  return url.startsWith("http://") || url.startsWith("https://");
}

export function extractDomain(url: string): string {
  try {
    const { hostname } = new URL(url);
    return hostname.replace(/^www\./, "");
  } catch {
    return url;
  }
}

export function isLocalHost(domain: string): boolean {
  if (domain === "localhost" || domain === "127.0.0.1") return true;
  if (domain.endsWith(".local")) return true;

  const octets = domain.split(".");
  if (octets.length === 4 && octets.every((o) => /^\d{1,3}$/.test(o))) {
    const [a, b] = octets.map(Number);
    if (a === 10) return true;
    if (a === 172 && b >= 16 && b <= 31) return true;
    if (a === 192 && b === 168) return true;
  }

  return false;
}

export function hashId(url: string, visitedAt: number): string {
  const str = `\({url}|\){visitedAt}`;
  let hash = 5381;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
    hash |= 0;
  }
  return (hash >>> 0).toString(36);
}

Each of these four functions solves a problem you won't notice until later in the build:

isHttpUrl is the shared scheme guard used by both live capture and the backfill, and the single gate that keeps chrome://, chrome-extension://, about:, and file:// URLs out of your data entirely. Both capture paths call it before anything else.
extractDomain strips a leading www. and returns the hostname, which is a simplification: bbc.co.uk and news.bbc.co.uk wouldn't collapse to the same domain under this logic, since true registrable-domain extraction needs the Public Suffix List. If the URL is malformed, it just returns the input unchanged rather than throwing.
isLocalHost exists for one reason: when you add brand enrichment later in this guide, you'll be sending domain names to an external API. localhost:5173 or 192.168.1.50 are meaningless to that API and would just be wasted lookups, so it's better to filter them here, once, at the source. It checks for localhost, 127.0.0.1, .local hostnames, and the standard private IPv4 ranges (10.x.x.x, 172.16.x.x–172.31.x.x, 192.168.x.x).
hashId combines the URL and timestamp into a short, deterministic string using a simple hashing algorithm (djb2), so the same (url, visitedAt) pair always produces the same ID. This makes writes idempotent: re-running the backfill produces the same IDs for the same visits, so IndexedDB's put overwrites cleanly instead of duplicating, which is what makes "Scan my history" safe to click more than once.

The Database Layer (So Far)

openloops stores everything in IndexedDB via the idb wrapper, which gives you a typed, promise-based API over the raw IndexedDB calls. Create src/db/index.ts:

import { openDB, type DBSchema, type IDBPDatabase } from "idb";
import type { RawEvent } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
}

const DB_NAME = "openloops";
const DB_VERSION = 1;

let _db: Promise> | null = null;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
      },
    });
  }
  return _db;
}

export async function clearEvents(): Promise {
  const db = await getDB();
  return db.clear("raw_events");
}

export async function putEvents(events: RawEvent[]): Promise {
  if (events.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("raw_events", "readwrite");
  await Promise.all([...events.map((e) => tx.store.put(e)), tx.done]);
}

export async function getAllEvents(): Promise {
  const db = await getDB();
  return db.getAllFromIndex("raw_events", "by_visitedAt");
}

export async function getEventCount(): Promise {
  const db = await getDB();
  return db.count("raw_events");
}

Four small functions round out this first version of the database layer: clearEvents wipes the store, which the backfill calls first so every scan starts from a clean snapshot. putEvents writes a batch using IDB's put, which overwrites rather than duplicates. getAllEvents returns everything sorted by visitedAt via the index. And getEventCount returns a simple count for the dashboard.

_db is a module-level singleton promise, so every part of the extension, the service worker and the dashboard alike, shares one connection. DB_VERSION starts at 1 here. As you add sessions, intent threads, and brand data in later parts, you'll add new stores guarded by if (!db.objectStoreNames.contains(...)) and bump this number. That guard means existing users upgrade safely without touching stores that already exist.

Capturing New Visits Live

The service worker is the always-on part of the extension. Create src/background.ts:

import { hashId, extractDomain, isHttpUrl } from "./lib/util";
import { putEvents } from "./db/index";
import type { RawEvent } from "./types";

chrome.runtime.onInstalled.addListener(() => {
  console.log("[openloops] Extension installed.");
});

chrome.action.onClicked.addListener(() => {
  chrome.runtime.openOptionsPage();
});

const DEDUP_MS = 3_000;
const recentCaptures = new Map();

chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
  if (changeInfo.status !== "complete" || !tab.url) return;

  const url = tab.url;

  if (!isHttpUrl(url)) return;

  const last = recentCaptures.get(tabId);
  const now = Date.now();
  if (last && last.url === url && now - last.at < DEDUP_MS) {
    console.log(`[openloops] dedup skip — tab \({tabId} \){url}`);
    return;
  }

  recentCaptures.set(tabId, { url, at: now });

  const event: RawEvent = {
    id: hashId(url, now),
    url,
    domain: extractDomain(url),
    title: tab.title ?? url,
    visitedAt: now,
    source: "live",
  };

  putEvents([event]).then(() => {
    console.log(`[openloops] captured \({event.domain} — \){event.title}`);
  }).catch((err) => {
    console.error("[openloops] putEvents failed:", err);
  });
});

chrome.action.onClicked is what makes the toolbar icon open the dashboard as a tab rather than a popup, working together with the options_page entry in your manifest.

Live capture happens inside the tabs.onUpdated listener, which Chrome fires repeatedly as a page loads, redirects, and updates its title, though you should only care about the moment changeInfo.status === "complete". From there, isHttpUrl drops anything that isn't a real web page, the dedup guard collapses the duplicate "complete" events that SPAs love to fire, and the rest becomes a RawEvent with source: "live".

That dedup guard is best-effort by design: recentCaptures is a plain in-memory Map, and Chrome can suspend the service worker between events, which wipes the Map along with it. It still collapses duplicate bursts within a single waking session, just not across service worker restarts, and that's an acceptable tradeoff since hashId already makes any duplicate that slips through harmless once it reaches IndexedDB.

The final write also looks slightly unusual: putEvents([event]).then(...).catch(...) instead of await. The listener doesn't need to block on the write finishing, and the service worker stays alive long enough to complete a single IndexedDB write even if it's about to be suspended, so firing the write and moving on is enough.

That source field carries more weight than it first appears, since it's how later code distinguishes "the user actually scanned their history" from "the extension has only been open for five minutes". This matters for onboarding when you design the dashboard later in this guide.

Build and reload the extension now (npm run build, then click the reload icon on the extension card in chrome://extensions), browse a few pages, then open the service worker's DevTools by clicking "service worker" on the extension card. You'll be able to see [openloops] captured ... log lines appear as confirmation that live capture is working.

Backfilling 14 Days of History

Live capture only sees what happens after you install the extension, so to make openloops useful immediately, you also need to backfill recent history. Create src/pipeline/backfill.ts:

import { extractDomain, hashId, isHttpUrl } from "../lib/util";
import { putEvents, clearEvents } from "../db/index";
import type { RawEvent } from "../types";

const CONCURRENCY = 50;

async function visitsForItem(
  item: chrome.history.HistoryItem,
  startTime: number
): Promise {
  if (!item.url) return [];
  if (!isHttpUrl(item.url)) return [];

  const visits = await chrome.history.getVisits({ url: item.url });

  const events: RawEvent[] = [];
  for (const visit of visits) {
    if (!visit.visitTime || visit.visitTime < startTime) continue;

    events.push({
      id: hashId(item.url, visit.visitTime),
      url: item.url,
      domain: extractDomain(item.url),
      title: item.title ?? item.url,
      visitedAt: visit.visitTime,
      source: "backfill",
    });
  }

  return events;
}

export async function backfillHistory(days = 14): Promise {
  await clearEvents();

  const startTime = Date.now() - days * 24 * 60 * 60 * 1000;

  const historyItems = await chrome.history.search({
    text: "",
    startTime,
    maxResults: 100_000,
  });

  let totalWritten = 0;

  for (let i = 0; i < historyItems.length; i += CONCURRENCY) {
    const batch = historyItems.slice(i, i + CONCURRENCY);
    const batchResults = await Promise.all(
      batch.map((item) => visitsForItem(item, startTime))
    );
    const events = batchResults.flat();
    await putEvents(events);
    totalWritten += events.length;
  }

  return totalWritten;
}

backfillHistory starts by calling clearEvents and wiping the store so each run produces a clean snapshot for the chosen window. Every real visit still exists in chrome.history, so nothing is lost by starting over. It then searches with maxResults: 100_000, since the default of 100 is far too low for anyone with more than a few days of real browsing.

Each matching HistoryItem goes through visitsForItem, which skips items that Chrome returns with no url at all, a quirk of some deleted-history entries, and skips non-web URLs using isHttpUrl, before fetching that item's full visit list.

Calling getVisits here, instead of relying on search alone, matters because chrome.history.search is tempting as a single call, but it collapses every visit to a URL down to just the most recent one. If you visited the same Stack Overflow answer three times over two days while debugging something, search gives you one row, and in the next section, where you segment events into sessions, you need all three: that's the difference between "one visit, three days ago" and "a sustained debugging session."

getVisits gives you that full timestamp list, but it returns all history for a URL regardless of date range, so visitsForItem filters by startTime itself. And because chrome.history.search can return tens of thousands of items for a heavy browser history, the backfill fans out to getVisits in batches of CONCURRENCY, set to 50, rather than firing everything at once. Chrome doesn't document a hard limit on concurrent getVisits calls, but 50 in flight at a time keeps things responsive without flooding it.

Checkpoint

You can verify live capture by browsing normally and watching raw_events fill up: open chrome://extensions, click "service worker" on the openloops card, then go to the Application tab → IndexedDB → openloops → raw_events, where each row should be a RawEvent with source: "live".

backfillHistory itself doesn't have a UI yet, but you'll wire it up to a "Scan my history" button when you build the dashboard rail in Part 13. For now, it's enough that it compiles and that raw_events is filling up from live capture. In the next part you'll start turning that raw stream into something structured: sessions.

How to Turn Noise into Sessions

A real browsing history is full of activity that has nothing to do with what you were actually trying to do. An afternoon of research might be interleaved with dozens of visits to Gmail, Slack, or YouTube, along with pages whose titles are just "New Tab" or "Dashboard" because the page hadn't finished loading when the browser recorded it.

Before any of this can be grouped into something meaningful, two things need to happen: the noise needs to be filtered out, and what remains needs to be broken into sessions, contiguous stretches of activity separated by gaps in time.

This section builds both of those steps, along with a small keyword extractor that each session uses to describe what it was about, since that description is what later powers clustering.

Filtering Out Noise

Create src/pipeline/noise.ts:

import type { RawEvent } from "../types";
import { isHttpUrl, isLocalHost } from "../lib/util";

export const BLOCKED_DOMAINS: readonly string[] = [
  "mail.google.com",
  "outlook.live.com",
  "outlook.office.com",
  "calendar.google.com",
  "slack.com",
  "app.slack.com",
  "discord.com",
  "web.whatsapp.com",
  "teams.microsoft.com",
  "messenger.com",
];

export const ADULT_DOMAINS: readonly string[] = [
  "xvideos.com",
  "pornhub.com",
  "xnxx.com",
  "xhamster.com",
  "redtube.com",
  "youporn.com",
  "spankbang.com",
];

export const JUNK_DOMAINS: readonly string[] = [
  "trk.myperfect2give.com",
  "t.buenotraffic.com",
  "bwredir.com",
  "osom.saintscommunity.net",
];

const ALL_BLOCKED = [...BLOCKED_DOMAINS, ...ADULT_DOMAINS, ...JUNK_DOMAINS];

function domainIsBlocked(domain: string): boolean {
  return ALL_BLOCKED.some(
    (blocked) => domain === blocked || domain.endsWith("." + blocked)
  );
}

export const NOISE_TITLE_PREFIXES: readonly string[] = [
  "new tab",
  "new chat",
  "untitled",
  "inbox",
  "home",
  "dashboard",
  "sign in",
  "log in",
  "loading",
];

function titleIsGeneric(title: string, domain: string): boolean {
  if (title.trim() === "") return true;
  if (title.toLowerCase() === domain.toLowerCase()) return true;

  const lower = title.toLowerCase();
  return NOISE_TITLE_PREFIXES.some((prefix) => lower.startsWith(prefix));
}

export function isNoise(event: RawEvent): boolean {
  if (!isHttpUrl(event.url)) return true;
  if (isLocalHost(event.domain)) return true;
  return domainIsBlocked(event.domain) || titleIsGeneric(event.title, event.domain);
}

isNoise is the single function the rest of the pipeline calls, and it layers four checks on top of each other, each one catching a different kind of noise.

The first two checks reuse the helpers from earlier: isHttpUrl and isLocalHost drop anything that isn't a real web page or that points at a local development server, the same filters that already protect capture. Checking them again here is a deliberate belt-and-suspenders measure: if anything ever reaches raw_events without having passed through capture's checks, it still can't make it into a session.

BLOCKED_DOMAINS covers communication and productivity tools, Gmail, Slack, Discord, WhatsApp Web, and similar. Those tools that you visit constantly but that carry no research intent of their own. domainIsBlocked matches both the exact domain and any subdomain, so slack.com in the list also catches app.slack.com. ADULT_DOMAINS and JUNK_DOMAINS exist for related reasons, keeping adult content and known tracker or redirect domains out of your threads entirely.

BLOCKED_DOMAINS is a curated, static list, and later in this guide it's complemented by a second, frequency-based detector in ambient.ts. This drops any domain that shows up in nearly every session regardless of what that domain actually is.

The last check, titleIsGeneric, catches pages whose titles tell you nothing useful: an empty title, a title that's identical to the domain name, or a title that starts with a generic prefix like "New Tab", "Dashboard", "Loading...", or "Sign in". NOISE_TITLE_PREFIXES is matched against the start of the lowercased title, so "Dashboard | Vercel" gets dropped right alongside a bare "Dashboard", while a content-rich title on that same domain passes through untouched.

Extracting Keywords

Create src/pipeline/keywords.ts. This isn't NLP, just frequency counting after stopword removal. This is good enough to surface something like "typescript generics" or "react hooks" from a session of related browsing:

import { BLOCKED_DOMAINS } from "./noise";

export const STOPWORDS: ReadonlySet = new Set([
  "the", "and", "for", "with", "you", "your", "how", "what", "this", "that",
  "from", "are", "was", "not", "but", "all", "can", "has", "have", "will",
  "its", "out", "one", "get", "our", "had", "just", "about", "also", "more",
  "into", "than", "then", "when", "their", "there", "which", "would", "been",
  "his", "her", "who", "they", "she", "him", "now", "any", "way", "use",
  "using", "used", "make", "made",
  "google", "youtube", "search", "chat", "new", "home", "www", "com", "org",
  "net", "page", "site", "tab", "view", "app", "log", "sign", "login",
  "official", "free", "online", "best", "top", "open",
]);

export const PLATFORM_STOPWORDS: ReadonlySet = new Set([
  "instagram", "facebook", "youtube", "claude", "google", "linkedin",
  "twitter", "reddit", "netflix", "amazon", "gmail", "whatsapp", "tiktok",
  "messenger",
  "stories", "story", "reel", "reels", "shorts", "short", "feed", "watch",
  "video", "videos", "music", "post", "posts", "message", "messages",
  "dm", "dms", "notification", "notifications", "profile", "home", "login",
  "signin", "follow", "followers",
]);

function derivedDomainLabels(): Set {
  const labels = new Set();
  for (const domain of BLOCKED_DOMAINS) {
    const label = domain.split(".").at(-2);
    if (label) labels.add(label);
  }
  return labels;
}

const ALL_STOP_TOKENS: ReadonlySet = new Set([
  ...STOPWORDS,
  ...PLATFORM_STOPWORDS,
  ...derivedDomainLabels(),
]);

export function extractKeywords(titles: string[], max = 8): string[] {
  const freq = new Map();

  for (const title of titles) {
    const tokens = title.toLowerCase().split(/[^a-z0-9]+/);
    for (const token of tokens) {
      if (token.length < 3) continue;
      if (/^\d+$/.test(token)) continue;
      if (ALL_STOP_TOKENS.has(token)) continue;

      freq.set(token, (freq.get(token) ?? 0) + 1);
    }
  }

  return [...freq.entries()]
    .sort((a, b) => b[1] - a[1])
    .slice(0, max)
    .map(([token]) => token);
}

extractKeywords takes the page titles from a group of events and returns the handful of words that show up most often, after stripping out everything that isn't a topic. That stripping is doing more work than the name "stopwords" suggests.

STOPWORDS covers common English function words like "the" and "with", plus generic site chrome like "search", "login", and "page". On its own, this would still let through tokens like "instagram" or "reels" from a title such as "Reels · Instagram", and those tokens would then show up as keywords for that session.

That gap is what PLATFORM_STOPWORDS closes. A title like "Reels · Instagram" or "Watch - YouTube" identifies the tool you were using, not what you were doing with it. So PLATFORM_STOPWORDS strips out platform and brand names along with social media UI chrome like "stories", "feed", "dm", and "notifications". Without this list, sessions on social platforms would extract keywords like "instagram" or "watch". Those would become thread titles that quietly pull unrelated sessions together during clustering, since every social-media session would share that one meaningless keyword.

derivedDomainLabels keeps a third source of stopwords in sync automatically: for every domain in BLOCKED_DOMAINS, it takes the label immediately before the top-level domain. So mail.google.com becomes google and web.whatsapp.com becomes whatsapp. Adding a new domain to that blocklist later also prevents its name from polluting keywords, without any extra bookkeeping.

With all three sets merged once at module load into ALL_STOP_TOKENS, extractKeywords itself is straightforward: lowercase every title, split on anything that isn't a letter or digit, drop tokens shorter than three characters or made entirely of digits, and drop anything in ALL_STOP_TOKENS. Then count what's left and return the most frequent entries.

Extending the Database For Sessions

Sessions need a place to live. Earlier in this guide, src/db/index.ts defined a schema with just raw_events at version 1. We'll add a sessions store and bump the version to 2.

First, extend the schema and the upgrade callback:

import type { RawEvent, Session } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
  sessions: {
    key: string;
    value: Session;
    indexes: { by_startedAt: number };
  };
}

const DB_VERSION = 2;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
        if (!db.objectStoreNames.contains("sessions")) {
          const s = db.createObjectStore("sessions", { keyPath: "id" });
          s.createIndex("by_startedAt", "startedAt");
        }
      },
    });
  }
  return _db;
}

Then add the helper functions sessions need, alongside the raw_events helpers you already wrote. They follow the same shape: putSessions writes a batch idempotently, clearSessions wipes the store before a rebuild, getAllSessions returns everything sorted by startedAt via the index, and getSessionCount returns a total.

export async function putSessions(sessions: Session[]): Promise {
  if (sessions.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("sessions", "readwrite");
  await Promise.all([...sessions.map((s) => tx.store.put(s)), tx.done]);
}

export async function clearSessions(): Promise {
  const db = await getDB();
  return db.clear("sessions");
}

export async function getAllSessions(): Promise {
  const db = await getDB();
  return db.getAllFromIndex("sessions", "by_startedAt");
}

export async function getSessionCount(): Promise {
  const db = await getDB();
  return db.count("sessions");
}

The if (!db.objectStoreNames.contains(...)) guard from earlier is what makes this safe: anyone who already has a version-1 database, with raw_events full of real data, gets the new sessions store added on top, without touching what's already there.

Segmenting Events into Sessions

A session is a contiguous block of browsing activity, with a new one starting whenever the gap between two consecutive events exceeds SESSION_GAP_MS. Create src/pipeline/sessions.ts:

import { getAllEvents, clearSessions, putSessions } from "../db/index";
import { isNoise } from "./noise";
import { extractKeywords } from "./keywords";
import { hashId } from "../lib/util";
import type { RawEvent, Session } from "../types";

const SESSION_GAP_MS = 30 * 60 * 1000;

function rankDomains(events: RawEvent[]): string[] {
  const freq = new Map();
  for (const e of events) {
    freq.set(e.domain, (freq.get(e.domain) ?? 0) + 1);
  }
  return [...freq.entries()]
    .sort((a, b) => b[1] - a[1])
    .map(([domain]) => domain);
}

function buildSession(events: RawEvent[]): Session {
  const startedAt = events[0].visitedAt;
  const endedAt = events[events.length - 1].visitedAt;

  return {
    id: hashId(events[0].url, startedAt),
    events,
    startedAt,
    endedAt,
    domains: rankDomains(events),
    keywords: extractKeywords(events.map((e) => e.title)),
  };
}

export async function buildSessions(): Promise<{ events: number; sessions: number }> {
  const allEvents = await getAllEvents();

  const meaningful = allEvents.filter((e) => !isNoise(e));

  if (meaningful.length === 0) {
    await clearSessions();
    return { events: 0, sessions: 0 };
  }

  const sessions: Session[] = [];
  let currentGroup: RawEvent[] = [meaningful[0]];

  for (let i = 1; i < meaningful.length; i++) {
    const gap = meaningful[i].visitedAt - meaningful[i - 1].visitedAt;

    if (gap > SESSION_GAP_MS) {
      sessions.push(buildSession(currentGroup));
      currentGroup = [meaningful[i]];
    } else {
      currentGroup.push(meaningful[i]);
    }
  }
  sessions.push(buildSession(currentGroup));

  const substantive = sessions.filter(
    (s) => !(s.events.length === 1 && s.keywords.length === 0)
  );

  await clearSessions();
  await putSessions(substantive);

  return { events: meaningful.length, sessions: substantive.length };
}

buildSessions does five things in order:

loads every raw event sorted by time,
drops anything isNoise flags,
walks the remaining list and starts a new session whenever the gap between two consecutive events exceeds SESSION_GAP_MS (pushing the final in-progress group once the loop ends since nothing else closes it off),
drops sessions that turned out to be a single event with no extractable keywords (usually stray page loads that never connected to anything else),
and persists the result.

Each session's domains and keywords come from rankDomains and extractKeywords running over just the events in that group. rankDomains counts how many events came from each domain and orders them by frequency, so the most-visited domain in a session comes first.

A worked example makes "walking the list" concrete. Take five events that survive noise filtering, A through E:

A  t= 0 min  "TypeScript generics - Stack Overflow"   stackoverflow.com
B  t= 5 min  "TypeScript Handbook"                    typescriptlang.org
C  t=10 min  "microsoft/TypeScript - GitHub"          github.com
   ↑ gap to D = 45 min  >  SESSION_GAP_MS (30 min)  → SPLIT HERE
D  t=55 min  "React hooks explained - YouTube"         youtube.com
E  t=60 min  "useEffect cleanup - Stack Overflow"     stackoverflow.com

As the loop walks from A to B to C, each gap is under the 30-minute limit, so all three stay in the same group. The jump from C to D is 45 minutes, which crosses SESSION_GAP_MS, so the loop closes off [A, B, C] as Session 1 and starts a fresh group with D. From D to E is only 5 minutes, so E joins D, and that group becomes Session 2 once the loop ends.

Session 1 ends up tagged with keywords like typescript and generics, while Session 2 is tagged with react and hooks, even though both sessions happened on the same day.

SESSION_GAP_MS is set to 30 minutes because that's the same default that Google Analytics and similar tools use, and it works well for most browsing patterns.

The tradeoff runs in both directions: a shorter gap produces more, smaller sessions, which gives clustering a more granular signal but risks fragmenting one continuous task into several pieces. A longer gap produces fewer, larger sessions, which risks merging activity that was actually unrelated.

30 minutes is a reasonable starting point, and it's the kind of constant you can come back and tune once you see how your own threads turn out.

Checkpoint

buildSessions doesn't have a UI yet either. It'll get wired up to a "Build sessions" button alongside "Scan my history" when you design the dashboard later in this guide.

For now, the goal is just for everything in this section to compile cleanly: src/pipeline/noise.ts, src/pipeline/keywords.ts, the updated src/db/index.ts, and src/pipeline/sessions.ts should all build without errors. getDB() should report version 2 the next time the extension reloads (visible in DevTools under Application → IndexedDB → openloops, where the database now lists both raw_events and sessions as object stores).

With sessions in place, the next section takes this structured-but-unconnected data and groups sessions together into the intent threads this whole project is named after.

How to Cluster Sessions into Intent Threads

Sessions group events that happened close together in time. But the things you're actually trying to do rarely fit inside one session. Comparing laptops might span three sessions over four days. A question you keep meaning to look into might surface for ten minutes every few days for two weeks.

This section groups related sessions together into intent threads, then scores each thread for how confident openloops is that it represents something real and how alive it still is.

Two files do this work. src/pipeline/ambient.ts detects domains that are part of your daily routine rather than any particular intent, so they don't create false similarity between unrelated sessions. src/pipeline/threads.ts does the actual clustering and scoring.

Detecting Ambient Domains

Some domains show up in almost every session regardless of what you're doing: youtube.com as background noise, github.com if you're a developer who commits daily, or claude.ai if you use it as a general assistant. If clustering compared sessions on these domains the same way it compares them on anything else, two completely unrelated sessions would look similar just because they both touched youtube.com, and everything would eventually merge into one enormous thread.

ambient.ts solves this with a frequency check: a domain is ambient if it shows up on a large enough fraction of your active days, regardless of topic.

Create src/pipeline/ambient.ts:

import type { Session } from "../types";

export const UBIQUITY_THRESHOLD = 0.6;
export const MIN_ACTIVE_DAYS = 3;

function toDay(epochMs: number): string {
  return new Date(epochMs).toDateString();
}

export function detectAmbientDomains(sessions: Session[]): Set {
  const allEvents = sessions.flatMap((s) => s.events);

  const activeDays = new Set(allEvents.map((e) => toDay(e.visitedAt)));
  const totalActiveDays = activeDays.size;

  if (totalActiveDays < MIN_ACTIVE_DAYS) {
    return new Set();
  }

  const domainDayMap = new Map>();
  for (const event of allEvents) {
    const day = toDay(event.visitedAt);
    if (!domainDayMap.has(event.domain)) {
      domainDayMap.set(event.domain, new Set());
    }
    domainDayMap.get(event.domain)!.add(day);
  }

  const ambient = new Set();
  for (const [domain, days] of domainDayMap) {
    const ubiquity = days.size / totalActiveDays;
    if (ubiquity >= UBIQUITY_THRESHOLD) {
      ambient.add(domain);
      console.log(
        `[openloops] ambient: \({domain} (\){days.size}/\({totalActiveDays} days, ubiquity=\){ubiquity.toFixed(2)})`
      );
    }
  }

  return ambient;
}

toDay collapses a timestamp down to a calendar-day string, so two events on the same day produce the same key, regardless of the exact time.

detectAmbientDomains first counts how many distinct days had any browsing activity at all – that's totalActiveDays – then builds a map from each domain to the set of days it appeared on. A domain's ubiquity is days.size / totalActiveDays, the fraction of your active days that domain showed up on. Anything at or above UBIQUITY_THRESHOLD 0.6 gets added to the returned set.

MIN_ACTIVE_DAYS exists because with only one or two days of data, almost every domain you visited would technically appear on 100% of your active days, and the detector would mark everything as ambient. Below three active days, it returns an empty set and skips detection entirely.

This approach has a real tradeoff. It correctly identifies genuinely ambient tools, but it can also suppress a domain you happened to research intensively every single day for a week, which would also cross the 60% threshold.

UBIQUITY_THRESHOLD is the knob for that tradeoff: raising it reduces false positives at the cost of letting some real ambient noise back in.

Extending the Database for Intent Threads

Threads need their own store. Bump DB_VERSION to 3 and add intent_threads, indexed by lastSeen, so the dashboard can show the most recently active threads first:

import type { RawEvent, Session, IntentThread } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
  sessions: {
    key: string;
    value: Session;
    indexes: { by_startedAt: number };
  };
  intent_threads: {
    key: string;
    value: IntentThread;
    indexes: { by_lastSeen: number };
  };
}

const DB_VERSION = 3;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
        if (!db.objectStoreNames.contains("sessions")) {
          const s = db.createObjectStore("sessions", { keyPath: "id" });
          s.createIndex("by_startedAt", "startedAt");
        }
        if (!db.objectStoreNames.contains("intent_threads")) {
          const s = db.createObjectStore("intent_threads", { keyPath: "id" });
          s.createIndex("by_lastSeen", "lastSeen");
        }
      },
    });
  }
  return _db;
}

Then add the matching helpers:

export async function putThreads(threads: IntentThread[]): Promise {
  if (threads.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("intent_threads", "readwrite");
  await Promise.all([...threads.map((t) => tx.store.put(t)), tx.done]);
}

export async function clearThreads(): Promise {
  const db = await getDB();
  return db.clear("intent_threads");
}

export async function getAllThreads(): Promise {
  const db = await getDB();
  const index = db
    .transaction("intent_threads", "readonly")
    .store.index("by_lastSeen");

  let cursor = await index.openCursor(null, "prev");
  const results: IntentThread[] = [];
  while (cursor) {
    results.push(cursor.value);
    cursor = await cursor.continue();
  }
  return results;
}

export async function getThreadCount(): Promise {
  const db = await getDB();
  return db.count("intent_threads");
}

putThreads, clearThreads, and getThreadCount follow the same pattern as the sessions helpers from earlier. getAllThreads is the odd one out: instead of getAllFromIndex, which only returns ascending order, it opens a cursor on by_lastSeen in "prev" direction and walks it manually. That gives you threads ordered with the most recently active first, the order the dashboard wants for status-grouped cards.

Clustering Sessions into Threads

With ambient domains identified, src/pipeline/threads.ts now does the real work: grouping sessions into threads, then scoring and classifying each one.

The approach is greedy agglomerative clustering. Walk through sessions in chronological order, and for each one, either merge it into the most similar existing thread or start a new thread if nothing is similar enough.

Start with the imports, the tuning constants, and the similarity calculation:

import { getAllSessions, clearThreads, putThreads } from "../db/index";
import { detectAmbientDomains } from "./ambient";
import { hashId } from "../lib/util";
import type { Session, IntentThread } from "../types";

export const SIMILARITY_THRESHOLD = 0.15;
export const DOMAIN_WEIGHT = 0.5;
export const KEYWORD_WEIGHT = 0.5;

interface ThreadBuilder {
  id: string;
  sessions: Session[];
  domainSet: Set;
  keywordSet: Set;
}

function jaccard(a: Set, b: Set): number {
  if (a.size === 0 && b.size === 0) return 0;
  let intersection = 0;
  for (const item of a) {
    if (b.has(item)) intersection++;
  }
  const union = a.size + b.size - intersection;
  return intersection / union;
}

function similarity(
  session: Session,
  thread: ThreadBuilder,
  ambient: Set
): number {
  const sessionDomains  = new Set(session.domains.filter((d) => !ambient.has(d)));
  const threadDomains   = new Set([...thread.domainSet].filter((d) => !ambient.has(d)));
  const sessionKeywords = new Set(session.keywords);

  const domainScore   = jaccard(sessionDomains, threadDomains);
  const keywordScore  = jaccard(sessionKeywords, thread.keywordSet);

  return DOMAIN_WEIGHT * domainScore + KEYWORD_WEIGHT * keywordScore;
}

ThreadBuilder is a mutable accumulator used only during clustering: a thread in progress, with its sessions plus the union of all domains and keywords seen so far. jaccard is the standard set-similarity measure, the size of the intersection divided by the size of the union, returning 0 for two empty sets rather than dividing zero by zero.

similarity compares one candidate session against one in-progress thread. Before comparing domains, it filters ambient domains out of both sides, so a shared youtube.com never contributes to the score. It then computes a domain Jaccard score and a keyword Jaccard score separately, and combines them with DOMAIN_WEIGHT and KEYWORD_WEIGHT, both 0.5, giving domain overlap and keyword overlap equal say in the final number.

Next, the clustering loop itself:

function clusterSessions(
  sessions: Session[],
  ambient: Set
): ThreadBuilder[] {
  const threads: ThreadBuilder[] = [];

  for (const session of sessions) {
    let bestThread: ThreadBuilder | null = null;
    let bestScore = 0;

    for (const thread of threads) {
      const score = similarity(session, thread, ambient);
      if (score > bestScore) {
        bestScore = score;
        bestThread = thread;
      }
    }

    if (bestThread && bestScore >= SIMILARITY_THRESHOLD) {
      bestThread.sessions.push(session);
      for (const d of session.domains)  bestThread.domainSet.add(d);
      for (const k of session.keywords) bestThread.keywordSet.add(k);
    } else {
      threads.push({
        id: hashId(session.id, session.startedAt),
        sessions: [session],
        domainSet:  new Set(session.domains),
        keywordSet: new Set(session.keywords),
      });
    }
  }

  return threads;
}

clusterSessions relies on sessions already being sorted chronologically, which getAllSessions guarantees via its index. For each session, it scores against every thread built so far and keeps the best match.

If that best score clears SIMILARITY_THRESHOLD, the session merges in and its domains and keywords get folded into the thread's accumulated sets. This means that later sessions are compared against the thread's entire accumulated history rather than only its seed session. If nothing clears the threshold, the session becomes the seed of a brand-new thread.

A worked example shows how this plays out. Suppose detectAmbientDomains returned { youtube.com }, and three sessions arrive in this order:

S1: domains=[stackoverflow.com, typescriptlang.org]
    keywords=[typescript, generics, interface, mapped]

S2: domains=[stackoverflow.com, typescriptlang.org, github.com]
    keywords=[typescript, generics, utility, types]

S3: domains=[python.org, docs.python.org]
    keywords=[python, async, await, coroutine]

S1 arrives first. With no threads yet, it seeds Thread A: domainSet = {stackoverflow.com, typescriptlang.org}, keywordSet = {typescript, generics, interface, mapped}.

S2 is scored against Thread A. Neither set contains the ambient youtube.com, so nothing gets filtered out. The domain Jaccard is |{stackoverflow.com, typescriptlang.org}| / |{stackoverflow.com, typescriptlang.org, github.com}|, or 2/3 ≈ 0.667. The keyword Jaccard is |{typescript, generics}| / |{typescript, generics, interface, mapped, utility, types}|, or 2/6 ≈ 0.333. The combined similarity is 0.5 × 0.667 + 0.5 × 0.333 = 0.5, comfortably above SIMILARITY_THRESHOLD (0.15), so S2 merges into Thread A, whose sets grow to include github.com, utility, and types.

S3 is scored against Thread A. There's no overlap at all between {python.org, docs.python.org} and Thread A's domains, or between their keyword sets, so both Jaccard scores are 0 and the combined similarity is 0. That's below the threshold, so S3 seeds a new Thread B.

The result: Thread A holds the TypeScript research across two sessions, and Thread B holds the Python session on its own.

SIMILARITY_THRESHOLD is the single most consequential constant in this file, and 0.15 is lower than you might guess for a 50/50 weighted Jaccard score. A starting value like 0.3 sounds more principled. That would mean two sessions need to share roughly a third of their combined domains and keywords before they're considered part of the same thread.

Run that against real, messy browsing history, though, and it produces far too many threads: sessions that were obviously part of the same research, but didn't share quite enough keywords to clear 0.3, end up scattered across separate threads.

Dropping the threshold to 0.15 lets sessions merge on weaker but still real signal. Two sessions sharing just one domain and one keyword out of several can already cross 0.15, and the result is fewer, more coherent threads that actually match what the browsing history looks like.

This is the kind of constant you tune empirically rather than deriving it from first principles: build your threads, look at the result, and adjust.

buildThreads, covered next, prints a table of every thread's title, type, status, confidence, and top keywords specifically so you can eyeball this. If two threads obviously belong together, lower SIMILARITY_THRESHOLD. If one thread is clearly several unrelated topics glued together, raise it.

Scoring and Classifying Threads

Clustering produces groups of sessions, but a group of sessions isn't yet an IntentThread. The rest of threads.ts turns each group into something with a type, a confidence score, a status, and a set of human-readable signals explaining why.

A few small helpers come first:

export const BUYING_WORDS: readonly string[] = [
  "vs", "versus", "alternative", "alternatives",
  "comparison", "pricing", "price", "review", "reviews", "best",
];

export const LEARNING_WORDS: readonly string[] = [
  "how to", "tutorial", "tutorials", "docs", "documentation",
  "guide", "learn", "example", "examples", "crash course", "introduction",
];

const STATUS_ACTIVE_MS  = 48 * 60 * 60 * 1000;
const STATUS_STALLED_MS = 7  * 24 * 60 * 60 * 1000;

function toTitleCase(s: string): string {
  return s.charAt(0).toUpperCase() + s.slice(1);
}

function findMatches(titles: string[], wordList: readonly string[]): string[] {
  const lower = titles.map((t) => t.toLowerCase());
  const found = new Set();

  for (const word of wordList) {
    const isPhrase = word.includes(" ");
    for (const title of lower) {
      if (isPhrase) {
        if (title.includes(word)) found.add(word);
      } else {
        const tokens = title.split(/[^a-z0-9]+/);
        if (tokens.includes(word)) found.add(word);
      }
    }
  }

  return [...found];
}

function toCalendarDay(epochMs: number): string {
  return new Date(epochMs).toDateString();
}

BUYING_WORDS and LEARNING_WORDS are small vocabularies that signal intent. findMatches checks a list of page titles against one of these vocabularies, and handles single words and phrases differently: a multi-word entry like "how to" is checked as a substring, since it's specific enough that false positives are unlikely. But a single word like "review" is checked as a whole token, split out of the title on non-alphanumeric characters.

Without that distinction, "review" would match inside "overview" too, which would misclassify any thread that happened to involve an "Overview" page. toTitleCase and toCalendarDay are small formatting helpers used by the scoring function next.

That scoring function, scoreThread, is the longest function in the project, since it's where every signal collected so far gets turned into the fields on IntentThread:

function scoreThread(builder: ThreadBuilder): IntentThread {
  const { sessions, keywordSet } = builder;

  const firstSeen  = sessions[0].startedAt;
  const lastSeen   = sessions[sessions.length - 1].endedAt;

  const allEvents  = sessions.flatMap((s) => s.events);
  const totalEvents = allEvents.length;
  const daySet     = new Set(allEvents.map((e) => toCalendarDay(e.visitedAt)));
  const distinctDays = daySet.size;

  const allTitles      = allEvents.map((e) => e.title);
  const buyingMatches  = findMatches(allTitles, BUYING_WORDS);
  const learningMatches = findMatches(allTitles, LEARNING_WORDS);

  let type: IntentThread["type"];
  if (buyingMatches.length > 0) {
    type = "buying";
  } else if (learningMatches.length > 0) {
    type = "learning";
  } else if (distinctDays > 5 && sessions.length >= 3) {
    type = "planning";
  } else if (totalEvents >= 3) {
    type = "research";
  } else {
    type = "unclassified";
  }

  const age = Date.now() - lastSeen;
  const status: IntentThread["status"] =
    age < STATUS_ACTIVE_MS  ? "active"  :
    age < STATUS_STALLED_MS ? "stalled" :
    "dormant";

  const confidence = parseFloat((
    Math.min(distinctDays / 5, 1) * 0.35 +
    Math.min(sessions.length / 5, 1) * 0.25 +
    Math.min(totalEvents / 20, 1)  * 0.20 +
    (type !== "unclassified" ? 1 : 0)  * 0.20
  ).toFixed(2));

  const signals: string[] = [];

  if (distinctDays > 1)
    signals.push(`revisited across ${distinctDays} days`);
  if (type === "buying" && buyingMatches.length > 0)
    signals.push(`comparison language: ${buyingMatches.join(", ")}`);
  if (type === "learning" && learningMatches.length > 0)
    signals.push(`learning language: ${learningMatches.join(", ")}`);
  signals.push(`\({sessions.length} session\){sessions.length !== 1 ? "s" : ""}`);
  if (totalEvents > 5)
    signals.push(`${totalEvents} total events`);
  if (type === "planning")
    signals.push("sustained activity across many days");

  const ageDays = Math.floor(age / (24 * 60 * 60 * 1000));
  if (ageDays === 0)       signals.push("last active today");
  else if (ageDays === 1)  signals.push("last active yesterday");
  else                     signals.push(`last active ${ageDays} days ago`);

  const title =
    [...keywordSet].slice(0, 3).map(toTitleCase).join(" ") || "Untitled Thread";

  return {
    id: builder.id,
    title,
    sessions,
    type,
    confidence,
    status,
    firstSeen,
    lastSeen,
    distinctDays,
    signals,
  };
}

There's a lot here, so it's worth walking through each field on IntentThread in the order it's computed.

firstSeen and lastSeen come straight from the boundary sessions, since sessions arrives in chronological order from clustering. distinctDays reuses the same calendar-day collapsing as ambient.ts. This time it counts how many different days this thread's events span, regardless of how many total active days you had overall.

Classification into type is a cascade, and the order matters. Comparison language (BUYING_WORDS) is checked first, because a thread where you're comparing two frameworks is "buying" even if it also contains tutorial pages. Comparison intent is the stronger signal.

Learning language comes next. After that, planning is reserved for threads that span more than five distinct days and have at least three sessions of sustained, recurring activity rather than a single deep dive.

research is the catch-all for anything with at least three events that didn't match anything more specific, and unclassified is what's left, usually threads with too little activity to say anything confident about.

status is purely a function of how long ago lastSeen was: under 48 hours is active, under 7 days is stalled, anything older is dormant.

confidence is a weighted sum of four signals, each normalized to a maximum of 1 before weighting, so the total can't exceed 1 either. distinctDays / 5, capped at 1, contributes up to 35%, treating five or more distinct days as fully confident on that axis. sessions.length / 5, capped at 1, contributes up to 25%. totalEvents / 20, capped at 1, contributes up to 20%. And whether type is anything other than unclassified contributes the final 20% as an all-or-nothing bonus.

A thread revisited across five-plus days, across five-plus sessions, with twenty-plus events, that also classified cleanly, scores a full 1.0. A thread that's a single session with two events and no classification scores close to 0.

signals is a plain-English audit trail for the confidence score and status: it explains why a thread looks the way it does, listing things like how many days it was revisited across, what comparison or learning language was found, the session and event counts, and how recently it was last active. The dashboard surfaces these directly.

Finally, title is a placeholder: the top three keywords from the thread's accumulated keywordSet, title-cased and joined with spaces, or "Untitled Thread" if there are none.

This is deliberately weak. Later in this guide, AI labeling replaces this heuristic title, along with summary and nextStep, with something grounded in what the thread is actually about (but the thread is fully usable without that step, too).

Putting it Together

buildThreads ties everything in this section together:

export async function buildThreads(): Promise<{ sessions: number; threads: number }> {
  const sessions = await getAllSessions();

  if (sessions.length === 0) {
    await clearThreads();
    return { sessions: 0, threads: 0 };
  }

  const ambient = detectAmbientDomains(sessions);

  const builders = clusterSessions(sessions, ambient);

  const substantive = builders.filter(
    (b) => !(b.sessions.length === 1 && b.sessions[0].events.length < 3)
  );

  const threads = substantive.map(scoreThread);

  await clearThreads();
  await putThreads(threads);

  console.table(
    threads.map((t) => ({
      title:        t.title,
      type:         t.type,
      status:       t.status,
      confidence:   t.confidence,
      distinctDays: t.distinctDays,
      sessions:     t.sessions.length,
      events:       t.sessions.reduce((n, s) => n + s.events.length, 0),
      keywords:     [...new Set(t.sessions.flatMap((s) => s.keywords))].slice(0, 5).join(", "),
    }))
  );

  return { sessions: sessions.length, threads: threads.length };
}

The order here matters. detectAmbientDomains runs once, over every session, before any clustering happens, since ambient detection needs the full picture of your browsing to know what counts as "every day".

clusterSessions then produces ThreadBuilders, which get filtered before scoring: a ThreadBuilder with exactly one session and fewer than three events is almost always a stray page load that didn't merge with anything, so it's dropped rather than becoming a thread with a confidence near zero.

Everything that survives gets scored by scoreThread, persisted, and printed via console.table, which is the tuning aid mentioned earlier. If you open the service worker's console after running this, every thread is laid out in a sortable table. This is the fastest way to spot a SIMILARITY_THRESHOLD that's too high or too low.

Checkpoint

Like the previous two sections, buildThreads doesn't have a UI yet. It'll get wired up to a "Build intent map" button alongside the other two when you design the dashboard later in this guide.

For now, confirm that src/pipeline/ambient.ts, the updated src/db/index.ts, and src/pipeline/threads.ts all build without errors, and that getDB() reports version 3 the next time the extension reloads. intent_threads should now be listed alongside raw_events and sessions in DevTools.

At this point, the entire core pipeline runs end to end, locally, with no API keys involved: your browsing history becomes raw events, raw events become sessions, and sessions become scored, classified intent threads.

Everything from here is optional and additive: cleaning up a source of self-referential noise this pipeline doesn't yet handle (which you probably want to look at and incorporate), then AI labeling, brand grounding, and the dashboard that ties it all together.

How to Clean Up Self-Referential Noise

Run the pipeline a few times against your own browsing and a strange kind of thread starts appearing: one made entirely of openloops itself.

The dashboard is a web page, so every time you open it to check your threads, that page load gets captured as an event. If you're also developing the extension, your localhost dev server and any private-network addresses end up in the data too.

The tool ends up watching itself use itself, and that self-reference pollutes the intent map in two distinct ways which are worth separating.

The Two Problems

The first problem is the extension's own pages. A Chrome extension's dashboard loads from a chrome-extension:// URL, and Chrome's own internal pages use chrome://. Left unfiltered, opening the openloops dashboard ten times in an afternoon produces ten events on a chrome-extension:// origin, which cluster happily into a thread about, essentially, looking at your threads.

This is circular and useless, and because you tend to open the dashboard often while the rest of your browsing is quieter, this self-thread can score deceptively high on recency and session count.

The second problem is local development infrastructure. If you're building the extension, or any local project, your history fills with localhost:5173, 127.0.0.1:8080, and maybe LAN addresses like 192.168.1.40. These are real page visits as far as Chrome is concerned, but they carry no browsing intent in the sense openloops cares about. Worse, they'd later be sent to context.dev during brand enrichment, where they can never resolve to anything and would only waste API credits.

Both problems share a root cause: the pipeline is capturing URLs that aren't really part of your browsing in the first place. The fix is to define what counts as a real, external web page once, and apply that definition everywhere a URL or domain enters the system.

One Definition, Applied Everywhere

The two helpers that do this, isHttpUrl and isLocalHost, were written back when you first built src/lib/util.ts. We deliberately introduced them early for exactly this moment.

isHttpUrl returns true only for http:// and https:// URLs, which excludes chrome-extension://, chrome://, about:, and file:// in one stroke. isLocalHost returns true for localhost, loopback and private IP ranges, and .local hostnames.

The thing that makes them effective is consistency: the same two functions guard every entry point, so the definition of "a real page" can never drift between one part of the pipeline and another. There are three such entry points.

Live capture, in src/background.ts, calls isHttpUrl before recording anything:

if (!isHttpUrl(url)) return;

The backfill, in src/pipeline/backfill.ts, applies the same guard to every history item before fetching its visits:

if (!item.url) return [];
if (!isHttpUrl(item.url)) return [];

And the noise filter, in src/pipeline/noise.ts, checks both helpers at the very top of isNoise, before any of its domain or title rules run:

export function isNoise(event: RawEvent): boolean {
  if (!isHttpUrl(event.url)) return true;
  if (isLocalHost(event.domain)) return true;
  return domainIsBlocked(event.domain) || titleIsGeneric(event.title, event.domain);
}

Capture and backfill already screen out non-web URLs, so checking isHttpUrl a third time inside isNoise looks redundant, and in normal operation it is. The third check is a guarantee: if a stray non-web event ever reaches raw_events through some path you didn't anticipate (like a future capture mechanism, imported data, or a bug), it still can't survive into a session.

Each stage defends its own input rather than trusting that an earlier stage did its job. This is what keeps a single missed case from silently propagating all the way into the intent map.

Defending the Enrichment Boundary Too

The same isLocalHost check appears once more, in the brand enrichment step you'll build next, where domains get sent to context.dev. Even though isNoise already strips local addresses before sessionization, the enrichment function filters them again before making any network call:

const unique = [...new Set(domains)].filter((d) => !isLocalHost(d));

The reasoning is the same defense-in-depth idea, applied to a boundary where the cost of a mistake is higher. A local address that somehow reached a thread's domain list shouldn't just be useless noise in the UI. It should never leave your machine as part of an API request. Putting the filter directly at the network boundary means that guarantee holds regardless of what happened upstream.

Checkpoint

After loading the updated build, openloops should stop appearing in its own intent map. To verify, open the dashboard a handful of times, browse some real pages, then rebuild the pipeline: the chrome-extension:// self-thread should be gone, and no localhost or private-IP domains should appear in any thread's domain list.

If you inspect raw_events in DevTools, you may still see live-captured events from before this fix, since the backfill clears and rewrites events but live capture appends. Running a fresh "Scan my history" wipes and repopulates raw_events cleanly under the new rules.

With the pipeline now producing a clean intent map of genuinely external browsing, it's worth making those threads more legible.

Up to now, each thread's title is just its top three keywords stitched together, and there's no summary or suggested next step at all. The next section adds the first optional, key-gated layer: AI labeling with Claude.

How to Label Threads with Claude

A thread titled "Typescript Generics Handbook" is readable, but it's a description of the keywords – not of what you were trying to do. "Learning TypeScript's advanced type system" is the kind of label a person would actually write, and the difference between those two is the gap this section closes.

Claude reads each thread's keywords, domains, and sample page titles, and returns a real title, a one-sentence summary, a classification, and a concrete next step.

This is the first part of openloops that calls an external API and requires a key. Everything about its design is shaped by one constraint: the request has to survive real data, where a person might have thirty or forty threads, each carrying a dozen page titles.

The naïve version of this is to send all the threads in one request and ask for all the labels back. And that's exactly what the first implementation did. But it failed in a way worth walking through, because the fix is the most instructive part of the whole section.

Storing Keys Locally

Before any API call, the key needs somewhere to live. openloops keeps it in chrome.storage.local, which never syncs anywhere and never leaves the device. Create src/lib/settings.ts:

export async function getApiKey(): Promise {
  const result = await chrome.storage.local.get("anthropicApiKey");
  return (result.anthropicApiKey as string) ?? null;
}

export async function setApiKey(key: string): Promise {
  await chrome.storage.local.set({ anthropicApiKey: key });
}

The same file later grows parallel getters and setters for the context.dev key and the assistant's model and effort preferences, all following this identical shape. So it's enough to understand this one pair to understand all of them.

The First Version, and How it Broke

The first labeling implementation sent every thread to Claude in a single request: serialize all forty threads into one JSON payload, ask for a JSON array of forty labels in return, parse it, write it back. It worked perfectly with five or six threads during early testing, then silently produced nothing once a real history with thirty-plus threads went through it. There was no error or thrown exception, just threads that kept their old keyword titles as if the labeling had never run.

The cause was output token truncation. A request specifies max_tokens, the ceiling on how much the model may generate in response, and forty threads' worth of titles, summaries, and next steps is a lot of output. When the response hit that ceiling mid-generation, the JSON array was cut off partway through an opening [ and thirty complete objects followed by half of the thirty-first and no closing ]. JSON.parse on that throws, the catch block logged it and returned nothing, and because labeling was designed to fail gracefully and leave existing titles intact, the failure was invisible from the UI.

Two design changes came out of this, and both are in the final code: split the work into small batches so no single response can grow large enough to truncate, and make the parsing resilient enough that one bad batch can't take down the whole run.

Batching the Requests

Create src/pipeline/label.ts, starting with the per-batch request function:

import { getAllThreads, putThreads, getAllBrands } from "../db/index";
import type { IntentThread } from "../types";

interface ThreadDescriptor {
  id: string;
  keywords: string[];
  domains: string[];
  sampleTitles: string[];
  domainContext: string[];
}

interface LabelResult {
  id: string;
  title: string;
  summary: string;
  type: string;
  nextStep: string;
}

const VALID_TYPES: ReadonlySet = new Set([
  "buying",
  "research",
  "learning",
  "planning",
  "unclassified",
]);

const BATCH_SIZE = 10;
const MAX_TOKENS_PER_BATCH = 4000;

async function callClaudeBatch(
  apiKey: string,
  systemPrompt: string,
  batch: ThreadDescriptor[],
): Promise {
  const response = await fetch("https://api.anthropic.com/v1/messages", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": apiKey,
      "anthropic-version": "2023-06-01",
      "anthropic-dangerous-direct-browser-access": "true",
    },
    body: JSON.stringify({
      model: "claude-haiku-4-5-20251001",
      max_tokens: MAX_TOKENS_PER_BATCH,
      system: systemPrompt,
      messages: [
        {
          role: "user",
          content: JSON.stringify(batch),
        },
      ],
    }),
  });

  if (!response.ok) {
    let body = "";
    try { body = (await response.text()).slice(0, 400); } catch { }
    console.error(
      `[openloops] label: API request failed\n` +
      `  → HTTP \({response.status} \){response.statusText}\n` +
      `  body: ${body || "(empty)"}`,
    );
    if (response.status === 401) {
      throw new Error("Invalid API key. Check your Anthropic API key and try again.");
    }
    throw new Error(`API request failed: \({response.status} \){response.statusText}`);
  }

  const data = await response.json();
  const raw: string = data.content[0].text;

  const cleaned = raw
    .trim()
    .replace(/^```(?:json)?\s*/, "")
    .replace(/```\s*$/, "")
    .trim();

  try {
    return JSON.parse(cleaned);
  } catch (err) {
    console.error(`[openloops] label: parse error: ${err instanceof Error ? err.message : String(err)}`);
    console.error(`[openloops] label: raw tail (last 400 chars):\n${raw.slice(-400)}`);
    return null;
  }
}

BATCH_SIZE of 10 with MAX_TOKENS_PER_BATCH of 4000 is the direct answer to the truncation problem. Ten threads' worth of labels comfortably fits inside 4000 output tokens with room to spare, so a batch can't hit the ceiling and get cut off. A history with forty threads becomes four independent requests rather than one oversized one.

The request itself uses raw fetch rather than Anthropic's TypeScript SDK, because the SDK isn't built to run in a browser or extension context.

Browser-originated calls to the Anthropic API also require the anthropic-dangerous-direct-browser-access header, which is what opts into this usage pattern. The model is Claude Haiku, the fastest and cheapest in the lineup, which is well-matched to a high-volume, structured-output task like this one where you're making several calls and want them quick.

The error handling splits into two deliberately different behaviors. An HTTP-level failure (a 401 from a bad key, a 429 from rate limiting) throws, because every subsequent batch would fail the same way and there's no point continuing. A parse failure, by contrast, returns null rather than throwing, so the caller can skip just that one batch and keep going with the rest.

The fence-stripping before JSON.parse handles a common real-world wrinkle: models sometimes wrap JSON output in a Markdown code fence (```json), even when asked for raw JSON. The two .replace calls strip a leading fence and a trailing fence if present, tolerating surrounding whitespace, so a response comes through whether or not it arrived wrapped.

When parsing still fails, the catch logs the last 400 characters of the raw response, which is precisely where you'd see the truncation signature of a cut-off array, the diagnostic that would have made the original bug obvious in minutes.

Building the Prompt and Merging Results

The public labelThreads function builds the descriptors, runs the batches, and merges what comes back:

export async function labelThreads(apiKey: string): Promise<{ labeled: number }> {
  const threads = await getAllThreads();
  if (threads.length === 0) return { labeled: 0 };

  const allBrands = await getAllBrands();
  const brandMap = new Map(allBrands.map((b) => [b.domain, b]));

  const descriptors: ThreadDescriptor[] = threads.map((t) => {
    const keywords = [...new Set(t.sessions.flatMap((s) => s.keywords))].slice(0, 8);
    const domains  = [...new Set(t.sessions.flatMap((s) => s.domains))].slice(0, 5);
    const titles   = [...new Set(t.sessions.flatMap((s) => s.events.map((e) => e.title)))].slice(0, 20);

    const domainContext = domains
      .map((d) => {
        const brand = brandMap.get(d);
        if (!brand || !brand.name) return null;
        let line = `\({d}: \){brand.name}`;
        if (brand.description) line += ` — ${brand.description}`;
        if (brand.industry)    line += ` (${brand.industry})`;
        return line;
      })
      .filter((s): s is string => s !== null);

    return { id: t.id, keywords, domains, sampleTitles: titles, domainContext };
  });

  const systemPrompt = `You label browsing intent threads. Return ONLY a JSON array — no markdown fences, no explanation.
Each element: { "id": "", "title": "<3-6 word title>", "summary": "<1 sentence>", "type": "", "nextStep": "" }
The nextStep must be grounded in what the person was actually looking at. Be specific — name the actual decision, comparison, or action (e.g. "Decide between MacBook Pro and Dell XPS — your open question was battery life") rather than generic advice ("continue researching"). Use the sampleTitles and domainContext to ground it.
Each thread descriptor may include a "domainContext" array of company descriptions for the sites visited. When present, use these to produce sharper, more specific titles, summaries, and next steps grounded in what each company actually does.
Respond with exactly one array covering every thread in the request.`;

  const allResults: LabelResult[] = [];
  let failedBatches = 0;
  for (let i = 0; i < descriptors.length; i += BATCH_SIZE) {
    const batch = descriptors.slice(i, i + BATCH_SIZE);
    const results = await callClaudeBatch(apiKey, systemPrompt, batch);
    if (results === null) {
      failedBatches++;
      continue;
    }
    allResults.push(...results);
  }

  const byId = new Map(allResults.map((r) => [r.id, r]));

  let labeled = 0;
  const updated = threads.map((t) => {
    const label = byId.get(t.id);
    if (!label) return t;

    const type = VALID_TYPES.has(label.type as IntentThread["type"])
      ? (label.type as IntentThread["type"])
      : t.type;

    labeled++;
    return {
      ...t,
      title:    label.title    || t.title,
      summary:  label.summary  || undefined,
      nextStep: label.nextStep || undefined,
      type,
    };
  });

  await putThreads(updated);
  return { labeled };
}

Each thread is compressed into a ThreadDescriptor carrying only what Claude needs to label it: up to eight keywords, five domains, and twenty sample page titles, capped so a thread with hundreds of events doesn't bloat the payload.

The domainContext field is the hook for the brand-grounding step covered in the next section. It's empty for now since no brands have been fetched yet, which is exactly why labeling works fine on its own and gets sharper once grounding is added.

The merge step is where a failed batch costs you only its own threads. Results come back as a flat list across all successful batches, indexed by thread id into byId.

Then every thread is walked: if a label came back for it, the AI title, summary, next step, and type are merged in, with the returned type validated against VALID_TYPES and falling back to the heuristic type if the model returned something unexpected. If no label came back, because that thread's batch failed to parse, the thread is returned untouched, keeping the keyword title and heuristic classification it already had.

A single failed batch costs you ten threads' worth of polish, not the entire run, and never corrupts a thread with malformed data.

Notice that title, summary, and nextStep all guard against empty strings with || t.title and || undefined. A thread always has a usable title even if the model returned a blank one, and summary and nextStep stay undefined rather than becoming empty strings. This keeps the dashboard's "does this thread have a summary?" checks honest.

Checkpoint

Labeling needs a key and a button, both of which arrive with the dashboard later in this guide, so a full end-to-end test waits until then.

What you can verify now is that src/lib/settings.ts and src/pipeline/label.ts compile, and that the request shape is correct by calling labelThreads with a real key from a temporary test harness if you want immediate feedback. When it runs against built threads, the console will show batch progress, and your threads' titles in IndexedDB will change from keyword fragments to readable phrases, with summary and nextStep fields appearing for the first time.

The labels are already a large improvement, but they're working from keywords and bare domain names. This means a thread built around mastra.ai and langchain.com has no idea those are AI agent frameworks. It only sees two domain strings.

The next section closes that gap by resolving domains into real company descriptions before labeling. This is the grounding step that gives the AI something concrete to reason about.

How to Ground Labels with context.dev

This is the most distinctive idea in openloops, so it's worth stating plainly before any code: instead of asking the model to label a thread from keywords and bare domain names, openloops first resolves each domain into a real company description – what the company is, what industry it's in, what it actually does – and feeds those descriptions into the labeling prompt. The model labels the thread knowing that mastra.ai and langchain.com are both AI agent frameworks, rather than seeing two opaque strings it has to guess about.

A thread whose keywords are "mastra langchain sholajegede" produces, ungrounded, a title like "Mastra Langchain Sholajegede", a literal echo of the keywords. Grounded with the knowledge that those domains are competing agent frameworks, the same thread becomes "Benchmarking Mastra against LangChain", a title that names the actual intent.

The raw material for a good label was always there in the browsing. What was missing was the context to interpret it, and that context is exactly what a brand-intelligence API provides.

What the API Returns

openloops uses context.dev, which resolves a domain into a structured brand record: company name, a one-line description, industry classification, brand colors, and logo URLs. The grounding step needs the name, description, and industry, while the logo and colors get used later by the dashboard to render domain chips.

This step is entirely optional: the labeling from the previous section works without it, and grounding simply makes the output sharper when a context.dev key is present.

Like the Anthropic key, the context.dev key lives in chrome.storage.local, via the same getter/setter pattern in src/lib/settings.ts:

export async function getContextKey(): Promise {
  const result = await chrome.storage.local.get("contextDevApiKey");
  return (result.contextDevApiKey as string) ?? null;
}

export async function setContextKey(key: string): Promise {
  await chrome.storage.local.set({ contextDevApiKey: key });
}

Brand records also need a place to be cached, since resolving the same domain twice is wasteful and costs API credits. Bump DB_VERSION to 4 and add a domain_brands store keyed by domain:

import type { RawEvent, Session, IntentThread, Brand } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: { key: string; value: RawEvent; indexes: { by_visitedAt: number } };
  sessions: { key: string; value: Session; indexes: { by_startedAt: number } };
  intent_threads: { key: string; value: IntentThread; indexes: { by_lastSeen: number } };
  domain_brands: {
    key: string;
    value: Brand;
  };
}

const DB_VERSION = 4;

Inside the upgrade callback, the new store is added with the same guard as the others, and domain_brands is keyed on domain rather than id because a domain is its own natural unique key:

if (!db.objectStoreNames.contains("domain_brands")) {
  db.createObjectStore("domain_brands", { keyPath: "domain" });
}

The matching helpers add one that's specific to caching, getCachedDomains. This returns the set of domains already resolved so the enrichment step can skip them:

export async function getBrand(domain: string): Promise {
  const db = await getDB();
  return db.get("domain_brands", domain);
}

export async function putBrands(brands: Brand[]): Promise {
  if (brands.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("domain_brands", "readwrite");
  await Promise.all([...brands.map((b) => tx.store.put(b)), tx.done]);
}

export async function getAllBrands(): Promise {
  const db = await getDB();
  return db.getAll("domain_brands");
}

export async function getCachedDomains(): Promise> {
  const db = await getDB();
  const keys = await db.getAllKeys("domain_brands");
  return new Set(keys);
}

Fetching One Brand

Create src/pipeline/enrich.ts. The core is a function that resolves a single domain, and most of its length is there to make sure a slow or failing lookup can never hang or crash the whole step:

import { getCachedDomains, putBrands } from "../db/index";
import { isLocalHost } from "../lib/util";
import type { Brand } from "../types";

const API_BASE        = "https://api.context.dev/v1";
const LOGO_LINK_BASE  = "https://logos.context.dev";

const REQUEST_TIMEOUT_MS = 15_000;
const BATCH_SIZE     = 3;
const BATCH_DELAY_MS = 2_000;

interface FetchResult {
  brand: Brand | null;
  errorCode?: string;
}

async function fetchBrand(domain: string, contextKey: string): Promise {
  const url = `\({API_BASE}/brand/retrieve?domain=\){encodeURIComponent(domain)}`;
  const headers = { Authorization: `Bearer ${contextKey}` };

  async function attempt(): Promise {
    const ctrl = new AbortController();
    const tid  = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
    try {
      return await fetch(url, { headers, signal: ctrl.signal });
    } finally {
      clearTimeout(tid);
    }
  }

  try {
    let res = await attempt();

    if (res.status === 408) {
      res = await attempt();
    }

    if (!res.ok) {
      let body = "";
      try { body = (await res.text()).slice(0, 400); } catch { }
      console.error(`[openloops] enrich: HTTP \({res.status} for "\){domain}" — ${body}`);
      return { brand: null, errorCode: String(res.status) };
    }

    let data: { status?: string; brand?: Record };
    try {
      data = await res.json();
    } catch (e) {
      return { brand: null, errorCode: "parse" };
    }

    if (data.status !== "ok" || !data.brand) {
      return { brand: null, errorCode: "shape" };
    }

    const b = data.brand as {
      title?:        string;
      description?:  string;
      colors?:       { hex?: string }[];
      logos?:        { url?: string }[];
      industries?:   { eic?: { industry?: string; subindustry?: string }[] };
    };

    const logoUrl =
      b.logos?.[0]?.url ||
      `\({LOGO_LINK_BASE}?domain=\){encodeURIComponent(domain)}`;

    return {
      brand: {
        domain,
        name:        b.title                          ?? domain,
        description: b.description                    ?? "",
        industry:    b.industries?.eic?.[0]?.industry ?? "",
        logoUrl,
        brandColor:  b.colors?.[0]?.hex               ?? "",
      },
    };

  } catch (err) {
    if (err instanceof Error && err.name === "AbortError") {
      return { brand: null, errorCode: "timeout" };
    }
    return { brand: null, errorCode: "network" };
  }
}

The request authenticates with a bearer token and hits a single brand/retrieve endpoint. The attempt inner function wraps each call in an AbortController with a 15-second timeout, so a stalled connection aborts itself rather than hanging the enrichment step indefinitely.

The finally clears the timer whether the request succeeds, fails, or aborts. A 408 response from context.dev means a cold cache miss on their side, which their documentation says to retry once, so a single retry handles it before giving up.

The response is unpacked defensively at every level: a non-OK status returns a FetchResult with the HTTP code, a body that won't parse returns a "parse" error, and a response whose shape isn't what's expected returns a "shape" error.

When the brand record does come through, each field falls back to a sensible default if absent, the company name falls back to the domain itself, the description and industry to empty strings, and the logo to context.dev's keyless logo CDN if the record carries no logo URL.

Every failure path returns { brand: null, errorCode } rather than throwing, which is what lets the batch driver above it treat a single domain's failure as a skip rather than a crash.

Enriching Domains in Batches

The public enrichDomains function resolves a list of domains, skipping ones already cached and respecting the API's rate limit:

export async function enrichDomains(
  contextKey: string,
  domains: string[],
): Promise<{ enriched: number; failed: number; error?: string }> {
  const unique = [...new Set(domains)].filter((d) => !isLocalHost(d));

  let cached: Set;
  try {
    cached = await getCachedDomains();
  } catch (err) {
    return { enriched: 0, failed: 0, error: "DB error" };
  }

  const toFetch = unique.filter((d) => !cached.has(d));
  if (toFetch.length === 0) return { enriched: 0, failed: 0 };

  let enriched = 0;
  let failed   = 0;
  let firstErrorCode: string | undefined;

  for (let i = 0; i < toFetch.length; i += BATCH_SIZE) {
    const batch   = toFetch.slice(i, i + BATCH_SIZE);
    const results = await Promise.all(batch.map((d) => fetchBrand(d, contextKey)));

    const brands = results.map((r) => r.brand).filter((b): b is Brand => b !== null);

    for (const r of results) {
      if (!r.brand) {
        failed += 1;
        if (!firstErrorCode) firstErrorCode = r.errorCode;
      }
    }

    if (brands.length > 0) {
      try {
        await putBrands(brands);
        enriched += brands.length;
      } catch (err) {
        failed += brands.length;
      }
    }

    if (i + BATCH_SIZE < toFetch.length) {
      await new Promise((resolve) => setTimeout(resolve, BATCH_DELAY_MS));
    }
  }

  let error: string | undefined;
  if (firstErrorCode) {
    const map: Record = {
      "401":     "401 — invalid key",
      "403":     "403 — check key permissions",
      "429":     "429 — rate limited, try again later",
      "timeout": "request timeout (15 s)",
      "network": "unreachable — check network/CORS",
    };
    error = map[firstErrorCode] ?? firstErrorCode;
  }

  return { enriched, failed, error };
}

The function opens by stripping local addresses with isLocalHost, the enrichment-boundary guard discussed in the self-referential noise section. This means that a dev server can never be sent to context.dev even if it slipped into a thread's domain list. It then removes already-cached domains via getCachedDomains, so re-running enrichment only ever fetches domains it hasn't seen. This keeps credit usage proportional to new browsing rather than total browsing.

The remaining domains are fetched three at a time, with a two-second pause between batches. This keeps the request rate well under the API's limit without making the user wait through a long serial queue.

Failures are tallied rather than thrown: a domain that fails to resolve increments failed and records its error code, but the loop carries on. The first error code encountered gets mapped to a human-readable message at the end so the UI can show something useful, such as an invalid-key or rate-limit notice.

The whole function returns counts rather than raising, which matters because the dashboard runs enrichment immediately before labeling, and a problem fetching brands should never prevent the labeling that follows it.

How Grounding Feeds Back into Labeling

Grounding connects back to labelThreads from the previous section, which already builds a domainContext array for each thread by looking up every domain in the brand cache:

const domainContext = domains
  .map((d) => {
    const brand = brandMap.get(d);
    if (!brand || !brand.name) return null;
    let line = `\({d}: \){brand.name}`;
    if (brand.description) line += ` — ${brand.description}`;
    if (brand.industry)    line += ` (${brand.industry})`;
    return line;
  })
  .filter((s): s is string => s !== null);

Before enrichment runs, the brand cache is empty, every lookup returns nothing, domainContext is an empty array, and the prompt falls back to keywords and domain names alone.

After enrichment, the same code produces lines like mastra.ai: Mastra — TypeScript framework for building AI agents (Developer Tools), and the labeling prompt's instruction to use domainContext "to produce sharper, more specific titles, summaries, and next steps" finally has something to work with.

The two steps are decoupled by design: labeling never requires grounding, but grounding measurably improves labeling. This is why the dashboard runs them in sequence as a single "enrich, then label" action.

Checkpoint

Like the labeling step, enrichment is exercised through the dashboard, so the full path waits for the dashboard section. For now, confirm that src/pipeline/enrich.ts and the updated src/db/index.ts compile, and that getDB() reports version 4 with domain_brands present in DevTools.

Once it runs against real threads with a context.dev key, the domain_brands store fills with cached records, and your thread labels should noticeably sharpen. The clearest single demonstration will be any thread built around niche or technical domains whose names don't, on their own, reveal what they are.

Every piece of the engine now exists: capture, sessions, clustering, scoring, labeling, and grounding. What's missing is the surface that drives them and shows the results.

The next section builds the dashboard, the three-column React interface with its onboarding flow and pipeline state machine, that turns this pipeline into something a person actually uses.

How to Design the Dashboard

The dashboard is a single React component tree rendered into the full-tab page you wired up at the very start when you set options_page in the manifest.

It does three jobs: it drives the pipeline (the buttons that run scanning, session-building, thread-building, and labeling), it displays the resulting intent map (threads grouped by status), and it hosts the assistant covered in the next section.

This section focuses on the structure and the one piece of genuinely interesting logic: the state machine that decides which pipeline button is live at any moment. We'll treat the styling at a summary level here, since it's mostly conventional CSS.

The Three-Column Layout

src/dashboard/App.tsx lays out three columns inside a flex shell. The left rail holds the pipeline controls, the API-key inputs, and the status filter. The center column is the main content: either the onboarding welcome screen or the intent map of threads. The right column holds overview statistics and the assistant chat.

┌──────────────┬───────────────────────────┬──────────────────┐
│  LEFT RAIL   │       MAIN COLUMN         │  RIGHT COLUMN    │
│              │                           │                  │
│  Pipeline    │  Welcome screen           │  Overview stats  │
│   · Scan     │    — or —                 │                  │
│   · Sessions │  Intent map:              │  Assistant chat  │
│   · Threads  │   ACTIVE   threads        │   · messages     │
│              │   STALLED  threads        │   · composer     │
│  Keys        │   DORMANT  threads        │   · model/effort │
│  Filter      │                           │                  │
└──────────────┴───────────────────────────┴──────────────────┘

Each thread renders as a card showing its title, type and status pills, the AI summary, the next-step row with a Resume button, a confidence bar, and a collapsible details section with domains, keywords, and signals.

The cards are grouped into ACTIVE, STALLED, and DORMANT sections, sorted by confidence within each group. The threads most worth acting on rise to the top of the most urgent group.

The styling lives in src/dashboard/app.css and is conventional: a dark theme defined through CSS custom properties (a near-black background, a single orange accent at --accent: #ff5c33, a small scale of grays for text and borders), a monospace font for labels and metadata, and a sans-serif for content.

The design choices that matter for usability are the status-based color coding (the accent for active, a muted amber for stalled, gray for dormant) and the confidence bar's width mapping directly to the thread's confidence score.

None of the CSS is load-bearing for understanding the build, so rather than reproduce it, the rest of this section focuses on the logic the styling sits on top of.

The Pipeline State Machine

The pipeline has a strict order: you can't build sessions before scanning history, and you can't build threads before building sessions. The dashboard encodes this as a small state machine, and getting it right is what makes the interface feel guided rather than confusing. Every button is either disabled (its input doesn't exist yet), highlighted as the next action to take, or done (re-runnable, but no longer the obvious next step).

type PipelineState = "disabled" | "next" | "done";

function pipelineStates(
  hasScanned: boolean,
  eventCount: number | null,
  sessionCount: number | null,
  threadCount: number | null,
): { scan: PipelineState; sessions: PipelineState; threads: PipelineState } {
  const hasEvents   = (eventCount   ?? 0) > 0;
  const hasSessions = (sessionCount ?? 0) > 0;
  const hasThreads  = (threadCount  ?? 0) > 0;

  if (!hasScanned)  return { scan: "next", sessions: "disabled", threads: "disabled" };
  if (!hasSessions) return { scan: "done", sessions: hasEvents ? "next" : "disabled", threads: "disabled" };
  if (!hasThreads)  return { scan: "done", sessions: "done", threads: "next" };
  return { scan: "done", sessions: "done", threads: "done" };
}

The function reads the presence of data at each stage and returns the state of all three buttons. Before any scan, only Scan is live, marked next, while the other two are disabled.

Once events exist but sessions don't, Scan flips to done and Sessions becomes next. Once sessions exist but threads don't, Threads becomes next. Once all three stages have produced output, everything is done, every step re-runnable but none demanding attention. The cascade walks the pipeline in order and lights up exactly one next action at a time, which is what turns a row of three buttons into a guided sequence.

The first parameter, hasScanned, is more subtle than a simple count. It's where a piece of plumbing from the very first capture section pays off.

The check can't just be "are there any events," because live capture starts populating raw_events the moment the extension is installed. There would always be events, and the onboarding would skip straight past the Scan step before the user had ever scanned.

The fix is the source field on every RawEvent, set to "backfill" or "live" back when you built capture. hasScanned comes from a dedicated query that checks specifically for backfill events:

export async function hasBackfillEvents(): Promise {
  const db = await getDB();
  let cursor = await db.transaction("raw_events", "readonly").store.openCursor();
  while (cursor) {
    if (cursor.value.source === "backfill") return true;
    cursor = await cursor.continue();
  }
  return false;
}

This walks raw_events until it finds a single event with source === "backfill", returning early the moment it does. Live-captured events alone never satisfy it, so "Scan my history" stays lit as the first step until the user actually runs a backfill, which is the correct onboarding behavior. The seemingly minor decision to tag each event with its origin, made several sections ago, is what makes this distinction possible now.

Driving the Welcome Screen from the Same Machine

A first-time user with no threads sees a centered welcome screen instead of an empty intent map. But rather than give that screen its own separate logic, the dashboard drives it from the same pipelineStates output. Whichever step is currently next determines which single call-to-action the welcome screen shows:

let welcomeStep: 1 | 2 | 3 = 1;
let welcomeCtaLabel = "Scan my history";
let welcomeCtaClick = handleScan;
if (scanState === "next") {
  welcomeStep = 1;
  welcomeCtaLabel = scanning ? "Scanning…" : "Scan my history";
  welcomeCtaClick = handleScan;
} else if (sessionsState === "next") {
  welcomeStep = 2;
  welcomeCtaLabel = buildingSessions ? "Building…" : "Build sessions";
  welcomeCtaClick = handleBuildSessions;
} else if (threadsState === "next") {
  welcomeStep = 3;
  welcomeCtaLabel = buildingThreads ? "Building…" : "Build your intent map";
  welcomeCtaClick = handleBuildThreads;
}

The welcome screen's single button always mirrors the rail's next action, so a user can move through scan, build sessions, and build threads by clicking one prominent button three times. The moment threads exist, the welcome screen is replaced by the intent map. The rail and the welcome screen never disagree about what to do next, because both read from the same source of truth.

Wiring the Handlers

The handlers themselves are thin: each runs a pipeline stage, then refreshes the component's view of the database. The action that runs grounding and labeling together is the one worth seeing, because it puts into practice the decoupling described in the previous two sections:

async function handleEnrichAndLabel() {
  setLabelError(null);
  setEnrichError(null);

  if (contextKey.trim() && contextKeySaved) {
    setEnriching(true);
    try {
      const allDomains = [...new Set(
        threads.flatMap((t) => t.sessions.flatMap((s) => s.domains))
      )];
      const result = await enrichDomains(contextKey.trim(), allDomains);
      if (result.error) setEnrichError(`context.dev: ${result.error}`);
      if (result.enriched > 0) {
        const all = await getAllBrands();
        setBrands(new Map(all.map((b) => [b.domain, b])));
      }
    } catch (err) {
      setEnrichError(`context.dev: ${err instanceof Error ? err.message : "unknown error"}`);
    } finally {
      setEnriching(false);
    }
  }

  setLabeling(true);
  try {
    await labelThreads(apiKey.trim());
    setThreads(await getAllThreads());
  } catch (err) {
    setLabelError(err instanceof Error ? err.message : "Labeling failed.");
  } finally {
    setLabeling(false);
  }
}

Enrichment runs only if a context.dev key is present, and it's wrapped so that any failure (like a network error, a bad key, or a rate limit) sets an error message but never stops execution. Labeling then runs unconditionally afterward, outside the enrichment block, so it proceeds whether enrichment succeeded, failed, or was skipped entirely for lack of a key.

That structure is the decoupling from the grounding section made concrete: grounding improves labeling when it works, and labeling degrades gracefully to keyword-and-domain context when it doesn't.

The enrichment error surfaces in amber rather than red, because it's a warning (labeling still happened) rather than a blocking failure. This is a small UI cue that matches the actual severity of what went wrong.

The Resume Button

One interaction ties the intent map back to live browsing. Each thread card has a Resume button that reopens the pages you were on, so acting on a thread is one click rather than a hunt through history:

const RESUME_SKIP_DOMAINS = new Set([
  "google.com", "youtube.com", "bing.com", "duckduckgo.com",
  "gmail.com", "mail.google.com",
]);

function resumeThread(thread: IntentThread): void {
  const seen = new Set();
  const urls: string[] = [];

  const sorted = thread.sessions
    .flatMap((s) => s.events)
    .sort((a, b) => b.visitedAt - a.visitedAt);

  for (const ev of sorted) {
    if (RESUME_SKIP_DOMAINS.has(ev.domain)) continue;
    if (seen.has(ev.url)) continue;
    seen.add(ev.url);
    urls.push(ev.url);
    if (urls.length >= 3) break;
  }

  urls.forEach((url, i) => {
    chrome.tabs.create({ url, active: i === 0 });
  });
}

Resume sorts the thread's events newest-first, skips search engines and webmail (which are waypoints rather than destinations you'd want to return to), dedupes by URL, and opens the three most recent meaningful pages. The first is the active tab and the rest are in the background. It's a small feature, but it's the thing that makes a thread feel like a place you can return to rather than a record of where you've been.

Checkpoint

With the dashboard wired up, the entire pipeline is finally usable end to end through the interface. Reload the extension, open the dashboard, and you should see the welcome screen prompting you to scan.

Click through scan, build sessions, build your intent map, and the threads should appear, grouped by status. Add an Anthropic key, optionally a context.dev key, and click "Label & enrich" to see titles and next steps sharpen. The full loop you've built across every previous section now runs from a single screen.

What remains is the conversational layer on the right: an AI assistant that can reason across all your threads at once and answer questions like "what should I close this week?" The next section builds it.

How to Build the AI Assistant

The labeling step asks Claude to describe one thread at a time. The assistant asks something harder: to reason across all of your threads together and answer open-ended questions about them, like what to close this week, what you've stalled on longest, or how to finish a particular one.

This is a chat interface, but a constrained one – grounded entirely in your own thread data, so its answers reference real threads by name rather than offering generic productivity advice.

The whole design rests on one idea: a chat assistant is only as good as the context it's given. So most of the work here is in building the right grounding context for each message, not in the chat mechanics themselves.

Grounding the Conversation

Before any message goes to Claude, the assistant assembles a system prompt describing the user's threads. It does this in one of two modes, depending on whether the user has clicked into a specific thread.

With no thread selected, it builds a compact digest of every thread. With one selected, it gives rich detail on that thread and a brief list of the others.

function buildGroundingContext(
  threads: IntentThread[],
  brands: Map,
  selectedThread: IntentThread | null,
): string {
  if (!selectedThread) {
    const digest = threads
      .map((t) => {
        const domains = [...new Set(t.sessions.flatMap((s) => s.domains))].slice(0, 5).join(", ");
        return `- \({t.title} (\){t.status}, \({t.type}): \){t.summary ?? "no summary yet"} | next: \({t.nextStep ?? "none"} | domains: \){domains || "none"}`;
      })
      .join("\n");

    return `\({SYSTEM_INSTRUCTION}\n\nHere is a digest of all the user's open intent threads:\n\){digest || "(no threads yet)"}`;
  }

  const keywords = [...new Set(selectedThread.sessions.flatMap((s) => s.keywords))].slice(0, 10).join(", ");
  const domains = [...new Set(selectedThread.sessions.flatMap((s) => s.domains))].slice(0, 5);

  const domainLines = domains
    .map((d) => {
      const brand = brands.get(d);
      if (brand?.description) return `- \({d}: \){brand.name} — ${brand.description}`;
      return `- ${d}`;
    })
    .join("\n");

  const sampleTitles = [...new Set(selectedThread.sessions.flatMap((s) => s.events.map((e) => e.title)))]
    .slice(0, 20)
    .map((t) => `- ${t}`)
    .join("\n");

  const otherTitles = threads
    .filter((t) => t.id !== selectedThread.id)
    .map((t) => t.title)
    .join(", ");

  return `${SYSTEM_INSTRUCTION}

The user is focused on this thread:
Title: ${selectedThread.title}
Status: ${selectedThread.status}
Type: ${selectedThread.type}
Summary: ${selectedThread.summary ?? "none"}
Next step: ${selectedThread.nextStep ?? "none"}
Keywords: ${keywords || "none"}

Domains visited:
${domainLines || "(none)"}

Recent page titles:
${sampleTitles || "(none)"}

For context, the user's other open threads are: ${otherTitles || "none"}.`;
}

The two modes match the two kinds of questions people ask. A question like "what should I close this week?" is about the whole set, so the digest mode gives Claude a one-line summary of every thread. This is enough breadth to compare and prioritize across all of them.

A question like "how do I finish this one?", on the other hand, is about a single thread, so the focused mode trades breadth for depth. It hands over that thread's keywords, its domains with their brand descriptions, and up to twenty real page titles, while still naming the other threads so Claude knows what else is in play.

The focused mode is where brand grounding shows up again. The same brand records fetched during enrichment get woven into the domain list, so when the user asks about a thread, Claude sees mastra.ai: Mastra — TypeScript framework for building AI agents rather than a bare domain. This is the identical grounding principle from labeling, now applied to conversation.

The system instruction that prefixes both modes pins the assistant to its data:

const SYSTEM_INSTRUCTION =
  `You are the assistant inside "openloops", a browser extension that reconstructs ` +
  `the user's browsing history into "intent threads" — decisions, research, or ` +
  `plans they started and haven't closed. Help the user understand and act on ` +
  `these open loops. Be concrete: reference the actual threads by name and ` +
  `suggest real next actions. You are grounded only in the thread data provided ` +
  `below — if the user asks about something not present in it, say so plainly ` +
  `rather than guessing.`;

The final instruction is the important one: telling the model to admit when something isn't in its data, rather than inventing a plausible answer, is what keeps the assistant trustworthy when a user asks about a thread that doesn't exist or a detail the data doesn't contain.

Sending a Message

The send function rebuilds the grounding context fresh on every message. The assistant always reflects the current state of the threads (including any that changed since the conversation started) and posts the whole message history to Claude:

async function send(text: string) {
  const trimmed = text.trim();
  if (!trimmed || sending) return;

  if (!keySaved) {
    setError("Add your Anthropic key above to chat.");
    return;
  }

  setError(null);
  const nextMessages: Message[] = [...messages, { role: "user", content: trimmed }];
  setMessages(nextMessages);
  setInput("");
  setSending(true);

  try {
    const systemPrompt = buildGroundingContext(threads, brands, selectedThread);
    const maxTokens = EFFORT_OPTIONS.find((e) => e.id === effort)?.maxTokens ?? 1024;

    const response = await fetch("https://api.anthropic.com/v1/messages", {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-api-key": apiKey,
        "anthropic-version": "2023-06-01",
        "anthropic-dangerous-direct-browser-access": "true",
      },
      body: JSON.stringify({
        model,
        max_tokens: maxTokens,
        system: systemPrompt,
        messages: nextMessages.map((m) => ({ role: m.role, content: m.content })),
      }),
    });

    if (!response.ok) {
      if (response.status === 401) {
        throw new Error("Invalid API key. Check your Anthropic API key and try again.");
      }
      throw new Error(`API request failed: \({response.status} \){response.statusText}`);
    }

    const data: { content: AnthropicContentBlock[] } = await response.json();
    const reply = data.content
      .filter((b) => b.type === "text" && b.text)
      .map((b) => b.text)
      .join("");

    setMessages((prev) => [...prev, { role: "assistant", content: reply || "(empty response)" }]);
  } catch (err) {
    setError(err instanceof Error ? err.message : "Something went wrong.");
  } finally {
    setSending(false);
  }
}

The mechanics mirror the labeling request, the same endpoint, the same browser-access header, and the same 401-aware error handling, since both talk to the same API from the same constrained environment. The user's message gets appended to the running messages array, the full array is sent so the model has the conversation so far, and the assembled grounding context rides along as the system prompt. The reply is extracted by concatenating the text blocks from the response, with a fallback string if the model returned nothing usable.

Rebuilding buildGroundingContext on every send rather than once per conversation is a deliberate choice: if the user re-runs the pipeline or labels their threads mid-conversation, the next message reflects the updated data automatically, with no stale snapshot from when the chat began.

Model and Effort Controls

The assistant exposes two selectors: which model to use and how much depth to allow. Both are persisted to chrome.storage.local through the same settings pattern as the keys:

const MODEL_OPTIONS = [
  { id: "claude-haiku-4-5-20251001", label: "Haiku 4.5 — fastest" },
  { id: "claude-sonnet-4-6",          label: "Sonnet 4.6 — balanced" },
  { id: "claude-opus-4-8",            label: "Opus 4.8 — most capable" },
];

const EFFORT_OPTIONS = [
  { id: "low",    label: "Low",    maxTokens: 512 },
  { id: "medium", label: "Medium", maxTokens: 1024 },
  { id: "high",   label: "High",   maxTokens: 2048 },
];

The model selector spans the speed-versus-capability range: Haiku for quick answers, Opus for harder reasoning over a tangled set of threads. The effort selector maps to max_tokens, controlling how long an answer the model may produce. This is a reasonable proxy for response depth given the Messages API has no dedicated depth control. A user wanting a one-line answer picks Low, while one wanting a reasoned, prioritized plan picks High.

Rendering Replies and the Empty State

The assistant renders Claude's replies as Markdown, since the model naturally formats prioritized lists and step-by-step suggestions with headings and bullets. This would look like raw asterisks and hashes if rendered as plain text. Using react-markdown, the reply component is essentially {m.content} for assistant messages, with user messages rendered as plain text. The accompanying styles target the rendered Markdown elements to match the dashboard's type scale.

Before any conversation starts, the panel shows an empty state with a one-line explanation and a few suggested prompts as clickable chips, "What should I close this week?", "Summarize my open loops", "What have I stalled on longest?". These both demonstrate what the assistant can do and give a one-click way to start.

The suggested prompts shift slightly when a thread is focused, offering "How do I finish this one?" in place of the whole-set summary, matching the focused grounding mode.

A privacy line sits permanently below the composer, stating that chats send thread titles and summaries to Anthropic and nothing else leaves the device. This is the same honest disclosure principle applied throughout, placed where the user will see it before they type.

Checkpoint

With the assistant in place, openloops is feature-complete. Reload, build your intent map, add your Anthropic key, and try the suggested prompts. Ask what to close this week and the assistant should name specific threads and reason about which are easy wins versus which need a real decision. Click into a single thread and ask how to finish it, and the answer should narrow to that thread's specifics.

The conversation reflects your real, current threads, and nothing about it leaves your machine except the thread summaries you can see in the grounding context itself.

The build is done. The final section steps back to look at what you've made: how it compares to the one mainstream attempt at this idea, what the privacy model adds up to, and where you might take it next.

What You've Built, and Where to Take It

You've built a complete system: browsing history flows in through capture, gets cleaned and segmented into sessions, clustered and scored into intent threads, optionally labeled and grounded by AI, and surfaced through a dashboard with a conversational assistant. Every stage runs on your own machine, and the AI layers are optional additions on top of a pipeline that works without them.

If the clustering reminds you of Chrome's old Journeys feature, that's a fair connection. Grouping history by topic instead of by time is the same starting point.

openloops takes it further: every thread carries a confidence score and a status, the AI layer adds labels and a concrete next step, the assistant reasons across threads on demand, and the whole thing is open source and local-first. This means that you can read and change exactly what it does with your data.

What the Privacy Model Adds Up To

Privacy shaped the build at every step, and it's worth collecting what that amounted to in one place. The entire core pipeline, capture through scored threads, runs locally in IndexedDB with no network calls of any kind. Your browsing history – the raw events, the sessions, the threads – never leaves your machine for the parts of the system that work without a key.

The two AI layers are the only paths by which any data leaves the device, and both are opt-in, gated on you providing your own API key. When they run, what they send is deliberately minimal: brand enrichment sends only bare domain names to context.dev, never URLs or page contents, and stripped of any local addresses first. Labeling and the assistant send thread titles, summaries, keywords, and sample page titles to Anthropic, the grounding context you can read directly in the code, and nothing more. Keys themselves live in chrome.storage.local, which never syncs.

Where to Take it Next

The build leaves a few deliberate simplifications that make good exercises.

The most satisfying one builds directly on code you've already written. The domain side has ambient.ts, which drops domains that appear on most of your active days. But the keyword side has no equivalent, so a word that's ubiquitous for you (say typescript, if you're a TypeScript developer) survives in every session's keywords and can nudge unrelated threads together.

The fix is a frequency-based keyword detector that mirrors detectAmbientDomains almost line for line, counting days-per-keyword instead of days-per-domain:

export function detectAmbientKeywords(sessions: Session[]): Set {
  const allEvents = sessions.flatMap((s) => s.events);
  const activeDays = new Set(allEvents.map((e) => new Date(e.visitedAt).toDateString()));
  const totalActiveDays = activeDays.size;
  if (totalActiveDays < MIN_ACTIVE_DAYS) return new Set();

  const keywordDayMap = new Map>();
  for (const session of sessions) {
    const day = new Date(session.startedAt).toDateString();
    for (const kw of session.keywords) {
      if (!keywordDayMap.has(kw)) keywordDayMap.set(kw, new Set());
      keywordDayMap.get(kw)!.add(day);
    }
  }

  const ambient = new Set();
  for (const [kw, days] of keywordDayMap) {
    if (days.size / totalActiveDays >= UBIQUITY_THRESHOLD) ambient.add(kw);
  }
  return ambient;
}

You'd then strip these keywords inside similarity exactly as ambient domains are stripped today, filtering them out of both sessionKeywords and the thread's keywordSet before the Jaccard call.

Two smaller exercises round it out. The session gap, similarity threshold, and ambient ubiquity threshold are all hardcoded constants. Lifting them into a settings panel backed by chrome.storage.local (the same store the API keys already use) would let you tune clustering to your own browsing.

And extractDomain strips only a leading www., so news.bbc.co.uk and bbc.co.uk are treated as different domains. Swapping its hostname logic for a library that uses the Public Suffix List (the canonical list of domain suffixes like .co.uk that browsers use to know where a registrable domain actually ends) would collapse subdomains of the same site correctly.

Since the whole pipeline is local and inspectable, each of these is straightforward to try against your own real data and see the effect immediately.

Wrapping up

openloops turns the flat, chronological record your browser keeps into a map of what you were actually trying to do, and helps you close the loops you left open.

The engineering underneath – time-gap segmentation, weighted Jaccard clustering with ambient-domain correction, heuristic scoring, AI labeling grounded in real company data, and a conversational layer over the result – is the kind of layered system where each stage is simple on its own and the value comes from how they compose.

Resources

Source Code

The complete source is available on GitHub under the MIT license, so you can run it, read it, and reshape it to fit how you browse. If it helped you, consider giving it a star.

Core Documentation

Chrome Extensions: Manifest V3: the extension platform openloops is built on
chrome.history API: the search and getVisits methods the backfill relies on
chrome.tabs API: onUpdated for live capture and create for Resume
chrome.storage API: where API keys and preferences live, locally
Anthropic API reference: the Messages endpoint used for labeling and the assistant

Services used

Anthropic Console: create the API key for AI labeling and the assistant
context.dev documentation: the brand-intelligence API used for grounding
IndexedDB (MDN): the local database every pipeline stage reads and writes

Build tooling

Vite: the build tool and dev server
CRXJS Vite plugin: compiles a Manifest V3 extension with hot reloading
idb: the typed, promise-based IndexedDB wrapper
react-markdown: renders the assistant's Markdown replies

Debugging tools

Chrome extension service worker DevTools: inspect live-capture logs and the pipeline console.table output
The Application → IndexedDB panel in Chrome DevTools: browse raw_events, sessions, intent_threads, and domain_brands directly to verify each stage

How to Avoid Overusing useCallback and useMemo in React

Olaleye Blessing — Wed, 17 Jun 2026 19:22:49 +0000

If you've spent enough time in the React ecosystem, you'll have likely seen codebases where nearly every function is wrapped with useCallback and the computed value is wrapped with useMemo.

The reason behind this is “memoization equals better performance”. But most of the time, this doesn’t really translate to better performance, and it often produces code that's harder to debug.

In this article, you'll learn how to structure your code to avoid overusing useCallback and useMemo.

Prerequisites

You should be comfortable with React hooks and components before reading this tutorial. Familiarity with useState, useEffect, and useRef is assumed. You can read the following freeCodeCamp articles if you need a refresher on useCallback and useMemo:

Prerequisites
What useCallback and useMemo Do
- useMemo
- useCallback
Problem With Memoization
The Problematic Page
- How to Move State Down
- Fix Your Code Before Reaching For These Hooks
When to Use useCallback and useMemo
- Measure Before You Optimize
- Stabilize References for React.memo Children
Conclusion

What `useCallback` and `useMemo` Do

Before moving to how to avoid overusing them, we'll look briefly at what these hooks do.

useMemo

useMemo caches the return value of a function between re-renders. Imagine you have a sorted list of items in a component:

interface Item {
  name: string;
  createdAt: string;
}

function App() {
  // == some other states ==
  // == some other states ==
  const [items, setItems] = useState([]);

  const sortedItems = [...items].sort(
    (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
  );

  return (
    <>
      
        {sortedItems.map((i) => (
          {i.name}
        ))}
      
    
  );
}

React recomputes sortedItems every time the App component re-renders. This means sortedItems will be recalculated anytime there are any state changes in the App component.

React developers often use useMemo to cache values like this.

Wrapping it with useMemo ensures that sortedItems is only calculated when items actually changes:

const sortedItems = useMemo(() => {
  return [...items].sort(
    (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
  );
}, [items]);

useCallback

useCallback caches the function itself. The function below will be recreated every time some states in the component change:

function App() {
  // == some other states ==
  // == some other states ==
  const [userId, setUserId] = useState(0);

  const verifyUser = async () => {
    // update a state to show loading
    console.log("__ Do something with user id __", userId);
    // update a state to remove loading
  };

  return (
    <>
      
    
  );
}

Wrapping it with useCallback keeps the same function reference as long as userId hasn’t changed:

function App() {
  // == some other states ==
  // == some other states ==
  const [userId, setUserId] = useState(0);

  const verifyUser = useCallback(async () => {
    // update a state to show loading
    console.log("__ Do something with user id __", userId);
    // update a state to remove loading
  }, [userId]);

  return (
    <>
      
    
  );
}

Problem With Memoization

Nothing is free in life, and memoization is no exception. Every time you use useCallback or useMemo:

Your app allocates memory to store the cached value and dependency array.
Your component runs a comparison to check if the dependencies have changed

This memoization isn't useful most of the time. Creating a JavaScript function is cheap. Sorting a list of 50 items is cheap. Wrapping these in a memoization hook adds more cost than it prevents. (But keep in mind that if profiling shows sorting is a bottleneck, useMemo is still reasonable there.)

The better approach is to structure your components so that re-renders are less frequent.

The Problematic Page

To see this in action, you'll go through a search page where a parent component manages all the state and logic for the entire page.

To code along, you can clone a simple Next.js project I set up for this:

git clone https://github.com/Olaleye-Blessing/freecodecamp-usecallback-usememo.git

# navigate to the folder
cd freecodecamp-usecallback-usememo

# install the packages
pnpm install

# start development
pnpm dev

The search page consists of the following:

A Header that shows the title of the page.
A Search field that allows user to search for the name of a product
A Filter button that opens a drawer for more filtering.
A Drawer for filtering by country, color, mode, and/or price range.
A Product table that shows the search result

All the child components mentioned above maintain no states and functions. They all derive their states and functions from the SearchPage component.

We won’t be going through the child components. They only render the UIs. They have no logic whatsoever.

The SearchPage component looks like this:

"use client";

import { ChangeEvent, useEffect, useRef, useState } from "react";
import { useQuery } from "@tanstack/react-query";
import {
  fetchColors,
  fetchCountries,
  fetchModes,
  fetchProducts,
} from "./utils";
import { Header } from "./_components/header";
import { FilterDrawer } from "./_components/filter-drawer";
import { ProductTable } from "./_components/products-table";
import { FilterChips } from "./_components/filter-chips";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
import { FilterState, LocalSortField, SortDir, SortField } from "./interfaces";

const DEFAULTS: FilterState = {
  query: "",
  country: "",
  color: "",
  mode: "",
  minPrice: "",
  maxPrice: "",
  sortField: "name",
  sortDir: "asc",
};

export default function SearchPage() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  const [drawerOpen, setDrawerOpen] = useState(false);

  const [localSort, setLocalSort] = useState<{
    field: LocalSortField;
    dir: "asc" | "desc";
  } | null>(null);

  const searchRef = useRef(null);
  const searchTimerRef = useRef | null>(null);

  const filters: FilterState = {
    query: searchParams.get("q") ?? DEFAULTS.query,
    country: searchParams.get("country") ?? DEFAULTS.country,
    color: searchParams.get("color") ?? DEFAULTS.color,
    mode: searchParams.get("mode") ?? DEFAULTS.mode,
    minPrice: searchParams.get("minPrice") ?? DEFAULTS.minPrice,
    maxPrice: searchParams.get("maxPrice") ?? DEFAULTS.maxPrice,
    sortField:
      (searchParams.get("sortField") as SortField) ?? DEFAULTS.sortField,
    sortDir: (searchParams.get("sortDir") as SortDir) ?? DEFAULTS.sortDir,
  };

  const apiFilters = {
    query: filters.query,
    country: filters.country || undefined,
    color: filters.color || undefined,
    mode: filters.mode || undefined,
    minPrice: filters.minPrice ? Number(filters.minPrice) : undefined,
    maxPrice: filters.maxPrice ? Number(filters.maxPrice) : undefined,
    sortField: filters.sortField,
    sortDir: filters.sortDir,
  };

  const productsQuery = useQuery({
    queryKey: ["products", apiFilters],
    queryFn: () => fetchProducts(apiFilters),
  });

  const countriesQuery = useQuery({
    queryKey: ["countries"],
    queryFn: fetchCountries,
    staleTime: Infinity,
  });

  const colorsQuery = useQuery({
    queryKey: ["colors"],
    queryFn: fetchColors,
    staleTime: Infinity,
  });

  const modesQuery = useQuery({
    queryKey: ["modes"],
    queryFn: fetchModes,
    staleTime: Infinity,
  });

  // Updates the filter in the drawer
  const setFilters = (partial: Partial) => {
    const next = new URLSearchParams(searchParams.toString());
    const merged = { ...filters, ...partial };

    const keyMap: Record = {
      query: "q",
      country: "country",
      color: "color",
      mode: "mode",
      minPrice: "minPrice",
      maxPrice: "maxPrice",
      sortField: "sortField",
      sortDir: "sortDir",
    };

    (Object.keys(merged) as (keyof FilterState)[]).forEach((k) => {
      const paramKey = keyMap[k];
      const val = merged[k];
      const def = DEFAULTS[k];
      if (val && val !== def) {
        next.set(paramKey, val);
      } else {
        next.delete(paramKey);
      }
    });

    router.push(`\({pathname}?\){next.toString()}`, { scroll: false });
  };

  const resetFilters = () => {
    router.push(pathname, { scroll: false });
  };

  const handleQueryChange = (e: ChangeEvent) => {
    const val = e.target.value;

    if (searchTimerRef.current) clearTimeout(searchTimerRef.current);

    searchTimerRef.current = setTimeout(() => {
      setFilters({ query: val });
    }, 400);
  };

  const handleClearQuery = () => {
    if (searchRef.current) {
      searchRef.current.value = "";
    }

    setFilters({ query: "" });
  };

  const handleColumnClick = (field: LocalSortField) => {
    setLocalSort((prev) => {
      if (!prev || prev.field !== field) return { field, dir: "asc" };

      if (prev.dir === "asc") return { field, dir: "desc" };

      return null;
    });
  };

  const hasPriceFilter = filters.minPrice || filters.maxPrice;
  const priceLabel = [
    filters.minPrice ? `$${filters.minPrice}` : null,
    filters.maxPrice ? `$${filters.maxPrice}` : null,
  ]
    .filter(Boolean)
    .join(" - ");

  const activeFilterCount = [
    filters.country,
    filters.color,
    filters.mode,
    filters.minPrice,
    filters.maxPrice,
  ].filter(Boolean).length;

  let sortedProducts = [...(productsQuery.data || [])];
  if (localSort) {
    sortedProducts = [...sortedProducts].sort((a, b) => {
      const aVal = a[localSort.field];
      const bVal = b[localSort.field];
      const cmp =
        typeof aVal === "string"
          ? aVal.localeCompare(bVal as string)
          : (aVal as number) - (bVal as number);
      return localSort.dir === "desc" ? -cmp : cmp;
    });
  }

  useEffect(() => {
    return () => {
      if (searchTimerRef.current) clearTimeout(searchTimerRef.current);
    };
  }, []);

  return (
    
       setDrawerOpen((v) => !v)}
        activeFilterCount={activeFilterCount}
        searchRef={searchRef}
        handleChange={handleQueryChange}
      />

       setDrawerOpen(false)}
        filters={filters}
        onChange={setFilters}
        onReset={resetFilters}
        countries={countriesQuery.data ?? []}
        colors={colorsQuery.data ?? []}
        modes={modesQuery.data ?? []}
        activeFilterCount={activeFilterCount}
      />

      
        {activeFilterCount > 0 && (
          
        )}

        
      
    
  );
}

The SearchPage component keeps track of all the logic needed to render the page:

It fetches the products, countries, colors, and modes. It passes the countries, colors and modes to the drawer component
It keeps track of the drawer state.
It defines the functions needed to sort the product locally, and so on.

The problem here is that a change in any of the states will lead to recreating all the functions in SearchPage component. For example, when isLoading in the useQuery of products (productsQuery) changes from false to true, all our functions and derived values will be recreated.

The first thing that might come to mind is caching functions and derived values using useCallback and useMemo. While this will work, it will add unnecessary performance overhead to this page.

A better solution is to move state and logic closer to where they are actually used.

How to Move State Down

The idea is this: if only one component needs a piece of state or a function, that component should own it. When a child component manages its own state, changes to that state don't re-render the parent. This means all the sibling components’ states and functions stay stable without any memoization.

That said, don’t move logic so far down that shared behavior becomes harder to test or coordinate. The goal isn't to hide every piece of logic inside the deepest possible component. The goal is to place state and logic at the lowest level where they still make sense for the feature.

Move ProductTable Logic to Its Component

Looking at how products are fetched and sorted, you'll notice that the only component that uses this data is ProductsTable. This means we can move the fetching and sorting logic to the ProductsTable.

The ProductsComponent currently receives its states and logic as props:

"use client";

interface ProductTableProps {
  products: Product[];
  isLoading: boolean;
  handleColumnClick: (field: LocalSortField) => void;
  localSort: { field: LocalSortField; dir: SortDir } | null;
}

export function ProductTable({
  products,
  isLoading,
  handleColumnClick,
  localSort,
}: ProductTableProps) {
  // renders the UI using the props
}

Now, ProductTable will fetch and manage its logic:

interface ProductTableProps {
  filters: FilterState;
}

export function ProductTable({ filters }: ProductTableProps) {
  const [localSort, setLocalSort] = useState<{
    field: LocalSortField;
    dir: "asc" | "desc";
  } | null>(null);

  const apiFilters = {
    query: filters.query,
    country: filters.country || undefined,
    color: filters.color || undefined,
    mode: filters.mode || undefined,
    minPrice: filters.minPrice ? Number(filters.minPrice) : undefined,
    maxPrice: filters.maxPrice ? Number(filters.maxPrice) : undefined,
    sortField: filters.sortField,
    sortDir: filters.sortDir,
  };

  const { data: products = [], isLoading } = useQuery({
    queryKey: ["products", apiFilters],
    queryFn: () => fetchProducts(apiFilters),
  });

  const handleColumnClick = (field: LocalSortField) => {
    setLocalSort((prev) => {
      if (!prev || prev.field !== field) return { field, dir: "asc" };
      if (prev.dir === "asc") return { field, dir: "desc" };

      return null;
    });
  };

  let sortedProducts = products;
  if (localSort) {
    sortedProducts = [...products].sort((a, b) => {
      const aVal = a[localSort.field];
      const bVal = b[localSort.field];
      const cmp =
        typeof aVal === "string"
          ? aVal.localeCompare(bVal as string)
          : (aVal as number) - (bVal as number);
      return localSort.dir === "desc" ? -cmp : cmp;
    });
  }

  return <>{/*== renders the UI using the props ==*/};
}

Now when isLoading changes, the SearchPage component won’t re-render. This means the derived values and other functions in the SearchPage component won’t be recreated. The only value and function that will be recreated here are the sortedProducts and handleColumnClick.

The SearchPage component becomes this:

"use client";

import { ChangeEvent, useEffect, useRef, useState } from "react";
import { useQuery } from "@tanstack/react-query";
import { fetchColors, fetchCountries, fetchModes } from "./utils";
import { Header } from "./_components/header";
import { FilterDrawer } from "./_components/filter-drawer";
import { ProductTable } from "./_components/products-table";
import { FilterChips } from "./_components/filter-chips";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
import { FilterState, SortDir, SortField } from "./interfaces";

const DEFAULTS: FilterState = {
  query: "",
  country: "",
  color: "",
  mode: "",
  minPrice: "",
  maxPrice: "",
  sortField: "name",
  sortDir: "asc",
};

export default function SearchPage() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  const [drawerOpen, setDrawerOpen] = useState(false);

  const searchRef = useRef(null);
  const searchTimerRef = useRef | null>(null);

  const filters: FilterState = {
    query: searchParams.get("q") ?? DEFAULTS.query,
    country: searchParams.get("country") ?? DEFAULTS.country,
    color: searchParams.get("color") ?? DEFAULTS.color,
    mode: searchParams.get("mode") ?? DEFAULTS.mode,
    minPrice: searchParams.get("minPrice") ?? DEFAULTS.minPrice,
    maxPrice: searchParams.get("maxPrice") ?? DEFAULTS.maxPrice,
    sortField:
      (searchParams.get("sortField") as SortField) ?? DEFAULTS.sortField,
    sortDir: (searchParams.get("sortDir") as SortDir) ?? DEFAULTS.sortDir,
  };

  const countriesQuery = useQuery({
    queryKey: ["countries"],
    queryFn: fetchCountries,
    staleTime: Infinity,
  });

  const colorsQuery = useQuery({
    queryKey: ["colors"],
    queryFn: fetchColors,
    staleTime: Infinity,
  });

  const modesQuery = useQuery({
    queryKey: ["modes"],
    queryFn: fetchModes,
    staleTime: Infinity,
  });

  // Updates the filter in the drawer
  const setFilters = (partial: Partial) => {
    const next = new URLSearchParams(searchParams.toString());
    const merged = { ...filters, ...partial };

    const keyMap: Record = {
      query: "q",
      country: "country",
      color: "color",
      mode: "mode",
      minPrice: "minPrice",
      maxPrice: "maxPrice",
      sortField: "sortField",
      sortDir: "sortDir",
    };

    (Object.keys(merged) as (keyof FilterState)[]).forEach((k) => {
      const paramKey = keyMap[k];
      const val = merged[k];
      const def = DEFAULTS[k];
      if (val && val !== def) {
        next.set(paramKey, val);
      } else {
        next.delete(paramKey);
      }
    });

    router.push(`\({pathname}?\){next.toString()}`, { scroll: false });
  };

  const resetFilters = () => {
    router.push(pathname, { scroll: false });
  };

  const handleQueryChange = (e: ChangeEvent) => {
    const val = e.target.value;

    if (searchTimerRef.current) clearTimeout(searchTimerRef.current);

    searchTimerRef.current = setTimeout(() => {
      setFilters({ query: val });
    }, 400);
  };

  const handleClearQuery = () => {
    if (searchRef.current) {
      searchRef.current.value = "";
    }

    setFilters({ query: "" });
  };

  const hasPriceFilter = filters.minPrice || filters.maxPrice;
  const priceLabel = [
    filters.minPrice ? `$${filters.minPrice}` : null,
    filters.maxPrice ? `$${filters.maxPrice}` : null,
  ]
    .filter(Boolean)
    .join(" - ");

  const activeFilterCount = [
    filters.country,
    filters.color,
    filters.mode,
    filters.minPrice,
    filters.maxPrice,
  ].filter(Boolean).length;

  useEffect(() => {
    return () => {
      if (searchTimerRef.current) clearTimeout(searchTimerRef.current);
    };
  }, []);

  return (
    
       setDrawerOpen((v) => !v)}
        activeFilterCount={activeFilterCount}
        searchRef={searchRef}
        handleChange={handleQueryChange}
      />

       setDrawerOpen(false)}
        filters={filters}
        onChange={setFilters}
        onReset={resetFilters}
        countries={countriesQuery.data ?? []}
        colors={colorsQuery.data ?? []}
        modes={modesQuery.data ?? []}
        activeFilterCount={activeFilterCount}
      />

      
        {activeFilterCount > 0 && (
          
        )}

        
      
    
  );
}

The SearchPage component no longer maintains fetching and sorting products data.

Move Filtering Logic To Its Component

We have different states, data, and functions to make this work:

drawerOpen and setDrawerOpen to control the filter drawer.
countries, colors and modes data to allow user to select different options.
activeFilterCount to show the number of active filters.

There are two components for the filtering currently. First is a button inside the Header component that looks like this:

Second is the FilterDrawer component that looks like this:

"use client";

import { useEffect, useRef } from "react";
import { X, RotateCcw } from "lucide-react";
import { FilterState } from "../interfaces";
import { SortSection } from "./filter/sort-section";
import { NarrowResultsSection } from "./filter/narrow-result-section";

interface FilterDrawerProps {
  open: boolean;
  onClose: () => void;
  filters: FilterState;
  onChange: (partial: Partial) => void;
  onReset: () => void;
  countries: string[];
  colors: string[];
  modes: string[];
  activeFilterCount: number;
}

export function FilterDrawer({
  open,
  onClose,
  filters,
  onChange,
  onReset,
  countries,
  colors,
  modes,
  activeFilterCount,
}: FilterDrawerProps) {
  const drawerRef = useRef(null);

  // Close on Escape
  useEffect(() => {
    const handler = (e: KeyboardEvent) => {
      if (e.key === "Escape") onClose();
    };
    document.addEventListener("keydown", handler);
    return () => document.removeEventListener("keydown", handler);
  }, [onClose]);

  // Prevent body scroll while open
  useEffect(() => {
    document.body.style.overflow = open ? "hidden" : "";
    return () => {
      document.body.style.overflow = "";
    };
  }, [open]);

  return (
    <>
      {/* Backdrop */}
      

      {/* Drawer panel */}
      
        {/* Header */}
        
          
            Filters & Sort
            {activeFilterCount > 0 && (
              
                {activeFilterCount}
              
            )}
          
          
        

        
          

          

          
        

        {/* Footer */}
        {activeFilterCount > 0 && (
          
            
          
        )}
      
    
  );
}

You can combine the 2 components into a single Filter component that owns all of this logic:

import { RotateCcw, SlidersHorizontal, X } from "lucide-react";
import { useEffect, useRef, useState } from "react";
import { SortSection } from "./filter/sort-section";
import { NarrowResultsSection } from "./filter/narrow-result-section";
import { FilterState } from "../interfaces";
import { usePathname, useRouter } from "next/navigation";
import { useQuery } from "@tanstack/react-query";
import { fetchColors, fetchCountries, fetchModes } from "../utils";

interface FilterProps {
  filters: FilterState;
  onChange: (partial: Partial) => void;
}

const Filter = ({ filters, onChange }: FilterProps) => {
  const { data: countries = [] } = useQuery({
    queryKey: ["countries"],
    queryFn: fetchCountries,
    staleTime: Infinity,
  });

  const { data: colors = [] } = useQuery({
    queryKey: ["colors"],
    queryFn: fetchColors,
    staleTime: Infinity,
  });

  const { data: modes = [] } = useQuery({
    queryKey: ["modes"],
    queryFn: fetchModes,
    staleTime: Infinity,
  });

  const router = useRouter();
  const pathname = usePathname();
  const [drawerOpen, setDrawerOpen] = useState(false);

  const drawerRef = useRef(null);

  const onClose = () => setDrawerOpen(false);
  const openDrawer = () => setDrawerOpen(true);
  const resetFilters = () => {
    onClose();
    router.push(pathname, { scroll: false });
  };

  const activeFilterCount = [
    filters.country,
    filters.color,
    filters.mode,
    filters.minPrice,
    filters.maxPrice,
  ].filter(Boolean).length;

  // Close on Escape
  useEffect(() => {
    const handler = (e: KeyboardEvent) => {
      if (e.key === "Escape") setDrawerOpen(false);
    };
    document.addEventListener("keydown", handler);
    return () => document.removeEventListener("keydown", handler);
  }, []);

  // Prevent body scroll while open
  useEffect(() => {
    document.body.style.overflow = drawerOpen ? "hidden" : "";
    return () => {
      document.body.style.overflow = "";
    };
  }, [drawerOpen]);

  return (
    <>
      
      {/* Backdrop */}
      

      {/* Drawer panel */}
      
        {/* Header */}
        
          
            Filters & Sort
            {activeFilterCount > 0 && (
              
                {activeFilterCount}
              
            )}
          
          
        

        
          

          

          
        

        {/* Footer */}
        {activeFilterCount > 0 && (
          
            
          
        )}
      
    
  );
};

export default Filter;

You can take this even further. Notice that NarrowResultsSection is the only component that uses the fetched countries, colors, and modes. And inside it, each SelectField uses a piece of this data.

import { FilterState } from "../../interfaces";
import { PriceRangeField } from "./price-range";
import { SelectField } from "./select-field";

interface NarrowResultsSectionProps {
  filters: FilterState;
  onChange: (partial: Partial) => void;
  countries: string[];
  colors: string[];
  modes: string[];
}

export function NarrowResultsSection({
  filters,
  onChange,
  countries,
  colors,
  modes,
}: NarrowResultsSectionProps) {
  return (
    
      
        Narrow Results
      

       onChange({ country: v })}
        placeholder="All countries"
      />

       onChange({ color: v })}
        placeholder="All colors"
      />

       onChange({ mode: v })}
        placeholder="All modes"
      />

      
    
  );
}

Instead of fetching everything at the top and passing it down, you can give each SelectField its own query.

The SelectField looked like this:

interface SelectFieldProps {
  label: string;
  value: string;
  options: string[];
  onChange: (v: string) => void;
  placeholder: string;
}

export function SelectField({
  label,
  value,
  options,
  onChange,
  placeholder,
}: SelectFieldProps) {
  return <>{/*=== Renders UI ===*/};
}

Now, it looks like this:

import { useQuery } from "@tanstack/react-query";

interface SelectFieldProps {
  label: string;
  value: string;
  onChange: (v: string) => void;
  placeholder: string;
  queryFn(): Promise;
  queryKey: string;
}

export function SelectField({
  label,
  value,
  onChange,
  placeholder,
  queryFn,
  queryKey,
}: SelectFieldProps) {
  const { data: options = [] } = useQuery({
    queryKey: [queryKey],
    queryFn: queryFn,
    staleTime: Infinity,
  });

  return <>{/*=== Renders UI ===*/};
}

Now each dropdown manages its own data. A state change inside one SelectField doesn't affect its siblings or its parent.

Move Search Logic Into Its Component

The Search component is the only component using the debouncing logic (searchTimerRef, handleQueryChange, handleClearQuery). You'll move logic inside the component:

"use client";

import { Search as SearchIcon, X } from "lucide-react";
import { ChangeEvent, useEffect, useRef } from "react";
import { FilterState } from "../interfaces";

interface SearchProps {
  query: string;
  onChange: (partial: Partial) => void;
}

const Search = ({ query, onChange }: SearchProps) => {
  const searchRef = useRef(null);
  const searchTimerRef = useRef | null>(null);

  const handleClearQuery = () => {
    if (searchRef.current) {
      searchRef.current.value = "";
    }

    onChange({ query: "" });
  };

  const handleQueryChange = (e: ChangeEvent) => {
    const val = e.target.value;

    if (searchTimerRef.current) clearTimeout(searchTimerRef.current);

    searchTimerRef.current = setTimeout(() => {
      onChange({ query: val });
    }, 400);
  };

  useEffect(() => {
    return () => {
      if (searchTimerRef.current) clearTimeout(searchTimerRef.current);
    };
  }, []);

  return {/*=== Renders UI ===*/};
};

export default Search;

Move Filter Chips into Its Component

The FilterChips component renders chips for active filters. The hasPriceFilter and priceLabel values that feed it can live inside the component instead of SearchPage:

interface FilterChipsProps {
  filters: FilterState;
  setFilters: (partial: Partial) => void;
  resetFilters: () => void;
}

export function FilterChips({
  filters,
  setFilters,
  resetFilters,
}: FilterChipsProps) {
  const priceLabel = [
    filters.minPrice ? `$${filters.minPrice}` : null,
    filters.maxPrice ? `$${filters.maxPrice}` : null,
  ]
    .filter(Boolean)
    .join(" - ");

  const hasPriceFilter = filters.minPrice || filters.maxPrice;

  return <>{/*=== Renders UI ===*/};
}

The Final SearchPage

After moving all state and logic to the components that need it, the SearchPage component looks like this:

"use client";

import { Header } from "./_components/header";
import { ProductTable } from "./_components/products-table";
import { FilterChips } from "./_components/filter-chips";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
import { FilterState, SortDir, SortField } from "./interfaces";

const DEFAULTS: FilterState = {
  query: "",
  country: "",
  color: "",
  mode: "",
  minPrice: "",
  maxPrice: "",
  sortField: "name",
  sortDir: "asc",
};

export default function SearchPage() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  const filters: FilterState = {
    query: searchParams.get("q") ?? DEFAULTS.query,
    country: searchParams.get("country") ?? DEFAULTS.country,
    color: searchParams.get("color") ?? DEFAULTS.color,
    mode: searchParams.get("mode") ?? DEFAULTS.mode,
    minPrice: searchParams.get("minPrice") ?? DEFAULTS.minPrice,
    maxPrice: searchParams.get("maxPrice") ?? DEFAULTS.maxPrice,
    sortField:
      (searchParams.get("sortField") as SortField) ?? DEFAULTS.sortField,
    sortDir: (searchParams.get("sortDir") as SortDir) ?? DEFAULTS.sortDir,
  };

  const setFilters = (partial: Partial) => {
    const next = new URLSearchParams(searchParams.toString());
    const merged = { ...filters, ...partial };

    const keyMap: Record = {
      query: "q",
      country: "country",
      color: "color",
      mode: "mode",
      minPrice: "minPrice",
      maxPrice: "maxPrice",
      sortField: "sortField",
      sortDir: "sortDir",
    };

    (Object.keys(merged) as (keyof FilterState)[]).forEach((k) => {
      const paramKey = keyMap[k];
      const val = merged[k];
      const def = DEFAULTS[k];
      if (val && val !== def) {
        next.set(paramKey, val);
      } else {
        next.delete(paramKey);
      }
    });

    router.push(`\({pathname}?\){next.toString()}`, { scroll: false });
  };

  const resetFilters = () => {
    router.push(pathname, { scroll: false });
  };

  const activeFilterCount = [
    filters.country,
    filters.color,
    filters.mode,
    filters.minPrice,
    filters.maxPrice,
  ].filter(Boolean).length;

  return (
    
      

      
        {activeFilterCount > 0 && (
          
        )}

        
      
    
  );
}

Notice that setFilters, resetFilters and activeFilterCount are still in the SearchPage component. This is intentional. These values depend on the URL. Any component that reads from the URL will re-render whenever the URL changes. It doesn’t matter where the values are calculated.

Fix Your Code Before Reaching For These Hooks

You might be tempted to reach for useCallback or useMemo when you have infinite re-rendering. Unstable object reference often leads to infinite re-renders, especially when a child component has a useEffect that depends on the object. It’s always better to understand why the loop is happening and fix the root cause.

Look at this example:

"use client";

import { useEffect, useState } from "react";
import { fetchUsers, Filter, User } from "./utils";

interface UserListProps {
  filters: Filter;
  onLoad(data: User[]): void;
  users: User[];
}

function UserList({ filters, onLoad, users }: UserListProps) {
  console.count("__ USER LIST __");

  useEffect(() => {
    fetchUsers(filters).then((data) => {
      onLoad(data);
    });
  }, [filters, onLoad]);

  return (
    
      {users.map((u) => (
        {u.name}
      ))}
    
  );
}

const UserPage = () => {
  const [userData, setUserData] = useState([]);

  const filters = {
    role: "admin",
    active: true,
  };

  return ;
};

export default UserPage;

The UserList component fetches users when it mounts. It uses filters and onLoad as dependencies.

The problem here is that the filters object in the UserPage component is recreated on every render. Even though the value looks the same, it’s a new reference each time there is a re-render. UserList sees it as a new value every time. This triggers its useEffect because it’s a dependency.

Wrapping filters in useMemo will stop the loop, but it misses the real issue. useMemo isn't meant to stop infinite re-rendering. There are some better solutions to fix this:

The first option is to use primitives in the dependency array instead of objects. Object compares by reference. This is why the useEffect sees different references whenever it reads the filter props. Primitives compare by value.

function UserList({ filters, onLoad, users }: UserListProps) {
  console.count("__ USER LIST __");

  useEffect(() => {
    fetchUsers(filters).then((data) => {
      onLoad(data);
    });
  }, [filters.active, filters.role]); // primitives compare by value, not reference

  return (
    
      {users.map((u) => (
        {u.name}
      ))}
    
  );
}

The second option is to define the object outside the component so it has a stable reference.

const filters = {
  role: "admin",
  active: true,
};

const UserPage = () => {
  const [userData, setUserData] = useState([]);

  return ;
};

The third solution is to store the object in a state if it's dynamic.

const UserPage = () => {
  const [userData, setUserData] = useState([]);
  const [filters, setFilters] = useState({
    role: "admin",
    active: true,
  });

  return ;
};

When to Use `useCallback` and `useMemo`

The goal of this article is not to tell you never to use these hooks. There are real situations where these hooks shine.

Measure Before You Optimize

Before going for any optimization, be it useCallback, useMemo, or restructuring your component, you should first confirm that there is a performance problem. Optimizing code that doesn’t need it isn’t beneficial to anybody.

React DevTools has a Profiler tab that lets you record a session and see exactly which components are re-rendering, how often, and how long each render takes. You should read How to Use React Developer Tools – Explained With Examples. If you are a video person, you can watch how Ben shows how to use the React Profiler to find and fix performance problems.

Stabilize References for `React.memo` Children

React.memo prevents a component from re-rendering if its props haven't changed. But if you pass a function or object as a prop, the child will still re-render on every parent render because functions and objects are recreated with new references each time.

This is the right time to use useCallback or useMemo:

const Child = React.memo(({ onClick }: { onClick: () => void }) => {
  console.log("Child rendered");
  return ;
});

function Parent() {
  const [count, setCount] = useState(0);

  const handleClick = useCallback(() => {
    console.log("clicked");
  }, []);

  return (
    <>
      
      
    
  );
}

Without useCallback, Child re-renders every time count changes, even though handleClick has nothing to do with count. With useCallback, the function reference stays stable.

It's often best to use both useCallback and React.memo together. But React.memo can be useful by itself if props are primitives or otherwise stable. And useCallback can be useful outside React.memo, such as when passing stable callbacks into effects, custom hooks, or third-party components.

Conclusion

useCallback and useMemo are useful memoization tools, but they're not a free performance upgrade. Every call adds memory overhead and a dependency comparison on each render.

Always structure your components so that optimization is rarely needed. Move state and logic as close as possible to the components that use them. Use useCallback and useMemo along with React.memo after you confirm that renders are actually a problem.

Stop Trusting AI Code Blindly: A React Code Refactoring Case Study

Tapas Adhikary — Wed, 03 Jun 2026 16:22:17 +0000

If you're a developer (or even a little bit familiar with all the AI developments of the past few years), the term Vibe Coding shouldn't be new to you. It is a software development practice where you describe what you want to AI (an LLM) in plain English, and in response, it gives you the source code for it.

You don't write anything manually line-by-line. You just completely focus on the vibe, like features, look-and-feel, and so on – and the AI generates the actual code for you. It's amazing and powerful.

Like millions of other software developers, I use and advocate the use of AI to a great extent. We should be using AI as a tool to expedite deliverables, to get repetitive work done, to make boilerplate, and anything that AI can help us with to stay productive.

But we shouldn't be doing any of this blindly, especially when it comes to delivering AI-generated work to customers.

All the modern AI tools like Claude, Gemini, or ChatGPT provide a warning upfront that AI can make mistakes. And we as users must double-check the responses before using them. Here's a similar notice from Claude:

The main message is this: don't trust AI-generated code blindly. You must do your due diligence before you think of pushing it to production.

To illustrate this, in this article you'll learn from a recent case study I did on generating some React-based source code for an Analytics Dashboard app with AI.

The AI gave me some error-free source code that I could run to see the app. But when I started digging deeper into it, I found potential bugs and tech debt that I needed to address. The generated source code was far from being ready for production and needed a great deal of refactoring.

This guide is also available as a video tutorial as part of the Full-Stack: Vibe Coding to Production Ready series. You can check it out if you’d like:

Let's start.

The Prompt
The Generated React Code
The Dashboard App
The Code Walkthrough and Identifying Problems
Refactoring the AI-Generated Code
A Task for You
Key Takeaways
If You've Read This Far...

The Prompt

First, we need a prompt to inform the AI in plain English that it should generate the source code for the Analytics Dashboard.

Here is the prompt – read it carefully:

Act as an expert React developer. 

I need a complex 'Creator Analytics Dashboard' for a video platform created using React.

It should include: 

- 1. A header with a user profile. 
- 2. Three summary cards showing total views, videos, and comments. 
- 3. A data table showing recent videos with their individual stats. 
- 4. A sidebar with navigation options. 

Use Tailwind CSS for styling. 

Fetch fake data for the dashboard using fetch with a 1-second timeout to simulate a network request. 

Make it in a way so that I can copy and paste it easily.

It's a straightforward request to create a Creator Analytics Dashboard with a bunch of feature requests using React and TailwindCSS.

Now, if we take up this prompt and use it on any of the AI tools like ChatGPT, Claude, or Gemini, it will generate the source code for us automatically.

The Generated React Code

Here's the AI-generated source code from the prompt. As you can see, it's a complete React component with state management, side effect management, and JSX.


import { useEffect, useState } from "react";

export default function CreatorDashboard() {
  const [stats, setStats] = useState({ views: 0, subs: 0, revenue: 0 });
  const [videos, setVideos] = useState([]);
  const [comments, setComments] = useState([]);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    let isMounted = true;

    const fetchData = async () => {
      try {
        await new Promise((resolve) => setTimeout(resolve, 1000));

        if (isMounted) {
          setStats({ views: '1.2M', subs: '45K', revenue: '$3,400' });
          setVideos([
            { id: 1, title: 'Vibe Coding Explained', views: '100K' },
            { id: 2, title: 'React 19 Features', views: '85K' }
          ]);
          setComments([{ id: 1, text: 'Great video!' }]);
          setIsLoading(false);
        }
      } catch (err) {
        setError('Failed to fetch data');
        setIsLoading(false);
      }
    };

    fetchData();
    return () => { isMounted = false; };
  }, []);

  if (isLoading) return Loading Dashboard...;
  if (error) return {error};

  return (
    
      
      
        tapaScript
        
           Dashboard
           Analytics
        
      

      
        
        
          Creator Analytics
          
            
            Tapas Adhikary
          
        

        
        
          
            Total Views
            {stats.views}
          
        

        
           
              Recent Videos
              {videos.map(v => {v.title})}
           
           
              Recent Comments
              {comments.map(c => {c.text})}
           
        
      
    
  );
}

Note that if you try the same prompt again, it will generate slightly different source code as the LLM's responses are probabilistic and non-deterministic. It can produce different responses for the same prompt across multiple calls.

Alright, let's try out the generated code.

The Dashboard App

Now, copy that AI-generated code and paste it into any React project. When you run it, you should see a beautiful Creator Analytics Dashboard matching the functionalities mentioned in the prompt.

This is amazing and powerful. As a developer, we must leverage it as much as possible. But as a developer, you also need to act like human guardrails to make sure that the generated code is modular, scalable, and bug-free.

Let's now do the walkthrough of the AI-generated code.

The Code Walkthrough and Identifying Problems

Before you read further, go back and read the generated source code once more. This time, slowly, carefully – like a code reviewer.

What have you found? Let's see if your findings match the list from my case study.

Problem 1: The God Component Syndrome

In software engineering, we have the Single Responsibility Principle(SRP). It means a function or component should do exactly one thing.

But here, our CreatorDashboard is acting as a "God Component". It manages state, it fetches data from the network, it renders the sidebar, it renders the header, the card, the tables...everything.

If the marketing team asks you to reuse that Stats Card on the marketing landing page, you simply can't. You need to rewrite it, as it's locked inside the giant file.

Problem 2: The State Soup Problem

Look at the top of the component. Five different useState declarations. When a component renders, tracking which piece of text triggered it becomes a nightmare. This should either be grouped or, even better, managed by a dedicated data fetching library like TanStack Query.

Remember, the fewer states you manage in your component, the better your life will be as a React developer.

Problem 3: The Data Fetching Anti-Pattern

AI loves to use useEffect for data fetching. It's one of the biggest anti-patterns in modern React. This is because the hook useEffect was never meant for data fetching. It doesn't handle caching, it doesn't handle retries if the network drops, and if the user navigates away and comes back, it forces a hard reload on the data every single time.

Modern React provides a better mechanism for data fetching. I've written a Handbook on how to use Suspense and Error Boundary to handle data fetching in React. You can give it a read.

Problem 4: The Missing Types Problem

We haven't mentioned TypeScript explicitly in the prompt. So, AI gave us JavaScript by default. Now, the problem is, can we guarantee what the videos array holds? What does a video object look like? We don't know, and our editor also can't help us.

Refactoring the AI-Generated Code

Now that we've identified the problems, the next logical step is to refactor the code to make it better.

Refactoring Strategy

The image below shows the refactoring strategy we'll follow. We'll break the giant AI-generated component into logical, smaller components like Header, Sidebar, RecentComments, and so on.

We also need to handle the data outside of the component and make the data fetching mechanism reusable for other components in the application to leverage it. To do this, we'll apply the Custom Hook Pattern.

Define Types

First, let's define all the types needed for the data objects. We need type definitions for video status, comments, and overall creator status.


// We use 'type' or 'interface' in TypeScript to define the shape of an object.

export interface CreatorStat {
  label: string;
  value: string | number;
}

export interface VideoStats {
  id: string; // ID should always be a string (UUID) or number, we'll enforce string here
  title: string;
  views: number;
  publishedAt: string;
}

export interface Comment {
  id: string;
  author: string;
  text: string;
  createdAt: string;
}

Break the Monoliths

Next, we'll solve the problem of SRP violation and the problem of CreatorDashboard being a God Component. Refactor the giant component by breaking it into multiple smaller components:

Header: A component represents the header of the analytics dashboard.

function Header() {
    return (
        
            
                Creator Analytics
            
            
                
                Tapas Adhikary
            
        
    );
}

export default Header;

Sidebar: The sidebar component holds the navigation links.

export default function Sidebar() {
    return (
        
            
                tapaScript
            
            
                
                    Dashboard
                
                
                    Analytics
                
            
        
    );
}

StatCard: This component accepts a status label and value and renders them. Note how we've applied the types here on the label and value props.

// 1. We define the Props interface.
// "Props" are the arguments passed into a React component.
// We are enforcing that whoever uses this component MUST pass a label and a value.
interface StatCardProps {
    label: string;
    value: string | number;
}

// 2. We extract the props cleanly using destructuring: { label, value }
function StatCard({ label, value }: StatCardProps) {
    return (
        
            
                {label}
            
            
                {value}
            
        
    );
}

export default StatCard;

VideoTable: This component lists out all the video information. So, it accepts an array of videos. Notice that we've solved the type problem here. Now we know that each video in the videos array is of the VideoStats type that we defined earlier.


import type { VideoStats } from '../types';

interface VideoTableProps {
  // We expect an array of VideoStats objects.
  videos: VideoStats[];
}

function VideoTable({ videos }: VideoTableProps) {
  if (videos.length === 0) {
    return No videos uploaded yet.;
  }

  return (
    
      
        Recent Videos
      
      
        {videos.map((video) => (
          
            {video.title}
            
              {video.views.toLocaleString()} views
            
          
        ))}
      
    
  );
}

export default VideoTable;

RecentComments: A component to show the list of comments.

import type { Comment } from "../types";

interface RecentCommentProps {
    // We expect an array of Comment objects.
    videos: Comment[];
}

function RecentCommentList({ comments }: RecentCommentProps) {
    if (comments.length === 0) {
        return (
            
                You don't have any comments posted.
            
        );
    }

    return (
        
            Recent Comments
            {comments.map((c) => (
                
                    {c.text}
                
            ))}
        
    );
}

export default RecentCommentList;

Custom Hook to Handle Data

Now that we have the components defined, and all of them are presentational components, they need data to render information on the dashboard. Also, we don't want to handle all the states inside our component. A custom hook would be a great choice here.

The hook handles the fetch call to get analytics data and tracks them using the state. We return the needed state values from the hook so that anyone using the hook anywhere would get this information. It's completely reusable.

import { useEffect, useState } from "react";
import type { Comment, CreatorStat, VideoStats } from "./types";

export function useDashboardData() {
    const [stats, setStats] = useState([]);
    const [videos, setVideos] = useState([]);
    const [comments, setComments] = useState([]);
    const [isLoading, setIsLoading] = useState(true);
     const [error, setError] = useState(null);

    useEffect(() => {
        let isMounted = true;

        const fetchData = async () => {
            try {
                // Simulating an API call
                await new Promise((resolve) => setTimeout(resolve, 1000));

                if (isMounted) {
                    setStats([
                        { label: "Views", value: "1.2M" },
                        { label: "subs", value: "45K" },
                        { label: "revenue", value: "$3,400" },
                    ]);
                    setVideos([
                        {
                            id: 1,
                            title: "Vibe Coding Explained",
                            views: "100K",
                        },
                        { id: 2, title: "React 19 Features", views: "85K" },
                    ]);
                    setComments([
                        { id: 1, text: "Great video!" },
                        { id: 2, text: "Fantastic video!" },
                    ]);
                    setIsLoading(false);
                }
            } catch (err) {
                setError(`Failed to fetch data: ${err?.message}`);
                setIsLoading(false);
            }
        };

        fetchData();
        return () => {
            isMounted = false;
        };
    }, []);

    return {
        stats,
        videos,
        comments,
        isLoading,
        error
    }

}

Everything Together

Finally, it's time to change the giant CreatorDashboard component. We'll first import all the smaller components created, and then call the hook to get the stats, videos, comments, and loading and error states. After that, it's just about using them.

import Header from "@/components/Header";
import Sidebar from "@/components/Sidebar";
import RecentCommentList from "./components/RecentComments";
import StatCard from "./components/StatCard";
import VideoTable from "./components/VideoTable";

import { useDashboardData } from "./hooks/useDashboardData";

export default function CreatorDashboard() {
    const { stats, videos, comments, isLoading, error } = useDashboardData();

    if (isLoading)
        return (
            Loading Dashboard...
        );
    if (error) return {error};

    return (
        
            {/* Sidebar Navigation */}
            

            
                {/* Header */}
                

                {/* Stats Cards */}
                
                    {stats.map((stat) => (
                        
                    ))}
                

                {/* Data Table & Comments - All mashed together */}
                
                    
                        
                    
                    
                
            
        
    );
}

That's all. We have now successfully refactored the big AI-generated component into smaller, reusable components and separated the data layer and state handling outside of it.

A Task for You

This is optional, yet I'd encourage you to try it. The task is to take the refactoring to the next level.

Can you get rid of the useDashboardData hook, and handle the data fetching using the Suspense and Error Boundary patterns? I would love to discuss the solution with you. Please reach out on my socials (given below) or my Discord Server.

Also, stay tuned for my upcoming article, where I'll refactor the same app with TanStack Query and teach you about fetch, mutation, and caching.

Key Takeaways

This is the reality of AI-generated code. It looks like a finished product on the surface. But underneath, it's a fragile house of cards. If you try to scale this, say by adding authentication, sorting to the tables, or real-time comment updates, the file will grow to 1K+ lines of unmaintainable code.

Our job isn't to reject AI's output. Instead, it's to refactor its output to make it production-ready. You can do that only when you have strong fundamentals, and you understand the new definition of software engineering in the age of AI.

If You've Read This Far...

Thank You!

I'm thrilled to announce that I've started a Full Stack FREE Course to take developers from vibe coding to a production-ready mental model. I'd be delighted if you check it out and take part.

Subscribe to my YouTube Channel
Follow on LinkedIn and X
Catch up with my React Clean Code Rules Book
All the source code used in this article is on my GitHub Repository.

See you soon with my next article. Until then, please take care of yourself and keep learning.

Build Professional Web Scrapers That Actually Work

Beau Carnes — Fri, 29 May 2026 15:19:17 +0000

Web scraping has evolved. If you’ve ever tried to pull data from a site, only to be hit with a CAPTCHA, an IP ban, or a "403 Forbidden" error, you know that modern websites are built to block automated scripts.

To get the data you need today, you have to bypass sophisticated anti-bot detection systems.

We are just posted full-stack web scraping course on the freeCodeCamp.org YouTube channel. Gavin Lon developed this course.

Many scraping tutorials focus on basic scripts that fail the moment they hit a real-world website. This course bridges the gap between a "toy script" and a production-ready application. You'll learn how to bypass advanced fingerprinting and bot detection using managed browser infrastructure and residential proxies.

Gavin will teach you how to build a fully deployed MERN (MongoDB, Express, React, Node.js) application. It's a dashboard that visualizes live data scraped from major platforms like Amazon, Booking.com, Indeed, and the TIOBE Index.

Evomi provided a grant to make this course possible. You can try out Evomi here: https://evomi.com/freecodecamp

Here are the key things you will learn in the course:

Master Modern Scraping: Move beyond basic libraries to use Playwright, Cheerio, and Evomi’s enterprise-grade Scraping Browser and Scraper API.
Defeat Anti-Bot Systems: Learn exactly why standard scripts get flagged and how to configure residential proxies and browser fingerprints to remain undetected.
Full-Stack Integration: Learn how to pipeline raw data into a MongoDB database and build a clean, responsive UI with React, Vite, and Bootstrap.

Watch the full course on the freeCodeCamp.org YouTube channel (6-hour watch).

How to Create Dynamic Emails in Go with React Email

Orim Dominic Adah — Mon, 20 Apr 2026 20:16:44 +0000

Backend applications are required to send emails to users to deliver notifications and maintain communication outside the application interface. These emails usually contain information specific to each user, such as the user's name or address, making them dynamic.

This article walks you through building a dynamic email template with React Email, converting it to HTML, and injecting data into it using Go templates. It also contains an optional section that shows you how to send and test the email delivery with MailHog.

To follow along with this article, you need to have Go and Node.js installed on your computer. You should also have a basic understanding of React and some familiarity with Go templates, though these aren't strict requirements because you can pick them up as you practise along.

What is React Email?
Go Templates
- Go Template Delimiters
Create Dynamic Emails in Go with React Email
Conclusion

What is React Email?

React Email is a JavaScript library that helps you build dynamic email templates with React. If you already know basic React, React Email provides a better developer experience for building dynamic email templates. Here are some reasons why:

Familiar syntax with React: If you know React already, React Email eliminates the hassle in learning a separate templating language, using inefficient drag-and-drop UIs, or writing emaiil templates from scratch with HTML tables.
Reusable built-in components: React Email provides ready-to-use UI components like Buttons and Footers so you don't have to start from scratch, making email development seamless and fast.
Consistency across email clients: React Email generates email templates that have been tested and work well across popular email clients. This helps eliminate worries over emails rendering inconsistently across email clients.
Email development tooling: React Email has features for previewing and assessing emails built with it. Some of these features include:
- A local development server that lets you preview mobile and desktop views of your emails in your web browser as you develop the emails in real time
- An email delivery feature that sends your email to a real email address for preview
- A compatibility checker that shows you how well your email is supported across popular email clients
- A spam scorer that analyses your email to determine if it's likely to be marked as spam
Tailwind integration: Tailwind is a popular CSS framework that provides classes for styling HTML and making it responsive. React Email integrates with Tailwind easily for creating beautiful emails.

All these features are free to use.

In this article, you'll learn how to generate an HTML file from a React Email template, convert it to a Go template, and inject data into the template for previewing.

Go Templates

The Go html/template package allows you to define reusable HTML templates that can be populated with dynamic data. These templates contain placeholders (called actions) that are evaluated by Go's templating engine and replaced with actual values during execution.

First, you give the package HTML content that contains Go-specific annotations. It converts the HTML content to a Go HTML template and the Go-specific annotations to actions in the template. The template is then executed with data to produce HTML output that contains the data.

package main

import (
	"html/template"
	"os"
)

func main() {
	tmpl := template.New("hello")
	tmpl, _ = tmpl.Parse(`Hello {{.}}`)
	tmpl.Execute(os.Stdout, "Gopher")
}

// Output: Hello Gopher
// Playground: https://goplay.tools/snippet/KxbkWPIArz5

In the code snippet above:

template.New creates an empty template object with the name "hello"
tmpl.Parse(`
Hello {{.}}
`) parses the HTML string Hello {{.}} to create a Go HTML template and saves it in tmpl . The {{.}} part of the HTML string is an action which acts as a placeholder for data. {{ and }} are called delimiters and . is the data access identifier.
tmpl.Execute(os.Stdout, "Gopher") populates the action with data - the "Gopher", string, and writes the resulting HTML output to the console.

Go Template Delimiters

In the previous code snippet, you used double curly braces ({{ and }}) as the delimiters in the Go template. Delimiters are symbols that Go uses to determine what parts of the input string represent an action – that is, a statement to be evaluated.

You can change the delimiters by using the Delims method on a template. An example is shown in the snippet below:

package main

import (
	"html/template"
	"os"
)

func main() {
	tmpl := template.New("hello")
	tmpl, _ = tmpl.Delims("((", "))").Parse(`Hello ((.))`)
	tmpl.Execute(os.Stdout, "Gopher")
}

// Output: Hello Gopher
// Playground: https://goplay.tools/snippet/00RuDzvZYwN

In the snippet above, (( and )) are used as the delimiters for the hello template.

This is important because you'll set your delimiters to prevent conflicts between Go's default delimiters and React's curly braces in React Email templates.

Create Dynamic Emails in Go with React Email

The image below summarizes how the sample application you'll build in this article works:

You'll create a React Email template that contains Go template annotations. Next, you'll use Node.js to create HTML files from it. Go will parse the HTML file to create a Go template, execute it, and send it.

Optionally, you'll use go-mail to send the email and MailHog, a local SMTP server, to preview it in your browser.

Set Up the Project

First, make sure that you have Go and Node.js installed on your computer already. Clone this freeCodeCamp-go-react-email repository and checkout the 01-setup branch using git checkout 01-setup.

The project contains a main.go file in the cmd directory and a go.mod file. It also contains a .gitignore file to instruct Git to ignore all node_modules directories.

Run go run cmd/main.go in the terminal of the project. If you see "It works!" logged to the console, you have set it up properly and you can continue to the next section.

Set Up React Email

In the project root directory, create a mailer directory which will serve as the mailer package. It will hold all functionality related to creating and sending mails.

In the mailer directory, you'll create the emails Node.js project that will handle React Email functionality. To create the project:

Create a directory called _emails in the mailer directory. The name of the directory starts with an underscore because it should be ignored when the go build command is run. So it won't be included in the Go compiled executable file.
Run npm init -y in the root terminal of the _emails directory to initialise the Node.js project in it. This will create a package.json file in the directory.
Update the value of the name field in package.json to "emails" to make the package name more conventional. This step is not compulsory.

Next, install the required React Email libraries by running the following commands in the root terminal of the _emails directory:

npm install @react-email/ui @types/react -D -E
npm install react-email react react-dom -E

After the installation is complete, replace the scripts field of the package.json file with the code snippet below:

  "scripts": {
    "dev": "email dev --dir ./src",
    "export": "email export --pretty --dir ./src --outDir ../templates"
  },

The dev script starts and runs the server for previewing the React Email templates in the browser. You will write the template with React and store it in the src directory under _emails. The export script transpiles the template files in the src directory from JSX (or TSX) to HTML and stores them in a directory called templates, a direct child of the mailer directory – not a child of the _emails directory.

The templates directory is stored as a child directory of the mailer directory because the Go project needs only the HTML output stored in the templates directory and not the contents of _emails.

If you've completed all these steps, you have set up React Email in the emails Node.js project. To view the current status of the project at this point, visit freeCodeCamp-go-react-email/02-setup-react-email.

In the next section, you'll create a React Email template and preview it in the browser.

Create a React Email Template

In this section, you'll create a React Email template and preview it in the browser. You'll also build and export the template to HTML files.

Create a directory called src inside the _emails directory. Inside the src directory, create a file called welcome.tsx. Copy and paste the content of the snippet below into welcome.tsx.

import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Html,
  Img,
  Preview,
  Section,
  Tailwind,
  Text,
} from "react-email";

interface WelcomeEmailProps {
  username?: string;
  company?: string;
  gophers?: string[];
}

const WelcomeEmail = ({
  username = "Nicole",
  company = "GoWorld",
  gophers = ["Tinky Winky", "Dipsy", "Laa-Laa", "Po"],
}: WelcomeEmailProps) => {
  const previewText = `Welcome to \({company}, \){username}!`;

  return (
    
      
      {previewText}
      
        
          
            
              
            
            
              Welcome to {company}, {username}!
            
            Hello {username},
            
              We're excited to have you onboard at {company}.
              We hope you enjoy your journey with us. If you have any questions
              or need assistance, feel free to reach out to any of the following
              gophers:
            
            
              
                {gophers.map((gopher) => (
                  {gopher}
                ))}
              
            
            
              
            
            
              Cheers,
              

              The {company} Team
            
          
        
      
    
  );
};

export default WelcomeEmail;

The code snippet above is the React Email template that you'll use in this article. To preview it, navigate to the terminal of the _emails root directory and run npm run dev . Use your web browser to visit the preview URL displayed on the terminal. Click on the "welcome" link on the left sidebar and you should see a UI similar to the one in the screenshot below:

In the UI above, React Email renders the email with the default values supplied to the welcome email template.

Stop the server by clicking on the terminal that runs it by pressing CTRL + C. Build the HTML output of the src directory and export it by running npm run export in the terminal of the _emails root directory. This creates a templates directory within the mailer directory where the exported HTML files are stored. In the templates directory, you'll see a welcome.html file – the HTML output from welcome.tsx.

To see the current status of the project, visit freeCodeCamp-go-react-email/03-create-react-email-template.

Set Up Go Templates from HTML Files

You have created a React Email template, previewed it, built it, and exported it as an HTML file. In this section, you'll update the React Email template to use the delimiters you set and not React's curly braces. You'll also create a Go template from the HTML file.

To get started, replace the content of welcome.tsx with the code snippet below to to use (( and )) as delimiters and remove TypeScript types:

import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Html,
  Img,
  Preview,
  Section,
  Tailwind,
  Text,
} from "react-email";

const WelcomeEmail = () => {
  const previewText = `Welcome to ((.Company)), ((.Username))!`;

  return (
    
      
      {previewText}
      
        
          
            
              
            
            
              Welcome to ((.Company)), ((.Username))!
            
            Hello ((.Username)),
            
              We're excited to have you onboard at ((.Company))
              . We hope you enjoy your journey with us. If you have any
              questions or need assistance, feel free to reach out to any of the
              following Gophers:
            
            
              
                ((range .Gophers))
                ((.))
                ((end))
              
            
            
              
            

            
              Cheers,
              

              The ((.Company)), Team
            
          
        
      
    
  );
};

export default WelcomeEmail;

Run npm run export in the root terminal of the _emails directory to build and export this version of the React Email template to HTML. The HTML generated will contain Go template annotations that will become actions when parsed by Go to form a Go HTML template.

In the mailer directory, create a file named fs.go. The code in the file will be used to embed the files in the templates directory for use in the Go application. Copy and paste the content of the snippet below into fs.go:

package mailer

import (
	"embed"
	"io/fs"
)

//go:embed templates/*
var embedded embed.FS
var templateFS, _ = fs.Sub(embedded, "templates")

//go:embed templates/* tells the Go compiler to embed files from the current directory (mailer) into the compiled binary of the Go application. You need this to access the HTML template files from the Go application. templateFS will be used to access the files in the templates subdirectory.

Create another file in the mailer directory and name it mailer.go. mailer.go will contain code used to parse HTML files to make Go HTML templates and also send emails. Copy the content of the code snippet below into mailer.go:

package mailer

import (
	"html/template"
	"io"
)

const (
	welcomeMailKey = "welcome_mail"
)

func setUpTemplates() (map[string]*template.Template, error) {
	templates := make(map[string]*template.Template)

	tmpl := template.New("welcome.html").Delims("((", "))")
	welcomeEmailTmpl, err := tmpl.ParseFS(templateFS, "welcome.html")
	if err != nil {
		return nil, err
	}

	templates[welcomeMailKey] = welcomeEmailTmpl

	return templates, nil
}

type Mailer struct {
	templates map[string]*template.Template
}

// NewMailer creates a new mailer
func NewMailer() (*Mailer, error) {
	tpls, err := setUpTemplates()
	if err != nil {
		return nil, err
	}

	return &Mailer{
		templates: tpls,
	}, nil
}

type WelcomEmailData struct {
	Username string
	Company  string
	Gophers  []string
}

func (mailer *Mailer) WriteWelcomeMail(w io.Writer, data WelcomEmailData) error {
	tmpl := mailer.templates[welcomeMailKey]
	err := tmpl.Execute(w, data)

	return err
}

In the code snippet above:

setUpTemplates creates a template object, tmpl, and sets its delimiters. tmpl parses welcome.html to convert it to a Go template and stores the template with welcomeEmailTmpl as its identifier. After that, welcomeEmailTmpl is added to the templates map with welcomeMailKey as its key and templates is returned.
NewMailer creates and returns a Mailer object which holds the templates map and methods to work with the mail templates.
WriteWelcomeMail is a method on Mailer that's used to execute the welcome email template with real data.

To view the current status of the codebase at this point, visit freeCodeCamp-go-react-email/04-create-golang-template.

Render the Dynamic Email in the Browser

In this section, you'll create a simple web server to view the rendered email template containing the dynamic values passed to it.

Replace the content of main.go with the code snippet below:

package main

import (
	"fmt"
	"net/http"
	"os"

	pkgMailer "github.com/orimdominic/freeCodeCamp-go-react-email/mailer"
)

func main() {
	mailer, err := pkgMailer.NewMailer()
	if err != nil {
		fmt.Fprint(os.Stderr, err)
		os.Exit(1)
	}

	http.HandleFunc("/mail", func(w http.ResponseWriter, r *http.Request) {
		username := r.URL.Query().Get("username")
		company := r.URL.Query().Get("company")
		gophers := []string{"Tinky Winky", "Dipsy", "Laa-Laa", "Po"}

		err := mailer.WriteWelcomeMail(w, pkgMailer.WelcomEmailData{
			Username: username,
			Company:  company,
			Gophers:  gophers,
		})
		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
	})

	port := ":8888"
	err = http.ListenAndServe(port, nil)
	if err != nil {
		fmt.Fprint(os.Stderr, err)
		os.Exit(1)
	}
}

The code snippet above first creates a mailer object using the NewMailer function from mailer.go. After the error handling, it creates a simple web server running on port 8888 with a GET /mail route.

The GET /mail route accepts two query parameters: username and company, which will be used as the dynamic data for the email. The result of executing the template with WriteWelcomeMail is written as an HTML response on the browser. You'll use this route to test the functionality of the mailer package.

Before you start the server, you should build and export the React Email templates so that your HTML files always have the most recent changes from React Email templates. Instead of navigating between different directories to build, export and run the server, you can use a Makefile.

Navigate to the terminal of the root directory of the project and create a file called Makefile. Copy and paste the content of the code snippet below into it:

run: email-build
	go run cmd/main.go

email-build: mailer/_emails
	npm --prefix mailer/_emails run export

The run script of the Makefile above builds and exports the React Email templates as HTML to the mailer/templates directory and then starts the Go application. Ensure that Makefile uses hard tabs, not spaces for indentation.

Run make run in the terminal of the root directory of the project and visit http://localhost:8888/mail?username=Nicole&company=GoWorld in the browser. You'll see the email rendered on the browser UI.

Replace the values of username and company in the URL to test the email with different values.

With this setup, you can integrate the result of executing the template with your mail client and the email recipient will see the email as it's displayed in the browser.

To view the current status of the codebase at this point, visit freeCodeCamp-go-react-email/05-render-dynamic-email.

Send and Test Email with go-mail and MailHog

In the previous section, you supplied data to execute your template, but it was rendered in the browser, not an email client. In this section, you'll use go-mail to send the email and MailHog to intercept and view it.

This section is optional. If you don't have MailHog installed locally, you'll need Docker Compose to set it up for this project. Make sure Docker Compose is installed on your computer before proceeding.

In your terminal, navigate to the root directory of the project and run go get github.com/wneessen/go-mail to install go-mail. Create a compose.yml file in the root directory of the project and paste the contents of the code snippet below into it:

services:
  mailhog:
    image: mailhog/mailhog
    restart: no
    logging:
      driver: "none" # disable saving logs
    ports:
      - 1025:1025 # smtp server
      - 8025:8025 # web ui

In your terminal, navigate to the project's root directory and run docker compose up to pull and start the MailHog SMTP server. MailHog listens for emails on port 1025 and exposes a web UI at http://localhost:8025 where you can view intercepted emails. Depending on your internet connection, the initial image pull may take a few minutes.

Replace mailer.go with the content of the code snippet below:

package mailer

import (
	"html/template"
	"io"

	"github.com/wneessen/go-mail"
)

const (
	welcomeMailKey = "welcome_mail"
    sender = "noreply@localhost.com"
)

func setUpTemplates() (map[string]*template.Template, error) {
	templates := make(map[string]*template.Template)

	tmpl := template.New("welcome.html").Delims("((", "))")
	welcomeEmailTmpl, err := tmpl.ParseFS(templateFS, "welcome.html")
	if err != nil {
		return nil, err
	}

	templates[welcomeMailKey] = welcomeEmailTmpl

	return templates, nil
}

type Mailer struct {
	client    *mail.Client
	templates map[string]*template.Template
}

// NewMailer creates a new mailer
func NewMailer() (*Mailer, error) {
	tpls, err := setUpTemplates()
	if err != nil {
		return nil, err
	}

	c, err := mail.NewClient(
		"localhost",
		mail.WithPort(1025),
		mail.WithTLSPolicy(mail.NoTLS),
	)

	if err != nil {
		return nil, err
	}

	return &Mailer{
		client:    c,
		templates: tpls,
	}, nil
}

type WelcomEmailData struct {
	Username string
	Company  string
	Gophers  []string
}

func (mailer *Mailer) WriteWelcomeMail(w io.Writer, data WelcomEmailData) error {
	tmpl := mailer.templates[welcomeMailKey]
	err := tmpl.Execute(w, data)

	return err
}

func (mailer *Mailer) SendWelcomeMail(to string, data WelcomEmailData) error {
	m := mail.NewMsg()
	m.From(sender)
	m.To(to)
	m.Subject("Welcome to " + data.Company)
	m.SetBodyHTMLTemplate(mailer.templates[welcomeMailKey], data)

	err := mailer.client.DialAndSend(m)
	return err
}

The new changes to mailer.go include:

An import of the go-mail
The creation of a sender constant which represents the email of the sender
The creation of a mail client with go-mail
The creation of a SendWelcomeMail method on the mailer struct which creates an email with welcomeEmailTmpl, executes it, and sends it to a receiver.

In main.go, update the GET /mail route to use SendWelcomeMail instead of WriteWelcomeMail. You can use any email address you want. The snippet below uses fcc@go.dev:

		err := mailer.SendWelcomeMail("fcc@go.dev", pkgMailer.WelcomEmailData{
			Username: username,
			Company:  company,
			Gophers:  gophers,
		})
		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}

		fmt.Fprint(w, "Email sent")

Ensure that the mail server is running by visiting http://localhost:8025 in your web browser. In another terminal, from the root directory of the project, run make run to start the server. Test the functionality of the route by visiting http://localhost:8888/mail?username=Nicole&company=GoWorld once again. Next, check the email server by visiting http://localhost:8025. You should see a UI similar to the one in the screenshot below:

Click on "Welcome to Helix" to view the email.

To view the current status of the codebase at this point, visit freeCodeCamp-go-react-email/06-send-email.

Conclusion

By following along with this tutorial, you have:

Learned how to create Go email templates from React Email templates
Learned how to use Makefiles to run custom scripts
Previewed your email in the browser and tested it using MailHog

You can now skip the hassle of writing raw HTML email tables or learning a new templating language. With React Email and Go templates, you have a cleaner, more developer-friendly way to build and send beautiful emails.

React - freeCodeCamp.org

How to Create a Scalable KYC Onboarding Flow in React with Shadcn UI

Table of Contents

Prerequisites

What You're Building

Project Structure

Radix UI vs Base UI: Which Primitives this Flow Uses

Scaffolding the Flow with v0 and an MCP Server

Step 1: Account Type with a Radio Group

Live Preview:

Step 2: Document Upload with Drag and Drop

Live Preview:

Step 3: Verification Status with an Alert

Live Preview:

Adding a Stepper to the Flow

Small Details that Make it Feel Finished

Live Preview:

Accessibility notes

Key Concepts Recap

Conclusion

Resources

How to Build an Open Source SaaS Landing Page Template with shadcn/ui

Table of Contents

The Stack Choices and Why They Matter

Getting Started

Project Structure

Lesson 1: shadcn/ui's New base-nova Style Changes What "Accessible" Means

Lesson 2: Tailwind CSS v4 Requires a Mental Model Shift

Lesson 3: OKLCH Colors Make Dark Mode Predictable

Lesson 4: Page Architecture — Flat Beats Clever

Lesson 5: Staggered Animations Without Managing Individual Delays

Lesson 6: CSS-Only Infinite Scroll — No Library Needed

Lesson 7: CSS Subgrid Solves Pricing Card Alignment Natively

Lesson 8: Inline SVGs Beat Image Libraries for Simple Logos

What I'd Do Differently

1. Extract Animation Variants to a Shared File

2. Use Subgrid in the Features Section Too

3. Use next/font More Consistently

Summary

A Guide to Modern React Form Architecture: TanStack Form + Zod + Shadcn

Table of Contents

The Problem with Traditional Forms

The Problem

The Uncontrolled "Ref" Workaround

The Ref Workaround

Why Not Just Use Native HTML Forms?

Introducing TanStack Form

Add New Speaker

Fine-Grained Reactivity

Validation with Zod

Headless TanStack Form with ShadCN UI

Handling Nested Dynamic Arrays with TanStack Form

TanStack Form's Granular Reactivity: useSelector vs form.Subscribe

With useSelector()

With form.Subscribe()

TanStack Form vs. React Hook Form

Dynamic Arrays

Deeply Nested Components

The Ecosystem Sync

Conclusion & Important Resources

If You've Read This Far...

How to Build a Reusable Date-Time Picker in React with shadcn/ui

Table of Contents

Prerequisites

What You'll Build

How to Install a Shadcn Date Time Picker

How to Build a Date and Time Picker

How This Component Works

How to Build a Date Range Picker

How the Date Range Picker Works

How to Build a Time Picker

How the Time Picker Works

Live Preview of the Components

Key Concepts Recap

Conclusion

Resources

How to Use Apple’s Foundation Models in a Web App with a macOS Companion

Table Of Contents

What You Will Build

Prerequisites

Lesson 1: shadcn/ui's New `base-nova` Style Changes What "Accessible" Means

3. Use `next/font` More Consistently

TanStack Form's Granular Reactivity: `useSelector` vs `form.Subscribe`

With `useSelector()`

With `form.Subscribe()`

3. `render` prop instead of `asChild`

2. `activeCount` is computed, not tracked

4. Toggling a category with `.filter()` and spread

`safeArray`

`safeString`

`safeNumber`

`safeObject`

Bonus: Combine Them into a `safeData` Helper