React - freeCodeCamp.org

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.

The Modern React Data Fetching Handbook: Suspense, use(), and ErrorBoundary Explained

Tapas Adhikary — Thu, 12 Feb 2026 15:19:30 +0000

Most React developers don’t break the data fetching process all at once. It usually degrades gradually, slowly.

Traditionally, you may have used a useEffect here, a loading flag there, and an error state along with it to tackle data fetching. Moving forward, another fetch depended on the first one, then a second useEffect, and another loading and error state.

This likely continued until you started feeling like you were writing code that you yourself could’t even maintain in the future.

Requests that should run in parallel started running sequentially. Components re-rendered unnecessarily just to satisfy another data fetch request-response. Loading spinners appeared when nothing meaningfully changed. Error states got scattered inside the component.

Well, none of these things are React’s problem. These are core design problems you should be aware of while coding your React Apps.

In this handbook, we’ll walk through one React Pattern that fixes data fetching at the architecture level without ignoring real data dependencies, and without introducing any new magic. If data fetching in React has ever felt harder than it should be, this pattern will make even more sense to you.

You’ll learn how to use React’s Suspense with the recently introduced use() API to handle data fetching smoothly. In case of errors, you’ll learn how an Error Boundary can help handle them gracefully.

Give this one a read, and code along to get a better grip on this pattern’s mental model.

This handbook is also available as a video tutorial as part of the 15 Days of React Design Patterns initiative. You can check it out if you’d like:

We’ll use a lot of source code to demonstrate the problems with the traditional data-fetching approach and how the Suspense Pattern can improve things. I would suggest that you try the code as you read. But if you want to take a look at the source code ahead of time, you can find it on the tapaScript GitHub.

The Traditional Way of Data Fetching in React
- The Problem with the Traditional Way
Let’s Build a Dashboard with the Traditional Data Fetching Approach
What is Suspense?
What is the use() API in React?
How to Use Suspense and the use() API for Data Fetching
Let’s Build the Dashboard with Suspense and the use() API
How to Handle Error Scenarios with Error Boundaries?
- Error Boundary
- Suspense and Error Boundary
Learn from the 15 Days of React Design Patterns
Before We End…

The Traditional Way of Data Fetching in React

To understand why data fetching can become painful in React, we first need to understand how React works under the hood.

React works in phases. It doesn’t do everything at once. At a high level, every update in React goes through three distinct phases:

Render phase – React figures out what the UI should look like
Commit phase – React applies those changes to the DOM
Effect phase – React synchronises with the outside world

This separation is intentional. It’s what allows React to be predictable, interruptible, and efficient.

Now, let’s see where data fetching with useEffect fits into this picture:

Where does useEffect actually run? It doesn’t run during rendering. It runs after React has already committed the UI to the DOM.

That means the flow looks like this:

React renders the component (without data)
React commits the UI
useEffect runs
Data fetching starts
State updates when the data arrives
React renders again

useEffect(() => {
  fetchData().then(setData);
}, []);

Hence, the fetch only starts after the UI has already rendered.

The Problem with the Traditional Way

Consider a very common scenario: you fetch a user, and then fetch related data using the user ID.

The traditional React data fetching solution would look like this:

useEffect(() => {
  fetchUser().then(setUser);
}, []);

useEffect(() => {
  if (!user) return;
  fetchOrders(user.id).then(setOrders);
}, [user]);

What actually happens is:

The component renders
React commits the UI
The first effect runs and fetches the user
React re-renders
The second effect runs and fetches orders

Even if the network is fast, the requests are forced to start one after another, because each fetch is triggered by a render that only happens after the previous fetch completes.

This paradigm of data fetching is called Fetch-On-Render. The fetching logic is no longer controlled by data dependencies – it’s controlled by render timing. But that’s not all. There are other problems with this approach: you create and maintain unnecessary states.

Now, let’s see both these problems in action by building something practical.

Let’s Build a Dashboard with the Traditional Data Fetching Approach

Let’s build a simple dashboard with the traditional data fetching approach using the useEffect hook at the center. The dashboard will have four primary sections:

A Static heading.
A Profile section welcoming the user with their name.
An Order section listing the items ordered by the user.
An Analytics section showing a few metrics for the same user.

You can visualise it like this:

The profile, order, and analytics sections should show the dynamic data of a user and their order and analytics. Hence, we’ll simulate three API calls to get the user details, order details, and the analytics data.

// API to fetch User
export function fetchUser() {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({ id: 1, name: "Tapas" });
    }, 1500);
  });
}

// API to fetch the Orders of a User
export function fetchOrders(userId) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      resolve([
          `Order A for user ${userId}`,
          `Order B for user ${userId}`
      ]);
    }, 1500);
  });
}

// API to fetch the Analytics of a User
export function fetchAnalytics(userId) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({
        revenue: "$12,000",
        growth: "18%",
        userId
      });
    }, 1500);
  });
}

As you can see in this code:

Each of the API functions returns a promise.
There is an intentional delay of 1.5 seconds using setTimeout to simulate the feel of a network call. The promise resolves after the delay passes.
Once the promise gets resolved, we get the data.

Now, let’s create the Dashboard component:

import { useEffect, useState } from "react";
import { fetchAnalytics, fetchOrders, fetchUser } from "../api";

export default function Dashboard() {
    const [user, setUser] = useState(null);
    const [orders, setOrders] = useState(null);
    const [analytics, setAnalytics] = useState(null);

    // Step 1: Fetch user
    useEffect(() => {
        fetchUser().then(setUser);
    }, []);

    // Step 2: Fetch orders (depends on user)
    useEffect(() => {
        if (!user) return;
        fetchOrders(user.id).then(setOrders);
    }, [user]);

    // Step 3: Fetch analytics (depends on user)
    useEffect(() => {
        if (!user) return;
        fetchAnalytics(user.id).then(setAnalytics);
    }, [user]);

    // Logic to ensure that user, orders, and analytics data 
    // loaded before we render them on JSX
    if (!user || !orders || !analytics) {
        return <p className="text-xl m-3">Loading dashboard...p>;
    }

    return (
        <div className="m-2">
            <header>
                <h1 className="text-5xl mb-12">📊 Dashboardh1>
            header>

            <h2 className="text-3xl">Welcome, {user.name}h2>

            <h2 className="text-3xl mt-3">Ordersh2>
            <ul>
                {orders.map((o) => (
                    <li className="text-xl" key={o}>
                        {o}
                    li>
                ))}
            ul>

            <h2 className="text-3xl mt-3">Analyticsh2>
            <p className="text-xl">Revenue: {analytics.revenue}p>
            <p className="text-xl">Growth: {analytics.growth}p>
        div>
    );
}

Let’s break it down:

The first thing you’ll notice is that we have three states for holding the data of users, orders, and analytics.
Then we have three useEffects to manage the fetching of data and updating the states.
Then we show the data values in the JSX.
We’re using a Fetch-On-Render methodology.

However, in between, there’s an explicit logic to check if the user data, order data, or analytics data has been loaded. If the data are not loaded, then we don’t even process the JSX – rather, we show a loading message.

// Logic to ensure that user, orders, and analytics data 
// loaded before we render them on JSX
if (!user || !orders || !analytics) {
  return <p className="text-xl m-3">Loading dashboard...p>;
}

This is good as a measure so that the UI doesn’t crash at runtime. But this is not a declarative approach. Since React is declarative, it would make more sense if we could handle this scenario in a declarative way as well.

In Declarative programming, you as a programmer don’t specify how to to solve certain problems. You declare what you want to achieve, and the programming language/framework takes care of the “how” part for you. When you specify the “how” part, it becomes imperative, not declarative.

React is declarative because you don’t specify how to update the browser DOM to render the UI changes. You declare them using JSX, and React takes care of it under the hood.

As an alternative to the explicit imperative logic like the above, you could also handle it using loading states. You could have loading states for profile, orders, and analytics. The loading states could decide when to show the data conditionally. But this approach needs additional state management and conditional rendering of JSX.

Along with these issues, think of handling errors! Again, you would need states for error handling and the conditional logic to show and hide the error messages. That’s too much to manage.

So, with the useEffect strategy, data fetching in React is not that effective. We need a better pattern to handle data along with loading states and errors.

But before we move on, I want to clarify that useEffect isn’t bad. It has a purpose, but sometimes we don’t use it as intended. If you’re someone who wants to learn the effective usages of this hook and how to debug it properly, you can check out this session.

What is Suspense?

At its core, React Suspense is not a loading feature. It’s a rendering coordination mechanism. Suspense allows a component to tell React, “I’m not ready to be rendered, yet”. When that happens, React pauses rendering for that part of the tree and shows a fallback UI until the required data becomes available.

This is fundamentally different from how data fetching works with useEffect.

With the traditional Fetch-On-Render approach, React must first render a component before it’s allowed to start fetching data. Effects run after the commit phase, which means data fetching is always a reaction to rendering, never a prerequisite for it. As applications grow, this creates render-fetch-re-render loops, hidden waterfalls, and loading logic spread across components.

Suspense flips that model.

Instead of rendering first and fetching later, Suspense enables Render-as-you-Fetch. Data fetching can begin before React attempts to commit the UI, and rendering simply waits until the data is ready. The UI doesn’t guess when to show loading states. React coordinates it declaratively through Suspense boundaries.

With Suspense, you need to wrap the component that handles the asynchronous call.

Suspense can pause the rendering while the wrapped component is dealing with the promise. Suspense can show a fallback UI (it could be a loader, UI skeleton, and so on) until the promise is resolved (or rejected). Once the promise is resolved, Suspense replaces the fallback UI with the actual wrapped component baked with the data. No hard-coded logic, no extra state management is needed.

What is the `use()` API in React?

use() is an API introduced in React 19 that accepts a promise and returns its resolved value. If the promise hasn’t resolved yet, React doesn’t continue rendering. It suspends. If the promise fails, React throws an error. Both cases are handled declaratively by Suspense and Error Boundaries.

import { use } from "react";

function fetchUser() {
  return fetch("/api/user").then(res => res.json());
}

const userPromise = fetchUser();

export default function Profile() {
  const user = use(userPromise);
  return <h2>Welcome, {user.name}h2>;
}

What’s important here:

use() is called during render
If the promise is unresolved, rendering pauses
No useEffect, no loading state

use() is very powerful. It can read promises that depend on other promises.

const userPromise = fetch("/api/user").then(r => r.json());

const ordersPromise = userPromise.then(user =>
  fetch(`/api/orders?userId=${user.id}`).then(r => r.json())
);

function Orders() {
  const orders = use(ordersPromise);
  return (
    <ul>
      {orders.map(o => <li key={o.id}>{o.title}li>)}
    ul>
  );
}

Here:

Dependencies are expressed in data, not effects
Rendering is coordinated automatically (declaratively)

The primary mental model is: this render is not allowed to complete without this data. It suspends.

const data = use(promise);

We need to use Suspense to handle this gap (when the promise hasn’t resolved yet) using a fallback UI, and then to continue rendering once the promise is resolved.

How to Use Suspense and the `use()` API for Data Fetching

The use() API is what finally makes Suspense practical for data fetching. Before use(), Suspense could pause rendering, but React didn’t have a clean way to consume asynchronous data during render without hacks. Most examples relied on custom abstractions or libraries to bridge that gap. use() changed that by allowing React components to read async values directly during rendering.

When a component reads data using use(promise), React treats that promise as a render dependency. If the promise hasn’t resolved yet, React pauses rendering at the nearest Suspense boundary. When it resolves, React retries rendering automatically, without manual state updates, effects, or conditional logic.

import { Suspense, use } from "react";

const userPromise = fetch("/api/user").then(res => res.json());

function Profile() {
  const user = use(userPromise);
  return <h2>Welcome, {user.name}h2>;
}

export default function App() {
  return (
    <Suspense fallback={<p>Loading profile...p>}>
      <Profile />
    Suspense>
  );
}

