React - freeCodeCamp.org

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.

A Developer’s Guide to Lazy Loading in React and Next.js

David Aniebo — Tue, 14 Apr 2026 20:31:59 +0000

Large JavaScript bundles can slow down your application. When too much code loads at once, users wait longer for the first paint and pages feel less responsive. Search engines may also rank slower sites lower in results.

Lazy loading helps solve this problem by splitting your code into smaller chunks and loading them only when they are needed

This guide walks you through lazy loading in React and Next.js. By the end, you'll know when to use React.lazy, next/dynamic, and Suspense, and you'll have working examples you can copy and adapt to your own projects.

What is Lazy Loading?
Prerequisites
How to Use React.lazy for Code Splitting
How to Use Suspense with React.lazy
How to Handle Errors with Error Boundaries
How to Use next/dynamic in Next.js
React.lazy vs next/dynamic: When to Use Each
Real-World Examples
Conclusion

What is Lazy Loading?

Lazy loading is a performance technique that defers loading code until it's needed. Instead of loading your entire app at once, you split it into smaller chunks. The browser only downloads a chunk when the user navigates to that route or interacts with that feature.

Benefits include:

Faster initial load: Smaller first bundle means quicker time to interactive
Better Core Web Vitals: Improves Largest Contentful Paint and Total Blocking Time
Lower bandwidth: Users only download what they use

In React, you achieve this with dynamic imports and React.lazy() or Next.js’s next/dynamic.

Prerequisites

Before you follow along, you should have:

Basic familiarity with React (components, hooks, state)
Node.js installed (version 18 or later recommended)
A React app (Create React App or Vite) or a Next.js app (for the Next.js examples)

For the React examples, you can use Create React App or Vite. For the Next.js examples, use the App Router (Next.js 13 or later).

How to Use `React.lazy` for Code Splitting

React.lazy() lets you define a component as a dynamic import. React will load that component only when it's first rendered.

React.lazy() expects a function that returns a dynamic import(). The imported module must use a default export.

Here's a basic example:

import { lazy } from 'react';

const HeavyChart = lazy(() => import('./HeavyChart'));
const AdminDashboard = lazy(() => import('./AdminDashboard'));

function App() {
  return (
    
      My App
      
      
    
  );
}

If you use named exports, you can map them to a default export:

const ComponentWithNamedExport = lazy(() =>
  import('./MyComponent').then((module) => ({
    default: module.NamedComponent,
  }))
);

You can also name chunks for easier debugging in the browser:

const HeavyChart = lazy(() =>
  import(/* webpackChunkName: "heavy-chart" */ './HeavyChart')
);

React.lazy() alone isn't enough. You must wrap lazy components in Suspense so React knows what to show while they load.

How to Use `Suspense` with `React.lazy`

Suspense is a React component that shows a fallback UI while its children are loading. It works with React.lazy() to handle the loading state of dynamically imported components.

Wrap your lazy components in Suspense and provide a fallback prop:

import { lazy, Suspense } from 'react';

const HeavyChart = lazy(() => import('./HeavyChart'));
const AdminDashboard = lazy(() => import('./AdminDashboard'));

function App() {
  return (
    
      My App
      Loading chart...}>
        
      
      Loading dashboard...}>
        
      
    
  );
}

You can use a single Suspense boundary for multiple lazy components:

Loading...}>

A more polished fallback improves perceived performance:

function LoadingSpinner() {
  return (
    
      
      Loading...
    
  );
}

}>

How to Handle Errors with Error Boundaries

React.lazy() and Suspense don't handle loading errors (for example, network failures or missing chunks). For that, you need an Error Boundary.

Error Boundaries are class components that use componentDidCatch or static getDerivedStateFromError to catch errors in their child tree and render a fallback UI.

Here is a simple Error Boundary:

import { Component } from 'react';

class ErrorBoundary extends Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    console.error('Error caught by boundary:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback || Something went wrong.;
    }
    return this.props.children;
  }
}

Wrap your Suspense boundary with an Error Boundary:

import { lazy, Suspense } from 'react';
import ErrorBoundary from './ErrorBoundary';

const HeavyChart = lazy(() => import('./HeavyChart'));

function App() {
  return (
    Failed to load chart. Please try again.}>
      Loading chart...}>
        
      
    
  );
}

If the chunk fails to load, the Error Boundary catches it and shows your fallback instead of a blank screen or unhandled error.

How to Use `next/dynamic` in Next.js

Next.js provides next/dynamic, which wraps React.lazy() and Suspense and adds options tailored for Next.js (including Server-Side Rendering).

Basic usage:

'use client';

import dynamic from 'next/dynamic';

const ComponentA = dynamic(() => import('../components/A'));
const ComponentB = dynamic(() => import('../components/B'));

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

Custom Loading UI

Use the loading option to show a placeholder while the component loads:

const HeavyChart = dynamic(() => import('../components/HeavyChart'), {
  loading: () => Loading chart...,
});

Disable Server-Side Rendering

For components that must run only on the client (for example, those using window or browser-only APIs), set ssr: false:

const ClientOnlyMap = dynamic(() => import('../components/Map'), {
  ssr: false,
  loading: () => Loading map...,
});

Note: ssr: false works only for Client Components. Use it inside a 'use client' file.

Load on Demand

You can load a component only when a condition is met:

'use client';

import { useState } from 'react';
import dynamic from 'next/dynamic';

const Modal = dynamic(() => import('../components/Modal'), {
  loading: () => Opening modal...,
});

export default function Page() {
  const [showModal, setShowModal] = useState(false);

  return (
    
      
      {showModal &&  setShowModal(false)} />}
    
  );
}

Named Exports

For named exports, return the component from the dynamic import:

const Hello = dynamic(() =>
  import('../components/hello').then((mod) => mod.Hello)
);

Using Suspense with next/dynamic

In React 18+, you can use suspense: true to rely on a parent Suspense boundary instead of the loading option:

const HeavyChart = dynamic(() => import('../components/HeavyChart'), {
  suspense: true,
});

// In your component:
Loading...}>

Important: When using suspense: true, you can't use ssr: false or the loading option. Use the Suspense fallback instead.

`React.lazy` vs `next/dynamic`: When to Use Each

Feature	React.lazy + Suspense	next/dynamic
Framework	Any React app (Create React App, Vite, etc.)	Next.js only
Server-Side Rendering	Not supported	Supported by default
Disable SSR	N/A	`ssr: false` option
Loading UI	`Suspense` fallback prop	Built-in `loading` option
Error handling	Requires Error Boundary	Requires Error Boundary
Named exports	Manual `.then()` mapping	Same `.then()` pattern
Suspense mode	Always uses Suspense	Optional via `suspense: true`

When to Use `React.lazy`

You're building a pure React app (no Next.js)
You use Create React App, Vite, or a custom Webpack setup
You don't need Server-Side Rendering
You want a simple, framework-agnostic approach

When to `Use next/dynamic`

You're building a Next.js app
You need SSR for some components and want to disable it for others
You want built-in loading placeholders without manually adding Suspense
You want Next.js-specific optimizations and defaults

Real-World Examples

Example 1: Route-Based Code Splitting in React

Split your app by route so each page loads only when the user navigates to it:

// App.jsx
import { lazy, Suspense } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import ErrorBoundary from './ErrorBoundary';

const Home = lazy(() => import('./pages/Home'));
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Settings = lazy(() => import('./pages/Settings'));

function App() {
  return (
    
      Failed to load page.}>
        Loading page...}>
          
            } />
            } />
            } />
          
        
      
    
  );
}

Example 2: Lazy Loading a Heavy Chart Library in Next.js

Defer loading a chart library until the user opens the analytics section:

// app/analytics/page.jsx
'use client';

import { useState } from 'react';
import dynamic from 'next/dynamic';

const Chart = dynamic(() => import('../components/Chart'), {
  ssr: false,
  loading: () => (
    
      
      
      
    
  ),
});

export default function AnalyticsPage() {
  const [showChart, setShowChart] = useState(false);

  return (
    
      Analytics
      
      {showChart && }
    
  );
}

Load a modal component only when the user clicks to open it:

// React (with React.lazy)
import { lazy, Suspense, useState } from 'react';

const Modal = lazy(() => import('./Modal'));

function ProductPage() {
  const [showModal, setShowModal] = useState(false);

  return (
    
      
      {showModal && (
        
           setShowModal(false)} />
        
      )}
    
  );
}

// Next.js (with next/dynamic)
'use client';

import { useState } from 'react';
import dynamic from 'next/dynamic';

const Modal = dynamic(() => import('./Modal'), {
  loading: () => null,
});

export default function ProductPage() {
  const [showModal, setShowModal] = useState(false);

  return (
    
      
      {showModal &&  setShowModal(false)} />}
    
  );
}

Example 4: Lazy Loading External Libraries

Load a library only when the user needs it (for example, when they start typing in a search box):

'use client';

import { useState } from 'react';

const names = ['Alice', 'Bob', 'Charlie', 'Diana'];

export default function SearchPage() {
  const [results, setResults] = useState([]);
  const [query, setQuery] = useState('');

  const handleSearch = async (value) => {
    setQuery(value);
    if (!value) {
      setResults([]);
      return;
    }
    // Load fuse.js only when user searches
    const Fuse = (await import('fuse.js')).default;
    const fuse = new Fuse(names);
    setResults(fuse.search(value));
  };

  return (
    
       handleSearch(e.target.value)}
      />
      
        {results.map((result) => (
          {result.item}
        ))}
      
    
  );
}

Conclusion

Lazy loading improves performance by splitting your bundle and loading code only when needed. Here's what you learned:

React.lazy() – Use in plain React apps for code splitting. It requires a default export and works with dynamic import().
Suspense – Wrap lazy components in Suspense and provide a fallback for the loading state.
Error Boundaries – Use them to catch chunk load failures and show a friendly error UI.
next/dynamic – Use in Next.js for the same benefits plus SSR control and built-in loading options.

Choose React.lazy for React-only projects and next/dynamic for Next.js. Combine them with Suspense and Error Boundaries for a solid lazy-loading setup.

Start by identifying your heaviest components (charts, modals, admin panels) and lazy load them. Measure your bundle size and Core Web Vitals before and after to see the impact.

How to Build a Fashion App That Helps You Organize Your Wardrobe

Mokshita V P — Tue, 14 Apr 2026 16:26:39 +0000

I used to spend too long deciding what to wear, even when my closet was full.

That frustration made the problem feel very clear to me: it was not about having fewer clothes. It was about having better organization, better visibility, and better guidance when making outfit decisions.

So I built a fashion web app that helps users organize their wardrobe, get outfit suggestions, evaluate shopping decisions, and improve recommendations over time using feedback.

In this article, I’ll walk through what the app does, how I built it, the decisions I made along the way, and the challenges that shaped the final result.

Table of Contents
What the App Does
Why I Built It
Tech Stack
Product Walkthrough (What Users See)
How I Built It
Challenges I Faced
What I Learned
What I Want to Improve Next
Future Improvements
Conclusion

What the App Does

At a high level, the app combines six core capabilities:

Wardrobe management
Outfit recommendations
Shopping suggestions
Discard recommendations
Feedback and usage tracking
Secure multi-user accounts

Users can upload clothing items, explore suggested outfits, and mark recommendations as helpful or not helpful. They can also rate outfits and track whether items are worn, kept, or discarded.

That feedback becomes structured data for improving future recommendation quality.

Why I Built It

I wanted to create something that felt personal and actually useful. A lot of fashion apps look polished, but they do not always help with everyday decisions. My goal was to build something that could make wardrobe management easier and outfit selection less overwhelming. The app needed to do three things well:

store each user’s wardrobe data
personalize recommendations
learn from user feedback over time .

That feedback loop mattered to me because it makes the app feel more alive instead of static.

Tech Stack

Here are the tools I used to built the app:

Frontend: React + Vite
Backend: FastAPI
Database: SQLite (local development)
Background jobs: Celery + Redis
Authentication: JWT (access + refresh token flow)
Deployment support: Docker and GitHub Codespaces

This ended up giving me a pretty modular setup, which helped a lot as features started increasing: fast frontend iteration, clean API boundaries, and room to evolve recommendations separately from UI.

Product Walkthrough (What Users See)

1. Onboarding and Account Setup

To start using the app, a user needs to register, verify their email, and complete some profile basics.

Each account is isolated, so wardrobe history and recommendations stay user-specific.

In this onboarding screen above, you can see account creation, email verification, and profile fields for body shape, height, weight, and style preferences.

2. Wardrobe Upload

Users can upload clothing images .

Image analysis labels each item and makes it searchable for recommendations. The wardrobe upload form shows image analysis results with category, dominant color, secondary color, and pattern details listed.

3. Outfit Recommendations

Users can request recommendations, then rate outputs.

Above you can see the outfit recommendation dashboard that shows ranked outfit cards with feedback and rating actions. Recommendations are ranked by a weighted scoring model.

4. Shopping and Discard Assistants

The app evaluates new items against existing wardrobe data and flags low-value wardrobe items that may be worth removing.

You can see the recommendation scores, written reasons (not just a binary decision), and styling guidance for each item above. It also features a "how to style it" incase the user still wants to keep the item.

How I Built It

1. Frontend Setup (React + Vite)

I used React + Vite because I wanted fast iteration and a clean component structure.

The frontend is split into feature areas like onboarding, wardrobe management, outfits, shopping, and discarded-item suggestions. I also keep API calls in a service layer so the UI components stay focused on rendering and interaction.

The snippet below is a simplified example of the API service pattern used in the app. It is not meant to be copy-pasted as-is, but it shows the same structure the frontend uses when talking to the backend.

Example API client pattern:

export async function getOutfitRecommendations(userId, params = {}) {
  const query = new URLSearchParams(params).toString();
  const url = `/users/\({userId}/outfits/recommend\){query ? `?${query}` : ""}`;

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${localStorage.getItem("access_token")}`,
    },
  });

  if (!response.ok) {
    throw new Error("Failed to fetch outfit recommendations");
  }

  return response.json();
}

Here's what's happening in that snippet:

URLSearchParams builds optional query strings like occasion, season, or limit.
The request path is user-scoped, which keeps each user’s recommendations isolated.
The Authorization header sends the access token so the backend can verify the session.
The response is checked before parsing so the UI can surface a useful error if the request fails.

This pattern kept the frontend simple and reusable as the number of API calls grew.

2. Backend Architecture with FastAPI

The backend is organized around clear route groups:

auth routes for register, login, refresh, logout, and sessions
user analysis routes
wardrobe CRUD routes
recommendation routes for outfits, shopping, and discard analysis
feedback routes for ratings and helpfulness signals

One of the most important design choices was enforcing ownership checks on user-scoped resources. That prevented one user from accessing another user’s wardrobe or feedback data.

The backend snippet below is another simplified example from the app’s route layer. It shows the request validation and orchestration logic, while the actual scoring work stays in the recommendation service.

@app.get("/users/{user_id}/outfits/recommend")
def recommend_outfits(user_id: int, occasion: str | None = None, season: str | None = None, limit: int = 10):
    user = get_user_or_404(user_id)
    wardrobe_items = get_user_wardrobe(user_id)

    if len(wardrobe_items) < 2:
        raise HTTPException(status_code=400, detail="Not enough wardrobe items")

    recommendations = outfit_generator.generate_outfit_recommendations(
        wardrobe_items=wardrobe_items,
        body_shape=user.body_shape,
        undertone=user.undertone,
        occasion=occasion,
        season=season,
        top_k=limit,
    )

    return {"user_id": user_id, "recommendations": recommendations}

Here's how to read that code:

get_user_or_404 loads the profile data needed for personalization.
get_user_wardrobe fetches only the current user’s items.
The minimum wardrobe check prevents the recommendation logic from running on incomplete data.
generate_outfit_recommendations handles the scoring logic separately, which keeps the route handler small and easier to test.
The response returns the results in a shape the frontend can consume directly.

That separation helped keep the API layer readable while the recommendation logic stayed isolated in its own service.

3. Recommendation Logic

I intentionally started with deterministic rules before introducing heavy ML. That made behavior easier to debug and explain.

The outfit recommender scores combinations using weighted signals:

$$\text{outfit score} = 0.4 \cdot \text{color harmony} + 0.4 \cdot \text{body-shape fit} + 0.2 \cdot \text{undertone fit}$$

The snippet below is a simplified example from the recommendation engine. It shows how the app combines multiple signals into a single score:

def score_outfit(combo, user_context):
    color_score = color_harmony.score(combo)
    shape_score = body_shape_rules.score(combo, user_context.body_shape)
    undertone_score = undertone_rules.score(combo, user_context.undertone)

    total = 0.4 * color_score + 0.4 * shape_score + 0.2 * undertone_score
    return round(total, 3)

The logic behind this approach is straightforward:

color harmony helps the outfit feel visually coherent
body-shape scoring helps the outfit feel flattering
undertone scoring helps the colors work better with the user’s profile

I used a similar structure for discard recommendations and shopping suggestions, but with different factors and thresholds.

4. Authentication and Secure Multi-user Design

Security was one of the most important parts of this build.

I implemented:

short-lived access tokens
refresh tokens with JTI tracking
token rotation on refresh
session revocation (single session and all sessions)
email verification and password reset flows

The snippet below is a simplified example of the refresh-token lifecycle used in the app. It shows the important control points rather than every helper function:

def refresh_access_token(refresh_token: str):
    payload = decode_jwt(refresh_token)
    jti = payload["jti"]

    token_record = db.get_refresh_token(jti)
    if not token_record or token_record.revoked:
        raise AuthError("Invalid refresh token")

    new_refresh, new_jti = issue_refresh_token(payload["sub"])
    token_record.revoked = True
    token_record.replaced_by_jti = new_jti

    new_access = issue_access_token(payload["sub"])
    return {"access_token": new_access, "refresh_token": new_refresh}

What this code is doing:

It decodes the refresh token and looks up its JTI in the database.
It rejects reused or revoked sessions, which helps prevent replay attacks.
It rotates the refresh token instead of reusing it.
It issues a fresh access token so the session stays valid without forcing the user to log in again.

This design made multi-device sessions safer and gave me server-side control over logout behavior.

5. Background Jobs for Long-running Operations

Image analysis can be expensive, especially when the app needs to classify clothing, analyze colors, and estimate body-shape-related signals. To keep the request path responsive, I added Celery + Redis support for background tasks.

That gave the app two modes:

synchronous processing for simpler local development
queued processing for heavier or slower jobs

That tradeoff mattered because it let me keep the developer experience simple without blocking the app during more expensive work.

6. Data Model and Feedback Capture

A recommendation system only improves if it captures the right signals.

So I added dedicated feedback tables for:

outfit ratings (1-5 + optional comments)
recommendation helpful/unhelpful feedback
item usage actions (worn/kept/discarded)

Here is the shape of one of those models:

class RecommendationFeedback(Base):
    __tablename__ = "recommendation_feedback"

    id = Column(Integer, primary_key=True)
    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
    recommendation_type = Column(String(50), nullable=False)
    recommendation_id = Column(Integer, nullable=False)
    helpful = Column(Boolean, nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow)

How to read this model:

user_id ties feedback to the person who gave it.
recommendation_type tells me whether the feedback belongs to outfits, shopping, or discard suggestions.
recommendation_id identifies the exact recommendation.
helpful stores the user’s direct response.
created_at makes it possible to analyze feedback trends over time.

This part of the system gives the app a real learning foundation, even though the feedback-to-model-update loop is still a future improvement.

Challenges I Faced

This was the section that taught me the most.

1. Image-heavy endpoints were slower than I wanted

The analyze and wardrobe upload flows were doing a lot of work at once: image validation, classification, color extraction, storage, and database writes.

At first, that made the request flow feel heavier than it should have.

What I changed:

I bounded concurrent image jobs so the app wouldn't try to do too much at once.
I separated slower jobs into background processing where possible.
I used load-test results to confirm which endpoints were actually expensive.

The practical effect was that heavy image requests stopped competing with each other so aggressively. Instead of letting many expensive tasks pile up inside the same request cycle, I limited the active work and pushed slower operations into the queue when needed.

Why this fixed it:

Bounding concurrency prevented the system from overloading CPU-bound tasks.
Moving expensive work into async jobs kept the main request/response cycle more responsive.
Load testing gave me evidence instead of guesswork, so I could tune the system based on real performance behavior.

In other words, I didn't just “optimize” the endpoint in theory. I changed the execution model so expensive analysis could not block every other request behind it.

2. JWT sessions needed real server-side control

A basic JWT setup is easy to get working, but it becomes less useful if you cannot revoke sessions or manage multiple devices cleanly.

What I changed:

I stored refresh tokens in the database.
I tracked token JTI values.
I rotated refresh tokens when users refreshed their session.
I added endpoints for logging out a single session or all sessions.

The important shift here was moving from “token exists, therefore session is valid” to “token exists, matches the database record, and has not been revoked or replaced.” That gave the server the authority to invalidate old sessions immediately.

Why this fixed it:

Server-side token tracking made revocation possible.
Rotation reduced the chance of token reuse.
Session management became visible to the user, which made the app feel more trustworthy.

This is what made logout-all and multi-device management work in a real way instead of just being cosmetic UI actions.

3. User data isolation had to be explicit

Because this is a multi-user app, I had to be careful that one account could never accidentally see another account’s wardrobe data.

What I changed:

I added ownership checks to user-scoped routes.
I kept all wardrobe and feedback queries filtered by user_id.
I used encrypted image storage instead of exposing raw paths.

In practice, this meant every route had to ask the same question: “Does this user own the resource they are trying to access?” If the answer was no, the request stopped immediately.

Why this fixed it:

Ownership checks made data access rules explicit.
User-filtered queries prevented accidental cross-account reads.
Encrypted storage improved privacy and reduced the risk of exposing image data directly.

That combination is what kept wardrobe data, feedback history, and images separated correctly across accounts.

The app includes the frontend, backend, Redis, Celery worker, and Celery Beat, so the first challenge was making the setup feel reproducible instead of fragile.

What I changed:

I defined the stack in Docker Compose.
I documented the required environment variables.
I kept the dev stack aligned with how the app runs in practice.

This removed a lot of setup ambiguity. Instead of asking someone to manually figure out how the frontend, backend, Redis, and workers fit together, I made the stack describe itself.

Why this fixed it:

Docker let contributors start the project with fewer manual steps.
Clear environment configuration reduced setup mistakes.
Matching the stack to the architecture made the app easier to understand and test.

That was important because the app depends on several moving parts, and the simplest way to make the project approachable was to make startup behavior predictable.

What I Learned

This project taught me a few important lessons:

Small features become much more valuable when they work together.
Feedback data is one of the strongest signals for improving recommendations.
Clean data modeling matters a lot when multiple users are involved.
Docker and clear setup instructions make a project much easier for other people to try.

I also learned that a project does not need to be huge to be useful. A focused app that solves one problem well can still feel meaningful.

What I Want to Improve Next

My roadmap from here:

Integrate feedback directly into ranking updates
Add visual analytics for recommendation quality trends
Improve mobile UX parity
Deploy with persistent cloud storage and production database defaults
Provide a public demo mode for easier evaluation

Future Improvements

There are still a few things I would like to add later:

a more advanced recommendation engine
visual analytics for user feedback
better mobile support
live deployment with persistent cloud storage
a public demo mode for easier testing

Conclusion

This project began as a personal frustration and turned into a full web application with authentication, wardrobe storage, recommendation logic, and feedback infrastructure.

The most rewarding part was seeing how practical software decisions, not just flashy UI, can help people make everyday choices faster.

If you want to explore or run the project, check out the repo. You can try the flows and share feedback. I would especially love input on recommendation quality, UX clarity, and what features would make this genuinely useful in daily life.

How to Build an Admin Dashboard Sidebar with shadcn/ui and Base UI

Vaibhav Gupta — Tue, 14 Apr 2026 16:25:08 +0000

Admin dashboards are one of the most common real-world UI components you will build as a React developer. At the heart of nearly every dashboard is a sidebar, a persistent navigation panel that organizes pages, tools, and features into a clean, scannable structure.

Building a sidebar from scratch involves much more than an

element. You need collapsible submenus, active state tracking across parent and child items, accessible keyboard navigation, a scroll area for long nav lists, and a consistent design system that holds together across screen sizes.

In this tutorial, you'll learn how to build a fully functional, accessible admin dashboard sidebar using shadcn/ui, a collection of beautifully designed, accessible React components, and a pre-built community block from Shadcn Space, which extends shadcn/ui with ready-to-use dashboard UI patterns.

By the end of this tutorial, you'll have a working sidebar that includes:

Grouped navigation sections with uppercase labels
Collapsible parent menu items with child links
Active state tracking across both parent and child items
A floating sidebar with an independent scroll area
A promotional card pinned inside the sidebar footer

Prerequisites
What You Will Build
Why shadcn/ui?
What is Shadcn Space?
How to Install the Sidebar Block
How to Understand the Folder Structure
How to Build the Page Layout
How to Build the AppSidebar Component
How to Define the Navigation Data
How to Build the NavMain Component
How to Handle Active States and Collapsible Menus
How to Style the Sidebar
Live Preview
Summary

Prerequisites

Before you start, make sure you have the following:

Node.js 18+ installed on your machine
Basic knowledge of React and TypeScript
Familiarity with Tailwind CSS utility classes
A package manager installed (npm, pnpm, yarn, or bun)

You don't need prior experience with shadcn/ui, but it helps to have read through the official docs at least once.

What You Will Build

In this article, you'll build a fully functional admin dashboard sidebar with the following features:

Floating sidebar shell: a card-style sidebar with rounded corners, a drop shadow, and a configurable width
Grouped navigation: navigation items organized under section labels like Dashboards, Pages, Apps, and Form Elements
Collapsible submenus: parent items like Blogs and Shadcn Forms that expand on click to reveal child links
Active state tracking: visual highlighting of the selected parent and child item at all times
Sidebar toggle: a trigger button in the page header that opens and closes the sidebar
Promotional card: a "Get Premium" card at the bottom of the sidebar scroll area

Why shadcn/ui?

shadcn/ui is a collection of beautifully designed, accessible React components built on top of Radix UI and styled with Tailwind CSS.

Instead of installing a traditional component library as a dependency, you copy components directly into your project using a CLI. This gives you full ownership of the code structure and styling. You can read every line, change anything, and the components never break because of a library update you didn't control.

Some key benefits of shadcn/ui include:

Accessible by default, built on Radix and Base UI primitives
Fully styled with Tailwind CSS utility classes
Zero lock-in: the code lives in your project, not inside node_modules
Works with Next.js, React, Astro, Vite, and other frameworks
A growing ecosystem of community-built blocks and registries

The Sidebar, Collapsible, ScrollArea, Card, and Button Components you'll use in this tutorial all come from shadcn/ui.

What is Shadcn Space?

Shadcn Space is an open-source library of pre-built UI blocks built on top of shadcn/ui. It provides ready-to-use dashboard layouts, sidebars, tables, cards, and other common admin UI patterns so you don't have to assemble them from individual primitives every time.

Each block in Shadcn Space is installable directly into your project using the shadcn CLI. Once installed, the code is yours: you can read it, extend it, and adapt it to your design system without any runtime dependency on Shadcn Space itself.

For this tutorial, you'll use the sidebar-06 block (it’s free to use), which is a floating admin sidebar with grouped navigation, collapsible submenus, and an integrated scroll area.

Shadcn Space also provides a companion Figma UI Kit that matches the design system used in the blocks, which is useful if you do design work alongside development.

You can explore the full block library and the getting-started documentation in the official Shadcn Space docs.

How to Set Up the Project

Start by creating a new Next.js project if you don't already have one:

npx shadcn@latest init --preset b0 --base base --template next

This command:

Creates a Next.js project
Configures Tailwind CSS
Sets up Base UI as the component foundation
Uses Nova style preset
Configures Lucide icons
Uses Inter font
Applies neutral theme tokens

Follow the prompts to configure your base color, CSS variables, and component output directory. This sets up the components/ui directory and the required Tailwind configuration that all shadcn/ui components depend on.

Once the initialization is complete, your components.json project will be created at the root of your project. This file tells the shadcn CLI where to place components, what path aliases you're using, and which styling configuration to follow.

Add this in components.json:

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

With shadcn/ui initialized, you can now pull in the sidebar-06 block from Shadcn Space. While Shadcn Space provides components for both Radix UI and Base UI, this tutorial uses the Base UI version. Run one of the following commands depending on your package manager:

npm:

npx shadcn@latest add @shadcn-space/sidebar-06

pnpm:

pnpm dlx shadcn@latest add @shadcn-space/sidebar-06

yarn:

yarn dlx shadcn@latest add @shadcn-space/sidebar-06

bun:

bunx --bun shadcn@latest add @shadcn-space/sidebar-06

This command fetches the block from the Shadcn Space registry and scaffolds all the required component files into your project automatically. It also installs any shadcn/ui primitives the block depends on (such as Sidebar, ScrollArea, Card, Button, and Collapsible) if they aren't already present in your components/ui directory.

You can preview the live block and find the installation command on their shadcn sidebar page.

How to Understand the Folder Structure

After installation, your project will contain the following new files:

app/
  sidebar-06/
    page.tsx                  ← Route entry point
assets/
  logo/
    logo.tsx                  ← Logo component
components/
  shadcn-space/
    blocks/
      sidebar-06/
        app-sidebar.tsx       ← Main sidebar shell
        nav-main.tsx          ← Navigation logic and rendering

Each file has a clearly defined responsibility:

app/sidebar-06/page.tsx: the route entry point that wires the sidebar into a page layout using SidebarProvider
assets/logo/logo.tsx: the logo component rendered in the sidebar header
components/shadcn-space/blocks/sidebar-06/app-sidebar.tsx: the main sidebar shell, including the header, scroll area, nav data, and promotional card
components/shadcn-space/blocks/sidebar-06/nav-main.tsx: all navigation rendering logic, including section labels, leaf items, collapsible parents, and active state management

You'll work through each of these files in detail in the sections below.

How to Build the Page Layout

Open app/sidebar-06/page.tsx. This file is the entry point for your dashboard page. It uses SidebarProvider to establish sidebar context across the page, and SidebarTrigger to render a toggle button inside the header.

import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar";
import { AppSidebar } from "@/components/shadcn-space/blocks/sidebar-06/app-sidebar";

const Page = () => {
  return (
    
      

      {/* Main content area */}
      
        
          
        
        
      
    
  );
};

export default Page;

Let's break down the key parts of this layout:

SidebarProvider wraps everything on the page. It manages the sidebar's open/closed state and passes it down to child components via React context. Any component that needs to read or change the sidebar state, including SidebarTrigger and AppSidebar, must be a descendant of SidebarProvider.

The --sidebar-width CSS custom property controls the rendered width of the sidebar. It's set inline using a type assertion (as React.CSSProperties) because TypeScript doesn't know about this custom property by default. Setting it here rather than in a CSS file keeps the width configurable on a per-page basis.

SidebarTrigger is a toggle button component that reads the sidebar open/closed state from the nearest SidebarProvider context and flips it on click. It renders in the header so users always have access to the toggle regardless of scroll position.

bg-muted on SidebarProvider creates the light gray outer background that makes the floating sidebar card visually stand out from the page.

How to Build the AppSidebar Component

Open components/shadcn-space/blocks/sidebar-06/app-sidebar.tsx. This component is the main sidebar shell. It composes shadcn/ui's Sidebar, SidebarHeader, and SidebarContent layout primitives and wraps the scrollable navigation area in a ScrollArea component to handle overflow independently.

"use client";

import {
  Sidebar,
  SidebarContent,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuItem,
} from "@/components/ui/sidebar";
import { ScrollArea } from "@/components/ui/scroll-area";
import { Card, CardContent } from "@/components/ui/card";
import { Button } from "@/components/ui/button";
import Logo from "@/assets/logo/logo";
import { NavItem, NavMain } from "@/components/shadcn-space/blocks/sidebar-06/nav-main";
import {
  AlignStartVertical,
  PieChart,
  CircleUserRound,
  ClipboardList,
  Notebook,
  NotepadText,
  Table,
  Languages,
  Ticket,
} from "lucide-react";

The "use client" directive at the top is required because this component uses React state (through NavMain) and event handlers, both of which require the component to run in the browser rather than being server-rendered by Next.js.

Inside app-sidebar.tsxthe navigation structure is defined as a flat array of NavItem objects. Each item belongs to one of three categories:

A section label marked with isSection: true and a label string. Renders as an uppercase group heading.
A leaf item has a title, icon, and href, but no children. Renders as a direct navigation link.
A parent item has a title, icon, and a children array of sub-items. Renders as a collapsible trigger.


export const navData: NavItem[] = [
  // Dashboards Section
  { label: "Dashboards", isSection: true },
  { title: "Analytics", icon: PieChart, href: "#" },
  { title: "CRM Dashboard", icon: ClipboardList, href: "#" },

  // Pages Section
  { label: "Pages", isSection: true },
  { title: "Tables", icon: Table, href: "#" },
  { title: "Forms", icon: ClipboardList, href: "#" },
  { title: "User Profile", icon: CircleUserRound, href: "#" },

  // Apps Section
  { label: "Apps", isSection: true },
  { title: "Notes", icon: Notebook, href: "#" },
  { title: "Tickets", icon: Ticket, href: "#" },
  {
    title: "Blogs",
    icon: Languages,
    children: [
      { title: "Blog Post", href: "#" },
      { title: "Blog Detail", href: "#" },
      { title: "Blog Edit", href: "#" },
      { title: "Blog Create", href: "#" },
      { title: "Manage Blogs", href: "#" },
    ],
  },

  // Form Elements Section
  { label: "Form Elements", isSection: true },
  {
    title: "Shadcn Forms",
    icon: NotepadText,
    children: [
      { title: "Button", href: "#" },
      { title: "Input", href: "#" },
      { title: "Select", href: "#" },
      { title: "Checkbox", href: "#" },
      { title: "Radio", href: "#" },
    ],
  },
  {
    title: "Form layouts",
    icon: AlignStartVertical,
    children: [
      { title: "Forms Horizontal", href: "#" },
      { title: "Forms Vertical", href: "#" },
      { title: "Forms Validation", href: "#" },
      { title: "Forms Examples", href: "#" },
      { title: "Forms Wizard", href: "#" },
    ],
  },
];

This flat array approach is intentionally simple to maintain. You don't need a nested tree structure because the NavMain component handles the rendering logic for each item type by inspecting each item's shape. Adding a new section, item, or submenu is as straightforward as appending a new object to the array.

How to Build the NavMain Component

Open components/shadcn-space/blocks/sidebar-06/nav-main.tsx. This file contains all the navigation rendering logic. Start with the type definition and the top-level NavMain function:

"use client";

import * as React from "react";
import { ChevronRight, LucideIcon } from "lucide-react";
import { cn } from "@/lib/utils";
import {
  Collapsible,
  CollapsibleTrigger,
  CollapsibleContent,
} from "@/components/ui/collapsible";
import {
  SidebarGroup,
  SidebarGroupLabel,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSub,
  SidebarMenuSubItem,
  SidebarMenuSubButton,
} from "@/components/ui/sidebar";

export type NavItem = {
  label?: string;
  isSection?: boolean;
  title?: string;
  icon?: LucideIcon;
  href?: string;
  children?: NavItem[];
};

export function NavMain({ items }: { items: NavItem[] }) {
  const [activeParent, setActiveParent] = React.useState(
    items.find((i) => !i.isSection)?.title || null
  );
  const [activeChild, setActiveChild] = React.useState(null);

  return (
    <>
      {items.map((item, index) => (
        
      ))}
    
  );
}

activeParent tracks which top-level nav item is currently selected. It initializes to the title of the first non-section item, so the sidebar always has a selection on first render, and you never show the sidebar with nothing highlighted. activeChild tracks which sub-item inside a collapsible menu is selected.

Both state values are passed down as props to each NavMainItem, so every item in the list can read the current selection and trigger updates to it.

How to Handle Active States and Collapsible Menus

The NavMainItem function branches into one of three rendering paths based on the shape of the incoming item.

How to Render Section Labels

if (item.isSection && item.label) {
  return (
    
      
        {item.label}
      
    
  );
}

Section labels use first:pt-0 to remove the top padding from the very first section, so the nav starts flush with the header.

How to Render Collapsible Parent Items

if (hasChildren && item.title) {
  return (
    
      
        
          
             setActiveParent(item.title!)}
                  className={cn(
                    "rounded-md text-sm font-medium px-3 py-2 h-9 transition-colors cursor-pointer",
                    isParentActive ? "bg-primary! text-primary-foreground!" : ""
                  )}
                >
                  {item.icon && }
                  {item.title}
                  
                
              }
            />
            
              
                {item.children!.map((child, index) => (
                  
                ))}
              
            
          
        
      
    
  );
}

A useEffect inside NavMainItem syncs the local isOpen state with activeParent so that when a different parent is activated, the previously open collapsible stays open until the user explicitly closes it:

React.useEffect(() => {
  if (isParentActive) {
    setIsOpen(true);
  }
}, [isParentActive]);

The ChevronRight icon rotates 90 degrees when the submenu is open, using a Tailwind transition class:

How to Render Leaf Items

if (item.title) {
  return (
    
      
        
           {
              setActiveParent(item.title!);
              setActiveChild(null);
            }}
            className={cn(
              "rounded-md text-sm font-medium px-3 py-2 h-9 transition-colors cursor-pointer",
              isParentActive ? "bg-primary! text-primary-foreground!" : ""
            )}
            render={}
          >
            {item.icon && }
            {item.title}
          
        
      
    
  );
}

The render prop on SidebarMenuButton replaces the default button element with an tag. This preserves correct anchor link semantics and accessibility while keeping the button's visual styling. When a leaf item is clicked, activeChild is reset to null since there is no child to track.

How to Render Child Items in a Submenu

The NavMainSubItem function handles sub-items inside a collapsible. When a child is clicked, it sets both activeChild to itself and activeParent to its parent's title so the parent item remains visually highlighted:

if (item.title) {
  return (
    
       {
          setActiveParent(parentTitle || "");
          setActiveChild(item.title!);
        }}
        render={{item.title}}
      />
    
  );
}

The child uses a different active style (bg-muted with text-foreground) compared to the parent (bg-primary with text-primary-foreground). This visual distinction makes it easy to see both which section you are in and which specific page is currently active.

Sub-items also support nesting. If a child item itself has a children array, NavMainSubItem renders another Collapsible with a nested SidebarMenuSub, allowing you to build multi-level navigation trees without any changes to the data structure.

The full AppSidebar render function puts all of the pieces together:

export function AppSidebar() {
  return (
    
      

        {/* Header with Logo */}
        
          
            
              
                
              
            
          
        

        {/* Scrollable Navigation Content */}
        
          
            
              
            

            {/* Promotional Card */}
            
              
                
                  
                  
                    
                      
                        Grab Pro Now
                      
                      
                        Customize your admin
                      
                    
                    
                  
                
              
            
          
        

      
    
  );
}

Let's walk through the key styling decisions:

variant="floating" gives the sidebar a card-like appearance with rounded corners and a subtle drop shadow. It visually lifts the sidebar off the background rather than making it flush with the page edge like a standard sidebar would.

[&_[data-slot=sidebar-inner]]:h-full is an arbitrary Tailwind variant selector that targets shadcn/ui's internal sidebar slot element. Without this, the sidebar inner container doesn't fill the full available height, which breaks the layout. The data-slot attribute is how shadcn/ui identifies internal sub-elements of compound components.

h-[calc(100vh-100px)] on ScrollArea makes the navigation list independently scrollable. The 100px offset accounts for the sidebar header and padding, so the scroll area doesn't overflow the viewport. The rest of the page layout remains static while the nav scrolls.

The bg-secondary card at the bottom of the scroll area is a common admin dashboard pattern, a soft prompt for an upgrade or onboarding action that lives passively in the sidebar without blocking navigation.

For more details on the Sidebar component's API, variants, and configuration options, refer to the official shadcn/ui sidebar docs.

Live Preview

Summary

Congratulations! You have now built a complete, production-ready admin dashboard sidebar using shadcn/ui and a community block from Shadcn Space.

Here is a recap of everything you covered:

Setting up a Next.js project with shadcn/ui initialized and a pre-built sidebar block installed from Shadcn Space
Using SidebarProvider and SidebarTrigger to manage the sidebar open/closed state across a page layout through React context
Defining navigation data as a flat array of typed NavItem objects covering section labels, leaf items, and collapsible parent items
Rendering all three item types from a single navData source in the NavMain and NavMainItem components
Tracking activeParent and activeChild state in a single location and passing them as props so every item can read and update the shared selection state
Using Collapsible with a useEffect sync to keep parent items open when they are active, and animate the chevron icon on expand and collapse
Applying the floating variant, an arbitrary Tailwind slot selector, and ScrollArea with a calculated height to produce a polished, production-appropriate sidebar layout

This pattern scales well beyond what you built here. You can extend NavItem with additional fields like badge counts, permission flags, or external link indicators. You can swap in real href values and connect activeParent and activeChild to your router so the selection always reflects the current URL. You can also add more sections to navData without touching any rendering logic.

For a quick checkout, we have used the Shadcn Space free Shadcn dashboard block in this dashboard shell.

If you want to explore more pre-built admin UI blocks, components, and templates built on top of shadcn/ui, you can browse the full library at Shadcn Space.

Resources

How to Build Responsive and Accessible UI Designs with React and Semantic HTML

Gopinath Karunanithi — Tue, 07 Apr 2026 17:06:31 +0000

Building modern React applications requires more than just functionality. It also demands responsive layouts and accessible user experiences.

By combining semantic HTML, responsive design techniques, and accessibility best practices (like ARIA roles and keyboard navigation), developers can create interfaces that work across devices and for all users, including those with disabilities.

This article shows how to design scalable, inclusive React UIs using real-world patterns and code examples.

Prerequisites
Overview
Why Accessibility and Responsiveness Matter
Core Principles of Accessible and Responsive Design
Using Semantic HTML in React
Structuring a Page with Semantic Elements
Building Responsive Layouts
Accessibility with ARIA
Keyboard Navigation
Focus Management
Forms and Accessibility
Responsive Typography and Images
Building a Fully Accessible Responsive Component (End-to-End Example)
Testing Accessibility
Best Practices
When NOT to Overuse Accessibility Features
Future Enhancements
Conclusion

Prerequisites

Before following along, you should be familiar with:

React fundamentals (components, hooks, JSX)
Basic HTML and CSS
JavaScript ES6 features
Basic understanding of accessibility concepts (helpful but not required)

Overview

Modern web applications must serve a diverse audience across a wide range of devices, screen sizes, and accessibility needs. Users today expect seamless experiences whether they are browsing on a desktop, tablet, or mobile device – and they also expect interfaces that are usable regardless of physical or cognitive limitations.

Two essential principles help achieve this:

Responsive design, which ensures layouts adapt to different screen sizes
Accessibility, which ensures applications are usable by people with disabilities

In React applications, these principles are often implemented incorrectly or treated as afterthoughts. Developers may rely heavily on div-based layouts, ignore semantic HTML, or overlook accessibility features such as keyboard navigation and screen reader support.

This article will show you how to build responsive and accessible UI designs in React using semantic HTML. You'll learn how to:

Structure components using semantic HTML elements
Build responsive layouts using modern CSS techniques
Improve accessibility with ARIA attributes and proper roles
Ensure keyboard navigation and screen reader compatibility
Apply best practices for scalable and inclusive UI design

By the end of this guide, you'll be able to create React interfaces that are not only visually responsive but also accessible to all users.

Why Accessibility and Responsiveness Matter

Responsive and accessible design isn't just about compliance. It directly impacts usability, performance, and reach.

Accessibility benefits:

Supports users with visual, motor, or cognitive impairments
Improves SEO and content discoverability
Enhances usability for all users

Responsiveness benefits:

Ensures consistent UX across devices
Reduces bounce rates on mobile
Improves performance and scalability

Ignoring these principles can result in broken layouts on smaller screens, poor screen reader compatibility, and limited reach and usability.

Core Principles of Accessible and Responsive Design

Before diving into the code, it’s important to understand the foundational principles.

1. Semantic HTML First

Semantic HTML refers to using HTML elements that clearly describe their meaning and role in the interface, rather than relying on generic containers like

or .These elements provide built-in accessibility, improve SEO, and make code more readable.

For example:

Non-semantic:

Submit

Semantic:

Another example:

Non-semantic:

My App

Semantic:

My App

Using semantic elements such as

, and

Then, React can enhance it with validation, dynamic feedback, or animations.

By prioritizing functionality first and enhancements later, you ensure your application remains usable in a wide range of real-world scenarios.

4. Keyboard Accessibility

Keyboard accessibility ensures that users can navigate and interact with your application using only a keyboard. This is critical for users with motor disabilities and also improves usability for power users.

Key aspects of keyboard accessibility include:

Ensuring all interactive elements (buttons, links, inputs) are focusable
Maintaining a logical tab order across the page
Providing visible focus indicators (for example, outline styles)
Supporting keyboard events such as Enter and Space

Bad Example (Not Accessible)

Submit

This element:

Cannot be focused with a keyboard
Does not respond to Enter/Space
Is invisible to screen readers

Good Example

This automatically supports:

Keyboard interaction
Focus management
Screen reader announcements

Custom Component Example (if needed)

 {
    if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault();
      handleClick();
    }
  }}
>
  Submit

But only use this when native elements aren't sufficient.

These principles form the foundation of accessible and responsive design:

Use semantic HTML to communicate intent
Design for mobile first, then scale up
Enhance progressively for better compatibility
Ensure full keyboard accessibility

Applying these early prevents major usability and accessibility issues later in development.

Using Semantic HTML in React

As we briefly discussed above, semantic HTML plays a critical role in both accessibility (a11y) and code readability. Semantic elements clearly describe their purpose to both developers and browsers, which allows assistive technologies like screen readers to interpret and navigate the UI correctly.

For example, when you use a

Why this is better:

The
It is automatically focusable and keyboard accessible
It supports Enter and Space key activation by default
Screen readers correctly announce it as a button

This reduces complexity while improving accessibility and usability.

Why all this matters:

There are many reasons to use semantic HTML.

First, semantic elements like


  );
}

How this works:

role="dialog" identifies the element as a modal dialog
aria-modal="true" indicates that background content is inactive
aria-labelledby connects the dialog to its visible title for screen readers
tabIndex={-1} allows the dialog container to receive focus programmatically
Focus is moved to the dialog when it opens
Pressing Escape closes the modal, which is a standard accessibility expectation

This ensures that users can understand, navigate, and exit the modal using both keyboard and assistive technologies.

Key ARIA Attributes

1. role

Defines the type of element and its purpose. For example, role="dialog" tells assistive technologies that the element behaves like a modal dialog.

2. aria-label

Provides an accessible name for an element when visible text is not sufficient. Screen readers use this label to describe the element to users.

3. aria-hidden

Indicates whether an element should be ignored by assistive technologies. For example, aria-hidden="true" hides decorative elements from screen readers.

4. aria-live

Used for dynamic content updates. It tells screen readers to announce changes automatically without requiring user interaction (for example, form validation messages or notifications).

Example: Accessible Dropdown (Custom Component)

function Dropdown({ isOpen, toggle }) {
  return (
    
      

      {isOpen && (
        
          
            
          
          
            
          
        
      )}
    
  );
}

How this works:

aria-expanded indicates whether the dropdown is open or closed
aria-controls links the button to the dropdown content via its id
The
The
- elements provide a natural list structure
- Using elements ensures proper navigation behavior and accessibility
Why this approach is correct:
- It follows standard web patterns instead of application-style menus
- It avoids misusing ARIA roles like role="menu", which require complex keyboard handling
- Screen readers can correctly interpret the structure without additional roles
- It keeps the implementation simple, accessible, and maintainable
If you need advanced menu behavior (like arrow key navigation), then ARIA menu roles may be appropriate – but only when fully implemented according to the ARIA Authoring Practices.

Note: Most dropdowns in web applications are not true "menus" in the ARIA sense. Avoid using role="menu" unless you are implementing full keyboard navigation (arrow keys, focus management, and so on).

Keyboard Navigation

Keyboard navigation ensures that users can fully interact with your application using only a keyboard, without relying on a mouse. This is essential for users with motor disabilities, but it also benefits power users and developers who prefer keyboard-based workflows.

In a well-designed interface, users should be able to:
- Navigate through interactive elements using the Tab key
- Activate buttons and links using Enter or Space
- Clearly see which element is currently focused
In the example below, we’ll look at common mistakes in keyboard handling and why relying on native HTML elements is usually the better approach.

Example:
Avoid adding custom keyboard handlers to native elements like
This automatically supports:
- Enter and Space key activation
- Focus management
- Screen reader announcements
Adding manual keyboard event handlers here is unnecessary and can introduce bugs or inconsistent behavior.

What this example shows:
Avoid manually handling keyboard events for native interactive elements like
Why this works:
- Supports both Enter and Space key activation by default
- Is focusable and participates in natural tab order
- Provides built-in accessibility roles and screen reader announcements
- Reduces the need for additional logic or ARIA attributes
Adding custom keyboard handlers (like onKeyDown) to native elements is unnecessary and can introduce bugs or inconsistent behavior. Always prefer native HTML elements for interactivity whenever possible.

Avoiding Common Keyboard Traps

One of the most common keyboard accessibility issues is “trapping users inside interactive components”, such as modals or custom dropdowns. This happens when focus is moved into a component but can't escape using Tab, Shift+Tab, or other keyboard controls. Users relying on keyboards may become stuck, unable to navigate to other parts of the page.

In the example below, you'll see a simple modal that tries to set focus, but doesn’t manage Tab behavior properly.
```
function Modal({ isOpen }) {
  const ref = React.useRef();

  React.useEffect(() => {
    if (isOpen) ref.current?.focus();
  }, [isOpen]);

  return (
    
      
    
  );
}
```
What this code shows:
- When the modal opens, focus is moved to the Close button using ref.current.focus()
- The modal uses role="dialog" to communicate its purpose
There are some issues with this code that you should be aware of. First, tabbing inside the modal may allow focus to move outside the modal if additional focusable elements exist.

Users may also become trapped if no mechanism returns focus to the triggering element when the modal closes.

There's also no handling of Shift+Tab or cycling focus is present.

This demonstrates a partial focus management, but it’s not fully accessible yet.

To improve focus management, you can trap focus within the modal by ensuring that Tab and Shift+Tab cycle only through elements inside the modal.

You can also return focus to the trigger: when the modal closes, return focus to the element that opened it.

Example improvement (conceptual):
```
function Modal({ isOpen, onClose, triggerRef }) {
  const modalRef = React.useRef();

  React.useEffect(() => {
    if (isOpen) {
      modalref.current?.focus();
      // Add focus trap logic here
    } else {
      triggerref.current?.focus();
    }
  }, [isOpen]);

  return (
    
      
    
  );
}
```
Remember that this modal is not fully accessible without focus trapping. In production, use a library like focus-trap-react, react-aria, or Radix UI.

Key points:
- tabIndex={-1} allows the div to receive programmatic focus
- Focus trap ensures users cannot tab out unintentionally
- Returning focus preserves context, so users can continue where they left off
Best practices:
- Always move focus into modals
- Return focus to the trigger element when closed
- Ensure Tab cycles correctly
As a general rule, always prefer native HTML elements for interactivity. Only implement custom keyboard handling when building advanced components that cannot be achieved with standard elements.

Focus Management

Focus management is the practice of controlling where keyboard focus goes when users interact with components such as modals, forms, or interactive widgets. Proper focus management ensures that:
- Users relying on keyboards or assistive technologies can navigate seamlessly
- Focus does not get lost or trapped in unexpected places
- Users maintain context when content updates dynamically
The example below shows a common approach that only partially handles focus:

Bad Example:
```
// Bad Example: Automatically focusing input without context
const ref = React.useRef();
React.useEffect(() => {
  ref.current?.focus();
}, []);
```
In the above code, the input receives focus as soon as the component mounts, but there’s no handling for returning focus when the user navigates away.

If this input is inside a modal or dynamic content, users may get lost or trapped. There aren't any focus indicators or context for assistive technologies.

This is a minimal solution that can cause confusion in real applications.

Improved Example:
```
// Improved Example: Managing focus in a modal context
function Modal({ isOpen, onClose, triggerRef }) {  
const dialogRef = React.useRef();

  React.useEffect(() => {
    if (isOpen) {
      dialogRef.current?.focus();
    } else if (triggerRef?.current) {
      triggerref.current?.focus();
    }
  }, [isOpen]);

  React.useEffect(() => {
    function handleKeyDown(e) {
      if (e.key === 'Escape') {
        onClose();
      }
    }

    if (isOpen) {
      document.addEventListener('keydown', handleKeyDown);
    }

    return () => {
      document.removeEventListener('keydown', handleKeyDown);
    };
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  return (
    
      Modal Title
      
      
    
  );
}
```
Explanation:
- tabIndex={-1} enables the dialog container to receive focus
- Focus is moved to the modal when it opens, ensuring keyboard users start in the correct context
- Focus is returned to the trigger element when the modal closes, preserving user flow
- aria-labelledby provides an accessible name for the dialog
- Escape key handling allows users to close the modal without a mouse
Note: For full accessibility, you should also implement focus trapping so users cannot tab outside the modal while it is open.

Tip: In production applications, use libraries like react-aria, focus-trap-react, or Radix UI to handle focus trapping and accessibility edge cases reliably.

Also, keep in mind here that the document-level keydown listener is global, which affects the entire page and can conflict with other components.
```
document.addEventListener('keydown', handleKeyDown);
```
A safer alternative is to scope it to the modal:
```
 {
    if (e.key === 'Escape') onClose();
  }}
>
```
For simple cases, attach onKeyDown to the dialog instead of the document.

Best Practice:

For complex components, use libraries like focus-trap-react or react-aria to manage focus reliably, especially for modals, dropdowns, and popovers.

Forms and Accessibility

Forms are critical points of interaction in web applications, and proper accessibility ensures that all users – including those using screen readers or other assistive technologies – can understand and interact with them effectively.

Proper labeling means that every input field, checkbox, radio button, or select element has an associated label that clearly describes its purpose. This allows screen readers to announce the input meaningfully and helps keyboard-only users understand what information is expected.

In addition to labeling, form accessibility includes:
- Providing clear error messages when input is invalid
- Ensuring error messages are announced to assistive technologies
- Maintaining logical focus order so users can navigate inputs easily
Bad Example:
Why this isn't good:
- This input relies only on a placeholder for context
- Screen readers may not announce the purpose of the field clearly
- Once a user starts typing, the placeholder disappears, leaving no guidance
- Keyboard-only users may not have enough context to know what to enter
Good Example:
```
Name
```
Why this is better:
- The is explicitly associated with the input via htmlFor / id
- Screen readers announce "Name" before the input, providing clear context
- Users navigating with Tab understand the field’s purpose
- The label persists even when the user types, unlike a placeholder
Error Handling:
```
Name



  Name is required
```
Explanation
- aria-describedby links the input to the error message using the element’s id
- Screen readers announce the error message when the input is focused
- aria-invalid="true" indicates that the field currently contains an error
- role="alert" ensures the error message is announced immediately when it appears
This creates a clear relationship between the input and its validation message, improving usability for screen reader users.

Tip: Only apply aria-invalid and error messages when validation fails. Avoid marking fields as invalid before user interaction.

Responsive Typography and Images

Responsive typography and images ensure that your content remains readable and visually appealing across a wide range of devices, from small smartphones to large desktop monitors.

This is important, because text should scale naturally so it remains legible on all screens, and images should adjust to container sizes to avoid layout issues or overflow. Both contribute to a better user experience and accessibility

In this section, we’ll cover practical ways to implement responsive typography and images in React and CSS.
```
h1 {
  font-size: clamp(1.5rem, 2vw, 3rem);
}
```
In this code:
- The clamp() function allows text to scale fluidly:
- The first value (1.5rem) is the “minimum font size”
- The second value (2vw) is the “preferred size based on viewport width”
- The third value (3rem) is the “maximum font size”
- This ensures headings are “readable on small screens” without becoming too large on desktops
Alternative methods include using media queries to adjust font sizes at different breakpoints

Responsive Images:
In this code, responsive images adapt to different screen sizes and resolutions to prevent layout issues or slow loading times. Key techniques include:

1. Fluid images using CSS:
```
img {
     max-width: 100%;
     height: auto;
   }
```
This makes sure that images never overflow their container and maintains aspect ratio automatically.

2. Using srcset for multiple resolutions:
This provides different image files depending on screen size or resolution and reduces loading times and improves performance on smaller devices.

3. Always include descriptive alt text

This is critical for screen readers and accessibility. It also helps users understand the image if it cannot be loaded.

Tip: Combine responsive typography, images, and flexible layout containers (like CSS Grid or Flexbox) to create interfaces that scale gracefully across all devices and maintain accessibility.

4. Ensure Sufficient Color Contrast

Low contrast text can make content unreadable for many users.
```
.bad-text {
  color: #aaa;
}

.good-text {
  color: #222;
}
```
Use tools like WebAIM Contrast Checker and Chrome DevTools Accessibility panel to check your color contrasts. Also note that WCAG AA requires 4.5:1 contrast ratio for normal text.

Building a Fully Accessible Responsive Component (End-to-End Example)

To understand how responsiveness and accessibility work together in practice, let’s build a reusable accessible card component that adapts to screen size and supports keyboard and screen reader users.

Step 1: Component Structure (Semantic HTML)
```
function ProductCard({ title, description, onAction }) {
  return (
    
      {title}
      {description}
      
    
  );
}
```
Why This Works
- provides semantic meaning for standalone content
- establishes a proper heading hierarchy
Step 2: Responsive Styling
```
.card {
  padding: 16px;
  border: 1px solid #ddd;
  border-radius: 8px;
}

@media (min-width: 768px) {
  .card {
    padding: 24px;
  }
}
```
This ensures comfortable spacing on mobile and improved readability on larger screens.

Step 3: Accessibility Enhancements
The visible button text provides a clear and accessible label, so no additional ARIA attributes are needed.

Step 4: Keyboard Focus Styling
```
button:focus {
  outline: 2px solid blue;
  outline-offset: 2px;
}
```
Focus indicators are essential for keyboard users.

Step 5: Using the Component
```
function App() {
  return (
    
       alert('Clicked')}
      />
    
  );
}
```
Key Takeaways

This simple component demonstrates:
- Semantic HTML structure
- Responsive design
- Built-in accessibility via native elements
- Minimal ARIA usage
In real-world applications, this pattern scales into entire design systems.

Testing Accessibility

Accessibility should be validated continuously, not just at the end of development. There are various automated tools you can use to help you with this process:
- Lighthouse (built into Chrome DevTools)
- axe DevTools for detailed audits
- ESLint plugins for accessibility rules
Manual Testing

But automated tools cannot catch everything. Manual testing is essential to make sure users can navigate using only the keyboard and use a screen reader (NVDA or VoiceOver. You should also test zoom levels (up to 200%) and check the color contrast manually.

Example: ESLint Accessibility Plugin
```
npm install eslint-plugin-jsx-a11y --save-dev
```
This helps catch accessibility issues during development.

Best Practices
- Use semantic HTML first
- Avoid unnecessary ARIA
- Test keyboard navigation
- Design mobile-first
- Ensure color contrast
- Use consistent spacing
When NOT to Overuse Accessibility Features
- Avoid adding ARIA when native HTML works
- Do not override browser defaults unnecessarily
- Avoid complex custom components without accessibility support
Future Enhancements
- Design systems with accessibility built-in
- Automated accessibility testing in CI/CD
- Advanced focus management libraries
- Accessibility-first component libraries
Conclusion

Building responsive and accessible React applications is not a one-time effort—it is a continuous design and engineering practice. Instead of treating accessibility as a checklist, developers should integrate it into the core of their component design process.

If you are starting out, focus on using semantic HTML and mobile-first layouts. These two practices alone solve a large percentage of accessibility and responsiveness issues. As your application grows, introduce ARIA enhancements, keyboard navigation, and automated accessibility testing.

The key is to build interfaces that work for everyone by default. When responsiveness and accessibility are treated as first-class concerns, your React applications become more usable, scalable, and future-proof.

How to Build an Interactive University Ranking System Using React and Data Viz Tools

Daria Filozop — Wed, 25 Mar 2026 21:02:53 +0000

Hi! I'm Daria, and I'm a software engineering student with a keen interest in data visualization. I've been actively exploring various visualization tools through small pet projects, and I'd like to share my latest demo with you.

In this tutorial, we'll build a project that displays the historical rankings of universities around the world. It's interesting to check out and analyze which institutions consistently maintain their top-tier positions and which ones experience significant movement up or down the rankings over the years.

While building the dashboard, we'll load and structure the dataset, display all important information in a pivot table, and then create charts to visualize the top 10 universities and their ranking trends over time.

Even though we'll walk through this specific example here, you can apply this same approach to many other datasets to build data viz dashboards.

Tech Stack

Let’s talk about the tools we’ll be using so you know what you’ll need to have before following along.

First, we’ll use React, which is a popular JavaScript library for building interactive web interfaces. It helps create reusable components and manage data efficiently. According to the 2025 Stack Overflow Developer Survey, React is the second most popular web framework.

We’ll also use Flexmonster Pivot Table, a web component for displaying data in a table format. In general, pivot tables are widely used for data visualization because they allow you to quickly group, aggregate, filter, and explore large datasets from different perspectives.

With Flexmonster, you can easily create reports and customize your information. It also integrates smoothly with almost all popular modern frameworks (like React, which we’re using here!).

Next, we have ECharts, which complements the detailed data provided by the pivot table. It’s a powerful, open-source charting library that’ll give us the visual insights we need, offering over 20 chart types to effectively visualize historical university ranking trends.

Finally, we’ll use the World University Rankings Dataset. It contains data from three global rankings (THE, ARWU, and CWUR), providing information about well-known universities from 2012 to 2015 for detailed analytical research. The dataset size is 186.38 kB.

As a small disclaimer, this tutorial uses React, so some familiarity with it will help you follow along. But actually, you can use any other framework that's convenient for you. Flexmonster Pivot Table offers many integrations with popular frameworks, including Angular, Vue, Svelte, and more.

When we’re done with the project, we’ll get an interactive dashboard like this:

So now that you’re familiar with the tools, let’s get started!

Flexmonster Pivot Table Setup

To get started, you’ll need to integrate Flexmonster into your React project. I’ll walk you through how it works with React, but you can use other frameworks, too. You can find complete instructions in the Flexmonster docs.

First, create a React application using Vite:

npm create vite@latest flexmonster-project -- --template react

Also, don’t forget to install npm dependencies:

cd flexmonster-project
npm install

Next, we’ll install the Flexmonster wrapper for React. To do this, use this command:

npm install -g flexmonster-cli
flexmonster add react-flexmonster

Then add Flexmonster styles and the component to your App.jsx file:

import FlexmonsterReact from "react-flexmonster";
import "flexmonster/flexmonster.css";

Loading and Displaying the Data

Now it’s time to create a report object. This is a configuration that defines how the pivot table should load and display data. It describes how the fields should be interpreted, and how the table should organize and aggregate the information.

The first part of this is dataSource. It defines where the data comes from and how it should be read by the pivot table (format of the dataset, location of the file, and the structure of the fields that will be used).

In our case, we'll load a CSV file that contains the university rankings dataset and define the fields that will appear in the pivot table:

  const report = {
        dataSource: {
            type: "csv",
            filename: "/data/world-university-rankings.csv",
            mapping: {
                world_rank: { type: "number", caption: "World Rank" },
                institution: { type: "string" },
                country: { type: "string" },
                score: { type: "number", caption: "Score" },
                year: { type: "number", caption: "Year" },
            },
        },
…
}

The second part is the slice section. It defines which subset of the dataset will be displayed and how it should be organized. There, you'll render a table by setting measures, rows, and columns. You can also set the flatOrder property, where you define the order of the fields in the flat form.

You can find more detailed information about the Slice Object here. There are lots of interesting functional possibilities!

const report = {
…
       slice: {
            rows: [{ uniqueName: "institution" }],
            columns: [{ uniqueName: "[Measures]" }],
            measures: [
                { uniqueName: "world_rank", aggregation: "min" },
                {
                    uniqueName: "year",
                    aggregation: "none",
                    filter: { members: [`year.[${selectedYear}]`] },
                },
            ],
            flatOrder: ["institution", "world_rank"],
        },
        options: {
            grid: { type: "flat", showGrandTotals: "off" },
        },
    };

You’ll also need to include Flexmonster inside the React component. In this example, we'll include the FlexmonsterReact tag in JSX and pass the report object (which we defined earlier) as a property. You can do that with this code snippet:

As a result, we've got pivot table with all the info about the universities:

Creating Charts

For some users, charts are easier to understand than tables, so let’s also create some now. I decided to display the top 10 universities in the world using bar charts. Bar charts are commonly used to compare values between categories, and they're quite useful for highlighting rankings or top performers.

We'll use ECharts here, but you can easily integrate Flexmonster with the most convenient chart library for you.

As a first step, make sure to install ECharts in your project:

npm install echarts

To prepare our data for display in the charts, we’ll create the prepareData() function. This function picks out the universities' names and their ranks, removes any invalid data, sorts it by rank, and keeps only the top 10. It returns two arrays: one with the names (for chart labels) and another with the rankings (for chart values):

const prepareData = (rawData) => {
    const rows = rawData.data
        .map((r) => ({ name: r.r0, rank: r.v0 }))
        .filter((r) => r.name && !isNaN(r.rank))
        .sort((a, b) => a.rank - b.rank)
        .slice(0, 10);
    return {
        labels: rows.map((r) => r.name).reverse(),
        values: rows.map((r) => r.rank).reverse(),
    };
};

Next, we'll set up chart options. You’ll need to decide in what form your dataset will be displayed: in this example, we'll choose a bar chart. We'll also set the title (here "Top 10 Universities by World Rank"), x-axis (shows the rank numbers) and y-axis (shows universities names), and tooltip, which shows info when you hover over a bar.

Also, don't forget to initialize the chart and apply these options. You can do all this with this code snippet:

const drawChart = (rawData) => {
    const { labels, values } = prepareData(rawData);
    const options = {
        title: {
            text: "Top 10 Universities by World Rank",
            left: "center",
            textStyle: { fontSize: 20, fontWeight: "bold" },
        },
        tooltip: { trigger: "axis", axisPointer: { type: "shadow" } },
        xAxis: { type: "value", name: "Rank" },
        yAxis: { type: "category", data: labels },
        series: [{ type: "bar", data: values, barMaxWidth: 30 }],
    };
    chartInstance = echarts.init(chartRef.current);
    chartInstance.setOption(options);
};

Also, an important part of chart configuration is the updateCharts() function, which redraws the chart when needed:

const updateChart = (rawData) => {
    if (chartInstance) chartInstance.dispose();
    drawChart(rawData);
};

So now we can see the charts we've created! This might look a bit basic and really hard to read, but don’t worry – we’ll make it look nicer and easier to understand in a later section.

Adding Year Filtering Buttons

You might have noticed that the dataset contains ratings for different years (from 2012 to 2015). It would be great if we could use the whole dataset, not just information for one year.

To manage this, we'll create filtering buttons for each year to provide more straightforward navigation.

First, we’ll add a div element which contains buttons for each year:


    {[2012, 2013, 2014, 2015].map((year) => (
        
    ))}

In the above code snippet, you can see that each button calls handleYearChange(year) when being clicked. Let’s now examine what this handler does:

const handleYearChange = (year) => {
    setSelectedYear(year);

    const pivot = pivotRef.current?.flexmonster;
    if (pivot) {
        const newReport = {
            ...report,
            slice: {
                ...report.slice,
                measures: [
                    { uniqueName: "world_rank", aggregation: "min" },
                    {
                        uniqueName: "year",
                        aggregation: "none",
                        filter: { members: [`year.[${year}]`] },
                    },
                ],
            },
        };
        pivot.setReport(newReport);
    }
};

This function modifies the pivot table report to filter by that year, and refreshes the table. This way, clicking a button instantly shows only the data for the chosen year.

And now we've got buttons which display years from our dataset:

Styling

Finally, here’s my favorite part of every project: customization! I love experimenting with different styles and choosing the most appropriate one.

For this dashboard, I chose light violet and white colors to make the interface clean and easy to read. I personally associate the university vibe with these colors, so I think they match our dashboard perfectly. So let's go step by step through it.

The main container defines the overall layout and background. It centers the content on the page, adds some spacing, and sets the base font and colors.

.app-container {
    min-height: 100vh;
    width: 100vw;
    padding: 32px;
    display: flex;
    flex-direction: column;
    align-items: center;

    background: #ebe6f7;
    font-family: "Inter", system-ui, -apple-system, sans-serif;
    color: #1b2a4e;
}

Next, we'll style the year filter buttons. They have rounded corners, a soft shadow, and a small hover effect so the interface feels interactive. The active button gets a violet background so it’s easy to see which year is selected.

.year-btn {
    padding: 10px 20px;
    background: #ffffff;
    border: 1px solid #cdd2e0;
    border-radius: 8px;
    cursor: pointer;
}

.year-btn:hover {
    background: #e1dffa;
}

.year-btn.active {
    background: #6c5ce7;
    color: white;
}

Also, the pivot table and the chart are located inside simple containers with rounded corners and slight shadows. This visually separates the components and keeps the layout logically structured.

.pivot-container,
.chart-container {
    width: 90%;
    background: #ffffff;
    border-radius: 12px;
    padding: 14px;
    box-shadow: 0 6px 20px rgba(15, 35, 95, 0.12);
}

.pivot-container {
    height: 56vh;
    margin-bottom: 24px;
}

.chart-container {
    height: 40vh;
}

And now, here's the result of our work!

Wrapping Up

In this tutorial, we've build an interactive dashboard for visualizing the world's top university rankings over the years. You learned how to load and show data in pivot table in a convenient and compact way, make bar charts to show comparative data, and add buttons to filter info by year.

You can now use these skills to visualize other datasets and play with different charts and customization options.

If you want to look closer at my code and get detailed styling code, you can check out my GitHub: https://github.com/filozopdasha/universities-dashboard

I would be delighted to hear your thoughts about this small project. I’m curious to see what you build!

How to Use OpenStreetMap as a Free Alternative to Google Maps

Aiyedogbon Abraham — Wed, 25 Mar 2026 17:35:27 +0000

Google Maps has been the default choice for developers building location-based applications for years. But for many teams, especially those operating at scale, pricing has become a real concern.

Google Maps provides a $200 monthly credit, but beyond that, usage is billed per request. For applications like logistics, ride-hailing, or fleet tracking – where thousands of requests are made daily – costs can grow quickly depending on which APIs you use.

OpenStreetMap (OSM) offers a different approach. Instead of charging for access to map APIs, it provides free, open geographic data that you can build on.

In this guide, you'll learn what OpenStreetMap is, how it differs from Google Maps, and how to integrate it into a React application using Leaflet.

What We'll Cover:

What is OpenStreetMap?
Why Choose OpenStreetMap Over Google Maps?
Understanding the OpenStreetMap Ecosystem
How to Integrate OpenStreetMap in React with Leaflet
How to Add Geocoding with Nominatim
Advanced Features
When to Choose OpenStreetMap vs Google Maps
Wrapping Up

What is OpenStreetMap?

OpenStreetMap is a free, open, and community-driven map of the world. Anyone can contribute to it, and anyone can use it.

Unlike Google Maps, which gives access through controlled APIs, OpenStreetMap gives you access to the underlying geographic data itself.

This data is structured in three main ways:

Nodes: single points (for example, a bus stop or a tree)
Ways: lines or shapes made up of nodes (like roads or buildings)
Relations: groups of nodes and ways that define more complex things (like routes or boundaries)

Each of these elements includes tags (key-value pairs), such as:

highway=residential
name=Allen Avenue

So instead of just displaying a map, OpenStreetMap lets you work with structured geographic data.

The Open Database License (ODbL)

OpenStreetMap data is licensed under the ODbL. This means:

You can use it for commercial or personal projects
You must give proper attribution

This makes it especially useful for developers who want clarity around data ownership.

Why Choose OpenStreetMap Over Google Maps?

Cost

OpenStreetMap data is free to use. But it's important to be precise here: OpenStreetMap removes licensing costs, but not infrastructure costs.

You may still need to pay for:

Tile hosting
Geocoding services
Routing engines

Control

With Google Maps, you can't modify the data, and you rely entirely on Google's APIs

But with OpenStreetMap, you can download and store the data, modify it, and build custom solutions on top of it.

Customization

OpenStreetMap gives you more flexibility:

You control how maps are rendered
You can choose or build your own map styles
You can create domain-specific maps

Adoption

OpenStreetMap is widely used. Companies like Meta and Microsoft contribute to it, and many platforms rely on it directly or indirectly.

This shows that the ecosystem is mature and reliable.

Understanding the OpenStreetMap Ecosystem

A common mistake is to think that OpenStreetMap works like a single API. It doesn't.

Instead, it works as a set of layers, where each layer handles a different responsibility.

Data Layer (OpenStreetMap)

This is the foundation. It contains all the raw geographic data:

Roads
Buildings
Landmarks
Boundaries

This is what you are ultimately working with.

Rendering Layer (Leaflet, MapLibre)

Raw data isn't visual. It needs to be turned into something users can see.

There are two main approaches:

Raster tiles (used by Leaflet): pre-rendered images
Vector tiles (used by MapLibre): raw geometry styled in the browser

Leaflet uses raster tiles by default, which makes it simple and fast to start with.

Services Layer

This is what makes your map interactive. Geocoding converts addresses into coordinates, while reverse geocoding converts coordinates into addresses.

Routing calculates directions between points, and tile servers provide the actual map visuals.

How Everything Works Together

When a user searches for a place:

The user enters a location
A geocoding service converts it into coordinates
The map updates its position
A tile server provides the visual map

Each part is separate, but they work together to create the full experience.

How to Integrate OpenStreetMap in React with Leaflet

Let's build a simple map.

Step 1: Create a React App

npm create vite@latest osm-app -- --template react
cd osm-app
npm install

Step 2: Install Dependencies

npm install leaflet react-leaflet
npm install --save-dev @types/leaflet

Step 3: Import Leaflet CSS

import 'leaflet/dist/leaflet.css';

This is required for the map to display correctly.

Step 4: Create a Map Component

import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';

function Map() {
  const position = [51.505, -0.09]; // latitude, longitude

  return (
    
      
      
        Hello from OpenStreetMap
      
    
  );
}

export default Map;

Let's break down the important parts here:

MapContainer initializes the map.

center is where the map starts
zoom is how close the view is
style must include height, or the map won't show

TileLayer defines where the map visuals come from.

{z} is the zoom level
{x}, {y} are the tile coordinates
{s} is the subdomain

Each tile is a small image (usually 256×256 pixels), and Leaflet combines them to form the full map.

Marker adds a point on the map at a specific coordinate.

Popup displays information when the marker is clicked.

Important note:

The default OpenStreetMap tile server:

https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

is meant for learning, demos, and low-traffic apps. For production, you should use a dedicated provider or your own tile server.

How to Add Geocoding with Nominatim

Nominatim is OpenStreetMap's geocoding service. It allows you to convert addresses into coordinates and coordinates into readable locations.

Custom Hook for Geocoding

import { useState } from 'react';

export function useGeocoding() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const searchAddress = async (query) => {
    setLoading(true);
    setError(null);

    try {
      const response = await fetch(
        `https://nominatim.openstreetmap.org/search?q=${encodeURIComponent(query)}&format=json&limit=5`,
        {
          headers: {
            'User-Agent': 'YourAppName/1.0'
          }
        }
      );

      if (!response.ok) {
        throw new Error('Request failed');
      }

      const data = await response.json();
      setLoading(false);
      return data;
    } catch (err) {
      setError(err.message);
      setLoading(false);
      return [];
    }
  };

  return { searchAddress, loading, error };
}