What happens here:

Profile tries to read userPromise
If the promise is unresolved, React pauses rendering
React renders the nearest Suspense fallback
When the promise resolves, React retries rendering automatically

Here, there are no effects, no loading flags, and no manual re-rendering.

Now, let’s see all these in action together by rebuilding the same Dashboard app.

Let’s Build the Dashboard with Suspense and the `use()` API

Now that we have a better understanding of Suspense and use(), let’s rewrite the same Dashboard application with it.

Project Setup

First, you’ll need to create a React project scaffolding using Vite. You can use the following command to create a Vite-based React project with modern toolings:

npx degit atapas/code-in-react-19#main suspense-patterns

This will create a React 19 project with TailwindCSS configured.

Now use the npm install command to install the dependencies. This will create the node_modules folder for you. At this point, the directory structure should look like this:

API Services

Now under src/, create a new folder called api/. Then create an index.js file under src/app/ with the following code snippet:

export function fetchUser() {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({ id: 1, name: "Tapas" });
    }, 1500);
  });
}

export function fetchOrders(userId) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      resolve([
          `Order A for user ${userId}`,
          `Order B for user ${userId}`
      ]);
    }, 1500);
  });
}

export function fetchAnalytics(userId) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({
        revenue: "$12,000",
        growth: "18%",
        userId
      });
    }, 1500);
  });
}

These are the same APIs we used before when constructing the dashboard with useEffect.

fetchUser: For fetching the user’s profile
fetchOrders: For fetching the orders made by a user
fetchAnalytics: For fetching the analytics data of a user

Create a Centralised User Resource

Now, let’s create a centralised JavaScript utility file where we can create each of the promises by calling their respective fetch methods. It’s a good practice to handle all the fetch APIs and their promises from a single place, rather than keeping them scattered. The same utility can export the promises so that we can consume them in the components.

Create a resources/ folder under src/. Create a file userResource.js file under src/resources/ with the following code:

import { fetchAnalytics, fetchOrders, fetchUser } from "../api";

let userPromise;
let ordersPromise;
let analyticsPromise;

export function createUserResources() {
  userPromise = fetchUser();

  ordersPromise = userPromise.then(user =>
    fetchOrders(user.id)
  );

  analyticsPromise = userPromise.then(user =>
    fetchAnalytics(user.id)
  );
}

export function getUserResources() {
  return {
    userPromise,
    ordersPromise,
    analyticsPromise
  };
}

Here, we export two functions:

The createUserResources() creates all the promises and keeps them ready.
The getUserResources() returns all the promises we can consume later.

Now, the question is, when will we create these promises? That is, where we will call the createUserResources() function? We should create these promises when the application starts up, and the main.jsx file would be the perfect place for that.

Open the main.jsx file, import {createUserResources}, and invoke it immediately.

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.jsx";
import "./index.css";

import { createUserResources } from "./resources/userResource.js";

createUserResources();

ReactDOM.createRoot(document.getElementById("root")).render(
    <React.StrictMode>
        <App />
    React.StrictMode>,
);

Great! Our data fetching APIs and the promises are ready. Let’s create the components where we’ll be using these promises.

Create Individual Components

We’ll create three components to compose the dashboard: Profile, Orders, and Analytics.

Let’s start with the Profile component. Create a folder components/ under the src/. Now, create a Profile.jsx with the following code:

import { use } from "react";
import { getUserResources } from "../resources/userResource";

export default function Profile() {
    const { userPromise } = getUserResources();
    const user = use(userPromise);
    return <h2 className="text-3xl">Welcome, {user.name}h2>;
}

Let’s break it down:

We imported the use() from React, as we’ll be dealing with the use promise here to handle it and get the user name to render.
Next, we need the user promise. We have the getUserResources() function to get that, so we imported it.
Then, inside the Profile component, we destructured userPromise from the getUserResources() function.
After that, we passed the promise to the use(). We have learned that the use() API accepts a promise and returns the result when it is resolved. Until then, the passed-in promise itself will be returned.
Finally, we used the resolved user to extract the name property and render it.

Simple, right? Let’s quickly create the Orders and Analytics components.

The Orders component:

import { use } from "react";
import { getUserResources } from "../resources/userResource";

export default function Orders() {
   const { ordersPromise } = getUserResources();
  const orders = use(ordersPromise);

  return (
    <>
      <h2 className="text-3xl mt-2">Ordersh2>
      <ul>
        {orders.map((o) => (
          <li className="text-xl" key={o}>{o}li>
        ))}
      ul>
    
  );
}

It has the same flow as the Profile component.

Now, let’s do the Analytics component:

import { use } from "react";
import { getUserResources } from "../resources/userResource";

export default function Analytics() {
    const { analyticsPromise } = getUserResources();
    const analytics = use(analyticsPromise);

    return (
        <>
            <h2 className="text-3xl mt-2">Analyticsh2>
            <p className="text-xl">Revenue: {analytics.revenue}p>
            <p className="text-xl">Growth: {analytics.growth}p>
        
    );
}

All three components are ready. Before we move further, let’s reflect once more on what we learned about Suspense.

Suspense wraps a component that deals with promises (async operations). Until the promise gets resolved, the Suspense holds the rendering and can show a fallback UI in the meantime. Once the promise gets resolved and we have the value, the fallback UI gets swapped with the actual component Suspense wrapped.

So, we have the ideal case now: wrapping the , , and with the … boundary to handle the promises and resolved data for each of the components.

Let’s do that, but aren’t we missing something? Yeah we are: the fallback UI. Let’s create it.

Create the Fallback UI

Now we’ll create three different fallback UI components. Create a file Skeletons.jsx under the src/components/ with the following code:

export const ProfileSkeleton = () => <p className="text-3xl m-2">Loading user...p>;
export const OrdersSkeleton = () => <p className="text-3xl m-2">Loading orders...p>;
export const AnalyticsSkeleton = () => <p className="text-3xl m-2">Loading analytics...p>;

We now have a fallback skeleton UI for each of our components. These are very simple components that just render loading messages.

Create the Dashboard Component with Suspense

Now we have everything to make our Dashboard work. Create a suspense/ folder under src/. Then create a Dashboard.jsx file under src/suspense/ with the following code:

import { Suspense } from "react";

import Analytics from "../components/Analytics";
import Orders from "../components/Orders";
import Profile from "../components/Profile";

import {
    AnalyticsSkeleton,
    OrdersSkeleton,
    ProfileSkeleton,
} from "../components/Skeletons";

export default function Dashboard() {
    return (
        <div className="m-2">
            <header>
                <h1 className="text-5xl mb-12">📊 Dashboardh1>
            header>

            <Suspense fallback={<ProfileSkeleton />}>
               <Profile />
            Suspense>
            <Suspense fallback={<OrdersSkeleton />}>
               <Orders />
            Suspense>
            <Suspense fallback={<AnalyticsSkeleton />}>
               <Analytics />
            Suspense>
        div>
    );
}

First, let me explain the code:

We imported Suspense from React, all the components, and all the fallback UI components.
Then we rendered a static header and three suspense boundaries for each of the components. We wrapped Profile, Orders, and Analytics with Suspense, respectively. To handle the pending promise state, we have passed the individual skeleton component as the fallback to the suspense.

How clean is this? If you scroll up and recheck our old implementation of the dashboard using useEffect and compare it with the one we created with suspense, the positive differences are clear.

It’s declarative.
There’s less code, with the chance of fewer bugs
There’s no effect management and synchronisations
There’s no conditional JSX

It’s a huge win 🏆.

Run the Dashboard App

To run the dashboard app, import the dashboard component in the App.jsx file and use it like this:

import Dashboard from "./suspense/Dashboard";
function App() {
    return (
        <div className="flex items-center justify-center gap-12">
            <Dashboard />
        div>
    );
}

export default App;

Next, open the terminal. Run the app using the npm run dev command. You get the same dashboard back, but it’s much improved:

It loads the data of each of the sections independently.
Each of the sections shows the data loading indicator when the promise is pending.
It doesn’t block the entire UI.

Suspense and use() together are very powerful. Now you have learned that powerful pattern end-to-end.

How to Handle Error Scenarios with Error Boundaries

This data fetching handbook wouldn’t be complete without talking about error scenarios and how to handle them. So far, we’ve spoken about only the happy path. But what if any of the promises are rejected? How do we handle that?

To understand this in depth, let’s reject one of the promises – say the Order promise. Open the index.js file under the src/api/ folder and replace the fetchOrder() function with this updated code:

export function fetchOrders(userId) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      // Simulate failure
      if (Math.random() < 0.5) {
        reject(new Error("Failed to fetch orders"));
      } else {
        resolve([
          `Order A for user ${userId}`,
          `Order B for user ${userId}`
        ]);
      }
    }, 1500);
  });
}

Here, the changes are:

We have simulated a failure by rejecting a promise.
The promise gets rejected randomly and throws an error with an error message.

At this point, if you refresh the UI a few times, you’ll randomly get a blank broken UI with the error message logged into the browser console. This isn’t ideal. It kills the UX of the app.

A better way of handling would be to show the error message on the UI and provide a way to retry and check if the user can recover from the error.

This is where Error Boundary comes in.

Error Boundary

Error Boundaries in React exist for a simple reason: Errors are inevitable, and we must handle them gracefully. There could be:

Network requests fail
Data is malformed
The assumptions break

Without boundaries, a single tiny rendering error can crash the entire React tree. Error Boundaries provide React with a structured way to handle failures.

Technically, an Error Boundary is a component that catches errors thrown during rendering. When an error occurs, React stops rendering the subtree and renders a fallback UI instead.

Let’s now create an Error Boundary. Create a file called ErrorBoundary.jsx under src/components with the following code:

import { Component } from "react";
import { createUserResources } from "../resources/userResource";

export default class ErrorBoundary extends Component {
  state = { error: null };

  static getDerivedStateFromError(error) {
    return { error };
  }

  handleRetry = () => {
    this.setState({ error: null });
    createUserResources();
  };

  render() {
    if (this.state.error) {
      return (
        <div className="border border-red-700 rounded p-1">
          <p className="text-xl">{this.state.error.message}p>
          <button 
                className="bg-orange-400 rounded-xl p-1 text-black cursor-pointer" 
                onClick={this.handleRetry}>
            Retry
          button>
        div>
      );
    }

    return this.props.children;
  }
}

Now, let’s understand what’s going on in the code above:

This is a class component that inherits from React.Component. That’s because Error Boundaries must use class lifecycle methods, which are not available in function components.
The component keeps track of whether an error has occurred. state = { error: null } means everything is rendering normally. When an error happens, this state will store the error object.
The static getDerivedStateFromError() is a special lifecycle method. React automatically calls it when a child component throws an error during render.
The handleRetry() method resets the error state back to null. It calls the createUserResources() to reinitialise the async resources.
In the render() method, if an error exists, render a fallback UI, show the error message, and provide an ability to retry the error using a retry button. If no error exists, render the children normally. The Error Boundary becomes invisible when everything works without an error. The fallback UI also can be an external component that we can pass as a prop to the Error Boundary.

If you’re interested in diving deep into the Error Boundary pattern and want to learn various use cases of it, here is a dedicated video you can check out.

Suspense and Error Boundary

Next, we’ll now use the Error Boundary to wrap each of the Suspense boundaries so that if an error originated from any of those, it can be managed. Open the Dashboard.jsx file and wrap each of the Suspense boundaries with the ErrorBoundary component as shown below:

import { Suspense } from "react";
import Analytics from "../components/Analytics";
import ErrorBoundary from "../components/ErrorBoundary";
import Orders from "../components/Orders";
import Profile from "../components/Profile";
import {
    AnalyticsSkeleton,
    OrdersSkeleton,
    ProfileSkeleton,
} from "../components/Skeletons";