In this code:

useState manages loading and error states
encodeURIComponent ensures safe URLs
User-Agent is required by Nominatim
response.json() converts response into usable data

Nominatim returns coordinates as strings, so you have to convert them before using them.

Important Usage Rules

The public Nominatim service:

Allows about 1 request per second
Requires proper identification
May block excessive usage

You should debounce user input, cache results, and avoid repeated requests.

Creating a Search Component

The search component lets users type an address or place name and get matching locations via Nominatim. It includes a text input and a submit button.

When the form is submitted, it calls our searchAddress function (from the useGeocoding hook), which fetches up to 5 address results. These results are displayed below the input as clickable items.

When the user clicks a result, the component parses the returned latitude and longitude into numbers and passes them (along with a display name) up to the parent component via the onLocationSelect callback. This will allow the parent (for example, the map) to update its center based on the chosen location.

function SearchBox({ onLocationSelect }) {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const { searchAddress, loading } = useGeocoding();

  const handleSearch = async (e) => {
    e.preventDefault();
    if (!query.trim()) return;

    const data = await searchAddress(query);
    setResults(data);
  };

  const selectLocation = (result) => {
    onLocationSelect({
      lat: parseFloat(result.lat),
      lon: parseFloat(result.lon),
      name: result.display_name
    });
  };

  return (
    
      
         setQuery(e.target.value)}
          placeholder="Search location"
        />
        
      

      
        {results.map((result) => (
           selectLocation(result)}>
            {result.display_name}
          
        ))}
      
    
  );
}

Key concepts here:

useState stores the current input (query) and the array of search results.
e.preventDefault() stops the form submission from reloading the page.
Calling searchAddress(query) fetches geocoding results from Nominatim.
parseFloat() converts the returned lat/lon strings into JavaScript numbers before using them.
onLocationSelect is a callback prop that sends the selected coordinates and name back to the parent component (for example to update the map).

Advanced Features

We can further extend the map app by adding more advanced functionality. For example:

Routing (OSRM, GraphHopper)

You can integrate turn-by-turn routing on your map. A common solution is to use a library like Leaflet Routing Machine, which supports OSRM out of the box and has plugins for GraphHopper. This adds a route UI control where users enter start and end points, and the library fetches a route from one of these engines to draw on the map.

Custom Tile Providers (Carto, MapTiler, and so on)

Instead of the standard tile.openstreetmap.org, you can use hosted tile services that offer OSM-based maps. For example, Carto and MapTiler both provide tile APIs (often with custom style options and higher usage limits).

Carto, MapTiler, and similar services are listed among the providers that allow free usage of OSM tiles. By using a custom tile provider, you gain flexibility in map design and avoid hitting the public server’s limits.

Vector Maps (MapLibre GL JS)

You can switch from raster tiles to vector tiles for even richer interactivity. Vector tiles send raw map data (geometries and attributes) to the client, which are then rendered in the browser. This allows dynamic styling and advanced features: for instance, you can change the map’s theme on the fly (for example, switch to a “dark mode” style at night) or highlight certain features like bike lanes more prominently.