export default function Dashboard() {
    return (
        <div className="m-2">
            <header>
                <h1 className="text-5xl mb-12">📊 Dashboardh1>
            header>

            <ErrorBoundary>
                <Suspense fallback={<ProfileSkeleton />}>
                    <Profile />
                Suspense>
            ErrorBoundary>

            <ErrorBoundary>
                <Suspense fallback={<OrdersSkeleton />}>
                    <Orders />
                Suspense>
            ErrorBoundary>

            <ErrorBoundary>
                <Suspense fallback={<AnalyticsSkeleton />}>
                    <Analytics />
                Suspense>
            ErrorBoundary>
        div>
    );
}

That’s it. Now, access the dashboard on the browser. Whenever the order promise rejects, we’ll get the fallback error UI from the error boundary. Note, the remaining UI isn’t broken and rendered successfully. The partial failure of the UI is also recoverable, as we have provided a retry button to attempt to revive that portion. It provides a great UX.

This is how the Suspense boundary, the use() API, and the Error Boundary work together to help you write scalable React code that can be maintained very easily in the future. I hope you found it helpful. All the source code used in this handbook is in the tapaScript GitHub Repository.

Learn from the 15 Days of React Design Patterns

I have some great news for you: after my 40 days of JavaScript initiative, I have now completed a brand new initiative called 15 Days of React Design Patterns (with Bonus Episodes).

If you enjoyed learning from this handbook, I’m sure you’ll love this series, featuring the 15+ most important React design patterns. Check it out, subscribe, and get it for free:

Before We End…

That’s all! I hope you found this insightful.

Let’s connect:

Subscribe to my YouTube Channel.
Check out my courses, 40 Days of JavaScript, 15 Days of React Design Patterns, and Thinking in Debugging.
Follow on LinkedIn if you don't want to miss the daily dose of up-skilling tips.
Join my Discord Server, and let’s learn together.
Follow my work on GitHub.

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

How to Debug React State Updates Like a Pro (Without Polluting Production)

Kelechi Apugo — Mon, 02 Feb 2026 21:22:46 +0000

When you’re debugging a large React codebase, you might start to feel like a detective. Especially when you are looking for unexpected state changes, components that re-render when they like, or Context values that disappear into thin air without any prior warning sign.

And the main difficulty isn’t necessarily what went wrong – it’s pinpointing where it went wrong.

React offers powerful ways to change state, but it doesn’t specify who or what caused those changes. In large apps with many layers of components, hooks, and contexts, this lack of insight can turn simple bugs into frustrating, time-consuming puzzles.

This is where more innovative debugging methods become crucial. Before now, the go-to solution was to sprinkle console.log calls at key points or to fall back to DevTools.

But these days, you can write a small but powerful utility function that can catch the criminal involved in the crimes against your codebase. This utility function can log changes, display meaningful stack traces, and work smoothly with useState, useReducer, Context providers, and custom hooks. And all of the above can occur while remaining invisible in production.

This article guides you through how to use this helper function to improve clarity, minimise guesswork, and debug efficiently without affecting performance or code cleanliness in your live environment.

The Problem
Why This Problem Exists
My Solution: createDebugSetter
- Practical Examples of createDebugSetter
Best Practices for using createDebugSetter
Things to Avoid
Bonus: How to Convert createDebugSetter to a Hook
Conclusion

The Problem

React’s state system is powerful, but it hides too much information when something goes wrong – for example, when an unexpected update happens or a component re-renders endlessly. React doesn’t tell you what triggered the update, what changed, or why it happened. This lack of visibility creates several challenges.

The first is that you can’t easily see which component, function, or effect initiated a state update. In large applications, where the same state may be modified from multiple places, this quickly turns debugging into guesswork. Without clear traces, developers often sprinkle console.log throughout their code to find the source of a single update.

Secondly, React lacks a built-in method for directly comparing previous and current values. This complicates diagnosing whether a bug stems from an incorrect calculation, a faulty API response, or erroneous business logic. The challenge increases with nested objects, arrays, or shared context.

Thirdly, Context updates can trigger re-renders across the entire tree, even for components wrapped in memoisation. But React doesn’t explain why a particular provider changed, leaving teams to wonder what triggered the cascade.

Finally, infinite loops caused by effects, unstable dependencies, or repeated setState calls provide no clues in the console. You only see symptoms like “loading…” repeating endlessly, with no indication of the source.

All of this makes debugging complex React apps frustrating, slow, and often misleading without additional tools or structured techniques.

Why This Problem Exists

React intentionally conceals its internal update process to keep the framework fast and predictable.

Because of this:

setState() doesn’t report where it was called from
Context re-renders can originate from anywhere.
State overrides can happen silently.
Debugging often relies on manually adding console logs.

In large applications, this lack of visibility makes it nearly impossible to trace unexpected state changes.

My Solution: `createDebugSetter`

A small helper function, createDebugSetter, wraps your state setter and logs:

The label of the state
The new value
A complete stack trace showing exactly where the update originated

And best of all, it automatically disables itself in production using NODE_ENV so there’s no impact on your live app.

createDebugSetter

export function createDebugSetter(
  label: string,
  setter:
    | React.Dispatch>
    | React.Dispatch
): React.Dispatch<React.SetStateAction<unknown>> | React.Dispatch<unknown> {
  // In production, return the original setter unchanged
  if (import.meta.env.PROD /* vite-react */) {
    return setter;
  }

  // Create a wrapper that logs before calling the original setter
  return (value: React.SetStateAction | unknown) => {
    // Log the state change
    console.groupCollapsed(
      `%c🔄 [${label}] State Update`,
      "color: #adad01; font-weight: bold;"
    );
    console.log("🆕 New value:", value);
    console.trace("📍 Update triggered from:");
    console.groupEnd();

    // Call the original setter
    setter(value);
  };
}

The function above is a debugging wrapper for React state setters that logs during development.

It takes two parameters: a label for identification and the setState function you want to debug. In development mode, every state update triggers a collapsible console log that shows the new value and the stack trace of the update's origin. In production, the hook skips entirely and returns the original setter unchanged, ensuring zero runtime overhead in deployed applications.

How it does it:

 // In production, return the original setter unchanged
  if (import.meta.env.PROD /* vite-react */) {
    return setter;
  }

In production, the createDebugSetter function returns the React setState as-is. This is because we don’t want to log anything when our code is running in a production environment. Here, we’re using the import.meta.env.PROD from React-vite. It returns a Boolean value that tells us if it’s in the production environment or not.

If it’s not in production, we return the modified setter below.

// Create a wrapper that logs before calling the original setter
  return (value: React.SetStateAction | unknown) => {
    // Log the state change
    console.groupCollapsed(
      `%c🔄 [${label}] State Update`,
      "color: #adad01; font-weight: bold;"
    );
    console.log("🆕 New value:", value);
    console.trace("📍 Update triggered from:");
    console.groupEnd();

    // Call the original setter
    setter(value);
  };

This new setter function first logs a collapsible console group with the label and emoji. Then it shows the new value being set. After that, it displays a stack trace showing where the update was triggered. Lastly, it calls the original setter to actually update the state.

Practical Examples of createDebugSetter

Let’s now see how createDebugSetter can be used in several places within a codebase.

Context Providers

You can use createDebugSetter within a Context provider to log state changes when setState is called. This can help log and trace state changes whenever setState is called in a Context Provider anywhere in the application.

import { createContext, useContext, useState, type ReactNode } from "react";
import { createDebugSetter } from "../utils/createDebugSetter";

interface User {
  name: string;
  email: string;
  role: string;
}

interface UserContextType {
  user: User | null;
  setUser: React.Dispatchnull>>;
  login: (name: string, email: string) => void;
  logout: () => void;
}

const UserContext = createContextundefined>(undefined);

export function UserProvider({ children }: { children: ReactNode }) {
  const [user, setUserOriginal] = useStatenull>(null);

  // Wrap setter with debug functionality
  const setUser = createDebugSetter(
    "UserContext",
    setUserOriginal
  ) as React.Dispatchnull>>;

  const login = (name: string, email: string) => {
    setUser({
      name,
      email,
      role: "user",
    });
  };

  const logout = () => {
    setUser(null);
  };

  return (
    
      {children}
    
  );
}

In the above code sample, we create a modified setUserOriginal called setUser that uses createDebugSetter under the hood. We then expose it to the context value instead of setUserOriginal .

Whenever setUser is called, it triggers createDebugSetter which does its job of checking the environment the code is running in, and returns a modified setter that will call setUserOriginal after the logging process, or will return setUserOriginal as-is.

This is useful because Context updates can trigger many re-renders. This reveals exactly who changed the shared state.

useState

As you saw in the Context provider example above, we can use the same technique in regular components that use React state setters (just as in Context providers). We log and trace the value. It also shows where it was triggered from within the component or application.

import { useState } from "react";
import { useDebugSetter } from "../hooks/useDebugSetter";

export function UseStateExample() {
  const [count, setCountOriginal] = useState(0);
  const [name, setNameOriginal] = useState("React");

  // Wrap setters with debug functionality
  const setCount = useDebugSetter("Counter", setCountOriginal);
  const setName = useDebugSetter("Name", setNameOriginal);

  const handleIncrement = () => {
    setCount(count + 1);
  };

  const handleDecrement = () => {
    setCount(count - 1);
  };

  const handleNameChange = () => {
    setName(name === "React" ? "Vite" : "React");
  };

  return (
    "20px",
        border: "1px solid #ccc",
        borderRadius: "8px",
        margin: "10px",
      }}
    >
      useState Example
      Open the console to see debug logs when state changes.

      "15px" }}>
        
          Count: {count}
        
        
        
      

      "15px" }}>
        
          Name: {name}
        
        
      
    
  );
}

This works exactly like the Context providers example. The only differences are that the component uses the setCount and setName functions out of the box in buttons and related components. Also, unlike the Context provider, this component has local state that can be passed to its child components if needed.

This is ideal for monitoring unforeseen local state changes or loops triggered by effects.

useReducer

React reducers are used to calculate complex logic before updating the state. This can introduce unwanted side effects during the complex phase. createDebugSetter can help in debugging, as shown below:

import { useReducer } from "react";
import { createDebugSetter } from "../utils/createDebugSetter";

interface CounterState {
  count: number;
  step: number;
}

type CounterAction =
  | { type: "increment" }
  | { type: "decrement" }
  | { type: "reset" }
  | { type: "setStep"; step: number };

function counterReducer(
  state: CounterState,
  action: CounterAction
): CounterState {
  switch (action.type) {
    case "increment":
      return { ...state, count: state.count + state.step };
    case "decrement":
      return { ...state, count: state.count - state.step };
    case "reset":
      return { ...state, count: 0 };
    case "setStep":
      return { ...state, step: action.step };
    default:
      return state;
  }
}

export function UseReducerExample() {
  const [state, dispatchOriginal] = useReducer(counterReducer, {
    count: 0,
    step: 1,
  });

  // Wrap dispatch with debug functionality
  const dispatch = createDebugSetter("CounterReducer", dispatchOriginal);

  return (
    "20px",
        border: "1px solid #ccc",
        borderRadius: "8px",
        margin: "10px",
      }}
    >
      useReducer Example
      Open the console to see debug logs for reducer actions.

      "15px" }}>
        
          Count: {state.count}
        
        
          Step: {state.step}
        

        "10px" }}>
          
          
          
          
        
      
    
  );
}

dispatchOriginal, which is the main dispatch function, is replaced with a custom function called dispatch that uses createDebugSetter. When the custom dispatch function is called, it does the job of createDebugSetter and by extension, the job of dispatchOriginal .

This is perfect for logging reducer actions and understanding complex state transitions.

Custom Hooks

Custom hooks are not left out of the equation, as they can use setState in some cases. They’re also capable of running complex logic that could backfire when updating state.

import { useState, useEffect } from "react";
import { useDebugSetter } from "../hooks/useDebugSetter";