Libraries like MapLibre GL JS (the open-source successor to Mapbox GL) can display OSM vector tiles with highly customizable styles and smooth zooming/rotation. This makes your map more responsive and adaptable to different use cases.

When to Choose OpenStreetMap vs Google Maps

Choose OpenStreetMap when:

You need flexibility
You want to reduce costs at scale
You want control over data

Choose Google Maps when:

You want an all-in-one solution
You need features like Street View
You want minimal setup

Wrapping Up

OpenStreetMap offers a powerful alternative to Google Maps for developers who need cost control, data ownership, and customization. While it requires understanding different components, the flexibility it provides is worth the learning curve.

How to Build a Full-Stack CRUD App with React, AWS Lambda, DynamoDB, and Cognito Auth

Benedicta Onyebuchi — Tue, 17 Mar 2026 15:13:02 +0000

Building a web application that works only on your local machine is one thing. Building one that is secure, connected to a real database, and accessible to anyone on the internet is another challenge entirely. And it requires a different set of tools.

Most production web applications share a common set of needs: they store and retrieve data, they expose that data through an API, they require users to authenticate before accessing sensitive operations, and they need to be deployed somewhere reliable and fast.

Meeting all of those needs used to require managing servers, configuring databases, handling authentication infrastructure, and provisioning hosting environments – often as separate, manual processes.

AWS changes that model significantly. With the combination of services you'll use in this tutorial (Lambda, DynamoDB, API Gateway, Cognito, and CloudFront), you can build and deploy a fully functional, secured, globally distributed application without managing a single server.

Each service handles one specific responsibility:

DynamoDB stores your data
Lambda runs your business logic on demand
API Gateway exposes your functions as a REST API
Cognito manages user authentication
CloudFront delivers your frontend worldwide over HTTPS.

The AWS CDK (Cloud Development Kit) ties all of this together by letting you define every one of those services as TypeScript code. Instead of clicking through the AWS Console to configure each resource manually, you describe your entire infrastructure in a single file and deploy it with one command.

By the end of this tutorial, you will have a fully deployed vendor management dashboard. Users can sign up, log in, and then create, read, and delete vendors, with all data securely stored in AWS DynamoDB and all routes protected by Amazon Cognito authentication.

What You'll Build

In this handbook, you'll build a two-panel web app where authenticated users can:

Add a new vendor (name, category, contact email)
View all saved vendors in real time
Delete a vendor from the list
Sign in and sign out securely

The frontend is built with Next.js. The backend runs entirely on AWS: DynamoDB stores the data, Lambda functions handle the logic, API Gateway exposes a REST API, Cognito manages authentication, and CloudFront serves the app globally over HTTPS.

Who This Is For
Prerequisites
Architecture Overview
Part 1: Set Up Your AWS Account and Tools
Part 2: Set Up the Project Structure
Part 3: Define the Database (DynamoDB)
Part 4: Write the Lambda Functions
Part 5: Build the API with API Gateway
Part 6: Deploy the Backend to AWS
Part 7: Build the React Frontend
Part 8: Add Authentication with Amazon Cognito
Part 9: Deploy the Frontend with S3 and CloudFront
What You Built
Conclusion

Who This Is For

This tutorial is for developers who know basic JavaScript and React but have never used AWS. You don't need any prior backend, cloud, or DevOps experience. I'll explain every AWS concept before we use it.

Prerequisites

Before starting, make sure you have the following installed and available:

Node.js 18 or higher: Download here
npm: Included with Node.js
A code editor: I recommend VS Code
A terminal: Any terminal on macOS, Linux, or Windows (WSL recommended on Windows)
An AWS account: You will create one in Part 1. A credit card is required, but the Free Tier covers everything in this tutorial.
Basic familiarity with React and TypeScript: You should understand components, useState, and useEffect.

Architecture Overview

Before writing any code, here's a plain-English description of how the pieces fit together.

When a user clicks "Add Vendor" in the React app:

The frontend reads the user's JWT auth token from the browser session
It sends a POST request to API Gateway, including the token in the request header
API Gateway checks the token against Cognito. If the token is invalid or missing, it rejects the request with a 401 error immediately
If the token is valid, API Gateway passes the request to the createVendor Lambda function
The Lambda function writes the new vendor to DynamoDB
DynamoDB confirms the write, and the Lambda returns a success response
The frontend re-fetches the vendor list and updates the UI

The same flow applies to reading and deleting vendors, with different Lambda functions and HTTP methods.

How the app is deployed: Your React app is exported as a static site, uploaded to an S3 bucket, and served globally through CloudFront. Your backend infrastructure (Lambda functions, API Gateway, DynamoDB, Cognito) is defined in TypeScript using AWS CDK and deployed with a single command.

Part 1: Set Up Your AWS Account and Tools

Before writing any application code, you need three things in place: an AWS account, the right tools on your machine, and credentials that let those tools communicate with AWS on your behalf.

1.1 Create Your AWS Account

If you don't have an AWS account:

Go to https://aws.amazon.com
Click Create an AWS Account
Follow the sign-up prompts and add a payment method
Once registered, log in to the AWS Management Console

AWS has a Free Tier that covers all the services used in this tutorial. You won't be charged for normal use while following along.

1.2 Install the AWS CLI and CDK

The AWS CLI is a command-line tool that lets you interact with AWS from your terminal: checking resources, configuring credentials, and more.

The AWS CDK (Cloud Development Kit) is the tool you will use to define your entire backend (database, Lambda functions, API) using TypeScript code. Instead of clicking through the AWS Console to create each resource, you describe what you want in a TypeScript file and CDK builds it for you.

Install both:

# Install AWS CLI (macOS)
curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

# For Linux, see: https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html
# For Windows, see: https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-windows.html

# Install AWS CDK globally
npm install -g aws-cdk

Verify both are installed:

aws --version
cdk --version

Both commands should print a version number. If they do, you are ready to move on.

1.3 Configure Your AWS Credentials (IAM)

This step is critical. Your terminal needs a set of credentials – like a username and password – to act on your behalf inside AWS.

Think of your root account (the one you signed up with) as the master key to your entire AWS account. You should never use it for day-to-day development. Instead, you will create a separate IAM user with its own set of keys. If those keys are ever exposed, you can delete them without compromising your root account.

Phase 1: Create an IAM User

Log in to the AWS Console and search for IAM in the top search bar
In the left sidebar, click Users, then click Create user
Name the user cdk-dev. Leave "Provide user access to the AWS Management Console" unchecked – you only need terminal access, not console access
On the permissions screen, choose Attach policies directly

Search for AdministratorAccess and check the box next to it

Note on permissions: In a production job you would use a more restricted policy. For this tutorial, Administrator access is needed because CDK creates many different types of AWS resources.

6. Click through to the end and click Create user

Phase 2: Generate Access Keys

Click on your newly created cdk-dev user from the Users list
Go to the Security credentials tab
Scroll down to Access keys and click Create access key
Select Command Line Interface (CLI), check the acknowledgment box, and click Next
Click Create access key

Important: Copy both the Access Key ID and the Secret Access Key right now. You will never be able to see the Secret Access Key again after closing this screen. Save both values in a password manager or secure note.

Phase 3: Connect Your Terminal to AWS

Run the following command in your terminal:

aws configure

You will be prompted for four values:

AWS Access Key ID:     [paste your Access Key ID]
AWS Secret Access Key: [paste your Secret Access Key]
Default region name:   us-east-1
Default output format: json

Use us-east-1 as your region for this tutorial. After this step, every CDK and AWS CLI command you run will use these credentials automatically.

Part 2: Set Up the Project Structure

You will use a monorepo layout – one top-level folder with two sub-projects inside: frontend for your React app and backend for your AWS infrastructure code. They are deployed independently but live side by side.

2.1 Create the Workspace

mkdir vendor-tracker && cd vendor-tracker
mkdir backend frontend

2.2 Initialize the Frontend (Next.js)

Navigate into the frontend folder and run:

cd frontend
npx create-next-app@latest .

When prompted, choose the following options:

TypeScript --> Yes
ESLint --> Yes
Tailwind CSS --> Yes
src/ directory -->No
App Router --> Yes
Import alias --> No

2.3 Initialize the Backend (CDK)

Navigate into the backend folder and run:

cd ../backend
cdk init app --language typescript

This generates a boilerplate CDK project. The most important file it creates is backend/lib/backend-stack.ts. This is where you will define all of your AWS infrastructure as TypeScript code.

Also install esbuild, which CDK uses to bundle your Lambda functions:

npm install --save-dev esbuild

2.4 Understanding CDK Before You Write Any Code

CDK is likely different from most tools you have used. Here is how it works:

Normally, you would create AWS resources by clicking through the AWS Console: create a table here, configure a Lambda function there. CDK lets you do all of that using TypeScript code instead.

When you run cdk deploy, CDK reads your TypeScript file, converts it into an AWS CloudFormation template (an internal AWS format for describing infrastructure), and submits it to AWS. AWS then creates all the resources you described.

A few terms you will see throughout this tutorial:

Stack: The collection of all AWS resources you define together. Your BackendStack class is your stack.
Construct: Each individual AWS resource you create inside a stack (a table, a Lambda function, an API) is called a construct.
Deploy: Running cdk deploy sends your TypeScript definition to AWS and creates or updates the real resources.

The main file you'll work in is backend/lib/backend-stack.ts. Think of it as the blueprint for your entire backend.

Your final project structure will look like this:

vendor-tracker/
├── backend/
│   ├── lambda/
│   │   ├── createVendor.ts
│   │   ├── getVendors.ts
│   │   └── deleteVendor.ts
│   ├── lib/
│   │   └── backend-stack.ts
│   └── package.json
└── frontend/
    ├── app/
    │   ├── layout.tsx
    │   ├── page.tsx
    │   └── providers.tsx
    ├── lib/
    │   └── api.ts
    ├── types/
    │   └── vendor.ts
    └── .env.local

Part 3: Define the Database (DynamoDB)

DynamoDB is AWS's NoSQL database. Think of it as a fast, scalable key-value store in the cloud. Every item in a DynamoDB table must have a unique ID called the partition key. For your vendor table, that key will be vendorId.

Open backend/lib/backend-stack.ts. Replace the entire file contents with the following:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';

export class BackendStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 1. DynamoDB Table
    const vendorTable = new dynamodb.Table(this, 'VendorTable', {
      partitionKey: {
        name: 'vendorId',
        type: dynamodb.AttributeType.STRING,
      },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY, // For development only
    });
  }
}

What each line does:

partitionKey tells DynamoDB that vendorId is the unique identifier for every record. No two vendors can share the same vendorId.
PAY_PER_REQUEST means you only pay when data is actually read or written. There is no charge when the table is idle, which makes it cost-effective for learning.
RemovalPolicy.DESTROY means the table will be deleted when you run cdk destroy. For production apps you would not use this.

Part 4: Write the Lambda Functions

A Lambda function is your server, but unlike a traditional server, it only runs when it's called. AWS spins it up on demand, runs your code, and shuts it down. You're only charged for the time your code is actually running.

You'll write three Lambda functions:

createVendor.ts: Adds a new vendor to DynamoDB
getVendors.ts: Returns all vendors from DynamoDB
deleteVendor.ts: Removes a vendor from DynamoDB by ID

Create a new folder inside backend:

mkdir backend/lambda

A Note on the AWS SDK

All three Lambda functions use AWS SDK v3 (@aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb). This is the current standard. An older version of the SDK (aws-sdk) exists but is deprecated and not bundled in the Node.js 18 Lambda runtime, which is what you'll use. Stick to v3 throughout.

4.1 Create Vendor Lambda

Create backend/lambda/createVendor.ts:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
import { randomUUID } from "crypto";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

export const handler = async (event: any) => {
  try {
    const body = JSON.parse(event.body);

    const item = {
      vendorId: randomUUID(), // Generates a collision-safe unique ID
      name: body.name,
      category: body.category,
      contactEmail: body.contactEmail,
      createdAt: new Date().toISOString(),
    };

    await docClient.send(
      new PutCommand({
        TableName: process.env.TABLE_NAME!,
        Item: item,
      })
    );

    return {
      statusCode: 201,
      headers: {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Headers": "Content-Type,Authorization",
        "Access-Control-Allow-Methods": "OPTIONS,POST,GET,DELETE",
      },
      body: JSON.stringify({ message: "Vendor created", vendorId: item.vendorId }),
    };
  } catch (error) {
    console.error("Error creating vendor:", error);
    return {
      statusCode: 500,
      headers: { "Access-Control-Allow-Origin": "*" },
      body: JSON.stringify({ error: "Failed to create vendor" }),
    };
  }
};

What each part does:

randomUUID() generates a universally unique ID using Node's built-in crypto module. No extra package is needed. This is more reliable than Date.now(), which can produce duplicate IDs if two requests arrive within the same millisecond.
process.env.TABLE_NAME reads the DynamoDB table name from an environment variable. You'll set this value in the CDK stack. This avoids hardcoding the table name inside your Lambda code.
The headers block is required for CORS (Cross-Origin Resource Sharing). Without Access-Control-Allow-Origin, your browser will block responses from a different domain than your frontend. Without Access-Control-Allow-Headers, the Authorization header you add later for Cognito will be rejected during the browser's preflight check.

4.2 Get Vendors Lambda

Create backend/lambda/getVendors.ts:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, ScanCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

export const handler = async () => {
  try {
    const response = await docClient.send(
      new ScanCommand({
        TableName: process.env.TABLE_NAME!,
      })
    );

    return {
      statusCode: 200,
      headers: {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Headers": "Content-Type,Authorization",
        "Content-Type": "application/json",
      },
      body: JSON.stringify(response.Items ?? []),
    };
  } catch (error) {
    console.error("Error fetching vendors:", error);
    return {
      statusCode: 500,
      headers: { "Access-Control-Allow-Origin": "*" },
      body: JSON.stringify({ error: "Failed to fetch vendors" }),
    };
  }
};

What each part does:

ScanCommand reads every item in the table and returns them as an array. For a learning project this is fine. In a production app with millions of rows, you would use a more targeted QueryCommand to avoid reading the entire table on every request.
response.Items ?? [] returns an empty array if the table is empty, preventing the frontend from crashing when there are no vendors yet.

4.3 Delete Vendor Lambda

Create backend/lambda/deleteVendor.ts:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, DeleteCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

export const handler = async (event: any) => {
  try {
    const body = JSON.parse(event.body);
    const { vendorId } = body;

    if (!vendorId) {
      return {
        statusCode: 400,
        headers: { "Access-Control-Allow-Origin": "*" },
        body: JSON.stringify({ error: "vendorId is required" }),
      };
    }

    await docClient.send(
      new DeleteCommand({
        TableName: process.env.TABLE_NAME!,
        Key: { vendorId },
      })
    );

    return {
      statusCode: 200,
      headers: {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Headers": "Content-Type,Authorization",
        "Access-Control-Allow-Methods": "OPTIONS,POST,GET,DELETE",
      },
      body: JSON.stringify({ message: "Vendor deleted" }),
    };
  } catch (error) {
    console.error("Error deleting vendor:", error);
    return {
      statusCode: 500,
      headers: { "Access-Control-Allow-Origin": "*" },
      body: JSON.stringify({ error: "Failed to delete vendor" }),
    };
  }
};

What each part does:

DeleteCommand removes the item whose vendorId matches the key you provide. DynamoDB doesn't return an error if the item doesn't exist. It simply does nothing.
The 400 guard at the top returns a clear error if the caller forgets to send a vendorId, rather than letting DynamoDB throw a confusing internal error.

Part 5: Build the API with API Gateway

API Gateway is what gives your Lambda functions a public URL. Without it, there's no way for your browser to trigger a Lambda function. Think of it as the front door of your backend: it receives HTTP requests, checks whether the caller is authorized, routes the request to the correct Lambda, and returns the Lambda's response to the caller.

Now you'll wire everything together in backend/lib/backend-stack.ts.

5.1 Add Lambda Functions and API Gateway to the Stack

Replace the entire contents of backend/lib/backend-stack.ts with this complete, assembled file:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';