// Custom hook that manages a timer
function useTimer(initialSeconds: number = 0) {
  const [seconds, setSecondsOriginal] = useState(initialSeconds);
  const [isRunning, setIsRunningOriginal] = useState(false);

  // Wrap setters with debug functionality
  const setSeconds = useDebugSetter("Timer.seconds", setSecondsOriginal);
  const setIsRunning = useDebugSetter("Timer.isRunning", setIsRunningOriginal);

  useEffect(() => {
    if (!isRunning) return;

    const interval = setInterval(() => {
      setSeconds((prev) => prev + 1);
    }, 1000);

    return () => clearInterval(interval);
  }, [isRunning, setSeconds]);

  const start = () => setIsRunning(true);
  const stop = () => setIsRunning(false);
  const reset = () => {
    setSeconds(0);
    setIsRunning(false);
  };

  return {
    seconds,
    isRunning,
    start,
    stop,
    reset,
  };
}

export function CustomHookExample() {
  const timer = useTimer(0);

  const formatTime = (seconds: number) => {
    const mins = Math.floor(seconds / 60);
    const secs = seconds % 60;
    return `${mins.toString().padStart(2, "0")}:${secs
      .toString()
      .padStart(2, "0")}`;
  };

  return (
    "20px",
        border: "1px solid #ccc",
        borderRadius: "8px",
        margin: "10px",
      }}
    >
      Custom Hook Example
      Open the console to see debug logs for internal hook state changes.

      "15px" }}>
        "24px", fontWeight: "bold" }}>
          {formatTime(timer.seconds)}
        
        
          Status: {timer.isRunning ? "Running" : "Stopped"}
        

        "15px" }}>
          
          
          
        
      
    
  );
}

As shown in previous examples, setSecondsOriginal and setIsRunningOriginal are replaced with setSeconds and setIsRunning. The latter uses the createDebugSetter helper function. This enables console log statements to be printed every second for better visualisation.

Custom hooks often hide multiple internal updates, making it hard to see exactly where each begins.

Best Practices for Using `createDebugSetter`

When using helper functions like createDebugSetter, it’s best to keep in mind why you’re actually using them. For our purpose here, we’re using it to debug a React application. So I’ll share some tips that will help with this debugging process.

Use Clear Labels

Using labels that can say where createDebugSetter was triggered from is a step in the right direction. Detailed labels will help you better understand where and why the issue may be occurring. Also, keep in mind that the createDebugSetter utility function could be used in several places in your application, and improper labelling could make debugging difficult.

Using the name of the component or area that calls it as the label for createDebugSetter can also be a good pointer for clear labelling, as shown below.

// Bad
createDebugSetter("aaa", setUser)
createDebugSetter("1", setUser)

// Good 
createDebugSetter("UserContextProvider", setUser)
createDebugSetter("From UserContextProvider", setUser)
// Too long but can still work
createDebugSetter("From UserContextProvider in user-context.tsx file", setUser)

Use `createDebugSetter` Only in Dev Mode

Using createDebugSetter only in a development environment can prevent many headaches. It’s not a good practice to mistakenly expose or log sensitive data in production. Also, logging in production can cause cluttering.

Use `createDebugSetter` with React DevTools

The createDebugSetter may not be enough for some complex bugs. You can use createDebugSetter and React DevTools for a more powerful/thorough debugging session. Although createDebugSetter cannot be directly integrated with React DevTools, it shows who triggered the update, whereas React DevTools displays what was re-rendered.

Place `createDebugSetter` in `utils`

createDebugSetter is a utility function, as I have mentioned above. This means you should place it in a utils folder so any team member can access and use it when needed across your React application.

Things to Avoid

Avoid using debug setters in production builds. While they are safe, unnecessary logs can slow down debugging tools. Also, sensitive credentials could be logged mistakenly. There are professional tools you can use, such as Sentry, that let you trace errors and debug your app effortlessly.
Don’t conditionally wrap setter functions within components. Perform wrapping outside renders to prevent the creation of new setter identities.
Don’t rely on it to replace proper state architecture. This tool helps identify issues, but doesn’t fix poor state design.
Don’t depend solely on console logs. Use it as part of a broader debugging workflow, not as the only strategy.

Bonus: How to Convert `createDebugSetter` to a Hook

Converting to a Hook

The plain createDebugSetter function works, but it creates a new wrapper function on every render when used inside React components. By converting it into a custom hook with useCallback, we can ensure that the wrapper function maintains a stable reference across re-renders, preventing unnecessary performance overhead and making it safe to use in dependency arrays.

Here’s the hook version:

import { useCallback } from "react";

export function useDebugSetter<T>(
  label: string,
  setState: React.Dispatch>
): React.Dispatch<React.SetStateAction<T>> {
  const debugSetter = useCallback(
    (newValue: React.SetStateAction) => {
      // Only log in development
      if (!import.meta.env.PROD) {
        console.groupCollapsed(
          `%c🔄 State Update: ${label}`,
          "color: #2fa; font-weight: bold;"
        );
        console.log("🆕 New value:", newValue);
        console.trace("📍 Update triggered from:");
        console.groupEnd();
      }

      setState(newValue);
    },
    [label, setState]
  );

  // In production, return the original setter (no wrapping overhead)
  // In development, return the debug wrapper
  return import.meta.env.PROD ? setState : debugSetter;
}

How the Hook Version Works

The core difference between the useDebugSetter hook and createDebugSetter is that the function is wrapped in a useCallback that logs debug information before calling the original setter. Apart from this, all other components of the functions remain the same.

Why the Hook Version is Better

The hook version is superior for component usage because it leverages useCallback memoisation of the debug wrapper. This means the function reference stays the same across renders, avoiding potential re-render cascades when the setter is passed to child components or used in useEffect dependencies.

The plain function, by contrast, generates a brand new wrapper on every render, which can break React's optimisation strategies and cause subtle bugs. In production, both versions simply return the original setter, so there's no performance difference there – but in development, the hook prevents unnecessary work.

When to Use the Hook

Use useDebugSetter whenever you're inside a React component and need to debug state updates. This covers the vast majority of cases: wrapping useState setters, passing debug setters to child components, or including them in effect dependencies.

Only reach for the plain createDebugSetter function when you're working outside React components entirely, such as in utility modules, global stores, or configuration files where hooks can't be used. For day-to-day component debugging, the hook is the right choice.

Conclusion

Debugging React state doesn’t have to be guesswork. With a simple helper, you can instantly see what changed, who changed it, where the change originated, and how your app reached that state – all without touching your production environment.

This small utility function can save hours spent searching through your codebase, making you faster, more precise, and more confident in your React application’s behaviour.

Once you adopt this approach, you’ll never debug state the old way again. 🚀

How to Use the tailwind-sidebar NPM Package in Your React and Next.js Apps

Hitesh Chauhan — Wed, 14 Jan 2026 17:53:43 +0000

These days, developers are increasingly preferring utility-first CSS frameworks like Tailwind CSS to help them build fast, scalable, and highly customizable user interfaces.

In this article, you’ll learn what the tailwind-sidebar NPM package is, how it works internally, and how to install and configure it in a real project. We’ll walk through setting up a responsive sidebar using Tailwind CSS, explore its key features with practical examples, and see how you can customize and control the sidebar behavior to fit different layouts and screen sizes.

If you’re building a React or Next.js application and want a lightweight yet powerful sidebar solution, tailwind-sidebar is an excellent choice.

Prerequisites
Introduction to the tailwind-sidebar NPM Package
Why Choose Tailwind Sidebar?
How to Get Started with Tailwind Sidebar
Features of Tailwind Sidebar:
Wrapping Up

Prerequisites

Basic knowledge of JavaScript (ES6+)
Familiarity with React fundamentals (components, props, JSX)
Basic understanding of Next.js project structure and routing
Experience using npm or yarn for package installation
Working knowledge of Tailwind CSS

The tailwind-sidebar NPM package is a modern, developer-friendly sidebar component that’s built entirely with Tailwind CSS. It’s designed to help developers create responsive, customizable, and accessible sidebars without the overhead of heavy UI frameworks.

tailwind-sidebar is a lightweight utility package designed to simplify building responsive sidebars using Tailwind CSS. Instead of manually handling sidebar state, transitions, and responsive behavior, the package provides a small JavaScript layer that works alongside Tailwind’s utility classes.

At its core, the package toggles Tailwind classes to control whether the sidebar is open or closed. This makes it framework-agnostic - it works with plain HTML, as well as frameworks like React, Vue, or Next.js, as long as Tailwind CSS is available.

Because it relies on Tailwind utilities rather than custom CSS, the sidebar stays easy to customize, extend, and maintain.

What is Tailwind CSS?

Tailwind CSS is a utility-first CSS framework that lets you build modern, responsive user interfaces directly in your markup. Instead of predefined components, Tailwind provides low-level utility classes that give you full design control without leaving your HTML.

Tailwind Sidebar is built on top of Tailwind CSS, offering a clean, flexible, and highly customizable sidebar solution for modern web applications.

Optimized Performance

Tailwind Sidebar relies on utility classes instead of heavy JavaScript logic. This means that it delivers fast load times and smooth interactions, and is ideal for performance-critical applications.

Developer-Friendly

It doesn’t have any complex configuration or component APIs. If you know Tailwind CSS, you already know how to customize the sidebar.

Easy Maintenance

With a simple and predictable structure, updates and custom changes are straightforward, making it suitable for both small projects and large-scale applications.

Growing Tailwind Community

Tailwind CSS has a massive and active community. This means better tooling, regular updates, and a wealth of learning resources to support your development workflow.

This section will walk you through installing and setting up tailwind-sidebar in a React and Next.js application. You’ll learn how to add a sidebar, create menus, add a logo, and customize navigation.

To begin, you’ll need to install tailwind Sidebar into your React and Next.js project. You can do this using either npm or yarn.

Using npm:

npm i tailwind-sidebar

Using yarn:

yarn add tailwind-sidebar

This will add tailwind-sidebar and its dependencies to your project.

Once the package is installed, you can import the necessary components from tailwind-sidebar into your project. These components will allow you to customize the sidebar with menus, submenus, and even a logo.

import {

  AMSidebar,

  AMMenuItem,

  AMMenu,

  AMSubmenu,

  AMLogo,

} from "tailwind-sidebar";

To use the default styles of tailwind-sidebar, you need to import its CSS file at the top of your project:

import "tailwind-sidebar/styles.css";

Step 3: Routing Setup for React and Next.Js

To enable navigation inside tailwind-sidebar components like AMMenuItem or AMLogo, you need to pass a link component from either react-router or next/link using the component prop inside the corresponding component, like what’s shown in the below example:

If you're using React:

import { Link } from "react-router-dom";

<AMSidebar width={"270px"}>

     <AMLogo img="https://adminmart.com/wp-content/uploads/2024/03/logo-admin-mart-news.png"
        component={Link}
        href="/"
      >
        Adminmart

      AMLogo>
      <AMMenu subHeading="HOME">
        <AMMenuItem
         icon={<Home />}
          link="/"  // Passing link to component for routing
          badge={true}
          badgeType="default"
          badgeColor={"bg-secondary"}
          isSelected={true}
        >
          {/* text for your link */}
          Link Text
        AMMenuItem>
      AMMenu>
   AMSidebar>

And if you're using Next.js:

import  Link  from "next/link";<AMSidebar width={"270px"}>
  <AMLogo img="https://adminmart.com/wp-content/uploads/2024/03/logo-admin-mart-news.png"
        component={Link} // Passing link to component for routing
        href="/"
      >
        Adminmart
      AMLogo>
        AdminMart
      Logo>
      <AMMenu subHeading="HOME">
         <AMMenuItem
          icon={<Home />}
          link="/tes"
          component={Link}
          isSelected={true}
        >
           Link Text {/* text for your link */}
        AMMenuItem>
      AMMenu>

Now we’ll set up the AMSidebar component in your application. You can set the width of the sidebar using the width prop. Here’s a simple example:

"270px"}> // pass the width you want your sidebar to have