export class BackendStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 1. DynamoDB Table 
    const vendorTable = new dynamodb.Table(this, 'VendorTable', {
      partitionKey: {
        name: 'vendorId',
        type: dynamodb.AttributeType.STRING,
      },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    // 2. Lambda Functions
    const lambdaEnv = { TABLE_NAME: vendorTable.tableName };

    const createVendorLambda = new NodejsFunction(this, 'CreateVendorHandler', {
      entry: 'lambda/createVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const getVendorsLambda = new NodejsFunction(this, 'GetVendorsHandler', {
      entry: 'lambda/getVendors.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const deleteVendorLambda = new NodejsFunction(this, 'DeleteVendorHandler', {
      entry: 'lambda/deleteVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    // 3. Permissions (Least Privilege)
    vendorTable.grantWriteData(createVendorLambda);
    vendorTable.grantReadData(getVendorsLambda);
    vendorTable.grantWriteData(deleteVendorLambda);

    // 4. API Gateway
    const api = new apigateway.RestApi(this, 'VendorApi', {
      restApiName: 'Vendor Service',
      defaultCorsPreflightOptions: {
        allowOrigins: apigateway.Cors.ALL_ORIGINS,
        allowMethods: apigateway.Cors.ALL_METHODS,
        allowHeaders: ['Content-Type', 'Authorization'],
      },
    });

    const vendors = api.root.addResource('vendors');
    vendors.addMethod('POST', new apigateway.LambdaIntegration(createVendorLambda));
    vendors.addMethod('GET', new apigateway.LambdaIntegration(getVendorsLambda));
    vendors.addMethod('DELETE', new apigateway.LambdaIntegration(deleteVendorLambda));

    // 5. Outputs
    new cdk.CfnOutput(this, 'ApiEndpoint', {
      value: api.url,
    });
  }
}

What each section does:

NodejsFunction is a special CDK construct that automatically bundles your Lambda code and all its dependencies into a single file using esbuild before uploading it to AWS. This is why you installed esbuild in Part 2.

Always use NodejsFunction instead of the basic lambda.Function construct. The basic version requires you to manually manage bundling, which causes "Module not found" errors at runtime.

Permissions (Least Privilege): In AWS, no resource can communicate with any other resource by default. A Lambda function has no access to DynamoDB, S3, or anything else unless you explicitly grant it.

This is called the Least Privilege principle: each piece of your system gets exactly the permissions it needs, and nothing more. grantWriteData lets a Lambda write and delete items. grantReadData lets a Lambda read items. Using separate grants for each function means the getVendors Lambda can never accidentally delete data.

CfnOutput prints a value to your terminal after cdk deploy completes. You'll use the ApiEndpoint URL to configure your frontend.

Part 6: Deploy the Backend to AWS

Your infrastructure is fully defined in code. Now you'll deploy it to AWS and get a live API URL.

6.1 Bootstrap Your AWS Environment

Before your first CDK deployment, AWS needs a small landing zone in your account – an S3 bucket where CDK can upload your Lambda bundles and other assets. This setup step is called bootstrapping and only needs to be done once per AWS account per region.

From inside your backend folder, run:

cdk bootstrap

Important: Bootstrapping is region-specific. If you ever switch to a different AWS region, you will need to run cdk bootstrap again in that region.

6.2 Deploy

Run:

cdk deploy

CDK will display a summary of everything it is about to create and ask for your confirmation. Type y and press Enter.

When the deployment finishes, you'll see an Outputs section in your terminal:

Outputs:
BackendStack.ApiEndpoint = https://abcdef123.execute-api.us-east-1.amazonaws.com/prod/

Copy that URL. You'll need it when building the frontend.

6.3 Troubleshooting: How to Read AWS Error Logs

Real deployments rarely go perfectly the first time. If something goes wrong after deploying, here is how to find the actual error message.

Error: 502 Bad Gateway

A 502 means API Gateway received your request but your Lambda crashed before it could respond. The most common cause is a missing environment variable – for example, if TABLE_NAME was not passed correctly and the Lambda cannot find the table.

To find the actual error message, use CloudWatch Logs:

Log in to the AWS Console and search for CloudWatch
In the left sidebar, click Logs --> Log groups

Find the group named /aws/lambda/BackendStack-CreateVendorHandler...
Click the most recent Log stream
Read the error message. It will tell you exactly what went wrong

Two common messages and their fixes:

Runtime.ImportModuleError : Your Lambda cannot find a module. Make sure you're using NodejsFunction (not lambda.Function) in your CDK stack. NodejsFunction automatically bundles dependencies; lambda.Function does not.
AccessDeniedException: Your Lambda tried to access DynamoDB but doesn't have permission. Check that you have the correct grantWriteData or grantReadData call in your stack for that Lambda.

Part 7: Build the React Frontend

Your backend is live. Now you'll build the React UI that talks to it.

7.1 Define the Vendor Type

Before writing any API or component code, define what a "vendor" looks like in TypeScript. This gives you type safety throughout your frontend code.

Create frontend/types/vendor.ts:

export interface Vendor {
  vendorId?: string; // Optional when creating — the Lambda generates it
  name: string;
  category: string;
  contactEmail: string;
  createdAt?: string;
}

The vendorId? is marked optional with ? because when you are creating a new vendor, you don't have an ID yet. The createVendor Lambda generates one. When you read vendors back from the API, vendorId will always be present.

7.2 Create the API Service Layer

Rather than writing fetch calls directly inside your React components, you'll centralize all your API logic in one file. This pattern is called a service layer. It keeps your components clean and makes it easy to update API calls in one place.

First, create a .env.local file inside your frontend folder to store your API URL:

# frontend/.env.local
NEXT_PUBLIC_API_URL=https://abcdef123.execute-api.us-east-1.amazonaws.com/prod

Replace the URL with the ApiEndpoint value from your cdk deploy output. The NEXT_PUBLIC_ prefix is required by Next.js to make an environment variable accessible in the browser.

You might be wondering: why not hardcode the URL? If you paste your API URL directly into your code and push it to GitHub, it becomes publicly visible. While an API URL alone does not expose your data (Cognito will protect that), it's good practice to keep URLs and secrets out of source control. Always use .env.local and add it to your .gitignore.

Make sure .env.local is in your .gitignore:

echo ".env.local" >> frontend/.gitignore

Now create frontend/lib/api.ts:

import { Vendor } from '@/types/vendor';

const BASE_URL = process.env.NEXT_PUBLIC_API_URL!;

export const getVendors = async (): Promise => {
  const response = await fetch(`${BASE_URL}/vendors`);
  if (!response.ok) throw new Error('Failed to fetch vendors');
  return response.json();
};

export const createVendor = async (vendor: Omit): Promise => {
  const response = await fetch(`${BASE_URL}/vendors`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(vendor),
  });
  if (!response.ok) throw new Error('Failed to create vendor');
};

export const deleteVendor = async (vendorId: string): Promise => {
  const response = await fetch(`${BASE_URL}/vendors`, {
    method: 'DELETE',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ vendorId }),
  });
  if (!response.ok) throw new Error('Failed to delete vendor');
};

What each part does:

Omit means the createVendor function accepts a vendor without an ID or timestamp (those are generated server-side).
if (!response.ok) throw new Error(...) ensures that any HTTP error (4xx or 5xx) surfaces as a JavaScript error in your component, where you can show the user a meaningful message instead of silently failing.

You'll update these functions later in Part 8 to include the Cognito auth token.

7.3 Build the Main Page

Now create the main page component. It includes a form for adding vendors and a live list that displays all current vendors.

Replace the contents of frontend/app/page.tsx with:

'use client';

import { useState, useEffect } from 'react';
import { createVendor, getVendors, deleteVendor } from '@/lib/api';
import { Vendor } from '@/types/vendor';

export default function Home() {
  const [vendors, setVendors] = useState([]);
  const [form, setForm] = useState({ name: '', category: '', contactEmail: '' });
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');

  const loadVendors = async () => {
    try {
      const data = await getVendors();
      setVendors(data);
    } catch {
      setError('Failed to load vendors.');
    }
  };

  // Load vendors once when the page first renders
  useEffect(() => {
    loadVendors();
  }, []);
  // The empty [] means this runs only once. Without it, the effect would
  // run after every render, causing an infinite loop of fetch requests.

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault(); // Prevent the browser from reloading the page on submit
    setLoading(true);
    setError('');
    try {
      await createVendor(form);
      setForm({ name: '', category: '', contactEmail: '' }); // Reset the form
      await loadVendors(); // Refresh the list from DynamoDB
    } catch {
      setError('Failed to add vendor. Please try again.');
    } finally {
      setLoading(false);
    }
  };

  const handleDelete = async (vendorId: string) => {
    try {
      await deleteVendor(vendorId);
      await loadVendors(); // Refresh after deleting
    } catch {
      setError('Failed to delete vendor.');
    }
  };

  return (
    
      Vendor Tracker
      Manage your vendors, stored in AWS DynamoDB.

      {error && (
        {error}
      )}

      

        {/* ── Add Vendor Form ── */}
        
          Add New Vendor
          
             setForm({ ...form, name: e.target.value })}
              required
            />
             setForm({ ...form, category: e.target.value })}
              required
            />
             setForm({ ...form, contactEmail: e.target.value })}
              required
            />
            
          
        

        {/* ── Vendor List ── */}
        
          
            Current Vendors ({vendors.length})
          
          
            {vendors.length === 0 ? (
              No vendors yet. Add one using the form.
            ) : (
              vendors.map(v => (
                
                  
                    {v.name}
                    {v.category} · {v.contactEmail}
                  
                  
                
              ))
            )}
          
        

      
    
  );
}

Key points in this component:

'use client' at the top is a Next.js directive. It tells Next.js that this component uses browser APIs (useState, useEffect, event handlers) and must run in the browser, not be pre-rendered on the server.
e.preventDefault() inside handleSubmit stops the browser's default form submission behavior, which would cause a full page reload and wipe your React state.
After every createVendor or deleteVendor call, loadVendors() is called again. This re-fetches the latest data from DynamoDB so the UI always matches what is actually stored in the database.

7.4 Test the App Locally

Start your Next.js development server:

cd frontend
npm run dev

Open http://localhost:3000 in your browser. You should see the two-panel layout. Try adding a vendor and confirm it appears in the list.

Verifying the connection to AWS:

Open Chrome DevTools (F12) and click the Network tab. When you add a vendor, you should see:

A POST request to your AWS API URL returning a 201 status code
A GET request returning 200 with the updated vendor list

You can also verify the data was saved by opening the AWS Console, navigating to DynamoDB --> Tables --> VendorTable --> Explore table items. Your vendor should appear there.

Part 8: Add Authentication with Amazon Cognito

Right now your API is completely open. Anyone who finds your API URL can add or delete vendors. You'll fix that with Amazon Cognito.

Cognito is AWS's authentication service. It manages a User Pool – a database of registered users with usernames and passwords. When a user logs in, Cognito issues a JWT (JSON Web Token): a cryptographically signed string that proves who the user is. Your API Gateway will check for this token on every request. No valid token means no access.

What is a JWT? A JSON Web Token is a string that looks like eyJhbGci.... It contains encoded information about the user and is signed by Cognito using a secret key.

API Gateway can verify the signature without contacting Cognito on every request, which makes token checking fast. Think of it as a tamper-proof badge: anyone can read the name on it, but only Cognito's signature makes it valid.

8.1 Add Cognito to the CDK Stack

Open backend/lib/backend-stack.ts and update it to include Cognito. Here is the complete updated file:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import * as cognito from 'aws-cdk-lib/aws-cognito';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';

export class BackendStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // ─── 1. DynamoDB Table ────────────────────────────────────────────────────
    const vendorTable = new dynamodb.Table(this, 'VendorTable', {
      partitionKey: { name: 'vendorId', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    // ─── 2. Lambda Functions ──────────────────────────────────────────────────
    const lambdaEnv = { TABLE_NAME: vendorTable.tableName };

    const createVendorLambda = new NodejsFunction(this, 'CreateVendorHandler', {
      entry: 'lambda/createVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const getVendorsLambda = new NodejsFunction(this, 'GetVendorsHandler', {
      entry: 'lambda/getVendors.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const deleteVendorLambda = new NodejsFunction(this, 'DeleteVendorHandler', {
      entry: 'lambda/deleteVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    // ─── 3. Permissions ───────────────────────────────────────────────────────
    vendorTable.grantWriteData(createVendorLambda);
    vendorTable.grantReadData(getVendorsLambda);
    vendorTable.grantWriteData(deleteVendorLambda);

    // ─── 4. Cognito User Pool ─────────────────────────────────────────────────
    const userPool = new cognito.UserPool(this, 'VendorUserPool', {
      selfSignUpEnabled: true,
      signInAliases: { email: true },
      autoVerify: { email: true },
      userVerification: {
        emailStyle: cognito.VerificationEmailStyle.CODE,
      },
    });

    // Required to host Cognito's internal auth endpoints
    userPool.addDomain('VendorUserPoolDomain', {
      cognitoDomain: {
        domainPrefix: `vendor-tracker-${this.account}`,
      },
    });

    const userPoolClient = userPool.addClient('VendorAppClient');

    // ─── 5. API Gateway + Authorizer ──────────────────────────────────────────
    const api = new apigateway.RestApi(this, 'VendorApi', {
      restApiName: 'Vendor Service',
      defaultCorsPreflightOptions: {
        allowOrigins: apigateway.Cors.ALL_ORIGINS,
        allowMethods: apigateway.Cors.ALL_METHODS,
        allowHeaders: ['Content-Type', 'Authorization'],
      },
    });

    const authorizer = new apigateway.CognitoUserPoolsAuthorizer(
      this,
      'VendorAuthorizer',
      { cognitoUserPools: [userPool] }
    );

    const authOptions = {
      authorizer,
      authorizationType: apigateway.AuthorizationType.COGNITO,
    };

    const vendors = api.root.addResource('vendors');
    vendors.addMethod('GET', new apigateway.LambdaIntegration(getVendorsLambda), authOptions);
    vendors.addMethod('POST', new apigateway.LambdaIntegration(createVendorLambda), authOptions);
    vendors.addMethod('DELETE', new apigateway.LambdaIntegration(deleteVendorLambda), authOptions);

    // ─── 6. Outputs ───────────────────────────────────────────────────────────
    new cdk.CfnOutput(this, 'ApiEndpoint', { value: api.url });
    new cdk.CfnOutput(this, 'UserPoolId', { value: userPool.userPoolId });
    new cdk.CfnOutput(this, 'UserPoolClientId', { value: userPoolClient.userPoolClientId });
  }
}

What changed:

CognitoUserPoolsAuthorizer tells API Gateway to check every request for a valid Cognito JWT before passing it to any Lambda. If the token is missing or invalid, API Gateway rejects the request with a 401 Unauthorized response without ever touching your Lambda.
authOptions is applied to all three API methods: GET, POST, and DELETE. All routes are now protected.
autoVerify: { email: true } tells Cognito to mark the email attribute as verified after a user confirms via the verification code email. It doesn't skip the verification email, as users still receive a code. If you want to skip verification during development, you can manually confirm users in the Cognito console (covered in section 8.5).
Two new CfnOutput values (UserPoolId and UserPoolClientId) will appear in your terminal after the next deployment. Your frontend needs them to connect to Cognito.

Deploy the updated stack:

cd backend
cdk deploy

After deployment, your terminal output will include three values:

Outputs:
BackendStack.ApiEndpoint     = https://abc123.execute-api.us-east-1.amazonaws.com/prod/
BackendStack.UserPoolId      = us-east-1_xxxxxxxx
BackendStack.UserPoolClientId = xxxxxxxxxxxxxxxxxxxx

Save all three values. You'll use them in the next step.

8.2 Install and Configure AWS Amplify

AWS Amplify is a frontend library that handles all the complex authentication logic for you: it manages the login UI, stores tokens in the browser, refreshes expired tokens automatically, and exposes a simple API to read the current user's session.

Install the Amplify libraries inside your frontend folder:

cd frontend
npm install aws-amplify @aws-amplify/ui-react

Create frontend/app/providers.tsx. This file initializes Amplify with your Cognito configuration. It runs once when the app loads:

'use client';

import { Amplify } from 'aws-amplify';

Amplify.configure(
  {
    Auth: {
      Cognito: {
        userPoolId: process.env.NEXT_PUBLIC_USER_POOL_ID!,
        userPoolClientId: process.env.NEXT_PUBLIC_USER_POOL_CLIENT_ID!,
      },
    },
  },
  { ssr: true }
);

export function Providers({ children }: { children: React.ReactNode }) {
  return <>{children};
}

Add the Cognito IDs to your frontend/.env.local file:

NEXT_PUBLIC_API_URL=https://abc123.execute-api.us-east-1.amazonaws.com/prod
NEXT_PUBLIC_USER_POOL_ID=us-east-1_xxxxxxxx
NEXT_PUBLIC_USER_POOL_CLIENT_ID=xxxxxxxxxxxxxxxxxxxx

Replace the values with the outputs from your cdk deploy.

8.3 Wire Providers into the App Layout

This step is critical. Amplify must be initialized before any component tries to use authentication. If you skip this step, fetchAuthSession() will throw an "Amplify not configured" error and nothing will work.

Open frontend/app/layout.tsx and update it to wrap the app in the Providers component:

import type { Metadata } from 'next';
import './globals.css';
import { Providers } from './providers';

export const metadata: Metadata = {
  title: 'Vendor Tracker',
  description: 'Manage your vendors with AWS',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    
      
        {children}
      
    
  );
}

By wrapping {children} in , you ensure that Amplify is configured once at the root of the app, before any child page or component renders.

8.4 Protect the UI with withAuthenticator

Now wrap your Home component so that unauthenticated users see a login screen instead of the dashboard.

Replace the contents of frontend/app/page.tsx with this updated version:

'use client';

import { useState, useEffect } from 'react';
import { withAuthenticator } from '@aws-amplify/ui-react';
import '@aws-amplify/ui-react/styles.css';
import { getVendors, createVendor, deleteVendor } from '@/lib/api';
import { Vendor } from '@/types/vendor';

// withAuthenticator injects `signOut` and `user` as props automatically
function Home({ signOut, user }: { signOut?: () => void; user?: any }) {
  const [vendors, setVendors] = useState([]);
  const [form, setForm] = useState({ name: '', category: '', contactEmail: '' });
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');

  const loadVendors = async () => {
    try {
      const data = await getVendors();
      setVendors(data);
    } catch {
      setError('Failed to load vendors.');
    }
  };

  useEffect(() => {
    loadVendors();
  }, []);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    setError('');
    try {
      await createVendor(form);
      setForm({ name: '', category: '', contactEmail: '' });
      await loadVendors();
    } catch {
      setError('Failed to add vendor.');
    } finally {
      setLoading(false);
    }
  };

  const handleDelete = async (vendorId: string) => {
    try {
      await deleteVendor(vendorId);
      await loadVendors();
    } catch {
      setError('Failed to delete vendor.');
    }
  };

  return (
    
      {/* ── Header ── */}
      
        
          Vendor Tracker
          Signed in as: {user?.signInDetails?.loginId}
        
        
      

      {error && (
        {error}
      )}

      

        {/* ── Add Vendor Form ── */}
        
          Add New Vendor
          
             setForm({ ...form, name: e.target.value })}
              required
            />
             setForm({ ...form, category: e.target.value })}
              required
            />
             setForm({ ...form, contactEmail: e.target.value })}
              required
            />
            
          
        

        {/* ── Vendor List ── */}
        
          
            Current Vendors ({vendors.length})
          
          
            {vendors.length === 0 ? (
              No vendors yet.
            ) : (
              vendors.map(v => (
                
                  
                    {v.name}
                    {v.category} · {v.contactEmail}
                  
                  
                
              ))
            )}
          
        

      
    
  );
}

// Wrapping Home with withAuthenticator means any user who is not logged in
// will see Amplify's built-in login/signup screen instead of this component.
export default withAuthenticator(Home);

8.5 Pass the Auth Token to API Calls

Now that API Gateway requires a JWT on every request, your fetch calls need to include the token in the Authorization header. Without it, every request will return a 401 Unauthorized error.

Update frontend/lib/api.ts with a token helper and updated fetch calls:

import { fetchAuthSession } from 'aws-amplify/auth';
import { Vendor } from '@/types/vendor';

const BASE_URL = process.env.NEXT_PUBLIC_API_URL!;

// Retrieves the current user's JWT token from the active Amplify session
const getAuthToken = async (): Promise => {
  const session = await fetchAuthSession();
  const token = session.tokens?.idToken?.toString();
  if (!token) throw new Error('No active session. Please sign in.');
  return token;
};

export const getVendors = async (): Promise => {
  const token = await getAuthToken();
  const response = await fetch(`${BASE_URL}/vendors`, {
    headers: { Authorization: token },
  });
  if (!response.ok) throw new Error('Failed to fetch vendors');
  return response.json();
};

export const createVendor = async (
  vendor: Omit
): Promise => {
  const token = await getAuthToken();
  const response = await fetch(`${BASE_URL}/vendors`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: token,
    },
    body: JSON.stringify(vendor),
  });
  if (!response.ok) throw new Error('Failed to create vendor');
};

export const deleteVendor = async (vendorId: string): Promise => {
  const token = await getAuthToken();
  const response = await fetch(`${BASE_URL}/vendors`, {
    method: 'DELETE',
    headers: {
      'Content-Type': 'application/json',
      Authorization: token,
    },
    body: JSON.stringify({ vendorId }),
  });
  if (!response.ok) throw new Error('Failed to delete vendor');
};

What getAuthToken does:

fetchAuthSession() reads the currently logged-in user's session from the browser. Amplify stores the session in memory and localStorage after the user signs in.

session.tokens?.idToken is the JWT string that API Gateway's Cognito Authorizer is looking for. Passing it as the Authorization header tells API Gateway: "This request is from an authenticated user."

8.6 Troubleshooting Cognito

When a new user signs up through the Amplify UI, Cognito marks the account as Unconfirmed until the user verifies their email address. A verification code is sent to the user's email. After entering the code, the account becomes confirmed and the user can log in.

If you are testing locally and want to skip the email step, you can manually confirm any account in the AWS Console:

Open the AWS Console and navigate to Cognito
Click on your User Pool (VendorUserPool...)
Click the Users tab
Click on the user's email address
Open the Actions dropdown and click Confirm account

401 Unauthorized errors after deployment

If you are getting 401 errors, check two things:

Open Chrome DevTools --> Network tab, click the failing request, and look at the Request Headers. You should see an Authorization header with a long string of characters. If it is missing, getAuthToken is failing. Check that Amplify is configured correctly in providers.tsx and wired in via layout.tsx.
In your CDK stack, confirm that authorizationType: apigateway.AuthorizationType.COGNITO is present on every protected method definition. If it is missing, API Gateway may not be checking tokens even though the authorizer is defined.

Part 9: Deploy the Frontend with S3 and CloudFront

Your app works locally. Now you'll deploy it to a real HTTPS URL that anyone in the world can visit.

The strategy: Next.js will export your React app as a set of static HTML, CSS, and JavaScript files. Those files will be uploaded to an S3 bucket (AWS's file storage service). CloudFront sits in front of the bucket as a Content Delivery Network (CDN), distributing your files to servers around the world and serving them over HTTPS.

9.1 Configure Next.js for Static Export

Open frontend/next.config.js (or next.config.mjs) and add the output: 'export' setting:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Generates a static /out folder instead of a Node.js server
};

export default nextConfig;

Note on 'use client' and static export: When output: 'export' is set, Next.js builds every page at compile time. Any component that uses browser-only APIs – like withAuthenticator from Amplify – must have 'use client' at the top of the file. This tells Next.js to skip server-side rendering for that component and run it only in the browser.

You already have 'use client' in page.tsx. If you ever see a build error mentioning window is not defined or similar, check that the relevant component has 'use client' at the top.

Build the frontend:

cd frontend
npm run build

This generates an /out folder containing your complete website as static files. Verify the folder was created:

ls out
# You should see: index.html, _next/, etc.

9.2 Add S3 and CloudFront to the CDK Stack

Open backend/lib/backend-stack.ts and add the hosting infrastructure. Here's the complete final version of the file:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import * as cognito from 'aws-cdk-lib/aws-cognito';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';
import * as origins from 'aws-cdk-lib/aws-cloudfront-origins';
import * as s3deploy from 'aws-cdk-lib/aws-s3-deployment';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';

export class BackendStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 1. DynamoDB Table 
    const vendorTable = new dynamodb.Table(this, 'VendorTable', {
      partitionKey: { name: 'vendorId', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    // 2. Lambda Functions
    const lambdaEnv = { TABLE_NAME: vendorTable.tableName };

    const createVendorLambda = new NodejsFunction(this, 'CreateVendorHandler', {
      entry: 'lambda/createVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const getVendorsLambda = new NodejsFunction(this, 'GetVendorsHandler', {
      entry: 'lambda/getVendors.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const deleteVendorLambda = new NodejsFunction(this, 'DeleteVendorHandler', {
      entry: 'lambda/deleteVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    // 3. Permissions
    vendorTable.grantWriteData(createVendorLambda);
    vendorTable.grantReadData(getVendorsLambda);
    vendorTable.grantWriteData(deleteVendorLambda);

    // 4. Cognito User Pool
    const userPool = new cognito.UserPool(this, 'VendorUserPool', {
      selfSignUpEnabled: true,
      signInAliases: { email: true },
      autoVerify: { email: true },
      userVerification: {
        emailStyle: cognito.VerificationEmailStyle.CODE,
      },
    });

    userPool.addDomain('VendorUserPoolDomain', {
      cognitoDomain: { domainPrefix: `vendor-tracker-${this.account}` },
    });

    const userPoolClient = userPool.addClient('VendorAppClient');

    // 5. API Gateway + Authorizer
    const api = new apigateway.RestApi(this, 'VendorApi', {
      restApiName: 'Vendor Service',
      defaultCorsPreflightOptions: {
        allowOrigins: apigateway.Cors.ALL_ORIGINS,
        allowMethods: apigateway.Cors.ALL_METHODS,
        allowHeaders: ['Content-Type', 'Authorization'],
      },
    });

    const authorizer = new apigateway.CognitoUserPoolsAuthorizer(
      this,
      'VendorAuthorizer',
      { cognitoUserPools: [userPool] }
    );

    const authOptions = {
      authorizer,
      authorizationType: apigateway.AuthorizationType.COGNITO,
    };

    const vendors = api.root.addResource('vendors');
    vendors.addMethod('GET', new apigateway.LambdaIntegration(getVendorsLambda), authOptions);
    vendors.addMethod('POST', new apigateway.LambdaIntegration(createVendorLambda), authOptions);
    vendors.addMethod('DELETE', new apigateway.LambdaIntegration(deleteVendorLambda), authOptions);

    // 6. S3 Bucket (Frontend Files) 
    const siteBucket = new s3.Bucket(this, 'VendorSiteBucket', {
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
      autoDeleteObjects: true,
    });

    // 7. CloudFront Distribution (HTTPS + CDN)
    const distribution = new cloudfront.Distribution(this, 'SiteDistribution', {
      defaultBehavior: {
        origin: new origins.S3Origin(siteBucket),
        viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
      },
      defaultRootObject: 'index.html',
      errorResponses: [
        {
          // Redirect all 404s back to index.html so React can handle routing
          httpStatus: 404,
          responseHttpStatus: 200,
          responsePagePath: '/index.html',
        },
      ],
    });

    // 8. Deploy Frontend Files to S3 
    new s3deploy.BucketDeployment(this, 'DeployWebsite', {
      sources: [s3deploy.Source.asset('../frontend/out')],
      destinationBucket: siteBucket,
      distribution,
      distributionPaths: ['/*'], // Clears CloudFront cache on every deploy
    });

    // 9. Outputs ───────────────────────────────────────────────────────────
    new cdk.CfnOutput(this, 'ApiEndpoint', { value: api.url });
    new cdk.CfnOutput(this, 'UserPoolId', { value: userPool.userPoolId });
    new cdk.CfnOutput(this, 'UserPoolClientId', { value: userPoolClient.userPoolClientId });
    new cdk.CfnOutput(this, 'CloudFrontURL', {
      value: `https://${distribution.distributionDomainName}`,
    });
  }
}

What the hosting infrastructure does:

The S3 bucket stores your static HTML, CSS, and JavaScript files. It is private – users cannot access it directly.
CloudFront is the CDN that sits in front of S3. It gives you an HTTPS URL and caches your files at edge locations worldwide, so the app loads fast no matter where users are located. REDIRECT_TO_HTTPS automatically upgrades any HTTP request to HTTPS.
The error response for 404 returns index.html instead of an error page. This is necessary for single-page apps: if a user navigates directly to a route like /vendors/123, CloudFront cannot find a file at that path, but sending back index.html lets the React app handle the routing correctly.
distributionPaths: ['/*'] tells CloudFront to invalidate its entire cache after every deployment. This ensures users always see the latest version of your app immediately.
BucketDeployment is a CDK construct that automatically uploads the contents of your frontend/out folder to the S3 bucket every time you run cdk deploy.

9.3 Run the Final Deployment

First, build the frontend with the latest environment variables:

cd frontend
npm run build

Then deploy everything from the backend folder:

cd ../backend
cdk deploy

After deployment finishes, copy the CloudFrontURL from the terminal output:

Outputs:
BackendStack.CloudFrontURL = https://d1234abcd.cloudfront.net

Open that URL in your browser. Your app is now live on the internet, served over HTTPS, globally distributed.

What You Built

You now have a fully deployed, production-style full-stack application. Here is a summary of every piece you built and what it does:

Layer	Service	What it does
Frontend	Next.js + CloudFront	React UI served globally over HTTPS
Auth	Amazon Cognito + Amplify	User sign-up, login, and JWT token management
API	API Gateway	Routes HTTP requests, validates auth tokens
Logic	AWS Lambda (×3)	Creates, reads, and deletes vendors on demand
Database	DynamoDB	Stores vendor records with no idle cost
Storage	S3	Holds your built frontend files
Infrastructure	AWS CDK	Defines and deploys all of the above as code

Conclusion

You have built and deployed the foundational pattern of almost every cloud application: a secured API backed by a database, deployed with infrastructure as code. Here is everything you accomplished:

You set up a professional AWS development environment with scoped IAM credentials. You defined your entire backend infrastructure as TypeScript code using AWS CDK, which means your database, API, Lambda functions, and authentication system are all version-controlled, repeatable, and deployable with a single command.

You wrote three Lambda functions that handle create, read, and delete operations, each with proper error handling and the correct AWS SDK v3 patterns. You connected them to a REST API through API Gateway and protected every route with Amazon Cognito authentication, so only registered, verified users can interact with your data.

On the frontend, you built a Next.js application with a service layer that cleanly separates API logic from UI components, manages JWTs automatically through AWS Amplify, and gives users a complete sign-up and sign-in flow without you writing a single line of authentication UI code.

Finally, you deployed the entire system: your backend to AWS Lambda and DynamoDB, and your frontend as a static site served globally through CloudFront over HTTPS.

The full source code for this tutorial is available on GitHub. Clone it, modify it, and use it as a reference for your own projects.

React - freeCodeCamp.org

How to Build a Reliable SSE Client in TypeScript

Table of Contents

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

How to Build an Animated Badge Component with shadcn/ui

Table of Contents

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

How to Build a Scalable Design System in a Monorepo

Table of Contents

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

Create Your Turborepo Project

Design Your Package Structure

Detailed file structure

Build Your Design Tokens Package

Create Primitive Components

Configure the Turborepo Pipeline

Build the @yourds Packages

Use Your Design System in an App

My App with Design System

Wrapping up

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

Table of Contents

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

A Few Shared Helpers

The Database Layer (So Far)

Capturing New Visits Live

Backfilling 14 Days of History

Checkpoint

How to Turn Noise into Sessions

Filtering Out Noise

Extracting Keywords

Extending the Database For Sessions

Segmenting Events into Sessions

Checkpoint

How to Cluster Sessions into Intent Threads

Detecting Ambient Domains

Extending the Database for Intent Threads

Clustering Sessions into Threads

Scoring and Classifying Threads

Putting it Together

Checkpoint

How to Clean Up Self-Referential Noise

What `useCallback` and `useMemo` Do

When to Use `useCallback` and `useMemo`

Stabilize References for `React.memo` Children