{/* Sidebar Content Goes Here */}

This initializes the sidebar with a width of 270px. You can adjust this width based on your design requirements.

You can add a logo inside the sidebar by using the AMLogo component. To do so, you can provide an img prop to link to a CDN logo image. You can also make the logo clickable by passing a navigation link using the component and href props. Here’s how you can include a logo:

"270px"}>

<AMLogo img="https://adminmart.com/wp-content/uploads/2024/03/logo-admin-mart-news.png"
component={Link}
href="/" 
>        
Adminmart
AMLogo>

In this example, we’ve added a logo from a CDN using the img prop, used the component prop to pass the Link, and set the navigation path to (/) homepage using the href prop and set the text “AdminMart” as the name of the application.

Now let’s create a menu inside the sidebar using the AMMenu component. You can specify a submenu heading using the subHeading prop. Inside the AMMenu, you can add AMMenuItem components for each item.

You can also provide a link prop along with the component prop to the AMMenuItem to turn the item into a clickable link.

Here’s how you can structure the menu:

"270px"}>
  <AMMenu subHeading="HOME">
  <AMMenuItem  component={Link}  link="/"  badge=”true”  isSelected={true} >
      Modern
    AMMenuItem>
    <AMMenuItem>eCommerceAMMenuItem>
    <AMMenuItem>AnalyticalAMMenuItem>
  AMMenu>

In this example:

We’ve added a AMMenu with the heading “HOME”.
The first AMMenuItem has a link prop, so clicking it will navigate to the homepage (/).
The second and third AMMenuItem components are simple text items without links.

You can use the badge="true" prop to indicate a badge or notification on the AMMenuItem. The isSelected={true} prop marks this menu item as currently selected or active (though you can customize this feature according to your needs).

Step 7: Adding Submenus (Optional)

To add submenus inside the main menu, use the AMSubmenu component. The AMSubmenu can be nested inside the AMMenu component and contains its own set of AMMenuItem. Use the title prop to set the submenu heading

Here’s an example of adding a submenu:

"270px"}>
    <AMMenu subHeading="SERVICES">
      <AMMenuItem  component={Link}   link="/web-development">Web DevelopmentAMMenuItem>
      <AMMenuItem component={Link}  link="/seo-services">SEO ServicesAMMenuItem>
      <AMSubmenu title="Marketing">
            <AMMenuItem component={Link}  link="/digital-marketing">Digital MarketingAMMenuItem>
           <AMMenuItem component={Link}  link="/content-marketing">Content MarketingAMMenuItem>
      AMSubmenu>
  AMMenu>

In this example:

A submenu under the "Marketing" heading is added inside the "SERVICES" menu.
The submenu contains two AMMenuItem with links to different service pages.

Utility-First & Lightweight

Tailwind Sidebar is built entirely using Tailwind CSS utility classes. This means there’s no heavy JavaScript logic or extra styling framework, keeping your bundle size small and performance fast.

Code Example:

"260px" className="bg-gray-900 text-white">
     <AMMenu>
           <AMMenuItem>DashboardAMMenuItem>
      AMMenu>

What’s going on here:

bg-gray-900 text-white: Applies a dark background and white text directly via Tailwind classes (no separate CSS file).
width="260px": The component prop sets the sidebar width. Here, it shows how Tailwind utilities combine with props to control layout.

Because all spacing and colors are from Tailwind classes, you don’t need additional custom styles.

Fully Responsive Design

The sidebar adapts seamlessly to different screen sizes. Whether you’re building for desktop, tablet, or mobile, Tailwind Sidebar ensures a smooth and consistent navigation experience.

Example usage:

"260px" className="hidden md:block">
  <AMMenu>
           <AMMenuItem>HomeAMMenuItem>
      AMMenu>

What’s going on here:

hidden md:block: Uses Tailwind responsive utility classes to hide the component (hidden) on mobile screens and show it starting at the md breakpoint (md:block).

This pattern is Tailwind’s common way of controlling visibility across breakpoints without media queries.

Highly Customizable

Tailwind Sidebar allows full customization of colors, hover states, spacing, and typography directly through Tailwind classes. You can customize layout and animations – all without touching custom CSS files.

Example usage:

 "hover:bg-blue-600 rounded-lg px-4 py-2”>
      Analytics

What’s going on here:

hover:bg-blue-600: When you hover the menu item, the background changes to blue, purely via Tailwind.
rounded-lg: Adds rounded corners.
px-4 py-2: Controls horizontal (px) and vertical (py) padding to adjust spacing.

Together, these utilities show how Tailwind gives control of design details directly at the HTML/JSX level.

Integration with React & Next.Js:

Tailwind Sidebar seamlessly integrates with both React & Next.js, offering a familiar and efficient development experience.

The sidebar works natively with both React Router and Next.js routing by passing the Link component.

React Example
{
  /* if you are using react then import link from  */
}

import { Link } from "react-router-dom";
<AMMenuItem component={Link} link="/dashboard">
            Dashboard 
AMMenuItem>

Next.js Example
{
  /* if you are using nextjs then import link from  */
}

import Link from "next/link";

<AMMenuItem component={Link} link="/dashboard">
         Dashboard
AMMenuItem>

What’s going on here:

component={Link} link="/dashboard": Shows how you pass your framework’s routing component into AMMenuItem, turning it into a real navigational link.

This means Tailwind Sidebar adapts to both React Router and Next.js routing without boilerplate.

Organize your navigation with:

Main menu items
Nested submenus

This makes it easy to manage complex navigation structures while keeping the UI clean and intuitive.

Example usage:

"MANAGEMENT">
             <AMMenuItem>UsersAMMenuItem>
                <AMSubmenu title="Reports">
                   <AMMenuItem>SalesAMMenuItem>
                      <AMMenuItem>RevenueAMMenuItem>
                    AMSubmenu>

What’s going on here:

subHeading="SERVICES": Adds a labeled grouping for menu items.
The nested demonstrates how nested navigation is rendered and structured in JSX.

This example clearly shows hierarchical menus without additional CSS – structure and Tailwind classes handle layout.

Icon Support

The sidebar comes with built-in support for icons, allowing developers to enhance the visual appeal and usability of their application. Developers can use any icon library and provide the icon component.

Example using lucide-react:

import { Home } from "lucide-react";

<AMMenuItem icon={<Home size={18} />}>
     Home
AMMenuItem>

What’s going on here:

icon={}: Here, an icon component is passed as a prop.
You control the size directly via the icon library (Lucide here) and Tailwind handles spacing/placement next to text.

This illustrates how icons and text combine in the sidebar component.

Smooth Transitions

Tailwind Sidebar provides built-in animation support through the animation prop. When enabled, menu items and submenus animate smoothly, improving the overall user experience without requiring custom CSS or JavaScript.

Example Usage:

"270px" animation={true}>
           <AMMenu subHeading="SETTINGS">
                  <AMMenuItem>ProfileAMMenuItem>
                  <AMMenuItem>SecurityAMMenuItem>
             AMMenu>

What’s going on here:

animation={true}: Enables built-in animation support.

The example shows how adding this prop triggers smooth transitions defined by the component itself (still relying on Tailwind utilities internally). You don’t have to write CSS keyframes or transition utilities manually.

Wrapping Up

You have now successfully integrated a fully functional sidebar in your React and Next.js application using tailwind-sidebar. You can further customize the sidebar by:

Modifying the width and design.
Adding more submenus, menu items, or icons.
Using links to navigate between pages.

This setup provides a flexible, responsive, and easy-to-use sidebar, which is perfect for most web applications.

If you want to see how this kind of sidebar fits into a real dashboard layout, you can explore an open-source Tailwind CSS admin template at https://tailwind-admin.com/.

Try It Out:

You can view the working demo of the tailwind-sidebar here: View Demo.

Note: in this tutorial, we utilized lucide-react to construct this sidebar. Feel free to choose an alternative library or use different icons based on your specific requirements.

You can also try Next.js Tailwind Sidebar – a simple and responsive sidebar built for Next.js, and React Tailwind Sidebar – a lightweight Tailwind-based sidebar for React applications.

How to Optimize React

Beau Carnes — Thu, 08 Jan 2026 15:32:30 +0000

React makes it easy to build UIs, but building fast React apps is a different skill altogether.

We just posted a hands-on, real-world React Performance Optimization course on the freeCodeCamp.org YouTube channel. You’ll learn how React actually re-renders, why your app slows down, and which performance patterns truly matter in production. Tapas created this course.

This video is about knowing what to optimize, when to optimize, and how to do it right.

Here are the sections in this course:

Performance Patterns
What’s in Part 1?
Re-Rendering in React
Memoization
The memo()
The useCallback()
the useMemo()
The Derived State
Debouncing
Throttling
Tasks from Part 1
Advanced Patterns
What’s in Part 2?
React Compiler
Lazy Loading & Suspense
Component Isolation
Context Optimizations
Virtualization
Concurrency and useTransition()
Deferred Value
List and Keys
Tools
Tasks from Part 2
One Word of Wisdom

Watch the full course on the freeCodeCamp.org YouTube channel (2-hour watch).

Real-Time Systems for Web Developers: From Theory to a Live Go + React App

Emmanuel Etukudo — Wed, 07 Jan 2026 17:24:03 +0000

Many developers think that “real-time” is about Websockets, Live data, or instant refreshes on web application dashboards.

And although these concepts are closely related to what real-time means, the systems engineering definition is a bit different. A real-time system is not defined by how fast it is, but how predictable it is.

In this tutorial, you’ll learn about what real-time systems are, why most web applications are not real-time, and how to build a soft real-time system with tools you’re likely already familiar with: Go, React, and TypeScript.

At the end of this tutorial, we’ll build a live application that:

processes time-sensitive events
enforces deadlines
drops work when it’s too late
and visualises latency and missed deadlines in real-time

This article will help shape your mind the next time you’re building a real-time system.

Prerequisites
What a Real-Time System Really Means
- Types of Real-Time Systems
- Why Most Web Apps Are Not Real-Time
What We Are Going to Build
System Architecture
Why Go is a Good Fit for Our Use Case
Final Thoughts

Prerequisites

This tutorial assumes that you have basic knowledge of Go, React, and WebSockets, particularly working with go-routines and consuming WebSockets events in React. If you don’t, I strongly recommend reviewing introductory tutorials before continuing so you can get the most out of this guide.

Helpful references include:

Go Concurrency and Goroutines: The official Go blog covers concurrency patterns, including goroutines and channels, which are fundamental for writing concurrent Go code.
WebSockets with Go: A thorough WebSocket tutorial using the popular gorilla/websocket package that shows how to set up a WebSocket server in Go and manage connections and messages. Here’s a Go WebSocket tutorial (with gorilla/websocket).
WebSockets in React: A complete guide to WebSockets in React, explaining how to open and manage a WebSocket connection and handle incoming messages in components. Here’s a complete guide to WebSockets with React.

Technologies we’ll work with include:

Go, for building our backend system and enforcing real-time guarantees
React, for building a responsive frontend UI that displays streamed events
Websocket, for low-latency delivery of data from the backend to the client

What a Real-Time System Really Means

In a traditional web application, correctness is measured by whether the system produced the right result. In a real-time system, correctness is measured by whether the system produced the right result before the deadline. If the result from the test is “No”, then the system has failed – even though the result is correct.

Types of Real-Time Systems

There are a few different types of real-time systems that you should be aware of, each with varying levels of strictness:

Realtime System	Niche applicable
Hard Real-time: Missing a deadline is catastrophic here.	Flight Control & Pacemakers
Soft Real-time: Missing deadline degrades quality but does not crash the system.	Video Streaming & Trading Dashboards
Firm Real-time: Late results are useless and should be discarded.	Car Auction Web/Mobile Apps

The majority of web-based real-time systems fall under the soft real-time category, and that’s exactly what we’ll build here.

Why Most Web Apps Are Not Real-Time

There are many reasons a system may not be real-time, and typically, even those marketed as real-time applications lack this guarantee.

Here’s why:

Websockets guarantee delivery, not timeliness
Massage queues are optimized for durability and throughput
Infinite buffering hides deadlines
User Interfaces (UIs) render when they can, not when they should

In other words, data will arrive eventually, but nothing enforces when it must be processed. That’s exactly the gap we’ll address in this tutorial.

What We Are Going to Build

In this tutorial, we’ll build a Deadline-Aware Live Event Monitor. You can think of it as a simplified real-time system for sensor data, trading events, alerts, or live telemetry.

Our app will have these features and constraints:

Events are generated at a fixed rate
Each event has a deadline
The backend processes events only if they can be completed on time
Late events are marked or dropped
The frontend visualizes:
- processing latency
- missed deadlines
- and system health

This will give us the required metrics to measure the real-time behavior of the system instead of guessing.

System Architecture

The high-level system architecture looks like this:


+-------------+     +------------------+     +----------------+
| Event       | --> | Deadline-Aware   | --> | WebSocket      |
| Generator   |     | Go Processor     |     | Server         |
+-------------+     +------------------+     +----------------+
                                                     |
                                                     v
                                           +----------------+
                                           | React Dashboard|
                                           +----------------+

Let’s break down the responsibilities:

Backend:

Generates time-sensitive events
Enforces deadline
Applies back pressure
Streams result to client (frontend)

Front End:

Consumes real-time events
Renders live metrics
Remains responsive under load

Time is part of your Data Model

In a real-time system, time is explicit, not implicit. This means that each event processed includes:

when it was created
how long is it allowed to live, and
when it was processed

Conceptually, a typical data model for an event looks like this:

{
  id: string
  createdAt: number
  deadlineMs: number
  processedAt?: number
  status: "on-time" | "late" | "dropped"
}

This is the mindset shift we hope to establish: in a real-time system, time is an essential component for your system that guarantees accuracy.

Why Go is a Good Fit for Our Use Case

Go is not a hard real-time language, but it’s excellent for soft real-time workloads. This is because of its:

Cheap goroutines
Structured concurrency with channels
Deadline propagation via context.Context
Simple runtime behavior

Most importantly, Go makes it easy to fail fast, which is essential for real-time systems.

Generating Events with Go

We’ll begin the development of our backend system by first defining the Event struct and creating a fixed-rate event generator function:

type Event struct {
        ID         string
        CreatedAt time.Time
        DeadlineMs  time.Duration
}

Here we’ve created an Event struct with the following properties:

ID a unique identifier that helps in the management of each event processed by the system
CreatedAt to track the time the event was created
Deadline to help evaluate if the event met the assigned deadline or if it failed

Next, we’ll create the event generator startGenerator function:

func startGenerator(out chan<- Event) {
        ticker := time.NewTicker(50 * time.Millisecond)
        defer ticker.Stop()

        for range ticker.C {
                event := Event{
                        ID:         uuid.New().String(),
                        CreatedAt:  time.Now(),
                        DeadlineMs: 100,
                }


                select {
                case out <- event:
                default:
                  // Drop event when load peaks on the goroutine
                }
        }
}

Here, the event generator function accepts a Go channel as a parameter and uses a time.Ticker channel that fires every 50 milliseconds. On each tick, it creates a new Event with a uniqueID, a creation timestamp, and a deadline of 100 milliseconds (DeadlineMs: 100).

The generator then attempts to send the event into the output channel using a non-blocking send. If the channel is ready, the event is delivered immediately. If the channel is not ready (for example, because downstream consumers are slow or overloaded), the default case is executed, and the event is dropped.

Why do we have to drop the event here? Well, because hiding overload drops real-time guarantees. In short, dropping events is a deliberate backpressure strategy: it prevents overload from cascading through the system and protects latency bounds, which is often more important than completeness in real-time streaming systems.

Deadline-aware Processing

Next, we’ll create the processEvent function to handle the processing of the event. In Go, you can enforce deadlines by using context.WithTimeout like this:

func processEvent(event Event) string {
        ctx, cancel := context.WithTimeout(
                context.Background(),
                event.Deadline,
        )

        defer cancel()
        workDone := make(chan struct{})

        go func() {
                time.Sleep(50 * time.Millisecond)
                close(workDone)

        }()

        select {
        case <-workDone:
                return "on-time"
        case <-ctx.Done():
                return "late"
        }
}

Here we’ve intentionally ensured that work finishes before the deadline or it fails immediately.

In the processEvent function, each event is processed under a hard deadline enforced by a context with a timeout. The timeout duration is derived directly from the event’s deadline, meaning the event is only considered valid within the specified time window.

The actual work is executed in a separate goroutine, which simulates processing by sleeping for 50 milliseconds and then signaling completion by closing the workDone channel. We’ve intentionally structured this so that work either completes within the deadline or is treated as a failure immediately.

Applying Back-Pressure

In real-time systems, queues do not solve overload – they merely postpone it. When incoming events arrive faster than they can be processed, a queue continues to grow, increasing the time each event spends waiting.

Buffers can also hide failure. By absorbing excess load, they create the illusion that the system is healthy, even as processing delays grow beyond acceptable limits. This hidden degradation is dangerous because the system continues operating in a compromised state, producing results that are technically correct but operationally useless due to lateness.

As queues and buffers grow, latency increases silently. There is often no explicit error or signal that deadlines are being missed – the system simply becomes slower over time. In real-time systems, this silent latency growth is especially harmful because it violates the assumption that results are delivered within a known and bounded time window.

For these reasons, I strongly recommend that you use bounded channels. When the system becomes overwhelmed, bounded channels enforce back-pressure by refusing additional work. Instead of blocking indefinitely or growing unbounded queues, the system drops events when it cannot keep up.

This behavior makes failures visible. Dropped events are an explicit signal that the system is operating beyond its capacity. Rather than degrading unpredictably, the system degrades in a controlled and observable way. In this context, dropping events is a feature, not a bug, because it preserves latency guarantees for the events that do get processed and allows operators to detect, reason about, and respond to overload conditions immediately.

Streaming Events to the Browser

Next, we’ll build the Websocket broadcast system to push processed events to the frontend using the Gorilla Go websocket package (but feel free to use any package of your choice).

package main

import (
        "encoding/json"
        "net/http"
        "github.com/gorilla/websocket"
)

var upgrader = websocket.Upgrader{
        CheckOrigin: func(r *http.Request) bool {
                return true
        },
}

func wsHandler(out <-chan Event) http.HandlerFunc {
        return func(w http.ResponseWriter, r *http.Request) {
                conn, _ := upgrader.Upgrade(w, r, nil)
                defer conn.Close()
                for event := range out {
                        data, _ := json.Marshal(event)
                        conn.WriteMessage(websocket.TextMessage, data)
                }
        }
}

Here, we simply upgrade an incoming HTTP request to a WebSocket connection and continuously reads events from our Event channel we created earlier, serializing each event to JSON and broadcasting it to the connected client. It acts purely as a transport layer, pushing already-processed events to clients with low latency.

It’s important to note that WebSockets do not make a system real-time. WebSockets merely provide low-latency delivery from the backend to the client. The real-time guarantees are established earlier in the backend pipeline through deliberate design choices: fixed-rate event generation, explicit per-event deadlines, bounded queues, non-blocking sends, deadline-aware processing using contexts, and fail-fast behavior when deadlines are exceeded.

By the time an event is sent over a WebSocket, it has already either met its real-time constraints or been discarded. The WebSocket layer simply transports the result – it doesn’t enforce or create real-time behavior.

Consuming a WebSocket Event (React + TypeScript)

Up until now, we’ve been building the backend of our real-time event generator and broadcast system. In the next sections, we’ll build the frontend of the system using React and TypeScript.

We’ll start by initializing a WebSocket client to consume incoming events from the backend using the traditional WebSocket browser interface.

const socket = new WebSocket("ws://localhost:8080/ws");
socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  buffer.push(data);
};

Here we simply initialize a new WebSocket, passing along the WebSocket URL from the backend. You have to reference the same URL. Instead of rendering every message immediately, it’s recommended that you always batch updates.

Making React Real-Time Friendly

Next, let’s create a React useRealTimeEvents hook to handle streaming and processing of event broadcasts from the backend. Rendering on every message causes render storms, UI lag, and misleading dashboards. Instead, we render on animation frames.

import { useEffect, useRef, useState } from 'react';
import type { RealTimeEvent } from 'types/types';

function useRealTimeEvents() {
  const [events, setEvents] = useState([]);
  const buffer = useRef([]);

  useEffect(() => {
    const ws = new WebSocket('ws://localhost:8080/ws');
    ws.onmessage = (msg) => {
      buffer.current.push(JSON.parse(msg.data));
    };

    let raf: number;

    const flush = () => {
      if (buffer.current.length > 0) {
        const pendingEvents = buffer.current.slice(0);

        setEvents((prev) => {
          const next = [...prev, ...pendingEvents];
          return next.slice(-50);
        });
      }
      raf = requestAnimationFrame(flush);
    };

    raf = requestAnimationFrame(flush);

    return () => {
      ws.close();
      cancelAnimationFrame(raf);
    };
  }, []);
  return events;
}

export default useRealTimeEvents;

The UI is part of the real-time system. It’s important to note that the system broadcasts messages to the frontend in milliseconds. This behavior already crosses the web browser refresh rate threshold.

In certain situations, you might even guess that the use of setTime should come in handy here. And that’s a good alternative – but there’s a better solution: using requestAnimationFrame().

The requestAnimationFrame() takes in a callback function flush which is regulated by the animation frame, ensuring that we don’t cross the refresh rate threshold before the next repaint. You can learn more about it requestAnimationFrame() here.

Creating the StatsBar Component

Next, let’s create a little statusBar component to show events that arrived within the deadline and those that came in late.

Create a new component StatsBar and add the code below:

import { type FC } from 'react';
import type { RealTimeEvent } from 'types/types';

const StatsBar: FC<{ events: RealTimeEvent[] }> = ({ events }) => {
  const late = events.filter((e) => e.status === 'late').length;
  return (
    "flex flex-row gap-2 bg-gray-500 w-full py-2.5 px-2">
      Events: {events.length} | 
      Late: {late}
    
  );
};

export default StatsBar;

Here we are creating a minimal stats component to show the total number of events and those that arrived late by looping through the incoming event list whose statuses are late.

Creating the Events Table

Next, we’ll create a EventTable component to display the events.

import { type FC } from 'react';
import type { RealTimeEvent } from 'types/types';

export const EventsTable: FC<{ events: RealTimeEvent[] }> = ({ events }) => {
  const formatDate = (date: string) => new Date(date).toLocaleString();
  return (
    "w-full">
      "relative overflow-x-auto bg-neutral-primary-soft shadow-xs rounded-base border border-default">
        "w-full text-sm text-left rtl:text-right text-body">
          "text-sm text-body bg-neutral-secondary-soft border-b rounded-base border-default">
            
            {events.map((e, i) => (
              "bg-neutral-primary border-b border-default"
              >
                
            ))}
          
              "col" className="px-6 py-3 font-medium">
                ID
              
              "col" className="px-6 py-3 font-medium">
                Satus
              
              "col" className="px-6 py-3 font-medium">
                Created At
              
              "col" className="px-6 py-3 font-medium">
                Processed At
              
              "col" className="px-6 py-3 font-medium">
                Deadline
              
            
          
          "px-6 py-4">{e.id.slice(0, 6)}
                "px-6 py-4">{e.status}
                "px-6 py-4">{formatDate(e.createdAt)}
                "px-6 py-4">{formatDate(e.processedAt)}
                "px-6 py-4">{e.deadlineMs}
              
        
      
    
  );
};

"col" className="px-6 py-3 font-medium"> ID	"col" className="px-6 py-3 font-medium"> Satus	"col" className="px-6 py-3 font-medium"> Created At	"col" className="px-6 py-3 font-medium"> Processed At	"col" className="px-6 py-3 font-medium"> Deadline
"px-6 py-4">{e.id.slice(0, 6)}	"px-6 py-4">{e.status}	"px-6 py-4">{formatDate(e.createdAt)}	"px-6 py-4">{formatDate(e.processedAt)}	"px-6 py-4">{e.deadlineMs}

Here we loop through all incoming events and display the event’s id, status, and deadline. These metrics will help us gain insight into the performance of our real-time events broadcast system.

Putting it All Together

At this point, we have implemented a complete, end-to-end real-time application that connects a deadline-aware Go backend to a lightweight React frontend. On the backend, events are generated at a fixed rate, processed under explicit deadlines, and dropped when the system is under load to preserve real-time guarantees. Only events that meet these guarantees are forwarded to connected clients via WebSocket broadcast.

On the frontend, we’ve built the useRealtimeEvents hook to establish a persistent WebSocket connection and continuously stream events from the backend as they arrive. The StatsBar component provides immediate visibility into the system’s behavior by summarizing key characteristics of the event stream, while the EventTable component renders individual events in the order they are received. Together, these components clearly mirror the behavior of the system under normal conditions in real-time.

With both the frontend and backend components in place, the application now functions as a real-time monitor. The backend enforces timelines and correctness, and the frontend simply reflects the outcome of those decisions in real-time. There is no buffering or replay logic on the client side – what’s displayed on the UI is exactly what the system was able to process within the specified deadline.

Finally, replace your Welcome component with the code below to display the StatusBar and EventsTable component.

import { useRealtimeEvents } from "./hooks/useRealtimeEvents";
import { StatsBar } from "./components/StatsBar";
import { EventTable } from "./components/EventTable";

export default function App() {
  const events = useRealtimeEvents();

  return (
    
      Real-Time Event Monitor
      
      
    
  );
}

The React frontend is scaffolded using create-react-app, but the same approach can be used for other frameworks, such as Next.js or Vite. The complete source code, including the frontend and backend, is available in the repository here. You can reach out to me on the X platform if you need my assistance.

Final Thoughts

If you’ve followed this tutorial up to this point, congratulations! You’ve learnt the most critical part of building resilient deadline-aware real-time systems.

Remember, real-time systems are not about being fast, but about how predictable they are. You don’t need a Real-Time Operating System (RTOS), a PhD, or specialized hardware to start learning real-time design.

All you need to excel is to respect time, bound your resources, and accept that sometimes, dropping data is the correct behavior. If you understand that, you’re already thinking like a real-time systems engineer.

How to Use the Optimistic UI Pattern with the useOptimistic() Hook in React

Tapas Adhikary — Fri, 12 Dec 2025 18:21:28 +0000

Have you ever clicked a Like icon on a social media app and noticed the count jumps instantly? The colour of the icon changes at the same time, even before the server finishes the action.

Now imagine you hit the same Like button, but it takes its sweet time in making the server call, performing the DB updates, and getting you the response back to update the state of the Like button.

Which experience would you like the most? You are most likely to select the first scenario. We all love “instant feedback”. The magic of instant feedback is powered by a pattern called the Optimistic UI Pattern.

In this article, we will uncover:

What does Optimistic UI really mean?
Why does it massively improve the user experience?
How does React 19’s new useOptimistic() hook make it easier than ever?
How to implement a real-world scenario using the Optimistic Pattern
A bunch of use cases where you will be able to use this pattern.

By the end, you will be proactively thinking of using this design pattern to improve the UX of your project.

This article is also available as a video tutorial as part of the 15 Days of React Design Patterns initiative. Please check it out.

What is Optimistic UI?
How Does it Work Under the Hood?
How to Build an Optimistic Like Button
The Pitfalls and Anti-Patterns
15 Days of React Design Patterns
Before We End...

What is Optimistic UI?

Optimistic UI (also known as optimistic updates) is a pattern that helps you update the UI immediately, assuming the server operation will succeed, and if it later fails, you roll back the UI to the correct state.

Instead of waiting for the round-trip of the client request, database write, server response, and then the UI render, the UI just updates instantly. This dramatically increases what’s called the perceived speed. The user of the application perceives the UI update as instant – but the actual operation may take place in the background.

Without an Optimistic Update:

If you’re not using the optimistic pattern, it’s just a traditional client-server mechanism, where:

At the client side, a user interacts with a UI element.
An async call (request) is made to the server.
The server processes the request and may make DB updates.
On a successful case, the server sends back the response to the client.
The client updates the relevant UI.
In an error case, the server sends back the error response to the client.
The client informs the user about the error.

In this case, the user has to wait for the success/failure of the request to perceive any change after their interaction. This wait is neither uniform nor optimal. It may vary based on the network speed, network latency, and deployment strategies of the application.

With an Optimistic Update:

When you’re using an optimistic update, here’s how things go:

At the client side, a user interacts with a UI element.
The UI gets updated instantly, and the user perceives the feedback immediately.
In parallel, in the background, the client initiates the server call.
The server processes the request and may make DB updates.
On a successful case, the server doesn’t do anything else, as the UI has been updated already, assuming this call will succeed.
In an error case, the server sends back the error response to the client.
The client rolls back the eager, optimistic UI update it made.

In this case, the user doesn’t wait for the server round-trip to complete before the UI is updated. It’s much faster, assuming that, in most cases, the parallel server call will succeed.

With this comparison, we can now understand why Optimistic Updates matter in modern UI.

It improves perceived speed
It keeps users engaged
It eliminates the awkward feelings like “Did my click work?”

And so on. Optimistic updates are critical for real-time feeling features like chat messages, likes, comments, cart updates, poll votes, collaborative editing, and more. Even AI-driven apps that take time to respond benefit from optimistic placeholders like “Thinking…”, “Sending…” and so on.

How Does it Work Under the Hood?

Under the hood, there are actually two states:

The Actual State: This is the actual source of truth. This data should be in sync with the server.
The Optimistic State: This is temporary and instantly shown to the user.

When the server request succeeds, do nothing. Your optimistic state is now correct. If the server request fails, perform a rollback, and return UI the actual state.

React 19 introduced a built-in hook to help with this pattern called useOptimistic() . In the next section, we will take a deep dive into it with code and working internals.

The `useOptimistic()` Hook in React 19

useOptimistic() is a React hook introduced in React 19 to help with optimistic updates. The syntax and usage of the hook go like this:

const [optimisticState, addOptimistic] = useOptimistic(state, updateFn);

When an async action is underway, the useOptimistic() hook allows you to show different states.

It accepts:

currentState: your real source of truth (useState, Redux, server state, and so on)
updateFn: a pure function that says how to compute the optimistic value

It returns:

optimisticState: the temporary UI state
addOptimisticUpdate(input): function you call to apply immediate updates

Take a look at the picture below. It shows the relationship between the current state and the optimistic state clearly:

Here’s what’s going on there:

We pass the current state and an updater function to the useOptimistic hook.
The updater function takes the current state and a user input to compute and return the next optimistic state.
The input to the updater function is supplied using the addOptimistic(input) function.
Finally, the optimistic state value is used in the component.

Let’s now build something exciting using this hook to understand its internals better.

How to Build an Optimistic Like Button

We will be building the Like button functionality optimistically. The flow will be like this:

The user clicks on the Like button.
We update the Like button’s state immediately and optimistically.
In parallel, we send the server call to persist the value into the DB (we will simulate it)
Then we handle any error scenarios.

First, let’s simulate a network call to the server using JavaScript’s Promise object and the setTimeout() web API:

// simulate a network call to the Server
async function sendLikeToServer(postId) {
    await new Promise((r) => setTimeout(r, 700));

    if (Math.random() < 0.2) throw new Error("Network failed");
    console.log(`Sent a like for the post id ${postId}`);
    return { success: true };
}

The sendLikeToServer function takes a post ID as a parameter and simulates a fake network call using a Promise and a delay of 700 ms. It pretends to submit a request to the server to persist a post’s likes value.

To make it a bit more realistic, we have created a random error. The function will throw an error randomly so that we can understand the rollback scenario as well.

Next, we will create the real source of truth, the actual state for the Like count:

const [likes, setLikes] = useState(initialLikes);

Then, create the optimistic state value with the useOptimistic() hook:

 const [optimisticLikes, addOptimisticLike] = useOptimistic(
        likes, (currentLikes, delta) => currentLikes + delta);

Let’s understand this declaration well:

We have passed the actual state value (likes) and the updater function to the useOptimistic() hook.
Take a look at the updater function, (currentLikes, delta) => currentLikes + delta. It’s an arrow function that gets the current like value and a delta. It returns the sum of the current like value and the delta. The return value logic is your own business logic. For incrementing the like count, it makes sense to increase the current like value by a delta value (of 1).
Now, the question is, how do we get this delta value? Who passes it? That’s where the return values of useOptimistic() come in handy. The addOptimisticLike is a function through which we can pass that delta value. How? Let’s take a look.

When someone clicks on the Like button, we need to handle the click event and increase the like count value. So here is a handleLike() function which does that:

const handleLike = async () => {
        addOptimisticLike(1);
        try {
            await sendLikeToServer(postId);
            setLikes((prev) => prev + 1);
        } catch (err) {
            console.error("Like failed:", err);
            setLikes((s) => s); 
        }
};

A lot is happening here:

We call the addOptimisticLike() function with a delta value of 1. This call will ensure that the updater function (currentLikes, delta) => currentLikes + delta of the useOptimistic() will be called. The return value will be set to the optimistic state, that is, optimisticLikes.
This optimistic state value we use in the JSX. So we can see the increased like count immediately.
Then we make the fake server call, and also update the actual state, provided the server call was successful.
In case of an error, the control goes into the catch-block, where we roll back the likes value to the previous one. This will also sync the optimistic state’s value with a rollback.

Here is the complete code of the LikeButton component:


import { startTransition, useOptimistic, useState } from "react";

// simulate a network call to the Server
async function sendLikeToServer(postId) {
    await new Promise((r) => setTimeout(r, 700));

    if (Math.random() < 0.2) throw new Error("Network failed");
    console.log(`Sent a like for the post id ${postId}`);
    return { success: true };
}

// The Like Button Component
export default function LikeButton({ postId, initialLikes = 0 }) {
    // the "real" source of truth for likes (committed)
    const [likes, setLikes] = useState(initialLikes);
    // optimistic state and updater function
    const [optimisticLikes, addOptimisticLike] = useOptimistic(
        likes,
        (currentLikes, delta) => currentLikes + delta
    );

    const handleLike = async () => {
        // 1) Apply optimistic change *immediately*
        addOptimisticLike(1);

        // 2) Start server call in low priority to avoid blocking UI

        try {
            await sendLikeToServer(postId);
            // On success, commit the real state update:
            // IMPORTANT: update the real state so optimistic snapshot eventually matches
            setLikes((prev) => prev + 1);
        } catch (err) {
            // On error, rollback the real state (or trigger a refetch)
            // Because we never incremented likes (real), just leave likes unchanged
            // But we should show an error to user:
            console.error("Like failed:", err);
            // Optionally: show toast or set an error state
            // And — to force the optimistic view to refresh and reflect real state,
            // call setLikes to current value
            setLikes((s) => s); // no-op but will cause optimistic to reflect the
                                // committed value Or you can trigger a re-fetch of the 
                                // post state
        }
    };

    return (
        <div className="flex">
            <button onClick={handleLike}>❤️ {optimisticLikes}button>
            <button onClick={() => startTransition(async () => handleLike())}>
                ❤️ {optimisticLikes}
            button>
        div>
    );
}

Have you noticed that we have wrapped the handleLike() call with the startTransition?

Without this, React gives us a warning:

“An optimistic state update occurred outside a transition or action.”

This is because optimistic updates are low-priority visual updates, not critical ones.

Using startTransition() ensures that:

React doesn’t block rendering
We do not get the warning
We get a smooth, optimistic experience

The transitions are part of React’s concurrency model that helps us improve the performance of React applications. If you are interested in learning various performance optimisation techniques, here is a two-part guide for you.

The Pitfalls and Anti-Patterns

With any design pattern, we need to be aware of possible pitfalls, misuses, and anti-patterns. Here are a few things you should be aware of:

Don’t assume that the server call will be successful. Network failure will happen, and you need to have a way to roll back. Rollback is the heart of optimistic UI. Omitting the rollback logic will cause adverse consequences.
Don’t try hiding the bad UX behind optimistic updates. The Optimistic UI is not a fix or replacement for poor designs.
Don’t perform any expensive work in optimistic updates. Keep the optimistic updater function lean, pure, and fast.

15 Days of React Design Patterns

I have some great news for you: after my 40 days of the JavaScript initiative, I have now started a brand new initiative called 15 Days of React Design Patterns.

If you enjoyed learning from this article, I am sure you will love this series, featuring the 15+ most important React design patterns. Check it out and join for FREE:

Before We End...

That’s all! I hope you found this article insightful. You can find all the source code used in this tutorial on the tapaScript GitHub.

Let’s connect:

Subscribe to my YouTube Channel.
Grab the React Hooks Cheatsheet.
Follow on LinkedIn if you don't want to miss the daily dose of up-skilling tips.
Join my Discord Server, and let’s learn together.
Subscribe to my fortnightly newsletter, The Commit Log.

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

React’s Critical "React2Shell" Vulnerability — What You Should Know, and How to Upgrade Your App

Arunachalam B — Wed, 10 Dec 2025 18:07:42 +0000

Web development is always evolving, and sometimes those changes happen a bit under the hood. One such change involved the shift to React Server Components (RSC). If you’re a NextJS or React developer, especially using the App Router, understanding the new security alert is really important for keeping your apps safe and secure.

What is "React2Shell"?
Why is this Happening Now?
Should You Worry About this Change?
Is this Mandatory?
How Bad Can It Get? The Extent of Exploitation
What Would be the Code Change for This?
Advanced: Verify with the Original Exploit (PoC)
Emergency Response: What If You Were Already Compromised?
Conclusion

What is "React2Shell"?

Think of your server receiving data like a mailroom receiving packages.

Usually, a mailroom checks if a package is safe before opening it. But in vulnerable versions of React and NextJS, the "Flight" protocol (used to communicate between the server and client) acts like a mailroom that blindly opens every package and follows any instructions inside immediately.

This vulnerability (CVE-2025-55182) allows an attacker to send a specifically crafted "package" (HTTP request) that forces your server to execute malicious code – like stealing passwords or installing viruses –without even logging in.

Why is this Happening Now?

It's all about how modern frameworks handle data serialization. There are a few reasons why this was just discovered.

First, React has complex serialization. To make Server Components seamless, React sends complex data structures back and forth.

Second, it has the "Flight" protocol. The vulnerability was found in how this specific protocol de-serializes (unpacks) data. It was too trusting of the input it received from the client side.

Should You Worry About this Change?

You need to pay attention if your app qualifies for any of the below:

You are using NextJS App Router: This is the default in newer NextJS versions (v13+).
You are using React 19: Specifically versions with Server Components enabled.
You use Server Actions: If your app takes user input and processes it on the server using React's server actions.

Is this Mandatory?

Yes. This is a critical security update. If your app qualifies in any of the above scenarios, you need to act immediately. Because, this vulnerability is being exploited right now.

How Bad Can It Get? The Extent of Exploitation

You might be thinking, "My site is just a simple content wrapper, surely I'm not a target?" Unfortunately, with Remote Code Execution (RCE), the attacker doesn't just "break" your site – they own the server it runs on.

Here is exactly what a hacker can do once they exploit this vulnerability:

Total Environment Theft

The most immediate risk is your .env file. Attackers can execute code to read your environment variables, instantly gaining access to your AWS Secret Keys, Database passwords, Stripe API keys, and OpenAI tokens.

The "Shell" Access

As the name "React2Shell" implies, attackers can open a reverse shell. This gives them a command-line interface on your server, allowing them to browse your file system as if they were sitting in front of your computer.

Lateral Movement

Once inside your NodeJS server, they are behind your firewall. They can now attack your internal services (like Redis, internal databases, or private micro-services) that are usually blocked from the outside world.

Supply Chain Poisoning

If your build server is vulnerable, an attacker could potentially inject malicious code into your deployment pipeline, affecting every user who visits your site in the future.

Botnet Recruitment

Hackers often automate these attacks to install crypto-miners, using your server's CPU (which you pay for!) to mine digital currency for them, often crashing your application in the process.

What Would be the Code Change for This?

You don’t need to rewrite your application code, but you must update your dependencies in your release line.

The vulnerability is fully resolved in the following patched NextJS releases:

15.0.5
15.1.9
15.2.6
15.3.6
15.4.8
15.5.7
16.0.7

Patched canary releases for NextJS 15 and 16:

15.6.0-canary.58 (for 15.x canary releases)
16.1.0-canary.12 (for 16.x canary releases)

These versions include the hardened React Server Components implementation.

Here are the patched versions for React JS:

19.0.1
19.1.2
19.2.1

Frameworks and bundlers using the aforementioned packages should install the latest versions provided by their respective maintainers.

Alternatively, you can run npx fix-react2shell-next in your NextJS project to launch an interactive tool which can check versions and perform deterministic version bumps per the recommended versions above. See the GitHub repository for full details.

There is no workaround other than upgrading to a patched version.

It’s highly recommended to rotate all your application secrets, once you have patched your version and re-deployed your application.

Advanced: Verify with the Original Exploit (PoC)

If you want to be 100% sure your patch is working, or if you want to understand how the attack actually works, you can use the original Proof of Concept (PoC) created by the security researcher (Lachlan Davidson) who found the bug.

Repository: React2Shell-CVE-2025-55182-original-poc

Lachlan provided three variations of the exploit script. The most important one for testing is 01-submitted-poc.js, which is the exact, simplified version submitted to Meta for the bug bounty.

How the Exploit Works

According to the repository, the attack works by tricking the parser:

The attacker sends a payload using $@x to access a specific data Chunk.
They "plant" a .then function on a fake object.
The JavaScript runtime thinks it is handling a Promise and tries to "unravel" it.
This allows the attacker to re-enter the parser with a malicious fake chunk, giving them access to internal server gadgets (like _response) to execute code (RCE).

Steps to Recreate the Issue

⚠️ WARNING: Only run this against a local development server (localhost) that you own. Never run this against production servers or public websites.

Note: I forked Lachlan’s repo and made minor changes to make it easy for you to run the script.

Step 1: Clone the Repository

Run the following commands to clone the repository, navigate into the project, and install dependencies:

git clone https://github.com/arunachalam-b/React2Shell-CVE-2025-55182-original-poc.git
cd React2Shell-CVE-2025-55182-original-poc
npm i

Step 2: Run a Vulnerable Local Server

Start your NextJS application locally (ensure it’s running a vulnerable version, for example NextJS 15.0.0, for the test to succeed).

npm run dev
# usually runs on http://localhost:3000

Step 3: Execute the Test

You will need to modify the script or use a tool like curl to send the payload structure found in 01-submitted-poc.js to your server's endpoint (usually a Server Action endpoint). Or simply run the following command if your app is accessible at http://localhost:3000:

node 01-submitted-poc.js

If the exploit succeeds (on the vulnerable version), the console will log the execution of the code (RCE). If the exploit fails (after you patch), the server will either reject the request or error out safely.

You can also confirm if your infected web server prints 50 in the console. Because we inject the code to do a calculation (look at _prefix field in the below JSON) that results in 50.

After you apply the fix, you should see an error while running the script. In this case, as I’m using NextJS v15.1, the fix is upgrading the next package to version 15.1.9. Here are the screenshots after upgrading the package and running the script.

Step 4: Verification

Once you have confirmed the exploit works on the old version, update your packages (as shown in the section above) and run the script again. It should no longer trigger the code execution.

Emergency Response: What If You Were Already Compromised?

If you suspect your server was exposed to the internet with a vulnerable version, assume the worst. A hacker may have already stolen your keys or left a "backdoor" to return later. Patching the code alone is NOT enough in this case.

Follow this "Nuke and Pave" protocol immediately:

Step 1: Isolate and Shutdown

Take the compromised server offline immediately. Do not try to "fix" it while it is running.

Step 2: Rotate ALL Secrets (Crucial Step)

Assume every secret in your .env file is in the hands of a hacker. You must generate new ones:

Change the password for your database users.
Rotate AWS Access Keys, Google Cloud Service Account keys, and so on.
Roll your Stripe/PayPal/Razorpay API keys.
Rotate your NEXTAUTH_SECRET or any JWT signing keys.

Step 3: Do Not "Clean" — Rebuild

Do not attempt to find and delete malware files on the server. Hackers are good at hiding.

Destroy the existing container, droplet, or EC2 instance entirely.
Build a fresh instance from your source code (after applying the patch).

Step 4: Audit Your Logs

Look at your database and cloud provider logs. Did anyone download your entire user database? Did anyone spin up expensive GPU instances on your AWS account? Check for unusual activity that occurred before you patched.

Conclusion

In this article, you learned about the "React2Shell" vulnerability, how to verify it using the original developer's tools, and how to upgrade your app to secure your Server Components. I hope you have a clear idea about why this update is urgent. By being proactive now, you can avoid a catastrophic data breach.

You can follow my Twitter/X account to receive the top AI news everyday. If you wish to learn more about cybersecurity, subscribe to my email newsletter and follow me on social media.

React - freeCodeCamp.org

How to Create Dynamic Emails in Go with React Email

Table of Contents

What is React Email?

Go Templates

Go Template Delimiters

Create Dynamic Emails in Go with React Email

Set Up the Project

Set Up React Email

Create a React Email Template

Set Up Go Templates from HTML Files

Render the Dynamic Email in the Browser

Send and Test Email with go-mail and MailHog

Conclusion

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

Table of Contents

What is Lazy Loading?

Prerequisites

How to Use React.lazy for Code Splitting

My App

How to Use Suspense with React.lazy

My App

How to Handle Errors with Error Boundaries

How to Use next/dynamic in Next.js

Custom Loading UI

Disable Server-Side Rendering

Load on Demand

Named Exports

Using Suspense with next/dynamic

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

When to Use React.lazy

When to Use next/dynamic

Real-World Examples

Example 1: Route-Based Code Splitting in React

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

Analytics

Example 3: Lazy Loading a Modal

Example 4: Lazy Loading External Libraries

Conclusion

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

Table of Contents

What the App Does

Why I Built It

Tech Stack

Product Walkthrough (What Users See)

1. Onboarding and Account Setup

2. Wardrobe Upload

3. Outfit Recommendations

4. Shopping and Discard Assistants

How I Built It

1. Frontend Setup (React + Vite)

2. Backend Architecture with FastAPI

3. Recommendation Logic

4. Authentication and Secure Multi-user Design

5. Background Jobs for Long-running Operations

6. Data Model and Feedback Capture

Challenges I Faced

1. Image-heavy endpoints were slower than I wanted

2. JWT sessions needed real server-side control

3. User data isolation had to be explicit

4. Docker made the project easier to share, but only after the stack was organized

What I Learned

What I Want to Improve Next

Future Improvements

Conclusion

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

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

Table of Contents

Prerequisites

Overview

Why Accessibility and Responsiveness Matter

Core Principles of Accessible and Responsive Design

1. Semantic HTML First

Key ARIA Attributes

1. role

2. aria-label

3. aria-hidden

4. aria-live

Keyboard Navigation

Avoiding Common Keyboard Traps

How to Use `React.lazy` for Code Splitting

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

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

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

When to Use `React.lazy`

When to `Use next/dynamic`

2. Using `srcset` for multiple resolutions: