But when you sit down to build a real SaaS application, you immediately hit a wall of unanswered questions. How do you structure your database? Where does authentication live? How do you make API calls type-safe? How do you handle payments without losing webhooks?

This handbook answers all of those questions. You'll build a production-ready SaaS application from scratch using TanStack Start, Elysia, Drizzle ORM, Neon PostgreSQL, Better Auth, Stripe, and Inngest.

By the end, you will have a deployed application with authentication, a type-safe API, database migrations, payment processing, and background jobs.

I chose this stack after building production applications with Next.js, Express, and Prisma. The combination of TanStack Start and Elysia with Eden Treaty gives you something rare: end-to-end type safety from your database schema to your React components, with zero code generation.

Change a column in your database, and TypeScript tells you everywhere that needs updating. That feedback loop changes how you build software.

Here's what you'll learn:

• How to set up a TanStack Start project with Vite and file-based routing

• How to configure a PostgreSQL database with Drizzle ORM and Neon

• How to build a type-safe API with Elysia embedded in your web app

• How to connect your frontend to your API with Eden Treaty

• How to add GitHub OAuth authentication with Better Auth

• How to build complete features using a repeatable four-layer pattern

• How to process payments with Stripe webhooks

• How to run reliable background jobs with Inngest

• How to deploy everything to Vercel with Neon

Why TanStack Start Instead of Next.js?

You might be wondering – why not just use Next.js? It's the default choice for full-stack React, and for good reason. Next.js pioneered server-side rendering, established conventions that shaped the React ecosystem, and has the largest community of any React framework.

But TanStack Start has three advantages that matter for this kind of project.

1. Deployment flexibility

TanStack Start compiles to standard JavaScript that runs anywhere: Node.js, Bun, Deno, Cloudflare Workers, AWS Lambda, or your own server. Next.js is notoriously difficult to self-host outside of Vercel.

If you search "Next.js Azure App Service container" or "Next.js ISR self-hosted," you'll find years of Stack Overflow questions about edge cases that only appear in production.

2. Simpler mental model

Next.js has grown complex: the App Router, React Server Components, Server Actions, partial prerendering, cache(), unstable_cache(), plus various rendering strategies.

TanStack Start uses full-document SSR with full hydration. There's no opaque server/client boundary confusion. The tradeoff is that you don't get RSC's granular streaming, but you gain clarity and predictability.

3. End-to-end type safety

Combined with Elysia and Eden Treaty, TanStack Start gives you compile-time type inference from your database to your UI. No code generation steps. No schema files to keep in sync.

TanStack Router itself provides fully type-safe routing with inferred path params, search params, and loader data.

This is a handbook, so it goes deep. Set aside a few hours, open your editor, and let's build something real.

Table of Contents

• Prerequisites

• How to Set Up the Project

• How to Configure the Database with Drizzle and Neon

• How to Build the API with Elysia

• How to Add Type-Safe API Calls with Eden Treaty

• How to Add Authentication with Better Auth

• How to Build a Complete Feature (The Four-Layer Pattern)

• How to Add Payments with Stripe

• How to Add Background Jobs with Inngest

• How to Deploy to Vercel with Neon

• Conclusion

Prerequisites

Before you start, make sure you have the following installed:

• Bun (v1.2 or later) for package management and running scripts

• Docker for running PostgreSQL locally

• Git for version control

• Basic knowledge of React and TypeScript

You'll also need free accounts on these services:

• Neon for your production PostgreSQL database

• Vercel for deployment

• GitHub for OAuth authentication (you will create an OAuth app)

• Stripe for payment processing (test mode is free)

All of these services have generous free tiers. You won't need to pay anything to follow this tutorial.

You should also be comfortable reading TypeScript code. This handbook assumes you understand generics, type inference, and async/await. If you're new to TypeScript, the official handbook is a solid starting point.

How to Set Up the Project

Start by creating a new TanStack Start project. TanStack provides a CLI that scaffolds a project with file-based routing, Vite, and server-side rendering out of the box.

bunx @tanstack/cli@latest create my-saas
cd my-saas
bun install

The CLI will ask you a few questions. Choose React as your framework and accept the defaults for the rest.

You're using Bun as your package manager and runtime. Bun is significantly faster than npm for installing dependencies and running scripts. It also natively supports TypeScript execution, which means you can run .ts files directly without a compilation step.

If you prefer npm or pnpm, the commands are similar, but this tutorial uses Bun throughout.

How to Understand the Project Structure

Before writing any code, let's look at how you'll organize this project. The key architectural decision is putting all library code under src/lib/. Each integration (database, auth, payments, and so on) gets its own directory with a clean public API through an index.ts file.

Here's the structure you'll build toward:

my-saas/
├── src/
│   ├── components/          # React components
│   ├── hooks/               # Custom React hooks
│   ├── lib/
│   │   ├── auth/            # Better Auth (server + client)
│   │   ├── db/              # Drizzle ORM + schema
│   │   ├── jobs/            # Inngest background jobs
│   │   └── payments/        # Stripe integration
│   ├── routes/              # TanStack file-based routing
│   ├── server/
│   │   ├── api.ts           # Elysia API definition
│   │   └── routes/          # API route modules
│   └── start.ts             # TanStack Start entry point
├── docker-compose.yml       # Local PostgreSQL + Neon proxy
├── drizzle.config.ts        # Drizzle Kit configuration
├── vite.config.ts           # Vite + TanStack Start config
└── package.json

Here's how all the pieces connect:

TanStack Start handles your frontend. It talks to an Elysia API server embedded in the same project. Elysia connects to three external services: Better Auth for authentication, Stripe for payments, and Inngest for background jobs. Below the API layer, Drizzle ORM provides type-safe database access to Neon PostgreSQL.

You'll build each layer one at a time, starting with the database.

This pattern keeps every integration isolated. When you need to change how authentication works, you go to src/lib/auth/. When you need to modify the database schema, you go to src/lib/db/. Nothing leaks across boundaries.

How to Configure Vite

TanStack Start runs on Vite. Your vite.config.ts needs the TanStack Start plugin, the React plugin, and path resolution for the @/ import alias:

// vite.config.ts
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { defineConfig } from "vite";
import tsConfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [
    tsConfigPaths({
      projects: ["./tsconfig.json"],
    }),
    tanstackStart(),
    viteReact(),
  ],
});

The tsConfigPaths plugin reads the paths setting from your tsconfig.json, so you can use @/lib/db instead of ../../lib/db throughout your code.

Add this to your tsconfig.json:

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

How to Install Dependencies

Install the core dependencies you'll need throughout this tutorial:

# Framework and routing
bun add @tanstack/react-router @tanstack/react-start react react-dom

# API layer
bun add elysia @elysiajs/eden

# Database
bun add drizzle-orm @neondatabase/serverless ws
bun add -d drizzle-kit

# Authentication
bun add better-auth

# Payments
bun add stripe

# Background jobs
bun add inngest

# Build tools
bun add -d @vitejs/plugin-react vite vite-tsconfig-paths typescript

Now you have a working TanStack Start project with all the dependencies you'll need. Start the dev server to make sure everything works:

bun run dev

Visit http://localhost:3000 and you should see your app running.

How to Configure the Database with Drizzle and Neon

Every SaaS needs a database. You'll use Drizzle ORM with Neon PostgreSQL. Drizzle gives you type-safe database queries that look like SQL, and Neon gives you a serverless PostgreSQL database that scales to zero when you aren't using it.

Why Drizzle Instead of Prisma?

If you have used an ORM in the TypeScript ecosystem before, it was probably Prisma. Prisma is excellent for many use cases, but it has a key limitation for this architecture: it uses code generation.

You write a .prisma schema file, run prisma generate, and Prisma generates a TypeScript client. That generation step adds friction to your development loop and creates artifacts you need to keep in sync.

Drizzle takes a different approach. Your schema is TypeScript. Your queries are TypeScript. Types are inferred at compile time without any generation step.

When you add a column to a table, the types update immediately. This fits perfectly with the rest of the stack, where types flow from Drizzle through Elysia to Eden Treaty without any intermediate steps.

Drizzle also produces SQL that looks like SQL. If you know PostgreSQL, you can read Drizzle queries. There is no Prisma-specific query language to learn.

How to Set Up Local PostgreSQL with Docker

For local development, you'll run PostgreSQL in Docker with a Neon-compatible proxy. This lets you use the same Neon serverless driver locally that you'll use in production.

Create a docker-compose.yml at the project root:

# docker-compose.yml
services:
  postgres:
    image: postgres:17
    container_name: my-saas-postgres
    restart: unless-stopped
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: my_saas
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  neon-proxy:
    image: ghcr.io/timowilhelm/local-neon-http-proxy:main
    container_name: my-saas-neon-proxy
    restart: unless-stopped
    environment:
      - PG_CONNECTION_STRING=postgres://postgres:postgres@postgres:5432/my_saas
    ports:
      - "4444:4444"
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:

The neon-proxy container is the important part. It translates HTTP requests into PostgreSQL wire protocol, which means your Neon serverless driver works locally without any code changes.

In production, Neon handles this translation on their infrastructure. Locally, you need this proxy to bridge the gap between the HTTP-based Neon driver and your plain PostgreSQL container.

The healthcheck on the PostgreSQL container ensures the proxy only starts after the database is ready. Without this, the proxy would try to connect to a database that's still initializing, causing connection errors on first startup.

Start the containers:

docker compose up -d

How to Define Your Schema

Create the database client and schema. Start with src/lib/db/index.ts for the connection:

// src/lib/db/index.ts
import { neon, neonConfig } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";
import ws from "ws";

import * as schema from "./schema";

const isProduction = process.env.NODE_ENV === "production";
const LOCAL_DB_HOST = "db.localtest.me";

let connectionString = process.env.DATABASE_URL;

if (!connectionString) {
  throw new Error("DATABASE_URL environment variable is not set");
}

neonConfig.webSocketConstructor = ws;

if (!isProduction) {
  connectionString = `postgres://postgres:postgres@${LOCAL_DB_HOST}:5432/my_saas`;
  neonConfig.fetchEndpoint = (host) => {
    const [protocol, port] =
      host === LOCAL_DB_HOST ? ["http", 4444] : ["https", 443];
    return `\({protocol}://\){host}:${port}/sql`;
  };
  neonConfig.useSecureWebSocket = false;
  neonConfig.wsProxy = (host) =>
    host === LOCAL_DB_HOST ? `\({host}:4444/v2` : `\){host}/v2`;
}

const client = neon(connectionString);
export const db = drizzle({ client, schema });

export * from "./schema";

The db.localtest.me hostname resolves to 127.0.0.1 and is the standard way to work with the local Neon proxy. In production, the Neon driver connects directly to your Neon database using the DATABASE_URL environment variable.

Now define your schema in src/lib/db/schema.ts. For a SaaS application, you need users, sessions, accounts (for OAuth), and a table for your core business entity. Here's a real production schema:

// src/lib/db/schema.ts
import {
  boolean,
  integer,
  pgEnum,
  pgTable,
  text,
  timestamp,
  varchar,
} from "drizzle-orm/pg-core";

export const purchaseTierEnum = pgEnum("purchase_tier", ["pro"]);
export const purchaseStatusEnum = pgEnum("purchase_status", [
  "completed",
  "partially_refunded",
  "refunded",
]);

export const users = pgTable("users", {
  id: text("id").primaryKey(),
  email: varchar("email", { length: 255 }).notNull().unique(),
  emailVerified: boolean("email_verified").notNull().default(false),
  name: text("name"),
  image: text("image"),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

export const sessions = pgTable("sessions", {
  id: text("id").primaryKey(),
  userId: text("user_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
  token: text("token").notNull().unique(),
  expiresAt: timestamp("expires_at").notNull(),
  ipAddress: text("ip_address"),
  userAgent: text("user_agent"),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

export const accounts = pgTable("accounts", {
  id: text("id").primaryKey(),
  userId: text("user_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
  accountId: text("account_id").notNull(),
  providerId: text("provider_id").notNull(),
  accessToken: text("access_token"),
  refreshToken: text("refresh_token"),
  accessTokenExpiresAt: timestamp("access_token_expires_at"),
  refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
  scope: text("scope"),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

export const verifications = pgTable("verifications", {
  id: text("id").primaryKey(),
  identifier: text("identifier").notNull(),
  value: text("value").notNull(),
  expiresAt: timestamp("expires_at").notNull(),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

export const purchases = pgTable("purchases", {
  id: text("id")
    .primaryKey()
    .$defaultFn(() => crypto.randomUUID()),
  userId: text("user_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
  stripeCheckoutSessionId: text("stripe_checkout_session_id")
    .notNull()
    .unique(),
  stripeCustomerId: text("stripe_customer_id"),
  stripePaymentIntentId: text("stripe_payment_intent_id"),
  tier: purchaseTierEnum("tier").notNull(),
  status: purchaseStatusEnum("status").notNull().default("completed"),
  amount: integer("amount").notNull(),
  currency: text("currency").notNull().default("usd"),
  purchasedAt: timestamp("purchased_at").notNull().defaultNow(),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

// Type exports for use in your application
export type User = typeof users.$inferSelect;
export type NewUser = typeof users.$inferInsert;
export type Purchase = typeof purchases.$inferSelect;
export type NewPurchase = typeof purchases.$inferInsert;

Push the schema to create the tables:

bun run db:push

A few things to notice about this schema:

1. The users, sessions, accounts, and verifications tables are required by Better Auth. You'll configure the auth library to use these tables in the next section.

2. The purchases table is your core business entity. It tracks Stripe checkout sessions and links them to users.

3. Type exports like User and Purchase give you inferred TypeScript types from your schema. You never define types manually. They come from the schema definition.

4. The $defaultFn on the purchases.id column generates a UUID automatically when you insert a row. The auth tables use text IDs because Better Auth generates its own IDs.

How to Configure Drizzle Kit

Create drizzle.config.ts at the project root:

// drizzle.config.ts
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/lib/db/schema.ts",
  out: "./drizzle",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
  verbose: true,
  strict: true,
});

Add these scripts to your package.json:

{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:push": "drizzle-kit push",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio"
  }
}

Now push your schema to the local database:

bun run db:push

Drizzle Kit reads your schema file, compares it to the database, and applies any changes. For development, db:push is fast and convenient. For production, you'll use db:generate and db:migrate to create versioned SQL migration files.

You can open Drizzle Studio to inspect your database visually:

bun run db:studio

This opens a web UI at https://local.drizzle.studio where you can browse tables, run queries, and inspect data.

How to Build the API with Elysia

Here's where this stack gets interesting. Instead of running a separate API server, you embed Elysia directly inside TanStack Start. Both your web app and your API live in the same process, share the same types, and deploy as a single unit.

Why Elysia Instead of Express?

If you've built Node.js APIs before, you've probably used Express. It is 15 years old and has a massive ecosystem. But Express was designed before TypeScript, before async/await, and before developers expected type safety across the full stack.

Elysia takes a different approach. It was built for TypeScript from day one. Request bodies, response types, and path parameters are all inferred at compile time.

Combined with Eden Treaty (which you'll set up in the next section), your frontend gets full type safety when calling your API. No code generation. No OpenAPI schemas to keep in sync. Just TypeScript inference.

Elysia also includes built-in request validation using its t (TypeBox) schema builder:

import { Elysia, t } from "elysia";

new Elysia().post(
  "/users",
  ({ body }) => {
    // body is typed as { name: string, email: string }
    return createUser(body);
  },
  {
    body: t.Object({
      name: t.String(),
      email: t.String(),
    }),
  }
);

The schema validates at runtime and provides TypeScript types at compile time. One definition serves both purposes.

How to Define Your API

Create src/server/api.ts. This is where all your API routes live:

// src/server/api.ts
import { Elysia, t } from "elysia";
import { eq } from "drizzle-orm";

import { auth } from "@/lib/auth";
import { db, purchases, users } from "@/lib/db";

export const api = new Elysia({ prefix: "/api" })
  .onRequest(({ request }) => {
    console.log(`[API] \({request.method} \){request.url}`);
  })
  .onError(({ code, error, path }) => {
    console.error(`[API ERROR] \({code} on \){path}:`, error);
  })
  .get("/health", () => ({
    status: "ok",
    timestamp: new Date().toISOString(),
  }))
  .get("/me", async ({ request, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    return { user: session.user };
  })
  .get("/payments/status", async ({ request, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    const purchase = await db
      .select()
      .from(purchases)
      .where(eq(purchases.userId, session.user.id))
      .limit(1);

    return {
      userId: session.user.id,
      purchase: purchase[0] ?? null,
    };
  });

export type Api = typeof api;

That last line is critical. export type Api = typeof api exports the full type signature of your API. Eden Treaty uses this type to generate a fully typed client on the frontend.

You'll see how that works shortly.

Notice the pattern for authenticated endpoints: call auth.api.getSession() with the request headers, check if the session exists, and return a 401 if it does not. This is straightforward and explicit. No decorators, no middleware magic.

The onRequest and onError hooks provide logging for every request. In production, you would replace these with structured logging to your observability platform.

How to Mount Elysia in TanStack Start

TanStack Start uses file-based routing. To handle all API requests with Elysia, create a catch-all route at src/routes/api.$.ts:

// src/routes/api.$.ts
import { createFileRoute } from "@tanstack/react-router";

import { api } from "../server/api";

const handler = ({ request }: { request: Request }) => api.fetch(request);

export const Route = createFileRoute("/api/$")({
  server: {
    handlers: {
      GET: handler,
      POST: handler,
      PUT: handler,
      PATCH: handler,
      DELETE: handler,
      OPTIONS: handler,
    },
  },
});

The $ in the filename is TanStack Router's wildcard syntax. This route matches any path starting with /api/, and the server.handlers object maps HTTP methods to your Elysia handler. Every request to /api/* gets forwarded to Elysia's fetch method.

This is the key architectural insight: Elysia is embedded inside TanStack Start. There is no separate API server. Your web app and API share the same process, the same port, and the same deployment.

This eliminates CORS issues, simplifies deployment, and means your API types are directly importable on the frontend.

Test your API by visiting http://localhost:3000/api/health. You should see:

{ "status": "ok", "timestamp": "2026-03-28T12:00:00.000Z" }

How to Add Type-Safe API Calls with Eden Treaty

Eden Treaty is Elysia's companion client library. It's an end-to-end type-safe HTTP client that mirrors your Elysia API's route structure as a JavaScript object. Instead of writing fetch("/api/users") and manually typing the response, you call api.api.users.get() and get full autocompletion, parameter validation, and return type inference, all derived from your server code at compile time with zero code generation.

This is what makes the stack special. Eden Treaty reads the type exported from your Elysia API and generates a fully typed client. Every endpoint, every parameter, every response shape is inferred at compile time.

How to Set Up the Treaty Client

Since Elysia is embedded in your TanStack Start app (same origin), you don't need to pass a URL to the Treaty client. You can create the client directly from the Elysia app instance for server-side usage and use a URL-based client for browser-side usage.

The simplest approach is to create a helper function that returns a treaty client:

// src/lib/treaty.ts
import { treaty } from "@elysiajs/eden";

import type { Api } from "@/server/api";

// For client-side usage, connect to the same origin
export const api = treaty<Api>(
  typeof window !== "undefined"
    ? window.location.origin
    : (process.env.BETTER_AUTH_URL ?? "http://localhost:3000")
);

Now you can use api anywhere in your application with full type safety:

// Calling GET /api/health
const { data } = await api.api.health.get();
// data is typed as { status: string, timestamp: string }

// Calling GET /api/me (authenticated)
const { data: me, error } = await api.api.me.get();
// data is typed as { user: { id: string, email: string, ... } }
// error is typed as { error: string } | null

Notice how the method chain mirrors your route structure. The /api/health endpoint becomes api.api.health.get(). Path segments become properties, and the HTTP method becomes the final function call.

This is all inferred from the type Api = typeof api export.

How Types Flow from Server to Client

Here's the full picture of how types flow through the stack:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Drizzle Schema  │     │    Elysia API    │     │   Eden Treaty   │
│  (schema.ts)     │────▶│   (api.ts)       │────▶│   (client)      │
│                  │     │                  │     │                  │
│  type User =     │     │  .get("/me",     │     │  api.api.me     │
│  typeof users    │     │    () => user)   │     │    .get()       │
│  .$inferSelect   │     │                  │     │    → { user }   │
└─────────────────┘     └─────────────────┘     └─────────────────┘

First, Drizzle infers TypeScript types from your table definitions. The User type comes from the users table schema.

Then Elysia uses those types in route handlers. When a handler returns { user: session.user }, Elysia captures the return type.

Finally, Eden Treaty reads the type Api = typeof api export and generates a client where every endpoint is fully typed.

If you add a field to your users table schema, Drizzle's inferred types update. If your Elysia handler returns that new field, Eden Treaty's client types update. If your React component accesses a field that no longer exists, TypeScript catches the error at compile time.

Zero code generation. Zero runtime overhead. Just TypeScript inference doing what it does best.

How to Handle Errors with Eden Treaty

Every Eden Treaty call returns a { data, error } tuple. This isn't a thrown exception. It's a discriminated union that forces you to handle both success and failure cases:

const { data, error } = await api.api.me.get();

if (error) {
  // error is typed based on what your Elysia handler can return
  console.error("Failed to fetch user:", error);
  return null;
}

// data is now narrowed to the success type
console.log(data.user.email);

This pattern eliminates the "forgot to handle the error" class of bugs that are common with fetch or Axios, where errors are thrown and easily missed. With Eden Treaty, the TypeScript compiler reminds you.

How to Use Eden Treaty in Route Loaders

TanStack Start routes have loader functions that run on the server during SSR and on the client during navigation. You can use Eden Treaty in these loaders to fetch data before the page renders:

// src/routes/_authenticated/dashboard.tsx
import { createFileRoute } from "@tanstack/react-router";

import { api } from "@/lib/treaty";

export const Route = createFileRoute("/_authenticated/dashboard")({
  loader: async () => {
    const { data } = await api.api.payments.status.get();
    return { purchase: data?.purchase ?? null };
  },
  component: DashboardPage,
});

function DashboardPage() {
  const { purchase } = Route.useLoaderData();

  return (
    <div>
      <h1>Dashboard</h1>
      {purchase ? (
        <p>Your plan: {purchase.tier}</p>
      ) : (
        <p>No active plan.</p>
      )}
    </div>
  );
}

The loader runs before the component renders, so the page never shows a loading spinner for its initial data. Route.useLoaderData() returns fully typed data based on what the loader returns. Change the loader's return type, and TypeScript catches mismatches in the component.

How to Add Authentication with Better Auth

Every SaaS needs authentication. In this tutorial, you'll use Better Auth with GitHub OAuth. Better Auth is a framework-agnostic auth library that works natively with Drizzle and has first-class support for TanStack Start.

How to Create a GitHub OAuth App

Before writing any code, create a GitHub OAuth application:

1. Go to GitHub Developer Settings

2. Click "New OAuth App"

3. Set the Homepage URL to http://localhost:3000

4. Set the Authorization callback URL to http://localhost:3000/api/auth/callback/github

5. Click "Register application"

6. Copy the Client ID and generate a Client Secret

Add these to a .env file at the project root:

# .env
DATABASE_URL=postgres://postgres:postgres@db.localtest.me:5432/my_saas
BETTER_AUTH_SECRET=your-random-32-character-string-here
BETTER_AUTH_URL=http://localhost:3000
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Generate a random secret for BETTER_AUTH_SECRET:

openssl rand -base64 32

How to Configure the Auth Server

Create src/lib/auth/index.ts. This is the server-side auth configuration:

// src/lib/auth/index.ts
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { tanstackStartCookies } from "better-auth/tanstack-start";

import * as schema from "@/lib/db";
import { db } from "@/lib/db";

const isDev = process.env.NODE_ENV !== "production";
const baseURL = process.env.BETTER_AUTH_URL ?? "http://localhost:3000";

export const auth = betterAuth({
  baseURL,
  database: drizzleAdapter(db, {
    provider: "pg",
    usePlural: true,
    schema: {
      users: schema.users,
      sessions: schema.sessions,
      accounts: schema.accounts,
      verifications: schema.verifications,
    },
  }),

  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID ?? "",
      clientSecret: process.env.GITHUB_CLIENT_SECRET ?? "",
    },
  },

  session: {
    expiresIn: 60 * 60 * 24 * 7, // 7 days
    updateAge: 60 * 60 * 24,      // refresh daily
    cookieCache: {
      enabled: true,
      maxAge: 5 * 60, // 5 minutes
    },
  },

  trustedOrigins: isDev
    ? ["http://localhost:3000"]
    : [baseURL],

  plugins: [tanstackStartCookies()],
});

export type Auth = typeof auth;
export type Session = typeof auth.$Infer.Session;

Key details in this configuration:

• drizzleAdapter connects Better Auth to your Drizzle database. The usePlural: true option tells it your tables are named users (not user), sessions (not session), and so on.

• tanstackStartCookies() is a plugin that handles cookie management for TanStack Start's SSR. Without this, sessions won't persist correctly during server-side rendering.

• cookieCache stores session data in the cookie for 5 minutes, reducing database lookups on every request.

How to Configure the Auth Client

Create src/lib/auth/client.ts for the browser-side auth client:

// src/lib/auth/client.ts
import { createAuthClient } from "better-auth/react";

export const authClient = createAuthClient({
  baseURL: "",
});

export const { signIn, signOut, useSession } = authClient;

The baseURL is an empty string because Elysia is embedded in your TanStack Start app. Auth requests go to /api/auth/* on the same origin. No separate auth server needed.

How to Mount Auth Routes

Better Auth needs to handle requests at /api/auth/*. Since Elysia handles all /api/* routes, you mount Better Auth's handler inside Elysia.

Add this to your src/server/api.ts:

// In src/server/api.ts, add Better Auth's handler
export const api = new Elysia({ prefix: "/api" })
  // Mount Better Auth to handle /api/auth/* routes
  .mount(auth.handler)
  // ... rest of your routes

The .mount(auth.handler) call tells Elysia to forward any request matching Better Auth's routes to the auth handler. This covers login, logout, session management, and OAuth callbacks.

How to Protect Routes

TanStack Start uses layout routes to protect groups of pages. Create src/routes/_authenticated.tsx:

// src/routes/_authenticated.tsx
import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { getRequestHeaders } from "@tanstack/react-start/server";

import { auth } from "@/lib/auth";

const getCurrentUser = createServerFn().handler(async () => {
  const rawHeaders = getRequestHeaders();
  const headers = new Headers(rawHeaders as HeadersInit);
  const session = await auth.api.getSession({ headers });
  return session?.user ?? null;
});

export const Route = createFileRoute("/_authenticated")({
  beforeLoad: async ({ location }) => {
    const user = await getCurrentUser();

    if (!user) {
      throw redirect({
        to: "/login",
        search: { redirect: location.pathname },
      });
    }

    return { user };
  },
  component: AuthenticatedLayout,
});

function AuthenticatedLayout() {
  return <Outlet />;
}

The _authenticated prefix (with underscore) makes this a layout route in TanStack Router. Any route nested inside src/routes/_authenticated/ will run the beforeLoad check first. If the user isn't logged in, they get redirected to /login with a redirect parameter so they return to the original page after signing in.

The createServerFn runs on the server during SSR. It reads the request cookies, checks for a valid session, and returns the user. This means your auth check happens server-side before any HTML is sent to the browser.

Now any file you create under src/routes/_authenticated/ is automatically protected. For example, src/routes/_authenticated/dashboard.tsx requires authentication.

How to Build the Login Page

Create a login page at src/routes/login.tsx:

// src/routes/login.tsx
import { createFileRoute } from "@tanstack/react-router";
import { useState } from "react";
import { z } from "zod";

import { signIn } from "@/lib/auth/client";

const searchSchema = z.object({
  redirect: z.string().optional(),
});

export const Route = createFileRoute("/login")({
  validateSearch: searchSchema,
  component: LoginPage,
});

function LoginPage() {
  const { redirect: redirectTo } = Route.useSearch();
  const [isLoading, setIsLoading] = useState(false);

  const handleGitHubLogin = async () => {
    setIsLoading(true);
    const callbackURL = redirectTo
      ? `\({window.location.origin}\){redirectTo}`
      : `${window.location.origin}/dashboard`;

    await signIn.social({
      provider: "github",
      callbackURL,
    });
  };

  return (
    <div className="flex min-h-screen items-center justify-center">
      <div className="w-full max-w-md rounded-lg border p-8">
        <h1 className="mb-6 text-2xl font-bold">Sign In</h1>
        <button
          onClick={handleGitHubLogin}
          disabled={isLoading}
          className="w-full rounded-md bg-gray-900 px-4 py-3 text-white"
        >
          {isLoading ? "Signing in..." : "Sign in with GitHub"}
        </button>
      </div>
    </div>
  );
}

TanStack Router's validateSearch validates query parameters with Zod. The redirect parameter is typed as an optional string, and Route.useSearch() returns a type-safe object. No manual parsing needed.

How to Add Login Redirect Middleware

You also want to redirect authenticated users away from the login page. Create the entry point at src/start.ts:

// src/start.ts
import { redirect } from "@tanstack/react-router";
import { createMiddleware, createStart } from "@tanstack/react-start";
import { getRequestHeaders, getRequestUrl } from "@tanstack/react-start/server";

import { auth } from "@/lib/auth";

const authMiddleware = createMiddleware({ type: "request" }).server(
  async ({ next }) => {
    const rawHeaders = getRequestHeaders();
    const headers = new Headers(rawHeaders as HeadersInit);
    const url = getRequestUrl();

    if (url.pathname !== "/login") {
      return next();
    }

    const session = await auth.api.getSession({ headers });

    if (session?.user) {
      const redirectTo = url.searchParams.get("redirect");
      throw redirect({
        to: redirectTo || "/dashboard",
      });
    }

    return next();
  }
);

export const startInstance = createStart(() => ({
  requestMiddleware: [authMiddleware],
}));

This middleware runs on every request. If the user is already authenticated and visits /login, they get redirected to the dashboard (or to whatever page they originally wanted to reach).

How to Build a Complete Feature (The Four-Layer Pattern)

Now that you have a database, API, type-safe client, and authentication, it's time to build a real feature. Every feature in this architecture follows the same four-layer pattern:

Once you understand this pattern, adding features becomes mechanical. Let's walk through building a complete purchase status feature that lets authenticated users check their purchase history.

Layer 1: Schema

You already defined the purchases table in your schema earlier. For reference:

// src/lib/db/schema.ts
export const purchases = pgTable("purchases", {
  id: text("id")
    .primaryKey()
    .$defaultFn(() => crypto.randomUUID()),
  userId: text("user_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
  stripeCheckoutSessionId: text("stripe_checkout_session_id")
    .notNull()
    .unique(),
  stripeCustomerId: text("stripe_customer_id"),
  stripePaymentIntentId: text("stripe_payment_intent_id"),
  tier: purchaseTierEnum("tier").notNull(),
  status: purchaseStatusEnum("status").notNull().default("completed"),
  amount: integer("amount").notNull(),
  currency: text("currency").notNull().default("usd"),
  purchasedAt: timestamp("purchased_at").notNull().defaultNow(),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

If you're adding a new feature, this is where you start. Define the table, run bun run db:push, and move to Layer 2.

Layer 2: API

Create an API route module at src/server/routes/purchases.ts:

// src/server/routes/purchases.ts
import { eq } from "drizzle-orm";
import { Elysia } from "elysia";

import { auth } from "@/lib/auth";
import { db, purchases } from "@/lib/db";

export const purchasesRoute = new Elysia({ prefix: "/purchases" })
  .get("/status", async ({ request, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session?.user) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    const purchase = await db
      .select()
      .from(purchases)
      .where(eq(purchases.userId, session.user.id))
      .limit(1);

    return purchase[0] ?? null;
  });

Then register this route module in your main API file:

// src/server/api.ts
import { purchasesRoute } from "./routes/purchases";

export const api = new Elysia({ prefix: "/api" })
  .mount(auth.handler)
  .use(purchasesRoute)
  // ... other routes

The .use() method composes Elysia instances. Each route module is an independent Elysia instance with its own prefix, and use merges them into the main app. Eden Treaty sees the full composed type, so your client automatically knows about the new endpoints.

Layer 3: Hooks

Create a custom hook that connects your React components to the API:

// src/hooks/use-purchase-status.ts
import { useQuery } from "@tanstack/react-query";

import { api } from "@/lib/treaty";

export function usePurchaseStatus() {
  return useQuery({
    queryKey: ["purchase-status"],
    queryFn: async () => {
      const { data, error } = await api.api.purchases.status.get();
      if (error) throw new Error("Failed to fetch purchase status");
      return data;
    },
  });
}

TanStack Query handles caching, refetching, loading states, and error states. The queryKey identifies this data in the cache. If multiple components call usePurchaseStatus(), only one network request is made.

For mutations (creating, updating, or deleting data), use useMutation:

// src/hooks/use-checkout.ts
import { useMutation } from "@tanstack/react-query";

import { api } from "@/lib/treaty";

export function useCheckout() {
  return useMutation({
    mutationFn: async () => {
      const { data, error } = await api.api.payments.checkout.post();
      if (error) throw new Error("Failed to create checkout session");
      return data;
    },
    onSuccess: (data) => {
      // Redirect to Stripe Checkout
      if (data?.url) {
        window.location.href = data.url;
      }
    },
  });
}

Layer 4: UI

Use the hooks in your React components:

// src/components/purchase-status.tsx
import { usePurchaseStatus } from "@/hooks/use-purchase-status";

export function PurchaseStatus() {
  const { data: purchase, isLoading, error } = usePurchaseStatus();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>Failed to load purchase status.</div>;
  }

  if (!purchase) {
    return (
      <div className="rounded-lg border p-6">
        <h2 className="text-lg font-semibold">No Active Purchase</h2>
        <p className="mt-2 text-gray-600">
          You have not purchased a plan yet.
        </p>
      </div>
    );
  }

  return (
    <div className="rounded-lg border p-6">
      <h2 className="text-lg font-semibold">
        {purchase.tier.charAt(0).toUpperCase() + purchase.tier.slice(1)} Plan
      </h2>
      <p className="mt-2 text-gray-600">
        Status: {purchase.status}
      </p>
      <p className="text-sm text-gray-500">
        Purchased on{" "}
        {new Date(purchase.purchasedAt).toLocaleDateString()}
      </p>
    </div>
  );
}

That's the complete four-layer pattern. The schema defines the data. The API exposes it. Hooks connect React to the API. The UI renders the result. Every feature you add follows these same four steps.

How the Layers Connect

Here's the full picture of how data flows through the four layers for a read operation:

User clicks "Dashboard"
  → TanStack Router triggers the route loader
    → Loader calls api.api.purchases.status.get() via Eden Treaty
      → Elysia receives GET /api/purchases/status
        → Handler calls auth.api.getSession() to verify the user
        → Handler queries db.select().from(purchases) via Drizzle
        → Handler returns { purchase } with inferred types
      → Eden Treaty receives typed response
    → Loader returns typed data
  → Component renders with Route.useLoaderData()

For a write operation (creating a new resource), the flow is similar but uses a mutation:

User clicks "Buy Now"
  → onClick calls checkout.mutate() from useMutation hook
    → mutationFn calls api.api.payments.checkout.post() via Eden Treaty
      → Elysia receives POST /api/payments/checkout
        → Handler creates a Stripe checkout session
        → Handler returns { url }
      → Eden Treaty receives typed response
    → onSuccess redirects to Stripe Checkout

How to Add a Second Feature

To cement the pattern, let's walk through adding a user profile update feature. This shows all four layers for a write operation.

Layer 1: Schema. The users table already has a name field you can update. No schema change needed.

Layer 2: API. Add a PATCH endpoint:

// In src/server/api.ts
.patch(
  "/me",
  async ({ request, body, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    const [updatedUser] = await db
      .update(users)
      .set({
        name: body.name,
        updatedAt: new Date(),
      })
      .where(eq(users.id, session.user.id))
      .returning();

    return { user: updatedUser };
  },
  {
    body: t.Object({
      name: t.String({ minLength: 1, maxLength: 100 }),
    }),
  },
)

The body option validates the request body at runtime and provides TypeScript types at compile time. If someone sends a request without a name field, Elysia returns a 400 error automatically. You don't write any validation logic yourself.

Layer 3: Hooks. Create a mutation hook:

// src/hooks/use-update-profile.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";

import { api } from "@/lib/treaty";

export function useUpdateProfile() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (data: { name: string }) => {
      const { data: result, error } = await api.api.me.patch(data);
      if (error) throw new Error("Failed to update profile");
      return result;
    },
    onSuccess: () => {
      // Invalidate any queries that depend on user data
      queryClient.invalidateQueries({ queryKey: ["me"] });
    },
  });
}

The onSuccess callback invalidates the cache for user-related queries. This means any component displaying user data will automatically refetch and show the updated name.

Layer 4: UI. Use the hook in a form component:

// src/components/profile-form.tsx
import { useState } from "react";

import { useUpdateProfile } from "@/hooks/use-update-profile";

export function ProfileForm({ currentName }: { currentName: string }) {
  const [name, setName] = useState(currentName);
  const updateProfile = useUpdateProfile();

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    updateProfile.mutate({ name });
  };

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="name" className="block text-sm font-medium">
        Display Name
      </label>
      <input
        id="name"
        type="text"
        value={name}
        onChange={(e) => setName(e.target.value)}
        className="mt-1 block w-full rounded-md border px-3 py-2"
      />
      <button
        type="submit"
        disabled={updateProfile.isPending}
        className="mt-4 rounded-md bg-blue-600 px-4 py-2 text-white"
      >
        {updateProfile.isPending ? "Saving..." : "Save"}
      </button>
      {updateProfile.isError && (
        <p className="mt-2 text-sm text-red-600">
          Failed to update profile. Please try again.
        </p>
      )}
    </form>
  );
}

Four layers, second feature. The pattern is identical every time.

The pattern is deliberately repetitive. Repetition is a feature, not a bug. When every feature follows the same structure, you always know where to look.

New code goes in predictable places. And if you use an AI coding assistant, it can learn this pattern from your codebase and generate all four layers for new features.

How to Add Payments with Stripe

Most SaaS applications need to collect payments. You'll integrate Stripe for one-time purchases using Stripe Checkout. The key architectural decision is handling webhooks reliably using background jobs, which you'll add in the next section.

How to Set Up Stripe

Create src/lib/payments/index.ts:

// src/lib/payments/index.ts
import Stripe from "stripe";

let stripeClient: Stripe | null = null;

function getStripe(): Stripe {
  if (!stripeClient) {
    const secretKey = process.env.STRIPE_SECRET_KEY;
    if (!secretKey) {
      throw new Error(
        "STRIPE_SECRET_KEY is not set. Payment functionality is unavailable."
      );
    }
    stripeClient = new Stripe(secretKey);
  }
  return stripeClient;
}

// Lazy-initialized proxy so imports don't crash without env vars
export const stripe = new Proxy({} as Stripe, {
  get(_, prop) {
    return Reflect.get(getStripe(), prop);
  },
});

export async function createOneTimeCheckoutSession(params: {
  priceId: string;
  successUrl: string;
  cancelUrl: string;
  metadata: Record<string, string>;
  customerEmail?: string;
  couponId?: string;
}) {
  const client = getStripe();

  const session = await client.checkout.sessions.create({
    mode: "payment",
    line_items: [{ price: params.priceId, quantity: 1 }],
    success_url: params.successUrl,
    cancel_url: params.cancelUrl,
    metadata: params.metadata,
    ...(params.customerEmail && {
      customer_email: params.customerEmail,
    }),
    ...(params.couponId
      ? { discounts: [{ coupon: params.couponId }] }
      : { allow_promotion_codes: true }),
  });

  return session;
}

export async function retrieveCheckoutSession(sessionId: string) {
  const client = getStripe();
  return client.checkout.sessions.retrieve(sessionId);
}

export async function constructWebhookEvent(
  payload: string | Buffer,
  signature: string
) {
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
  if (!webhookSecret) {
    throw new Error("STRIPE_WEBHOOK_SECRET is not set");
  }
  const client = getStripe();
  return client.webhooks.constructEventAsync(payload, signature, webhookSecret);
}

The Proxy pattern for the Stripe client is a production technique. It lazily initializes the Stripe SDK so your module can be imported without crashing if the STRIPE_SECRET_KEY environment variable is missing. This is useful during builds and in environments where not every service is configured.

How to Create the Checkout Endpoint

Add a checkout endpoint to your API:

// In src/server/api.ts
.post("/payments/checkout", async ({ set }) => {
  const priceId = process.env.STRIPE_PRO_PRICE_ID;

  if (!priceId) {
    set.status = 500;
    return { error: "Price not configured" };
  }

  const baseUrl = process.env.BETTER_AUTH_URL ?? "http://localhost:3000";

  const checkoutSession = await createOneTimeCheckoutSession({
    priceId,
    successUrl: `${baseUrl}/dashboard?purchase=success&session_id={CHECKOUT_SESSION_ID}`,
    cancelUrl: `${baseUrl}/pricing`,
    metadata: { tier: "pro" },
  });

  return { url: checkoutSession.url };
})

The {CHECKOUT_SESSION_ID} placeholder is a Stripe template variable. Stripe replaces it with the actual session ID when redirecting the user back to your app.

How to Handle Webhooks

Stripe sends webhook events when payments are processed. Your webhook handler needs to verify the signature, parse the event, and process it.

Here's the critical design decision: don't do heavy processing inside the webhook handler. Stripe expects a response within a few seconds. If your handler takes too long, Stripe will retry the webhook, potentially causing duplicate processing.

Instead, use the "webhook receives, background job processes" pattern:

// In src/server/api.ts
.post("/payments/webhook", async ({ request, set }) => {
  const body = await request.text();
  const sig = request.headers.get("stripe-signature");

  if (!sig) {
    set.status = 400;
    return { error: "Missing signature" };
  }

  try {
    const event = await constructWebhookEvent(body, sig);
    console.log(`[Webhook] Received ${event.type}`);

    if (event.type === "charge.refunded") {
      const charge = event.data.object as {
        id: string;
        payment_intent: string;
        amount: number;
        amount_refunded: number;
        currency: string;
      };
      await inngest.send({
        name: "stripe/charge.refunded",
        data: {
          chargeId: charge.id,
          paymentIntentId: charge.payment_intent,
          amountRefunded: charge.amount_refunded,
          originalAmount: charge.amount,
          currency: charge.currency,
        },
      });
    }

    return { received: true };
  } catch (error) {
    console.error("[Webhook] Stripe verification failed:", error);
    set.status = 400;
    return { error: "Webhook verification failed" };
  }
})

The webhook handler does three things: verifies the signature, identifies the event type, and forwards the data to Inngest for background processing. It responds immediately with { received: true }. The actual business logic (sending emails, granting access, updating records) happens in the background job, which you'll build next.

How to Claim Purchases on the Frontend

After a successful checkout, Stripe redirects the user back to your app with a session ID. You need an endpoint that claims the purchase by verifying the session and creating a database record:

// In src/server/api.ts
.post(
  "/purchases/claim",
  async ({ body, request, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    const { sessionId } = body;

    // Check if already claimed (idempotency)
    const existing = await db
      .select()
      .from(purchases)
      .where(eq(purchases.stripeCheckoutSessionId, sessionId))
      .limit(1);

    if (existing[0]) {
      return { success: true, alreadyClaimed: true, tier: existing[0].tier };
    }

    // Verify payment with Stripe
    const stripeSession = await retrieveCheckoutSession(sessionId);

    if (stripeSession.payment_status !== "paid") {
      set.status = 400;
      return { error: "Payment not completed" };
    }

    const tier = (stripeSession.metadata?.tier ?? "pro") as "pro";

    // Create purchase record
    await db.insert(purchases).values({
      userId: session.user.id,
      stripeCheckoutSessionId: sessionId,
      stripeCustomerId:
        typeof stripeSession.customer === "string"
          ? stripeSession.customer
          : stripeSession.customer?.id ?? null,
      stripePaymentIntentId:
        typeof stripeSession.payment_intent === "string"
          ? stripeSession.payment_intent
          : stripeSession.payment_intent?.id ?? null,
      tier,
      status: "completed",
      amount: stripeSession.amount_total ?? 0,
      currency: stripeSession.currency ?? "usd",
    });

    // Trigger background processing
    await inngest.send({
      name: "purchase/completed",
      data: {
        userId: session.user.id,
        tier,
        sessionId,
      },
    });

    return { success: true, tier };
  },
  {
    body: t.Object({
      sessionId: t.String(),
    }),
  }
)

Notice the idempotency check at the top. If the user refreshes the success page or the frontend retries the claim request, the endpoint returns the existing purchase instead of creating a duplicate.

This is essential for payment flows. You never want to accidentally charge someone twice or create duplicate records.

The inngest.send() call triggers background processing for the purchase. That's where you send confirmation emails, grant access to resources, track analytics events, and perform any other post-purchase work.

How to Test Payments Locally

Install the Stripe CLI and forward webhooks to your local server:

# Install Stripe CLI (macOS)
brew install stripe/stripe-cli/stripe

# Login to Stripe
stripe login

# Forward webhooks to your local server
stripe listen --forward-to localhost:3000/api/payments/webhook

The Stripe CLI gives you a webhook signing secret that starts with whsec_. Add it to your .env:

STRIPE_WEBHOOK_SECRET=whsec_your-local-webhook-secret

Create a test product and price in your Stripe dashboard (or use the Stripe CLI), then add the price ID to your .env:

STRIPE_SECRET_KEY=sk_test_your-test-secret-key
STRIPE_PRO_PRICE_ID=price_your-test-price-id

How to Add Background Jobs with Inngest

Background jobs are critical for any SaaS. You use them for processing webhooks, sending emails, granting access to resources, and any work that shouldn't block your API response. Inngest provides durable, retry-able functions with built-in checkpointing.

Why Background Jobs Matter

Consider what happens when someone purchases your SaaS product:

1. Verify the payment with Stripe

2. Create a purchase record in the database

3. Send a confirmation email to the customer

4. Send a notification email to the admin

5. Grant access to a private GitHub repository

6. Track the purchase event in your analytics platform

7. Schedule a follow-up email sequence

If you try to do all of this inside an API endpoint, several things can go wrong. The email service might be down. The GitHub API might rate-limit you. Your analytics call might time out.

Any failure means the user sees an error, and you have to figure out which steps completed and which did not.

Inngest solves this with durable execution. Each step is checkpointed. If step 3 fails, Inngest retries step 3 without re-running steps 1 and 2.

If the entire function fails, Inngest retries the whole thing. You get at-least-once execution with automatic deduplication.

How to Set Up Inngest

Create the Inngest client at src/lib/jobs/client.ts:

// src/lib/jobs/client.ts
import { Inngest } from "inngest";

export const inngest = new Inngest({
  id: "my-saas",
});

How to Write Your First Inngest Function

Create src/lib/jobs/functions/stripe.ts with the purchase completion handler:

// src/lib/jobs/functions/stripe.ts
import { eq } from "drizzle-orm";

import { inngest } from "../client";
import { db, purchases, users } from "@/lib/db";

export const handlePurchaseCompleted = inngest.createFunction(
  {
    id: "purchase-completed",
    triggers: [{ event: "purchase/completed" }],
  },
  async ({ event, step }) => {
    const { userId, tier, sessionId } = event.data as {
      userId: string;
      tier: string;
      sessionId: string;
    };

    // Step 1: Look up user and purchase details
    const { user, purchase } = await step.run(
      "lookup-user-and-purchase",
      async () => {
        const userResult = await db
          .select({
            id: users.id,
            email: users.email,
            name: users.name,
          })
          .from(users)
          .where(eq(users.id, userId))
          .limit(1);

        const foundUser = userResult[0];
        if (!foundUser) {
          throw new Error(`User not found: ${userId}`);
        }

        const purchaseResult = await db
          .select({
            amount: purchases.amount,
            currency: purchases.currency,
          })
          .from(purchases)
          .where(eq(purchases.stripeCheckoutSessionId, sessionId))
          .limit(1);

        return {
          user: foundUser,
          purchase: purchaseResult[0] ?? {
            amount: 0,
            currency: "usd",
          },
        };
      }
    );

    // Step 2: Send purchase confirmation email
    await step.run("send-purchase-confirmation", async () => {
      // Send email using your email service (Resend, SendGrid, and so on)
      console.log(
        `Sending purchase confirmation to ${user.email}`
      );
      // await sendEmail({
      //   to: user.email,
      //   subject: "Your purchase is confirmed!",
      //   template: PurchaseConfirmationEmail,
      // });
    });

    // Step 3: Send admin notification
    await step.run("send-admin-notification", async () => {
      const adminEmail = process.env.ADMIN_EMAIL;
      if (!adminEmail) return;

      console.log(
        `Notifying admin about purchase from ${user.email}`
      );
      // await sendEmail({
      //   to: adminEmail,
      //   subject: `New sale: ${user.email}`,
      //   template: AdminNotificationEmail,
      // });
    });

    // Step 4: Update purchase record
    await step.run("update-purchase-record", async () => {
      await db
        .update(purchases)
        .set({ updatedAt: new Date() })
        .where(eq(purchases.stripeCheckoutSessionId, sessionId));
    });

    return { success: true, userId, tier };
  }
);

export const stripeFunctions = [handlePurchaseCompleted];

Each step.run() is a checkpoint. If the function fails after step 2, Inngest retries from step 3, not from the beginning. The results of completed steps are cached.

How to Register Your Functions

Create an index file that collects all your functions:

// src/lib/jobs/functions/index.ts
import { stripeFunctions } from "./stripe";

export const functions = [...stripeFunctions];

And a barrel export:

// src/lib/jobs/index.ts
export { inngest } from "./client";
export { functions } from "./functions";

How to Connect Inngest to Your API

Mount the Inngest handler in your Elysia API. Add this to src/server/api.ts:

// src/server/api.ts
import { serve } from "inngest/bun";

import { inngest, functions } from "@/lib/jobs";

const inngestHandler = serve({
  client: inngest,
  functions,
});

export const api = new Elysia({ prefix: "/api" })
  // Inngest endpoint - handles function registration and execution
  .all("/inngest", async (ctx) => {
    return inngestHandler(ctx.request);
  })
  // ... rest of your routes

The .all("/inngest") route handles both GET (for function registration) and POST (for function execution) requests from Inngest.

How to Run Inngest Locally

Inngest provides a dev server that runs locally and provides a dashboard for monitoring your functions:

npx inngest-cli@latest dev -u http://localhost:3000/api/inngest --no-discovery

This starts the Inngest dev server at http://localhost:8288. Open that URL in your browser to see a dashboard showing your registered functions, event history, and function execution logs.

The -u flag tells Inngest where your app is running. The --no-discovery flag disables automatic app discovery, which is more reliable for local development.

Add this as a script in your package.json:

{
  "scripts": {
    "inngest:dev": "npx inngest-cli@latest dev -u http://localhost:3000/api/inngest --no-discovery"
  }
}

Now you can trigger your functions by sending events from your API:

await inngest.send({
  name: "purchase/completed",
  data: {
    userId: "user_123",
    tier: "pro",
    sessionId: "cs_test_abc",
  },
});

The event appears in the Inngest dashboard, the function executes step by step, and you can see the output of each step. If a step fails, you can retry it manually from the dashboard.

How to Handle Refunds with Background Jobs

Here's a more complex example that shows why durable execution matters. When processing a refund, you need to update the purchase status, revoke access, send notifications, and track analytics. If any step fails, the others should still complete:

// src/lib/jobs/functions/stripe.ts
export const handleRefund = inngest.createFunction(
  {
    id: "refund-processed",
    triggers: [{ event: "stripe/charge.refunded" }],
  },
  async ({ event, step }) => {
    const { paymentIntentId, amountRefunded, originalAmount, currency } =
      event.data as {
        chargeId: string;
        paymentIntentId: string;
        amountRefunded: number;
        originalAmount: number;
        currency: string;
      };

    const isFullRefund = amountRefunded >= originalAmount;

    // Step 1: Find the purchase and user
    const { user, purchase } = await step.run(
      "lookup-purchase",
      async () => {
        const purchaseResult = await db
          .select()
          .from(purchases)
          .where(eq(purchases.stripePaymentIntentId, paymentIntentId))
          .limit(1);

        if (!purchaseResult[0]) {
          return { user: null, purchase: null };
        }

        const userResult = await db
          .select()
          .from(users)
          .where(eq(users.id, purchaseResult[0].userId))
          .limit(1);

        return {
          user: userResult[0] ?? null,
          purchase: purchaseResult[0],
        };
      }
    );

    if (!purchase || !user) {
      return { success: false, reason: "no_matching_purchase" };
    }

    // Step 2: Update purchase status
    await step.run("update-purchase-status", async () => {
      await db
        .update(purchases)
        .set({
          status: isFullRefund ? "refunded" : "partially_refunded",
          updatedAt: new Date(),
        })
        .where(eq(purchases.id, purchase.id));
    });

    // Step 3: Send customer notification
    await step.run("notify-customer", async () => {
      console.log(
        `Sending \({isFullRefund ? "full" : "partial"} refund notification to \){user.email}`
      );
      // await sendEmail({ ... });
    });

    return { success: true, isFullRefund };
  }
);

Even if the email service is down in step 3, step 2 (updating the database) has already completed and will not be re-run. Inngest retries only the failed step.

This is what makes durable execution valuable for payment processing. You get reliable, idempotent processing without building your own retry logic.

How to Deploy to Vercel with Neon

You now have a working application with authentication, a database, a type-safe API, payments, and background jobs. Time to deploy it.

How to Provision a Neon Database

1. Sign up at neon.tech and create a new project

2. Choose a region close to your users (Neon supports multiple AWS regions)

3. Copy the connection string from the dashboard

The connection string looks like this:

postgresql://username:password@ep-something.us-east-1.aws.neon.tech/my_saas?sslmode=require

How to Run Migrations in Production

For production, you should use versioned migrations instead of db:push. Generate a migration from your schema:

bun run db:generate

This creates SQL files in the drizzle/ directory. Review the generated SQL to make sure it matches your expectations. Then apply the migration:

DATABASE_URL="your-neon-connection-string" bun run db:migrate

How to Deploy to Vercel

1. Push your code to a GitHub repository

2. Go to vercel.com/new and import your repository

3. Vercel will auto-detect TanStack Start and configure the build settings

Set the following environment variables in Vercel's dashboard:

Click "Deploy." Vercel builds your app and deploys it to a .vercel.app URL.

How to Update OAuth Callbacks

After deploying, update your GitHub OAuth app's callback URL:

1. Go to your GitHub OAuth app settings

2. Change the Authorization callback URL to https://your-app.vercel.app/api/auth/callback/github

3. Add https://your-app.vercel.app as the Homepage URL

How to Configure Stripe Webhooks for Production

Create a webhook endpoint in the Stripe dashboard:

1. Go to Stripe Dashboard > Developers > Webhooks

2. Click "Add endpoint"

3. Set the URL to https://your-app.vercel.app/api/payments/webhook

4. Select the events you want to receive (charge.refunded, checkout.session.expired, and so on)

5. Copy the webhook signing secret and add it to Vercel's environment variables

How to Set Up Inngest in Production

Inngest has a cloud service that handles function execution in production:

1. Sign up at inngest.com

2. Create an app and copy your event key and signing key

3. Add INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY to Vercel's environment variables

4. In Inngest's dashboard, set your app URL to https://your-app.vercel.app/api/inngest

Inngest automatically discovers your functions and starts processing events.

Common Deployment Pitfalls

1. SSR externals. Some packages do not work with Vite's SSR bundling. If you see errors about packages like elysia or inngest during the build, add them to the ssr.external array in vite.config.ts:

// vite.config.ts
export default defineConfig({
  ssr: {
    external: ["elysia", "inngest"],
  },
  // ...
});

2. Environment variable access. In TanStack Start, server-side code can access process.env directly. Client-side code can only access variables prefixed with VITE_. Your Stripe secret key and database URL should never have the VITE_ prefix.

3. Neon connection pooling. For production, use the pooled connection string from Neon (it uses port 5432 instead of the direct connection on port 5433). The pooled connection handles concurrent requests better.

4. Build failures. If your build fails, the most common cause is a TypeScript error. Run bun run type-check locally before pushing. Fix all errors before deploying.

5. Missing environment variables. If your app crashes immediately after deployment, check the Vercel function logs. The most common issue is a missing environment variable. Neon connection strings, Stripe keys, and Better Auth secrets all need to be set before the first deployment.

How to Set Up a Custom Domain

Once your app is deployed to Vercel:

1. Go to your project's Settings in Vercel

2. Click "Domains"

3. Add your custom domain

4. Update your DNS records as instructed (usually a CNAME record pointing to cname.vercel-dns.com)

After adding a custom domain, update these environment variables in Vercel:

• Set BETTER_AUTH_URL to https://yourdomain.com

• Update your GitHub OAuth app's callback URL to https://yourdomain.com/api/auth/callback/github

• Update your Stripe webhook endpoint to https://yourdomain.com/api/payments/webhook

Vercel automatically provisions an SSL certificate for your custom domain. No additional configuration needed.

How to Verify Your Deployment

After deploying, run through this checklist:

1. Health check. Visit https://yourdomain.com/api/health. You should see a JSON response with { "status": "ok" }.

2. Authentication. Click "Sign in with GitHub" and complete the OAuth flow. You should be redirected to your dashboard.

3. Database. After signing in, check your Neon dashboard. You should see a new row in the users table.

4. Payments. On your pricing page, click "Buy" and use Stripe's test card (4242 4242 4242 4242) to complete a purchase. Check that a purchase record appears in your database.

5. Background jobs. After a test purchase, check the Inngest dashboard. You should see a purchase/completed event and the corresponding function execution.

If any of these steps fail, check the Vercel function logs (Settings, Functions, Logs) for error messages. Most deployment issues are misconfigured environment variables or missing webhook secrets.

Conclusion

You just built a production-ready SaaS application. Let's recap what you have:

• TanStack Start handles server-side rendering, file-based routing, and the dev server

• Elysia provides a type-safe API embedded in the same process as your web app

• Eden Treaty gives you a fully typed API client with zero code generation

• Drizzle ORM with Neon handles your database with type-safe queries and serverless PostgreSQL

• Better Auth provides GitHub OAuth with session management and route protection

• Stripe processes payments with webhook handling

• Inngest runs reliable background jobs with automatic retries and checkpointing

• Vercel hosts everything with zero infrastructure management

The four-layer pattern (Schema, API, Hooks, UI) gives you a repeatable process for adding new features. Every feature follows the same structure. Define the data, expose it through the API, connect it to React with hooks, and render it in your components.

This architecture scales well. The explicit boundaries between layers mean you can swap out individual pieces without rewriting everything.

If you outgrow Neon, switch to a self-hosted PostgreSQL. If you need a different payment provider, replace the Stripe module. The rest of the application doesn't change.

What you build next is up to you. Here are natural next steps:

• Email notifications with Resend and React Email for transactional emails (purchase confirmations, password resets, welcome sequences)

• Analytics with PostHog for tracking user behavior and feature flags

• Error tracking with Sentry for catching production errors before your users report them

• Content management with MDX for a blog or documentation section

• File uploads with S3-compatible storage for user-generated content

The src/lib/ pattern makes adding new integrations straightforward. Create a new directory, add an index.ts, and import it where you need it. Each integration stays isolated, so adding analytics does not affect your payment code.

If you want to skip the setup and start building your product immediately, Eden Stack includes everything from this article (and more), pre-configured and production-tested. It ships with 30+ Claude Code skills that encode the patterns described here, so AI coding assistants can generate features following your codebase conventions out of the box.

Whatever you build, build it with type safety. The feedback loop of "change the schema, see the errors, fix the errors" is the fastest way I know to ship reliable software.

Magnus Rodseth builds AI-native applications and is the creator of Eden Stack, a production-ready starter kit with 30+ Claude skills encoding production patterns for AI-native SaaS development.

A plugin architecture allows an application to load external modules that extend its functionality at runtime. Instead of embedding every feature directly in the core application, the system exposes a controlled interface (the host API) that plugins use to integrate with the platform. These plugins can register UI components, contribute functionality, or interact with application services while remaining isolated from the core codebase.

This architectural pattern is widely used across software ecosystems. Platforms such as IDEs, content management systems, and browser extensions rely on plugins to allow third-party developers to extend their functionality without compromising stability.

In a web application context, a similar approach allows large frontend systems to evolve modularly, enabling multiple teams to ship features independently.

In this tutorial, you'll learn how to design a type-safe, lazy-loaded, and secure plugin architecture in React — complete with lifecycle management, independent bundling, hot-loading, and real TypeScript examples.

By the end, you'll have everything you need to transform your React application into a modular platform capable of hosting independent extensions without sacrificing maintainability, performance, or security.

Table of Contents

• A Common Pain Point: Scaling Frontend Platforms

• What This Article Will Cover

• Prerequisites

• Why a Plugin Architecture?

• Core Concepts of a React Plugin Architecture

• High-Level Architecture of a React Plugin System

• Real TypeScript Example: A Chat Plugin

  • Chat Plugin Implementation

  • Host Application Usage

  • 1. How to Define the Host API

  • 2. How to Define the Plugin Lifecycle

  • 3. How to Bundle Plugins Separately

  • 4. How to Lazy-Load Plugins

  • 5. Security & Permission Model

  • 6. Plugin Hot-loading

  • 7. CI & Deployment Considerations

  • Putting It All Together

• Best Practices

• When NOT to Use a Plugin Architecture

  • Small or Single-Team Applications

  • Tightly Coupled Features

  • Performance-Critical Systems

  • Limited Security Controls

  • Early-Stage Products

• Future Enhancements

• Conclusion

A Common Pain Point: Scaling Frontend Platforms

Consider a large internal admin dashboard used by multiple teams across an organization. Each team wants to add its own functionality, like analytics dashboards, workflow management tools, user administration panels, and domain-specific reporting modules.

If all these features are implemented directly in the main React application, several problems quickly emerge. Merge conflicts in the core repository become frequent, unrelated features grow tightly coupled, and release cycles slow down because every change requires redeploying the entire application. Worse, adding new features carries a constant risk of breaking existing functionality.

A plugin architecture solves this problem by allowing each feature to be developed as an independent plugin. The host application provides a stable platform and a controlled API, while teams can ship their own plugins without modifying the core system.

What This Article Will Cover

This guide walks you through how to design a type-safe, lazy-loaded, and secure plugin architecture in React using TypeScript. You'll learn how to design a host API that plugins can safely interact with, how to define a plugin lifecycle for initialization, mounting, updates, and cleanup, and how to bundle plugins independently so they can be developed and deployed separately.

You'll also learn how to lazy-load plugins at runtime to improve performance, how to implement a security model that prevents plugins from accessing sensitive application state, and how to enable hot-loading during development while enforcing safety through CI/CD pipelines.

By the end of this article, you'll understand how to build a flexible plugin system that allows your React application to grow into a modular platform capable of hosting independent extensions without sacrificing maintainability, performance, or security.

Prerequisites

Before following along with this guide, you should be familiar with several core technologies and concepts used throughout the examples.

React Fundamentals
A basic understanding of React components, hooks, and JSX is required. The examples assume familiarity with functional components, useState, and useEffect.

TypeScript Basics
Since the plugin architecture relies heavily on type contracts between the host application and plugins, you should understand TypeScript interfaces, generics, and module exports.

Modern JavaScript Modules
Knowledge of ES modules (import / export) and dynamic imports will help when working with lazy-loaded plugins.

React Tooling (Vite or Webpack)
The examples reference modern frontend build tools such as Vite. Familiarity with how bundlers compile React applications and manage dependencies will help when configuring plugin builds.

Basic Web Security Concepts
Some sections discuss sandboxing and restricted APIs. A general understanding of browser security concepts such as iframes, same-origin policies, and API boundaries is helpful but not strictly required.

Why a Plugin Architecture?

Imagine you're building an internal admin platform where multiple teams need to ship independent features as plugins without risking the core application. A plugin architecture allows each team to contribute functionality safely, while the host maintains type safety, security, and performance.

This guide targets React/TypeScript engineers who want to design a plugin system capable of hosting third-party extensions without compromising maintainability.

The benefits of this approach are significant. Extensibility means developers or third parties can add features without touching core code. Isolation allows plugins to be sandboxed so they can't affect unrelated parts of the application. Lazy loading ensures only the features a user actually needs are fetched, keeping the application fast. TypeScript enforces a strict contract between plugins and the host, catching errors at compile time rather than at runtime. Finally, controlled APIs and permission boundaries prevent malicious or poorly written plugins from interfering with the rest of the system.

A well-architected plugin system balances all of these qualities – flexibility, safety, and maintainability – without forcing unnecessary trade-offs between them.

Core Concepts of a React Plugin Architecture

Before diving into code, it helps to understand the key building blocks that make up a React plugin system.

At a high level, a plugin architecture in React revolves around five concerns.

1. The Host API is the interface the core application exposes to plugins.

2. The Plugin Lifecycle defines methods for initialization, mounting, updating, and cleanup.

3. Bundling means compiling each plugin separately to avoid coupling it to the host.

4. The Security Model covers permissions and sandboxing to prevent misuse.

5. Finally, Hot-loading and CI streamline the development and deployment experience.

We'll explore each of these concepts in detail in the sections that follow. First, let's look at how they fit together visually.

High-Level Architecture of a React Plugin System

The following diagram illustrates how the host application interacts with independently bundled plugins. The host exposes a controlled API, loads plugins dynamically, and manages their lifecycle while maintaining security boundaries.

The core application serves as the runtime environment for all plugins, housing the plugin loader, lifecycle manager, and the host API.

The plugin loader dynamically imports plugin bundles at runtime using import(), while the host API ensures plugins interact with the application through a controlled interface rather than accessing internal state directly.

Each plugin is compiled as a separate bundle and registers itself with the host during initialization. A dedicated security layer enforces all of these boundaries, ensuring plugins cannot directly manipulate internal state or sensitive resources.

Together, these pieces ensure that plugins remain independent, lazy-loadable, and secure, while the host application retains full control over lifecycle management and platform stability.

Real TypeScript Example: A Chat Plugin

Now that you have a mental model of the architecture, let's look at a minimal working example before diving into each concept individually. This example demonstrates how a plugin registers itself with the host application and exposes a UI component through the host API.

The following plugin implements a simple chat feature that registers a React component with the host platform.

Chat Plugin Implementation

// plugins/chat-plugin/src/plugin.ts

import { Plugin, HostAPI } from '../../src/plugins';

const ChatPlugin: Plugin = {
  name: 'ChatPlugin',
  version: '1.0.0',
  init(host: HostAPI) {
    host.registerComponent('Chat', () => (
      <div>Welcome to the Chat Plugin!</div>
    ));
    host.log('ChatPlugin initialized');
  },
};

export default ChatPlugin;

Host Application Usage

The host application loads the plugin and renders the component it registered.

const Chat = hostAPI.getComponent('Chat');

return (
  <div>
    {Chat ? <Chat /> : 'Loading Chat Plugin...'}
  </div>
);

In this example, the plugin doesn't directly modify the host application. Instead, it interacts through the Host API, registering a component that the host can render dynamically. The sections below break down exactly how each piece of this system is built.

1. How to Define the Host API

The host API is the contract between the core app and its plugins. It defines what functionality plugins can access. Before plugins can do anything useful, the host must expose a controlled interface, establishing the contract between the core application and its extensions.

Example: TypeScript Host API

// src/plugins/host.ts

export interface HostAPI {
  // Using ComponentType instead of FC<any> reinforces type-safety while allowing class/function components
  registerComponent: (name: string, component: React.ComponentType<any>) => void;
  getComponent: (name: string) => React.ComponentType<any> | undefined;
  log: (message: string) => void;
}

// Note: We still use `any` for props here for extensibility; plugins can define stricter props locally if needed.

export const hostAPI: HostAPI = { 
    registerComponent(name, component) { 
        console.log(Registered component: ${name}); 
        componentRegistry[name] = component; 
    }, 
    getComponent(name) { 
        return componentRegistry[name]; 
    }, 
    log(message) { 
        console.log([PLUGIN LOG]: ${message}); 
    }, 
};

const componentRegistry: Record<string, React.ComponentType<any>> = {};

This API allows plugins to register UI components and log messages, without giving them unrestricted access to the application state.

2. How to Define the Plugin Lifecycle

A plugin lifecycle ensures consistent behavior across all extensions. Once the host API exists, plugins need a structured way to initialize, render, and clean up resources.

Lifecycle Interface

// src/plugins/plugin.ts

import { HostAPI } from './host';

export interface Plugin {
  name: string;
  version: string;
  init: (host: HostAPI) => void;
  mount?: () => void;
  update?: () => void;
  unmount?: () => void;
}

// Typically, the host calls mount/update/unmount based on route changes, feature flags, or user interactions.

The init method is called when the plugin is first loaded and receives the host API as its argument. mount is called when the plugin's UI is displayed, while update is an optional hook triggered when props or state change.

When a plugin is removed, unmount is called to clean up any resources the plugin was holding, preventing memory leaks and side effects in the host application.

3. How to Bundle Plugins Separately

Each plugin should be packaged as an independent module so that it can be developed, versioned, and deployed without tightly coupling it to the host application.

Modern build tools such as Vite or Webpack make it possible to compile plugins into standalone bundles that the host can load dynamically at runtime.

Example Vite Configuration for a Plugin

// vite.config.ts

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

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: 'src/plugin.ts',
      name: 'MyPlugin',
      fileName: 'my-plugin',
      formats: ['es'],
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
    },
  },
});

The external option ensures the plugin uses the host's React, preventing duplicate React versions in memory.

4. How to Lazy-Load Plugins

Even when plugins are bundled independently, loading all of them during application startup would significantly increase initial load time. Instead, plugins should be loaded on demand using dynamic imports so that functionality is only fetched when the user actually needs it.

// src/plugins/loader.ts

export async function loadPlugin(url: string): Promise { 

    // Using /* @vite-ignore */ because the URL is dynamic and cannot be         statically analyzed by Vite.
    // Tradeoff: plugin cannot be pre-bundled; ensure URLs are trusted to avoid security risks.

    const module = await import(/ @vite-ignore */ url); 
    return module.default as Plugin; 
}

Usage in React:

const [plugin, setPlugin] = React.useState<Plugin | null>(null);

React.useEffect(() => {
  loadPlugin('/plugins/my-plugin.js').then((p) => {
    p.init(hostAPI);
    setPlugin(p);
  });
}, []);

This pattern allows applications to scale without preloading all plugins, improving initial load time.

5. Security & Permission Model

Because plugins run code that originates outside the core application, security boundaries are essential. Even though plugins interact through the host API, the platform must still restrict what capabilities they can access in order to prevent misuse or accidental interference with application state.

Example: Restricted API

export interface SecureHostAPI {
  log: (message: string) => void;
  registerComponent: (name: string, component: React.ComponentType<any>) => void;
  fetchData?: (endpoint: string) => Promise<any>; // Only if allowed
}

You can enhance security further using iframe sandboxing or Web Workers for heavier isolation.

// Example of a sandboxed iframe plugin

<iframe
  src="/plugins/my-plugin.html"
  sandbox="allow-scripts"
  style={{ width: '100%', height: '400px', border: 'none' }}
/>

// Advanced isolation notes:
// - You can define different SecureHostAPI shapes for internal vs. third-party plugins,
//   exposing more capabilities to trusted plugins while restricting untrusted ones.
// - For stronger isolation, use message passing (postMessage) with iframes or Web Workers
//   so plugins cannot access the DOM or host state directly.

This approach prevents DOM and network access outside the API.

6. Plugin Hot-loading

Hot-loading is essential for developer productivity. Tools like Vite's HMR let you see plugin updates immediately, speeding up iteration and reducing friction.

React Example with HMR:

if (import.meta.hot) {
  import.meta.hot.accept('/plugins/my-plugin.js', (newModule) => {
    const updatedPlugin = newModule.default as Plugin;
    updatedPlugin.init(hostAPI);
    setPlugin(updatedPlugin);
  });
}

With hot-loading, developers can update plugins without restarting the host app.

7. CI & Deployment Considerations

To deploy safely, plugins must be verified and tested. CI/CD pipelines enforce type safety, bundling, and security checks automatically. For a production-grade plugin system, continuous integration pipelines should:

1. Lint and type-check each plugin using TypeScript.

2. Run automated tests to ensure plugin compliance.

3. Bundle plugins independently with versioned outputs.

4. Deploy plugins to a secure CDN or internal repository.

5. Verify signatures or hashes to prevent tampering.

GitHub Actions Example for Plugin CI:

name: Build Plugin

on:
  push:
    paths:
      - 'plugins/**'

jobs:
  build:
    runs-on: ubuntu-latest
    steps: 
      - uses: actions/checkout@v3 
      - uses: actions/setup-node@v3 
      with:
        node-version: 20
      - run: npm install 
      - run: npm run build --workspace plugins/my-plugin 
      - run: npm run test --workspace plugins/my-plugin
      # Optional: sign plugin artifacts or generate a checksum to verify integrity before loading in the host

This ensures every plugin is type-safe, tested, and ready for deployment.

Putting It All Together

At this point, you have walked through each architectural layer independently. Here's how all the pieces map to a real project structure:

src/
├── plugins/ 
│ ├── host.ts ← Host API definition 
│ ├── plugin.ts ← Plugin lifecycle interface 
│ └── loader.ts ← Dynamic plugin loader 
plugins/ 
└── chat-plugin/ 
    └── src/ 
        └── plugin.ts ← Chat plugin implementation

Each file has a single, clear responsibility. host.ts owns the contract, plugin.ts owns the lifecycle shape, loader.ts handles runtime importing, and the plugin itself lives entirely outside the core src/ tree – deployable and versioned independently.

Best Practices

At this point, you have a host API, a well-defined plugin lifecycle, isolated bundles, lazy-loading, and a security model. These foundations ensure plugins are robust, type-safe, and maintainable — ready to be extended with versioning, testing, and CI/CD pipelines.

1. Type safety: Always define TypeScript interfaces for host APIs and plugin contracts.

2. Lazy loading: Only load plugins when required.

3. Security: Expose a minimal API and avoid giving plugins unrestricted access.

4. Isolated state: Keep plugin state isolated to prevent accidental interference.

5. Versioning: Maintain plugin versions to ensure compatibility with the host.

6. Testing: Unit-test plugins against host API mocks.

7. CI/CD: Automate linting, testing, and bundling for plugins.

When NOT to Use a Plugin Architecture

In some cases, introducing a plugin system can add unnecessary complexity without delivering meaningful benefits.

Small or Single-Team Applications

If a project is maintained by a small team and the feature set is relatively stable, a plugin architecture may be excessive. A simpler modular structure within the main codebase is usually easier to maintain and reason about.

Tightly Coupled Features

Plugin systems work best when features can operate independently. If new functionality requires deep access to application state or tightly integrated workflows, forcing it into a plugin model may introduce unnecessary abstractions and complexity rather than solving a real problem.

Performance-Critical Systems

Although lazy-loading can mitigate performance issues, plugin architectures still introduce additional runtime complexity. Applications with strict performance constraints may benefit from a more tightly optimized architecture rather than dynamic plugin loading.

Limited Security Controls

Allowing external code to run inside an application always introduces security risks. If the platform can't enforce strong API boundaries, sandboxing, or validation of plugins, it may be safer to avoid a plugin architecture altogether.

Early-Stage Products

In early product development, requirements often change rapidly. Designing a plugin system too early can slow development because engineers must maintain abstraction layers before the product's core architecture has stabilized. It's usually better to wait until the platform's boundaries are well understood before introducing this level of extensibility.

Future Enhancements

As the platform matures, there are several directions worth exploring.

Dynamic permissions would allow plugins to explicitly request capabilities, with the host deciding whether to grant them. This makes the security model more granular and auditable.

A plugin marketplace could serve as a central registry of verified plugins, making discovery and distribution easier for teams.

For use cases that require stronger isolation, Web Workers or iframes offer more robust sandboxing than API boundaries alone.

An event bus is another useful addition, allowing plugins to communicate with each other through a shared message system rather than direct API calls, which keeps inter-plugin dependencies loose and manageable.

Conclusion

Designing a plugin architecture in React is ultimately about treating your application as a platform rather than a single codebase. By defining clear contracts between the host application and its extensions, you enable teams to ship features independently while preserving stability, security, and performance.

If you are building a system that multiple teams (or even third-party developers) need to extend, start by establishing a minimal host API and plugin contract. Focus on strong TypeScript interfaces, clear lifecycle boundaries, and strict API access rules. These foundations ensure that plugins remain predictable and safe as the ecosystem grows.

As your platform evolves, you can gradually introduce more advanced capabilities such as plugin versioning, capability-based permissions, sandboxed execution environments, or an internal plugin marketplace.

Observability and monitoring also become increasingly important as the number of plugins grows, allowing you to detect compatibility issues or performance regressions early.

The key takeaway is to start simple but intentional. A small, well-defined plugin interface combined with lazy loading and secure API boundaries is often enough to support the first generation of extensions. From there, your architecture can expand naturally into a full ecosystem where features are delivered as modular, independently deployable plugins.

When implemented thoughtfully, a React plugin architecture transforms a single application into a scalable, extensible platform capable of supporting long-term growth and collaboration across teams.

React is a highly popular and powerful JavaScript library for user interface development. Its component-based architecture, combined with its declarative nature, is one of the primary reasons it works well for both small and large-scale applications.

But like with any technology, there are pitfalls that you can fall into when you're writing React code if you're not careful.

In this article, we will discuss these common mistakes and I'll provide you with best practices to avoid them. This will help you keep your React projects efficient, maintainable, and scalable.

1. Mistakes in Key Props Usage

One of the most common mistakes when using React involves the key prop. There are several scenarios where key props are used, with lists being the most common.

The key prop is crucial because it helps React track which items have changed, been added, or removed. If they are not correctly set, React's diffing algorithm can become inefficient, leading to performance issues and bugs.

Best Practice: Always pass a stable and unique key for the items in a list. If possible, use unique IDs from your data instead of array indices as keys.

const ItemList = ({ items }) => (
  <ul>
    {items.map(item => (
      <li key={item.id}>{item.name}</li>
    ))}
  </ul>
);

In the above code snippet, each item in the list has a key with item.id. This ensures that every list item is uniquely identifiable, helping React render more efficiently and reduce unnecessary renders.

For more tips on optimizing performance, check out this article on caching in React.

2. Ignoring the Virtual DOM

Some developers mistakenly believe that the role of the Virtual DOM means they need to update the DOM themselves. This goes against how React works and can result in unpredictability and bugs.

What is the Virtual DOM?

For those new to React, the Virtual DOM is an in-memory representation of the real DOM. It allows React to update the UI efficiently by minimizing direct manipulations of the actual DOM. React compares the new Virtual DOM with the previous one and updates only the necessary parts of the real DOM.

Developers might assume they need to synchronize the Virtual DOM with the real DOM due to experiences with other libraries or frameworks.

Best Practice: Always let React handle the DOM. If you must interact directly with the DOM, use refs.

const ItemList = ({ items }) => (
  <ul>
    {items.map(item => (
      <li key={item.id}>{item.name}</li>
    ))}
  </ul>
);

Explanation:

Using a unique identifier from the data, such as item.id, ensures that each key is unique and stable. This allows React to efficiently determine which items have changed, been added, or removed. It helps React's reconciliation algorithm to update the UI efficiently and prevents bugs related to item reordering or deletion.

3. Overusing State

State management is crucial in React, but excessive state usage can make a component complex and difficult to maintain. Any change in state triggers a re-render, which can be expensive if not handled properly.

Best Practice: Minimize the use of state and lift state only when necessary. For global state, use contexts or state management libraries like Redux.

import React, { useState } from 'react';

const MyComponent = () => {
  const [count, setCount] = useState(0);
  const [name, setName] = useState(''); // Additional state

  const handleIncrement = () => setCount(count + 1);
  const handleNameChange = (e) => setName(e.target.value);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={handleIncrement}>Increment</button>
      <input
        type="text"
        value={name}
        onChange={handleNameChange}
        placeholder="Enter name"
      />
    </div>
  );
};

In the above example, the useState hook is used to maintain a simple count state. When the button is pressed, it displays and increments the count, demonstrating a very basic use of state.

4. Forgetting to Clean Up Effects

When using the useEffect hook, it is essential to clean up side effects to prevent memory leaks and other unintended behaviors. Side effects might include setting up subscriptions, timers, or event listeners that need to be cleared when the component unmounts or when the effect dependencies change.

Best Practice: Always return a cleanup function from your effect when setting up side effects that need to be cleared.

Example without Cleanup:

const Timer = () => {
  const [time, setTime] = React.useState(0);

  React.useEffect(() => {
    const intervalId = setInterval(() => {
      setTime(prevTime => prevTime + 1);
    }, 1000);
    // No cleanup function provided here
  }, []);

  return <div>Time: {time}s</div>;
};

In the example above, a timer is set up with setInterval, but no cleanup function is provided to clear the interval when the component unmounts. This can lead to memory leaks.

Correct: Cleanup with useEffect:

const Timer = () => {
  const [time, setTime] = React.useState(0);

  React.useEffect(() => {
    const intervalId = setInterval(() => {
      setTime(prevTime => prevTime + 1);
    }, 1000);

    // Cleanup function to clear the interval
    return () => clearInterval(intervalId);
  }, []);

  return <div>Time: {time}s</div>;
};

In this corrected example, a cleanup function is provided to clear the interval when the component unmounts, preventing potential memory leaks.

5. Ignoring Performance

A React application can encounter serious performance issues, such as excessive re-renders and heavy calculations during render.

Best Practice: Memoize components and values using React.memo, useMemo, and useCallback for improved performance.

const MemoizedComponent = React.memo(({ data }) => {
  return <div>{data}</div>;
});

This example uses React.memo to memoize a functional component, preventing it from re-rendering unnecessarily when the data prop hasn't changed.

6. Overusing the Context API

The Context API is very handy for passing data through your component tree without prop drilling. But it's often overused, leading to performance issues.

Best Practice: Avoid using context for frequently changing values. Mainly use it for static values or rare updates.

const ThemeContext = React.createContext('light');

const ThemedComponent = () => {
  const theme = useContext(ThemeContext);
  return <div className={theme}>Themed Component</div>;
};

In the above example, ThemeContext is initialized with the default value 'light'. The ThemedComponent uses the useContext hook to get the actual value of the theme.

7. Not Handling Errors Properly

One important feature of React is error boundaries. They catch and handle errors in the component tree. Without them, unhandled errors may eventually crash the entire application.

Best Practice: Implement error boundaries using componentDidCatch or ErrorBoundary components.

const UserProfile = ({ userId }) => {
  const [user, setUser] = React.useState(null);
  const [error, setError] = React.useState(null);

  React.useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(response => {
        if (!response.ok) {
          throw new Error('Network response was not ok');
        }
        return response.json();
      })
      .then(data => setUser(data))
      .catch(err => setError(err.message));
  }, [userId]);

  if (error) {
    return <div>Error: {error}</div>;
  }

  if (!user) {
    return <div>Loading...</div>;
  }

  return <div>{user.name}</div>;
};

By adding error handling, we catch any issues with the API request and display an appropriate error message.

This approach improves the robustness of the component, providing users with feedback in case of an error and ensuring the application remains functional even when unexpected issues occur.

8. Failing to Keep Components Pure

React components should always be pure functions of their props. Impure components depend on external states and side effects, making the system unpredictable.

Best Practice: Ensure that your components are pure and that their output depends entirely on their props.

const MyComponent = ({ name }) => {
  return <div>{name}</div>;
};

This functional component is pure because it only depends on the name prop to render its output.

9. Not Using React Developer Tools

React Developer Tools is a simple yet essential extension for debugging and optimizing the performance of a React application. Development can become more complicated if you don't use this helpful toolkit.

Best Practice: Install and use React Developer Tools regularly to inspect component hierarchies, state, and props.

10. Ignoring SEO Best Practices

SEO is an important aspect of any web application, and this holds true for React applications as well. Many developers overlook SEO, leading to poor search engine rankings and reduced visibility.

Here are some of the most common React SEO mistakes:

Wondering how to implement the React SEO Best Practices? Good news, I made a follow up video:

Best Practices: If video is not your thing, here are the key points to remember:

• Always render your content server-side: Google has publicly stated to avoid Client-Side Rendering (CSR).
• Ensure unique URLs for different pages: Since React is a Single Page Application (SPA), always render different URLs for different pages. For example, if you have 5 landing pages, make sure you render 5 unique URLs.
• Ensure unique metadata for each page: As a bonus tip, use React Helmet to ensure every single page has unique metadata.
• Internally link your website: Surprisingly, many developers completely ignore this. Make sure to add internal links to improve navigation and SEO.

Conclusion

In conclusion, avoiding these common React mistakes can greatly improve the performance and maintainability of your applications.

If you're interested in learning more about my work or need help with React or Next.js development, check out hirenext.dev. Alternatively you can keep up with my blog OhMyCrawl.

Also, some props (for example, the current authenticated user, UI theme, or preferred language) will be required by many components within an application.

React's Context API provides a way to share values like these between components without having to explicitly pass them down as a prop through every level of the tree. So, Context is designed to share data that can be considered "global" for a tree of React components.

What You'll Learn in This Article

• What is the React Context API and when should you use it?
• React Context API example: how to switch between light and dark mode UI themes
• How to create multiple React Contexts (and why you should)
• How to prevent the React Context re-render issue
• React Context API vs Redux for global state management

Source Code

All examples from this article are in this repo: https://github.com/DoableDanny/React-context-API-tutorial

I also made a video version of this article to make it easier for you to follow along with the examples: React Context Tutorial with Examples

What is the React Context API and When Should You Use It?

The Context API is a feature in React that provides a way to share values like themes, user information, or configuration settings between components without having to explicitly pass props through every level of the component tree. This makes it particularly useful for managing global state, or state that is needed by many components at different nesting levels.

The Context API is a part of the React library, meaning that you don't need to install it as a third-party package in a React application.

So, the Context API can be used for sharing global variables between components in a React app, without having to pass these variables as props down the component tree. This is especially useful if there are components that are deeply nested that need access to variables from higher up components.

Now, let's learn how the Context API works by going through a common use case example for the Context API...

React Context API Example — Light and Dark Mode UI Theme

A very common real-world usecase for the React Context API is for storing the current user's prefered theme – that is, "light mode" or "dark mode".

Think about it: many of the UI components in a React app will need to know about the current theme, in order to display the approprate styles. Buttons, Headings, the Navbar, the Footer, Dropdowns – lots of components are going to need to display themselves differently depending on the current theme.

The passing-down-a-prop solution

The most simple and obvious "React" way to solve this would be to create a theme variable in the main top-level App component, and then keep on passing it down as a prop to all of the components in the tree. But this leads to a React problem known as "prop drilling".

Prop drilling is a term used in React to describe the process of passing data from a parent component to a deeply nested child component through multiple intermediary components. This can happen when you need to pass state or functions several levels down the component tree.

Prop drilling example:

function App() {
  const theme = 'dark';
  return <Parent theme={theme} />;
}

function Parent({ theme }) {
  return <Child theme={theme} />;
}

function Child({ theme }) {
  return <Button theme={theme} />;
}

function Button({ theme }) {
  return <button style={{ background: theme === 'dark' ? 'black' : 'white' }}>Click me</button>;
}

As you can see, each intermediary component needs to include the prop, even if it doesn't use it, just to pass it down further. This clutters the code and makes it more difficult to understand.

Also, intermediary components that do not use the props might still re-render when the props change, leading to performance issues. This can be particularly problematic in large applications with deep component trees.

Context API To The Rescue

We can solve this prop drilling issue by using the Context API.

Creating a context

First, we need to create the context, and pass in the light theme as the default value:

// src/contexts/ThemeContext.js

import { createContext } from "react";

export const themes = {
  light: {
    background: "white",
    text: "black",
  },
  dark: {
    background: "black",
    text: "white",
  },
};

export const ThemeContext = createContext(themes.light);

Above, we have created a contexts folder inside of our src folder for storing all of our contexts. It's considered good practice to create each context in its own file. In our case, we just need to create a context for storing the current theme.

Notice that contexts are created by calling the createContext() function that comes from the React library. We pass the createContext() function a default value of themes.light.

Providing a context

Next, we need to wrap all of the components that need access to the theme in a context provider. The context provider takes a value prop, where we can pass the value that we want to make global.

Below, <Navbar /> and <Button /> will have access to the theme state, even though we haven't explicitly passed it down as a prop. This is because we have wrapped these components in the theme context provider, and passed it the value (theme) that needs to be made global.

// src/App.js

import React, { useState } from "react"
import { ThemeContext, themes } from "./contexts/ThemeContext"
import Navbar from "./components/Navbar"
import Button from "./components/Button"

const App = () => {
  const [theme, setTheme] = useState(themes.light)

  const toggleTheme = () => {
    setTheme(state => (state === themes.light ? themes.dark : themes.light))
  }

  return (
    <div className="App">
      <ThemeContext.Provider value={theme}>
        <Navbar />
        <Button changeTheme={toggleTheme} />
      </ThemeContext.Provider>
    </div>
  )
}

export default App

If we also wanted to make setTheme() available throughout our app via context, we could pass the following object to the value prop. We'd then be able to toggle the theme from any component within the Theme Context Provider:

<ThemeContext.Provider value={{ theme, setTheme }}>

Now let's create the Button and Navbar components that will consume the theme context using the useContext() hook. Notice how the CSS styles of the components change depending on the current theme values:

// src/components/Button.js

import React, { useContext } from "react"
import { ThemeContext } from "../contexts/themeContext"

const Button = ({ changeTheme }) => {
  const theme = useContext(ThemeContext)

  return (
    <button
      style={{ backgroundColor: theme.background, color: theme.text }}
      onClick={changeTheme}
    >
      Toggle theme
    </button>
  )
}

export default Button

// src/components/Navbar.js

import React, { useContext } from "react"
import { ThemeContext } from "../contexts/themeContext"

const Navbar = () => {
  const theme = useContext(ThemeContext)

  return (
    <nav style={{ backgroundColor: theme.background }}>
      <ul>
        <li style={{ color: theme.text }}>Home</li>
        <li style={{ color: theme.text }}>About</li>
      </ul>
    </nav>
  )
}

export default Navbar

Here are the steps involved in using a context:

1. Import the context that you want to use (ThemeContext in this example) into the component.
2. Import the useContext hook from React.
3. Inside of the component that needs access to the context value(s), call the useContext hook and pass the context that you want to use. Assign this to a variable (const theme = useContext(ThemeContext) in our example)
4. The component now has access to the global variable, and the component will re-render/be updated every time a value inside of the context is updated.

OK, that's everything that we need for this example. Let's now start up our application by running the following command in the project route:

npm run start

Now let's test things out in the browser.

Light mode:

Press the Toggle Theme button

Dark mode:

And there we go, we've used the context API to share the theme state throughout our application – without having to pass it down as a prop. Cool! 👌

How to Create Multiple React Contexts

In our example above, we only created one context, ThemeContext. But what if we had other data that needed to be made global, such as the current logged in user's username and age?

We could just create one big context for storing all variables that needed to be consumed globally:

<OneBigContext.Provider value={{ theme, username, age }}>
  <Button changeTheme={toggleTheme} />
  <Navbar />
</OneBigContext.Provider>

But this is considered bad practice, as whenever a context value is updated, all components consuming that context will be re-rendered. This means that all components that only need to know about the theme, and not the user variables, will get re-rendered whenever any of the user variables are updated. This can worsen an app's performance, especially in larger apps with lots of complex components.

We can solve this by creating multiple contexts – one context for the theme and another for the user data – and wrapping our app in both providers, like so:

<ThemeContext.Provider value={theme}>
  <UserContext.Provider value={{ username, age }}>
    <Button changeTheme={toggleTheme} />
    <Navbar />
  </UserContext.Provider>
</ThemeContext.Provider>

By only storing related data in each context, we help prevent unnecessary re-renders of components, and improve the performance of our app.

How to Prevent the React Context Re-render Issue

As we've discussed, whenever a context value is updated, all components consuming that context will be rerendered – even if wrapped in React.memo(). (If you don't know what React.memo() is, don't panic – we'll discuss it soon!) This can worsen an app’s performance.

But we can mitigate this problem with the following methods:

1. Use Multiple React Contexts

This is what we discussed above, and is the "preferred" way of solving the rerender problem (see this answer).

2. Split the Component and Pass the Needed Value

You can also split the component up and pass down (as a prop) the needed value from context, with the child components wrapped in React.memo(). Example:

const Card = () => {
  const appContextValue = useContext(AppContext);
  const theme = appContextValue.theme;

  return (
    <div>
      <CardTitle theme={theme} />
      <CardDescription theme={theme} />
    </div>
  );
};

const CardTitle = React.memo(({ theme }) => {
  return <h2 style={{ color: theme.text }}>This is the Title </h2>;
});

const CardDescription = React.memo(({ theme }) => {
  return <p style={{ color: theme.text }}>lorem ipsum dolor sit amet,</p>;
});

React.memo() is a higher-order component (HOC) in React that is used to optimize functional components by preventing unnecessary re-renders. It does this by memoizing the component, meaning it will only re-render if its props change.

• Without React.memo(): The components, CardTitle and CardDescription, would re-render whenever their parent, Card, re-renders – even if their props haven't changed. This can lead to performance issues in larger applications or with components that are expensive to render.
• With React.memo(): CardTitle and CardDescription only re-render if their props change, reducing unnecessary renders and improving performance.

So, by splitting the component up, passing down only the values that are needed as props, and wrapping the components in React.memo(), CardTitle and CardDescription will only be re-rendered if theme is updated, but not if username is updated.

This solution is particularly useful if we can’t split out context for whatever reason.

3. One Component with React.useMemo() Inside

Below, theme is a dependency of useMemo(), so we will only get a re-render of the elements returned by the callback function when theme is changed:

const Card = () => {
  const appContextValue = useContext(AppContext);
  const theme = appContextValue.theme;

  return useMemo(
    () => (
      <div>
        <CardTitle theme={theme} />
        <CardDescription theme={theme} />
      </div>
    ),
    [theme]
  );
};

const CardTitle = ({ theme }) => {
  return <h2 style={{ color: theme.text }}>This is the Title </h2>;
};

const CardDescription = ({ theme }) => {
  return <p style={{ color: theme.text }}>lorem ipsum dolor sit amet,</p>;
};

Here's how useMemo() works:

1. The first parameter of useMemo() is a callback function that returns a memoized value. In this case, it returns a React element, or tree of React elements.
2. The second parameter is an array of dependences. If any of the values in this dependency array are updated, then the callback function provided as the first argument is called, and the elements that the callback function returns are re-rendered.

So, useMemo() can be used to only re-render React elements if certain values specified in the dependency array are updated.

By wrapping these elements in useMemo(), and specifying theme as the only dependency, the elements only get re-rendered if theme is updated, but won't get re-rendered if any other context value is updated.

This solution is also particularly useful if we can’t split out context.

React Context API vs Redux

This is a very common and much-depated topic within the React community. React Context API and Redux are both tools for managing state in a React application, but they have different use cases, strengths, and limitations.

The Context API is a built-in feature of React, with the primary purpose of allowing state to be shared across a tree of React components without prop drilling.

The Context API has a simple API: React.createContext(), Provider, and the useContext() hook. And is good for small to medium-sized apps, as it is straightforward to use, and requires little setup and boilerplate code.

On the other hand, Redux is a state management library that has to be installed as a third-party package into an application. Its primary purpose is to manage application-wide state in a predictable way, especially in large and complex applications.

Why Context API is good for small-to-medium-sized apps:

• Simplicity: It's simpler than Redux.
• Built-in: It's part of React, so no need to install extra packages, making maintenance of the project easier.
• Minimal boilerplate: Requires less boilerplate and setup than Redux.

Why Redux is good for larger, more complex applications:

• Single Store: Maintains a single store for the entire application state, which makes debugging and testing easier.
• Predictable State Updates: Uses pure functions (reducers) to manage state updates, ensuring predictability and immutability.
• Middleware Support: Powerful middleware system (like redux-thunk or redux-saga) for handling asynchronous actions and side effects.
• DevTools Integration: Excellent developer tools for time-travel debugging and state inspection.
• Suitable for Large Apps: Designed to handle complex state logic and large-scale applications.

Redux maintainer, Mark Erikson, gives the following reasons for using Redux:

• Consistent architectural patterns
• Debugging capabilities
• Middleware
• Addons and extensibility
• Cross-platform and cross-framework usage
• Depending on your app's setup, much better performance than working with just Context (we don't have to worry about the rerender problem we get with Context, mentioned above – components only rerender when the value they are using updates)

In summary:

• Redux is a more complex state management tool that provides more features and tools. It provides a consistent way of managing state throughout an application, which is very helpful on larger projects with multiple developers (as they won't all be implementing their own styles of state management and making the codebase inconsistent).
• React Context API is more straightforward, requires less setup, and is a good solution for smaller to medium sized projects where the added complexity and overhead of using a tool like Redux isn't necessary.

Thank you for reading!

If you found this article useful, you can hear more from me by:

• Subscribing to my YouTube channel. I plan to turn it into a React/NextJS/Node-focused channel, with in-depth videos 😎.
• Following me on Twitter where I tweet about my freelancing journey, side projects and current learnings.
• Checking out my tech blog

Free React Hooks Course

Want to learn all the hooks in React? I created a free 2 hour video explaining all 9 core React Hooks with examples: React Hooks Tutorial — All React Hooks Explained with Examples. If you enjoy, consider subscribing to my channel.

Cheers!

Hooks also make your life easier by providing some convenient features. Among these hooks, we have useMemo and useCallback that help improve your website's performance.

In today's tutorial, we are going to discuss both the useMemo and useCallback hooks. You'll learn the difference between them and when to use each hook.

The useMemo Hook

The useMemo hook memoizes the return value of an expensive calculation between renders. Memoizing means storing the value as a cached value so that the value need not be calculated again (unless it's required).

useMemo is a hook used for optimising the performance of your renders. Normally, when you declare a variable inside a component, it gets re-created on every render. If it stores the return value of a function, then the function gets called every time your component renders.

Normally, this wouldn't be a problem. But, what if the function is expensive? What if it takes a longer time to execute? Take the following example:

function calculate() {
  let result = 0;
  for (let i = 0; i < 1000000000; i++) {
    result += i;
  }
  return result;
}

function App1() {
  const [count, setCount] = useState(0);

  const value = calculate();

  return (
    <div className="App">
      <button onClick={() => setCount(count + 1)}>Increment Count</button>
      <p>Count: {count}</p>
    </div>
  );
}

When you click on 'Increment Count', it takes a few seconds to update the count state. This is because the calculate function runs every time a component re-renders after state change.

Now, imagine if there were multiple state variables in the component, each serving its own purpose. Each state update would cause a re-render and execute this expensive function.

These state variables could be completely unrelated to the expensive calculation performed, which would cause unnecessary delays. This would affect the performance of your website and could lead to a terrible user experience.

useMemo can help you tackle this issue. Let's first understand its syntax:

const value = useMemo(expensiveFunction, [...dependencyArray])

The useMemo hook should be declared at the top level of your component. It takes the following arguments:

• expensiveFunction contains the expensive calculation you want to perform. If you have declared the function outside, pass the function reference only, without the brackets. You can also pass arrow functions directly.

• dependencyArray contains list of dependencies for the hook. The expensive function will be called only when one of these dependencies is updated. You can pass state variables or props that are dependent on this calculation. Any other state updates will not trigger the function.

On the first render, useMemo returns the result of expensiveFunction and caches the result. During the subsequent renders, it will return the cached value if no dependencies have changed. If they change, then it will call the function again.

Let's use this in our case:

const [dependentCount, setDependentCount] = useState(10);

const value = useMemo(calculate, [dependentCount]);

return (
  <div className="App">

    // ...

    <button onClick={() => setDependentCount(dependentCount + 1)}>
      Increment Dependent Count
    </button>
    <p>Dependent Count: {dependentCount}</p>
  </div>
);

We have created another state dependentCount that we assume is dependent on the expensive calculation. When this state updates and renders the component, the calculate function will run.

But if any other state changes, then useMemo will return the cached value instead of running the function again.

Let's test this by adding a console.log inside the function:

Output with useMemo

Now, when you click "Increment Count", the rendering is faster, since the calculate function is not getting called on every render. This is the same during every other state update not listed in the useMemo dependency array.

But when you click on "Increment dependent Count", it takes time to render the updated value. This is because dependentCount is a dependency of useMemo and changing it calls the expensive function, so the component takes time to re-render.

In this way, with useMemo, you can control the execution of an expensive function by calling it only for state updates that actually need the value returned. This can drastically improve your app's performance.

When to use useMemo:

• When you have a state dependent on an expensive calculation, but you don't want to run the calculation on every render.

• When you declare an array or object inside a component, its reference changes on every render, even though the value remains the same. Wrapping the values inside useMemo maintains referential equality and prevents unnecessary re-renders. This is essential when there's a useEffect dependent on the array or object.

• When you are rendering lists using Array.map that do not need to change unless a certain state value changes.

The useCallback Hook

Similar to useMemo, you can also use this hook to optimise performance. The useCallback hook memoizes a callback function and returns it.

Note that the useCallback hook memoizes the function itself, not its return value. useMemo caches the functions return value so that the function need not execute again. useCallback caches the function definition or the function reference.

A function declared inside a component gets re-created on every component render, similar to a variable. The difference is, it gets rendered with a different reference every time. So, a useEffect dependent on this function will execute again on each render. A similar thing happens with child components.

Let's take an example:

const App = () => {
  const [count, setCount] = useState(0);
  const [value, setValue] = useState("");

  const handleClick = () => {
    setValue("Kunal");
  };
  return (
    <div className="App">
      <button onClick={() => setCount(count + 1)}>Increment Count</button>
      <p>Count: {count}</p>
      <p>Value: {value}</p>
      <SlowComponent handleClick={handleClick} />
    </div>
  );
};

const SlowComponent = React.memo(({ handleClick, value }) => {

  // Intentially making the component slow
  for (let i = 0; i < 1000000000; i++) {}

  return (
    <div>
      <h1>Slow Component</h1>
      <button onClick={handleClick}>Click Me</button>

    </div>
  );
});

Here, we have a SlowComponent as the child of the App component. When a parent component renders, all of its child components render, regardless of whether anything has changed inside them.

To avoid unnecessary renders of the child components, we generally use the React.memo function. This basically caches the component and only re-renders it if its props have changed.

Now, when you click on 'Increment Count', it still takes a long time to render, because SlowComponent re-renders on state change. But why is that? We're not changing any of its props.

On the surface, we may not appear to change the value of handleClick prop. But, since functions are re-created with a different reference, on every render of the App component, its child (that is SlowComponent) renders.

To maintain referential equality, we wrap this function's definition inside a useCallback.

Let's understand its syntax:

const cachedFn = useCallback(fn, [...dependencyArray])

useCallback takes the following arguments:

• fn is the function you want to cache. It is the function definition that you want to create, and can take any arguments and return any value.

• dependencyArray is a list of dependencies, changes to which trigger re-creation of the function. You can pass state values or props that are dependent on this function.

On the first render, React creates the function (does not call it) and caches it. On the subsequent renders, the cached function is returned to you. Remember, this hook returns and caches the function and not its return value.

Let's use this hook in our example:

import { useCallback } from "react";

const App = () => {

  // ...

  const handleClick = useCallback(() => {
    setValue("Kunal");
  }, [value, setValue]);

  // ...
};

Here, we have wrapped the function inside a useCallback and passed two dependencies that are involved with this function.

Now, when you click on 'Increment Count', the rendering is much faster. This is because the handleClick reference is cached between renders and hence, SlowComponent does not re-render.

But when you click on the button inside SlowComponent it will re-render. This is because when the value state changes, the handleClick method is created again and so the props of the slow component have changed.

Value takes time to render

You can add many more states to the App component and update them without inhibiting performance as long as you don't update value's state.

When to use useCallback

• When you have event handlers defined for an element inside your component, wrap them inside a useCallback to avoid unnecessary re-creations of event handlers.

• When you call a function inside a useEffect, you usually pass the function as a dependency. To avoid using useEffect unnecessarily on every render, wrap the function definition inside a useCallback.

• If you are writing a custom hook, and it returns a function, it is recommended to wrap it inside a useCallback. So, there's no need for the users to worry about optimizing the hook – rather, they can focus on their own code.

Differences Between useMemo and useCallback

Let's summarize the differences between the two hooks:

• useMemo caches the return value of a function. useCallback caches the function definition itself.

• useMemo is used when you have an expensive calculation you want to avoid on every render.

• useCallback is used to cache a function to avoid re-creating it on every re-render.

• useMemo makes sure that an expensive function should only be called for state values dependent on it.

• useCallback creates stable functions that maintain the same reference between renders. This avoids unnecessary rendering of child components.

And here are a few more things to remember. Use these hooks only if you want to memoize expensive calculations or prevent unnecessary re-renders. Do not use useMemo and useCallback everywhere.

For regular functions, these hooks don't make much difference. Overusing them will make your code unreadable. Instead, you can figure out other ways to improve app performance.

Conclusion

useMemo and useCallback are useful hooks in React that can help you optimize performance of your web app. It is important to understand the difference between the two and their usages.

In this article, we have discussed how both hooks work. useMemo caches the result of an expensive calculation, while useCallback caches the function reference. We also listed down scenarios when you should use each hook. Together, both these hooks can make your website faster.

I hope this article helps clear up any confusion. If you have further questions or comments regarding the post, reach out to me on Twitter. I would love to hear suggestions. Till next time, goodbye!

Unfortunately, it was not as simple as just running $ nvm use 18 and sailing into the sunset. Luckily, if you follow all the proper steps, you'll get past many significant hurdles and upgrade successfully. In this guide, I will share all the knowledge I wish I had known going into the process. The goal is to get your React application using Node 18+ and Jest 29+ while not making the treacherous upgrade to React Scripts 5.

If you can upgrade to React Scripts 5 (which is impractical for most real-world applications), I highly recommend that path instead. This is because the newest version of CRA fixes many issues with older dependencies, like the MD4 envelope or Babel process() return shapes, that we'll manually tackle in this tutorial. If you can upgrade to v5, then Node versions 18+ should work out of the box.

Unfortunately, going up to React Scripts 5 introduces many breaking changes, mostly due to the upgrade to Webpack 5. While many small/tutorial-level applications can upgrade fairly easily, any real-world application faces a steep uphill journey to upgrade.

If the React Scripts 5 upgrade approach doesn't work for you, you can follow what I've written below on making the Node upgrade work while still staying on React Scripts 4. At the end of this page, I've written a small note about my journey trying the v5 upgrade.

Everyone's upgrade journey will vary, especially considering the Jenga of npm dependencies and the relative lack of maintenance of Create React App's React Scripts in recent years.

These are the steps of the upgrade that I've tried with a few different React applications, but you may encounter issues I didn't encounter myself. Google is your best friend in these cases, and it will often lead you to Stackoverflow, GitHub issues, other tutorials, and maybe even source code. Don't be afraid; you'll be able to figure it out!

Note: In this tutorial, I'll refer to Create React App as CRA. React Scripts is the name of the installed package that abstracts all the configuration created by the Create React App command, and in most cases you'll see online resources use both interchangeably.

Table Of Contents

1. Prerequisites
2. How to Validate Every Step
3. How to Bump to React Scripts v4.0.3
4. How to Bump Node Version to 18
   – Understanding the MD4 Issue
5. How to Eject Out of React Scripts
   – How to Add Linter Ignores For Ejected Files
   – How to update your Dockerfile and Other Build Processes with the ejected folders
   – How to Fix Absolute Paths for Jest
   – How to update your Dockerfile and Other Build Processes with the ejected folders
6. How to Override Webpack MD4 to SHA256
7. How to Upgrade to the Latest Version of Jest
   – How to Bump to Jest 28
   – How to explicitly set jsdom as the test environment
   – How to Fix Transformer Return Type for process() and processAsync()
   – How to Bump Jest to 29
8. How Far Should I Upgrade NodeJS?
9. Should You Still Use Create React Scripts? What Alternatives Are There?
10. Conclusion
11. Alternatively: How to Upgrade to React Scripts 5.0.1

Prerequisites

To follow along with this guide, you should have a React application that is:

• created with create-react-app v4 or upgraded to use react-scripts v4. I've tested this tutorial on both scenarios.
• running on Node 16

If you're running NodeJS behind 16, I highly suggest upgrading to version 16. The upgrade path to 16 isn't too bad, but the jump from 16 to 18 creates breaking issues with CRA 4 defaults.

Our application also ran jest (v26), the most common test framework in React and shipped by default in CRA v4. If you aren't running Jest, then you can skip the steps relevant to it.

We were also using yarn, but the process should be identical with different syntax if you use any other runner/package manager like npm.

Ideally, you have some test case coverage to ensure things don't break between versions, so it's well worth taking some time to write some broad integration and unit tests before any upgrade.

I recommend using version control like git for each stage while working on a branch. I started over three different times using different upgrade strategies until I had something that worked. Here's a quick intro to git branches if you're unfamiliar with them.

I also recommend using nvm (Node Version Manager) to to swap versions quickly. You don't have to use it, and there are many other alternatives out there to manage versions, but it makes quickly switching very easy with just nvm use. I'll use nvm syntax in this tutorial, but it should be pretty similar for your tool.

How to Validate Every Step

Throughout the tutorial, to ensure things still work, you'll run the following:

• $ yarn build – End-to-end build to catch a lot of library-level issues
• $ yarn test – Regression tests to catch breaks in functionality
• $ yarn start – The starter scripts to catch many initialization bugs.

If you have any more validation steps (CI builds, Docker, staging environments, smoke tests), make sure they're working already and use them throughout the process to validate the upgrade worked correctly. For the rest of the tutorial, I'll refer to these as validation commands.

Before you start the upgrade, make sure all validation steps are working on your current Node 16 and CRA 4. At the end of the tutorial, all these validation steps should be working too. Ultimately, make sure to actually use your React application extensively as the final test once all the upgrade process is done.

Occasionally, you may need to $ rm -rf node_modules and $ rm package.lock.json / $ rm yarn.lock because some library changes may not propagate correctly. Ideally you won't need to do this, but it's reasonably safe since it just downloads all packages again.

How to Bump to React Scripts v4.0.3

Depending on when you started your project from CRA, you'll likely be at different versions along v4. First, we upgrade to the latest minor version to smooth over the rest of the upgrade process.

There shouldn't be any major breaking changes between the minor versions, but make sure to upgrade it incrementally in your package.json going from 4.0.0 -> 4.0.1 -> 4.0.2 -> 4.0.3. Going to 4.0.3 will streamline your upgrade process since these minor updates have a lot of useful bug, library, and dependency fixes while not creating new work for now.

I ran $ yarn install after each step and then checked my validation commands to ensure everything was still working.

... 
"dependencies": { 
    "react-scripts": "4.0.1", 
    ... 
}, 
...

In my projects, I didn't encounter any issues, but your mileage may vary. The official CRA v4 changelog documentation has a list of small changes and upgrade steps between the versions, which will narrow down the causes.

How to Bump Node Version to 18

After making sure your validation commands are working on your current Node 16, set your version to 18. Then we work on fixing all the validation commands until all of them work. Occasionally you may switch back to 16 to make sure things still work in the older version.

In your command line, run the following:

$ nvm install 18
$ nvm use 18

Note: If you have a .nvmrc file, you can skip the version numbers in the nvm install and nvm use commands. Update the file as you change node versions.

Unfortunately, if you try $ yarn start or $ yarn build, you'll immediately run into the cryptography error that comes from openssl, which blocks all encryption using MD4. This is the main error blocking the upgrade to Node 18 while on CRA 4.

Error: error:0308010C:digital envelope routines::unsupported

Understanding the MD4 Issue

MD4 is an old encryption algorithm from the 1990s and has been considered very insecure since 1995 (Wikipedia). OpenSSL from version 3 onward changed MD4 to not be supported by default, but it can be enabled with an allow unsafe legacy flag on your system openssl or --openssl-legacy-provider if adding it to your node/CRA script (see the Node docs).

It's a seemingly simple fix to the solution, but this is more of a last resort since allowing unsafe cryptography is generally a bad idea, and OpenSSL has disabled the algorithm entirely for a reason.

Note: If you're curious, Webpack has a 1000+ response discussion on this topic that might have something useful. Later versions of Webpack also eventually allowed a better algorithm called xxHash, added a built-in MD4 wasm implementation, and added a new config option called deterministic that sidesteps the issue.

I highly recommend reading this StackOverflow answer for a quick overview of the major options if we aren't patching it ourselves. Since upgrading dependencies isn't possible here, and we don't want to stay on an old Node version or allow insecure algorithms, we need to dive into the internals of CRA to fix it.

How to Eject Out of React Scripts

CRA is designed for a zero-configuration experience for React Apps that lets you focus on just working on your business logic.

When you want to start changing configuration, CRA doesn't have a built-in method to override any option. Instead, it offers a command called eject that copies over all the internals of CRA to your project while leaving your yarn/npm commands intact and then removing React scripts from your project entirely. It's a one-way action, so make sure you save the previous version in git.

$ yarn eject

This is a huge command that will change lots of files in the config/ and scripts/ directories as well as your list of packages in package.json. Once you rerun yarn install, make sure to run all your validation commands to make sure everything still works on Node 16 since nothing should have changed in terms of functionality.

Alternatively, if you don't want to try eject, there are also workarounds like:

• CRACO uses a clever override mechanism to allow you to still use React Scripts while customizing. Read Getting Started and Why I built CRACO. Start off with version 6.4.5 for CRA v4.
• patch-package applies specific npm package changes for your project and then you share the patch with your team/project. For this guide, you will patch react-scripts with the modified webpack and config setups.
• Forking CRA with your own modifications. This way you can still keep the zero config CRA with no hacks to patch in new functionality, but this might get complicated. Here's a guide I saw online: Customizing create-react-app: How to Make Your Own Template.

There's also react-app-rewired for a similar purpose, but it's mostly unmaintained right now and intended for older versions of CRA behind v4.

How to Add Linter Ignores for Ejected Files

A lot of the new files from the ejected configuration might not follow your existing project's linter rules. Until you're done with the upgrade, I recommend just adding new ignores on the top of the failing files like:

/* eslint-disable import/order */

// rest of file
...

Once you're done with the entire tutorial, feel free to go back and try fixing some of the linter issues, but it might be okay to leave these files as-is since you'll rarely go in to change anything.

How to Fix Absolute Paths for Jest

In your package.json, the jest "testRunner" option might be encoded to the absolute path that only makes sense on your computer. So, you'll want to change it to a path based on your project's root directory.

While this might work fine for your local development, it will break for any collaborators or cloud computers.

... 
"jest": { 
    ... 
    "testRunner": "/my/computer/path/project_name/node_modules/jest-circus/runner.js", 
    ... 
}, 
...

We use the option <rootDir> that is provided by Jest:

... 
"jest": { 
    ... 
    "testRunner": "<rootDir>/node_modules/jest-circus/runner.js", 
    ... 
}, 
...

You might not have to do this on all projects, but "modulePaths" may need an update as well:

...
"jest": { 
    ... 
    "modulePaths": [ "/my/computer/path/project_name/src" ] 
    ... 
}, 
...

Just remove the reference to your computer's absolute path:

...
"jest": { 
    ... 
    "modulePaths": [ "src" ] 
    ... 
}, 
...

How to Update your Dockerfile and Other Build Processes with the Ejected Folders

Make sure to include the new ejected folders, scripts/ and config/, into your Dockerfile and other build processes you might be using that existed outside CRA.

For example, the Dockerfile will have the additions of new directories that CRA created that we also want to copy over.

... 
COPY scripts scripts/
COPY config config/ 
...

How to Override Webpack MD4 to SHA256

Based on this StackOverflow answer, we add to webpack.config.js right before we start defining module.exports to use the relatively more modern and secure SHA256 instead of MD4 that's also built into Webpack:

// ... 
// https://stackoverflow.com/a/78005686 
const crypto = require("crypto"); 
const crypto_orig_createHash = crypto.createHash; crypto.createHash = algorithm => crypto_orig_createHash(algorithm == "md4" ? "sha256" : algorithm); 
// This is the production and development configuration. 
// It is focused on developer experience, fast rebuilds, and a minimal bundle. 
module.exports = function (webpackEnv) 
// ...

Once you've changed this, the envelope errors should disappear and your validation commands should now work for Node 18.

How to Upgrade to the Latest Version of Jest

The eject also exposes the Babel configuration used for making more recent versions of Jest work correctly. This works great for version 26 but moving the CRA config to the latest version (v29 at the time of writing) has a few more steps.

You should go through v26 -> v28 -> v29 (skipping v27) for all the Jest dependencies. This part is optional if you're happy with CRA v4's Jest 26, but until you eject, you're blocked from upgrading to a recent version of Jest.

I'm skipping Jest 27 because it'll require a change in config/jest/babelTransform.js where you'll have to change module.exports = babelJest.default.createTransformer({ to module.exports = babelJest.createTransformer({. This was a bug fixed in version 28. Still, if you want to go through Jest 27 as well, you'll be able to follow the rest of the steps with this change and then optionally reverting it on Jest 28.

I also highly recommend reading the introduction articles for each of the Jest version upgrades:

• Jest 27: New Defaults for Jest, 2021 edition ⏩
• Jest 28: Shedding weight and improving compatibility 🫶
• Jest 29: Snapshot format changes

Most of the issues come from Jest 28 having many breaking changes, but the rest of the upgrade path is fairly straightforward.

How to Bump to Jest 28

For each upgrade, I recommend doing a find and replace for all the many Jest-related packages in your package.json since the version numbers are all synced. Once you update the numbers, just run $ yarn install:

... 
"devDependencies": { 
    ...
    "babel-jest": "^28.1.3", 
    ...
    "jest": "^28.1.3", 
    "jest-circus": "^28.1.3", 
    "jest-resolve": "^28.1.3", 
    ...
} 
...

How to Explicitly Set jsdom as the Test Environment

If you try running your tests out of the box with $ yarn test. It'll give you this error:

● Validation Error: 
Test environment jest-environment-jsdom cannot be found. 
Make sure the testEnvironment configuration option points to an existing node module. 
Configuration Documentation: https://jestjs.io/docs/configuration 
As of Jest 28 "jest-environment-jsdom" is no longer shipped by default, make sure to install it separately.

In Jest 27, Jest changed the default test environment to be meant for a more lightweight NodeJS backend environment. However, we have a frontend application, so we still want to test with a simulated browser environment that older Jest versions were based off called jsdom.

To fix this, add "jest-environment-jsdom" to your dependencies and then run $ yarn install.

... 
"devDependencies": { 
    ...
    "babel-jest": "^28.1.3", 
    ...
    "jest": "^28.1.3", 
    "jest-circus": "^28.1.3", 
    "jest-resolve": "^28.1.3", 
    "jest-environment-jsdom": "^28.1.3", 
    ...
} 
...

How to Fix Transformer Return Type for process() and processAsync()

‌‌Now, if you run yarn test, you'll get this:

FAIL  src/App.test.js 
● Test suite failed to run 
● Invalid return value: `process()` or/and `processAsync()` method of code transformer found at "path/in/my/computer" 
should return an object or a Promise resolving to an object. The object must have `code` property with a string of processed code. 
This error may be caused by a breaking change in Jest 28: https://jestjs.io/docs/upgrading-to-jest28#transformer Code Transformation Documentation: https://jestjs.io/docs/code-transformation

This is because the process() functions that used to return a string now expect an object in the format of { code:old_string_here}.

To fix this, we go into our ejected config/jest folder, and we change the output shape for all our files. For CSS, it's a single line change:

// This is a custom Jest transformer turning style imports into empty objects. 
// http://facebook.github.io/jest/docs/en/webpack.html 

module.exports = { 
    process() { 
        return { code: 'module.exports = {};' }; 
    }, 
    getCacheKey() { 
        // The output is always the same. 
        return 'cssTransform'; 
    }, 
};

and for files, you have to change both branch return statements:

const path = require('path'); 
const camelcase = require('camelcase'); 

// This is a custom Jest transformer turning file imports into filenames. // http://facebook.github.io/jest/docs/en/webpack.html 
module.exports = { 
    process(src, filename) { 
        const assetFilename = JSON.stringify(path.basename(filename)); 
        if (filename.match(/\.svg$/)) { 
            // Based on how SVGR generates a component name: 
            // https://github.com/smooth-code/svgr/blob/01b194cf967347d43d4cbe6b434404731b87cf27/packages/core/src/state.js#L6 
            const pascalCaseFilename = camelcase(path.parse(filename).name, { pascalCase: true, }); 
            const componentName = `Svg${pascalCaseFilename}`; 
            return { code: `const React = require('react')...` // pretty long string }; 
        }

        return {code: `module.exports = ${assetFilename};` }; 
    }, 
};

Note: As of the time of writing, the error message link to the upgrade guide tutorial doesn't work, but you can find the correct link at https://jest-archive-august-2023.netlify.app/docs/28.x/upgrading-to-jest28/. There's also an older archive link if that doesn't work.

How to Bump Jest to 29

Once all the validation steps are working with Jest 28, the upgrade to 29 should be smoother. Just update your package.json and run $ yarn install:

... 
"devDependencies": { ... 
    "babel-jest": "^29.7.0", 
    "jest": "^29.7.0", 
    "jest-circus": "^29.7.0", 
    "jest-resolve": "^29.7.0", 
    "jest-environment-jsdom": "^29.7.0" ... 
} 
...

At this point, $ yarn test should work correctly with your existing test suite.

How Far Should I Upgrade NodeJS?

Trying to decide how far ahead to upgrade Node versions can be a tricky question. Following the above steps, I was able to get all the Node versions up until the most recent Node 22 working.

At the time of writing, 18 is a pretty good stopping point in terms of current support and recent ECMAScript support. But if you're looking to decide, then the following three factors are the most important:

1. Library support: Look at all your critical libraries and see if they have a strong preference for a certain version or have breaking issues for more recent versions. Later Node versions are usually better, but sometimes old libraries didn't get the right patches and might block your upgrade.
2. Support windows: Different Node versions have a window where the maintainers consider it under "Maintenance", "Active", "Current" or "Unsupported", and over time the older versions lose maintenance. The even versions are also designated LTS (Long Term Support), giving support for a long time and what works for most people. The website has a helpful chart for this: https://nodejs.org/en/about/previous-releases.
3. Language feature support: ECMAScript's specification is always evolving with every year, and getting to use the newer syntax with nicer constructs is always a big quality of life upgrade. I love https://node.green/ which has a table of Node versions against ECMAScript syntax features with code examples for each feature.

Due to technologies like Babel (bundled with Create React App), you don't need to worry too much about the end users of your website, as newer Node features will just get transpiled to browser-compliant ones.

Should You Still Use Create React Scripts? What Alternatives Are There?

In this tutorial, I decided to eject out of CRA to access the Webpack and Babel configuration, and many CRA projects have eventually come to do this as well. Maintenance of CRA has nearly stopped while the ecosystem keeps evolving.

Personally, I recommend someone creating a React project today to try newer alternatives like Vite or Parcel which have a nice starter applications that are simple and easier to understand. Unfortunately, they might not have as many bells and whistles as what CRA gives, but it's good enough for almost all practical modern development.

In the context of education, my old tutorials used create-react-app, and it was such a major help, but my newer ones will use Vite.

Still, your application and development experience might be very different than mine. I recommend reading and learning from these resources to form your own perspective:

• GitHub issue with 200+ responses and 1000s of reactions on if Create React App should be replaced with Vite on the official docs. It also has a note from the maintainer side of CRA explaining a lot of important context that is highly worth reading. Parcel's maintainer made a really good comment as well.
• Some interesting comments (one, two) on how CRA created a simple and easy to use React experience out of the box without worrying about setup hell and focusing on the actual application.
• News article explaining that the React Team has chosen to stop recommending Create React App, along with some context behind this and future alternatives.

Conclusion

At this point, you should be able to run all your validation scripts and have an application that works with Node 18+ and Jest 29+.

In an ideal world, you'd run into the same hurdles as I did, and everything would be working. Realistically, everyone's application is different, and the internet is full of numerous developers who have gone through this upgrade process with various issues.

I highly suggest making Google, StackOverflow, GitHub, and official library documentation your best friends in the process, and I wish you good luck!

Alternatively: How to Upgrade to React Scripts 5.0.1

This is beyond the scope of this tutorial, so I'll be briefer here – but here's a little information to get you started.

I suggest starting with the official docs changelog for CRA v5 that includes all the major changes as well as some version upgrade instructions: https://github.com/facebook/create-react-app/blob/main/CHANGELOG.md.

Bumping the version is fairly easy, setting react-scripts to 5.0.1 in your package.json, but then the hard part is all the breaking changes.

The most complicated part of the upgrade is the upgrade to Webpack 5 from Webpack 4. Read Webpack's official guide To v5 from v4 which has a nice overview, and look around the internet for guides for this upgrade. A few more hurdles that you might come across:

• For @babel/helper-compilation-targets: 'opera_mobile' is not a valid target you can add "not op_mob >= 1" to the browserslist array as suggested by this comment on the babel issue tracker. The other comments may also be helpful.
• You'll probably have to access the CRA internals for many steps using either React Scripts eject or something like CRACO version 7.
• Webpack 5 has a breaking change which removes support for a lot of browser specific APIs like os, http, util that worked in Webpack 4 that your application may have been using. You can either add all of them back using a package like node-polyfill-webpack-plugin or add imports piecewise following this cheatsheet.
• For Babel eslint parser load errors like Error: Failed to load parser 'babel-eslint' declared in '.eslintrc': Cannot find module 'babel-eslint' , you might have to swap out "parser": "babel-eslint" with "parser": "@babel/eslint-parser" in your .eslintrc and install "@babel/eslint-parser" in your package.json. This might be caused by the move of babel-eslint to the @babel monorepo, see The State of babel-eslint for more info.
• Some filetype imports that used to work with Webpack 4 will start breaking with Module build failed: UnhandledSchemeError (the actual error took several screens in my Terminal). The solution here will be fixing the prefixes of the files you import, and for external files that were being included, see if you can find a npm package for it. For example, one of my projects stopped using semantic-ui.min.css downloaded from the internet, and instead I added "semantic-ui-css": "^2.5.0" to my package.json. Definitely read this issue thread in the webpack repo for more information.

After all of these I was able to get yarn test and yarn build to succeed, but yarn start still had too many issues and I pivoted to making CRA v4 work instead. Hopefully you might get further than I did.

In this tutorial, we will build a button that tracks the number of times a button has been clicked. Along the way, you will learn some fundamental concepts in React such as components, JSX, passing props between components, and managing state with hooks. You will also get small introductions to Tailwind and TypeScript.

This tutorial builds upon examples and concepts outlined in the "Learn" section of the React documentation, which you can find here.

Prerequisites

• Basic familiarity with JavaScript, such as working with variables, functions, arrays, and objects.
• Basic familiarity with CSS and HTML.
• Basic familiarity with the command line.
• Node installed.
• A code editor of your choice (I'll be using Visual Studio Code here)

Table of Contents

1. How to Build the Counter Button
2. How to Refactor the Project
3. Two Components with Independent and Shared State
4. How to Add Both Pairs of Buttons to our Website
5. How to Deploy the Site to Netlify

Chapter 1: How to Build the Counter Button

What is React?

Before we dive in, let's define React. React is a JavaScript library for creating user interfaces out of pieces called components. Components are JavaScript functions that can receive and display data interactively to your users.

Project setup

We're going to use Next.js for our local React setup.

Within the directory you'd like to store this project, open your terminal and execute the following command:

npx create-next-app@latest

Name your project however you like, and answer the commands as follows:

What is your project named? react-counter-button
Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like to use `src/` directory? No
Would you like to use App Router? (recommended) Yes
Would you like to customize the default import alias (@/*)? No

Now let's cd into our project directory

cd react-counter-button

And run the project in Visual Studio Code:

code .

Note: if you don't have the code command in your PATH, you can press ⇧⌘P (Ctrl+Shift+P on Windows/Linux) and type in 'Shell Command: Install 'code' command in PATH'. Alternatively, you can drag the folder onto the Visual Studio Code icon in MacOS. Or, within Visual Studio Code, you can select File -> Open, and find "react-counter-button", or the name of your project.

In your terminal run:

npm run dev

Open your browser to localhost:3000 and you should see the following page:

Next.js boilerplate

We now have the project up and running. Back over in our code editor, we can begin the work.

Remove boilerplate

In app/page.tsx, let's delete most of the boilerplate code except the two main tags. Then let's add a title for our project in an h1 tag in between the main tags. Our code should look like this:

export default function Home() {
    return (
        <main className="flex min-h-screen flex-col items-center justify-between p-24">
            <h1>React Counter Button</h1>
        </main>
    );
}

Here's what we should now see:

Initial state of our project

Writing our first component

Let's create our first component. A React component is a function that returns markup. Below and outside of the scope of our Home function, let's write the following:

function Button() {
    return <button>I have been clicked X times</button>;
}

Here we have a function Button that returns some markup in JSX. JSX looks a lot like HTML, but it can display dynamic content, and has stricter rules than HTML. You can learn more about JSX in the React docs here.

The Button function must be uppercase to be recognized as a valid React component. This contrasts it with an HTML tag, which is lower case.

You'll notice that we still see no change on our webpage – we need to render this component in order to see it on the screen.

We can use our Button component as if it were an HTML tag we created. If we nest the Button component within the Home component, we should see it on the screen:

export default function Home() {
    return (
        <main className="flex min-h-screen flex-col items-center justify-between p-24">
            <h1>React Counter Button</h1>
            <Button />
        </main>
    );
}

function Button() {
    return <button>I have been clicked X times</button>;
}

Rendering the Button component (with less than ideal CSS)

Styling our first component with Tailwind

You'll notice the button is on the bottom of the screen. This is because the styles on main include justify-between in the flex-col direction. If we remove justify-between we should see this:

Improving the CSS of the initial state of our application

You can read more about aligning items in a flexbox from MDN here.

You'll also notice that the button is un-styled. This is because Tailwind removes default styling on buttons as a part of their "preflight" styles. If you're curious to see where these styles come from, you can open node_modules/tailwindcss/src/css/preflight.css and check out ~line 193 (permalink on GitHub here):

/*
1. Correct the inability to style clickable types in iOS and Safari.
2. Remove default button styles.
*/

button,
[type='button'],
[type='reset'],
[type='submit'] {
  -webkit-appearance: button; /* 1 */
  background-color: transparent; /* 2 */
  background-image: none; /* 2 */
}

We're not going to change the styles within node_modules – instead we'll add our own styling to the Button component. One of the benefits of Tailwind is that our CSS is co-located with our JavaScript, making quick changes to styles easier than opening a separate stylesheet file.

Let's make the following changes:

export default function Home() {
    return (
        <main className="flex min-h-screen flex-col items-center p-24 gap-4">
            <h1>React Counter Button</h1>
            <Button />
        </main>
    );
}

function Button() {
    return (
        <button className="bg-blue-500 hover:bg-blue-700 rounded text-white font-bold px-4 py-2">
            I have been clicked X times
        </button>
    );
}

We've added styles to our button, and we've also added a gap-4 to our main parent flex box to provide a space between the h1 and the button. (You can read more about the CSS property "gap" in the MDN here.) We should now see this:

Viewing our styled Button component

Wait, but what is Tailwind?

Now that we've styled our button component and spaced the items out, let's reflect on what Tailwind is, and what it provided for us. Tailwind is a CSS framework that provides a set of "utility" classes that we can use to style each element.

But what is a utility class? You'll see that to style our button, we added classes such as bg-blue-500 – which corresponds to setting the CSS background-color property to blue, and rounded – which corresponds to border-radius: 0.25rem.

Each class is defined according to its utility: changing the background color, the border radius, and so on. Through adding these utility classes to our elements, we arrive at our desired styles.

Tailwind sits in contrast to other frameworks, such as Bootstrap, that provide predefined classes for elements such as buttons. In Bootstrap, we would add a class of btn to achieve a styled button. And of course, with standard CSS we would likely add a custom class (perhaps called button) to our element and create CSS rulesets in a separate stylesheet.

Returning to our project, so far we've set up a React project using Next.js, created our first React component, and styled our button using Tailwind. How do we introduce the counter functionality?

How to add state

In order to display the number of times a button has been clicked, we need to use an event handler, and we need a way to manage state.

State is component-specific memory. In our example, this is how the button will remember how many times it has been clicked. Using a special React function "hook", we trigger a re-render and retain the data across renders – the [useState](https://react.dev/reference/react/useState) hook is provided by React for this purpose.

At the top of our page.tsx, let's import useState:

import { useState } from "react"

and within our Button component, let's add the following:

function Button() {
  const [count, setCount] = useState(0)
    return (
        <button className="bg-blue-500 hover:bg-blue-700 rounded py-2 px-4 text-white font-bold">
            I have been clicked X times
        </button>
    );
}

Let's unpack what we have here:

• We're using the destructuring assignment to get the values of count and the function setCount from useState. The convention is to name these two values something and setSomething, though we could name them anything.
• The argument to useState is the initial value of our state variable. Here we've set it to 0.
• count is our current state.
• setCount is the function that updates our state and triggers a re-render.

However, if you click save you'll see the following error in your terminal and in your browser:

You're importing a component that needs useState. It only works in a Client Component but none of its parents are marked with "use client", so they're Server Components by default.
Learn more: https://nextjs.org/docs/getting-started/react-essentials

   ╭─[/[...your project path]/src/app/page.tsx:1:1]
 1 │ import { useState } from "react";
   ·          ────────
 2 │ 
 3 │ export default function Home() {
 4 │     return (
   ╰────

Maybe one of these should be marked as a client entry with "use client":
  ./src/app/page.tsx

This is due to Next.js's use of React Server Components, which you can learn more about here. React Server Components is a large topic, but the bottom line is that, by default, components are Server Components in Next.js and useState only works in a Client Component. If we write the "use client" directive at the top of our page.tsx, we resolve the error.

How to Evaluate JavaScript within JSX

If we click the button, we still don't see the numbers update. This is because we need a way to interpolate (or evaluate) JavaScript within our JSX markup. Enter the curly braces: {}.

We can use curly braces to "escape" into JavaScript from within JSX markup. This way we can evaluate JavaScript expressions (such as adding to a counter) and dynamically display data in our components. Here's what we'll do:

function MyButton() {
    const [count, setCount] = useState(0);
    return (
        <button className="bg-blue-500 hover:bg-blue-700 rounded py-2 px-4 text-white font-bold">
            I have been clicked {count} times
        </button>
    );
}

We have added {count} to evaluate the value of count from useState within our button. We should see the following:

Displaying data in JSX with curly braces {}

We see a 0 – this comes from the count variable that we destructured from our useState hook, which we initially set to 0. We've successfully interpolated the JavaScript within our JSX markup!

Event handling

You'll notice that if we click the button, still nothing happens. How do we get the number to increment when we click it?

For this, we'll make use of an event handler function as well as the setter function (which we named setCount) that we get from useState:

function MyButton() {
    const [count, setCount] = useState(0);

    function handleClick() {
        setCount(count + 1);
    }
    return (
        <button className="bg-blue-500 hover:bg-blue-700 rounded py-2 px-4 text-white font-bold">
            I have been clicked {count} times
        </button>
    );
}

What we've done here is add a function handleClick to update the state of the count variable. The convention is to name event handler functions handle followed by the name of your event (for example, handleClick).

[setCount](https://react.dev/reference/react/useState#setstate) is a special set function returned by useState that will update the state of the count variable to whatever we pass in as an argument. For example, we could call setCount(2), and it would update count to 2. setCount(7) would set it to 7, and so on.

We are calling setCount(count + 1), which evaluates to setCount(0 + 1), because the initial value of count is 0. Upon the next click, count will be 1, so we'd be calling setCount(1 + 1), and the next click would call setCount(2 + 1) and so on.

This allows us to update the counter with every click. But, if you click, you'll notice that still nothing happens – why? Perhaps take a moment to try to figure this out for yourself before reading on to help the concept stick even better.

How to Pass an Event Handler as a Prop to Your JSX

Looking at our code, there is no relationship between the user clicking the button, and the handleClick function. We need to pass the handleClick event handler to the onClick property on the button! Let's add that here:

function MyButton() {
    const [count, setCount] = useState(0);

    function handleClick() {
        setCount(count + 1);
    }
    return (
        <button
            onClick={handleClick}
            className="bg-blue-500 hover:bg-blue-700 rounded py-2 px-4 text-white font-bold"
        >
            I have been clicked {count} times
        </button>
    );
}

Notice how we haven't said onClick={handleClick()}. We aren't calling the function ourselves here – we are instead passing it down. This is an important distinction, as React calls the function for us when the user clicks the button, instead of it firing immediately.

You can learn more about passing props to components in the React docs here.

Our working project

Try it out now, the button works!

You now have a button that updates its count when you click it. This shows usage of interpolating JavaScript within JSX using curly braces, creating your own component and nesting it within other components, using state and hooks within React, as well as working with Next.js and Tailwind. Congratulations!

Our working project

Here would be a good point to commit our changes using Git. You can close the current terminal process by pressing ctrl + c, and then type in git add ., followed by git commit -m "counter button" or some other message that is meaningful.

Chapter 2: How to Refactor the Project

Moving our component to another file

As our project sits, all the code is within app/page.tsx. What if we wanted to add another component, or several? Over time, our page.tsx would get large and difficult to read.

Instead, we can break our components up into their own files to help with readability as well as modularity (reusing the component in multiple different places).

Let's start by creating a folder components at the root of our project to store our components. Inside components, create a file called button.tsx. Then, within app/page.tsx cut (copy and then delete) the entire Button function component and paste it within components/button.tsx.

components/button.tsx should look like this:

function Button() {
    const [count, setCount] = useState(0);

    function handleClick() {
        setCount(count + 1);
    }
    return (
        <button
            onClick={handleClick}
            className="bg-blue-500 hover:bg-blue-700 rounded text-white font-bold px-4 py-2"
        >
            I have been clicked {count} times
        </button>
    );
}

Fix the useState import error

You'll likely notice in your code editor that useState(0) has red squiggly lines underneath it. In Visual Studio Code, if you hover over it, you will see an error that says:

Error: cannot find name 'useState'

Why is this? We are using useState but we have not imported the module from React. Adding import { useState } from "react"; to the top of our button.tsx file will fix this error.

If you look at the beginning of the function, you'll see that Button() is underlined with white lines in Visual Studio Code. Hovering over it will show this error. Reflect on why this might be the case – we'll address this later.

Error: 'Button' is declared but its value is never read

Importing and Exporting Components

Let's return to app/page.tsx . You'll see two errors here: one on import { useState } from "react"; and another on <Button />.

Let's address the useState error first. We used useState within our Button component, but now that we've moved that component to its own file, we no longer it. Deleting it will solve our error. You can use cmd (ctrl on Windows) + shift + k to delete the entire line in Visual Studio Code.

If you've saved your app/page.tsx you will see this error in the console:

 ⨯ app/page.tsx (7:14) @ Button
 ⨯ ReferenceError: Button is not defined
    at Home (./app/page.tsx:19:89)
digest: "2129895745"
   5 |         <main className="flex min-h-screen flex-col items-center p-24 gap-4">
   6 |             <h1>React Counter Button</h1>
>  7 |             <Button />
     |              ^
   8 |         </main>
   9 |     );
  10 | }
 GET / 500 in 87ms

Why wouldn't Button be defined? The issue is that within our app/page.tsx we have no way to access the Button component over in components/button.tsx. We solve this by exporting and importing the appropriate module.

Within components/button.tsx, at the beginning of our function declaration, let's add the keywords export default. The file will look like this now:

import { useState } from "react";

export default function Button() {
    const [count, setCount] = useState(0);

    function handleClick() {
        setCount(count + 1);
    }
    return (
        <button
            onClick={handleClick}
            className="bg-blue-500 hover:bg-blue-700 rounded text-white font-bold px-4 py-2"
        >
            I have been clicked {count} times
        </button>
    );
}

You'll notice that our earlier error of 'Button' is declared but its value is never read has gone away, because now the value is being read as a default export.

But what have we done here? What is an export, or a default export? Exporting and importing allows us to modularize JavaScript components into their own sections and use them in others.

There are two types: default exports, and named exports. Each file can have multiple named exports but only one default export. You can read more about importing and exporting components the React documentation here.

Now that we have exported the component from components/button.tsx, we have to import it within app/page.tsx. Visual Studio Code can help with "intellisense" suggestions: at the top of your file if you start typing "Button", it will suggest the correct import with the correct filepath:

import Button from "@/components/button";

Within Next.js we can use this @/ syntax to reference the root of the project. This is a convenience added in case our import is several file layers deep. You can read the examples of the @/ syntax in the Next.js documentation here.

You'll see that our errors have disappeared and the project still works! We haven't added any new features but we have successfully refactored our code to make it more modular, readable, and maintainable.

Here let's follow the same steps to commit our changes, adding a message such as refactor: move button to its own file.

Chapter 3: Two Components with Independent and Shared State

Two Components with Independent State

What if we wanted to have two buttons that can count independently of each other? This will showcase the beauty of React and component-based development implementation will be simpler than building the button from scratch entirely again.

Within app/page.tsx we can simply add another <Button />. You can focus your cursor on <Button /> and press option + shift + ↓ to create another <Button />:

"use client";

import Button from "@/components/button";

export default function Home() {
    return (
        <main className="flex min-h-screen flex-col items-center p-24 gap-4">
            <h1>React Counter Button</h1>
            <Button />
            <Button />
        </main>
    );
}

You should now see two button counters with their own independent state:

Two buttons with independent state

Component-based design with React makes re-using parts of your application easy. Easy win.

Two Components with Shared State

What if we wanted the buttons to share their state and update together? You'll notice that as we click each button, they separately increment.

In order for the buttons to share their state, we will need to move their state from each individual components "upward" to their common parent component (in this case, the Home function in app/page.tsx). You'll also hear this referred to as "lifting state up".

Cut the counting logic from components/button.tsx and paste it into app/page.tsx within the body of the Home function. We will also need our useState import at the top of the file:

"use client";

import { useState } from "react";

import Button from "@/components/button";

export default function Home() {
    const [count, setCount] = useState(0);

    function handleClick() {
        setCount(count + 1);
    }
    return (
        <main className="flex min-h-screen flex-col items-center p-24 gap-4">
            <h1>React Counter Button</h1>
            <Button />
            <Button />
        </main>
    );
}

Passing Props Down to a Component

Now that we have our state in the parent component of each button (Home), we can pass this state down via props to the Button component. We will want to pass down both the event handler handleClick as well as the count variable we wish to display:

"use client";

import { useState } from "react";

import Button from "@/components/button";

export default function Home() {
    const [count, setCount] = useState(0);

    function handleClick() {
        setCount(count + 1);
    }
    return (
        <main className="flex min-h-screen flex-col items-center p-24 gap-4">
            <h1>React Counter Button</h1>
            <Button count={count} onClick={handleClick} />
            <Button count={count} onClick={handleClick} />
        </main>
    );
}

The count from useState is passed to the count prop, and the function handleClick is passed to the onClick prop, both on the Button component. In JSX, we can define our own props (which might remind you of HTML attributes) so that we can pass data from one component to another.

You might see some errors related to TypeScript at this point – we will come back to these later.

Read Props in Your Child Component

Now that we have passed the data as props to our component, we need to adjust our Button component to read the props from its parent component. Within components/button.tsx:

export default function Button({ count, onClick }) {
    return (
        <button
            onClick={onClick}
            className="bg-blue-500 hover:bg-blue-700 rounded text-white font-bold px-4 py-2"
        >
            I have been clicked {count} times
        </button>
    );
}

React function components accept a single props object as an argument. Here we destructure the props that we want to pass into our Button component. In other words, we are taking count, and onClick from the props object directly, as an argument to Button.

If you save your file you'll see that this now works: you have two buttons with shared state:

Two buttons with shared state

But why did we pass onClick and not handleClick to the Button component? Isn't handleClick what we want to run when we click the button?

Within the Home component in app/page.tsx, we define handleClick and pass it down as a prop to the Button component. Within the Button component's body in components/button.tsx we read the prop onClick, not the event handler handleClick itself. So when the Button component fires, it calls the onClick prop, which sits "up" the component tree inside Home, where it then calls handleClick, updates the count, and then passes that state back down to both Button components.

Tiny Crash Course in TypeScript

If you check components/button.tsx you will see the following errors for both the count and onClick props you are reading into Button:

Binding element 'count' implicitly has an 'any' type.

(You can get these "pretty" TypeScript syntax-highlighted errors with the Visual Studio Code extension here).

What do these errors mean, and what is TypeScript? TypeScript is a superset of JavaScript that adds types to JavaScript. These can help ensure that our program works as we intend. Examples of types are number, boolean, and string. This error is telling us that we haven't defined a type for the props count or onClick.

So what will the type of count be? If we consider the result of count, the answers could be 1, 2, 3, and so on. These are all numbers, so we will assign the type number to count.

The onClick prop is a function that doesn't take any arguments or return any value – we use it for its side effect of updating setCount. So we assign it the type () => void.

We create an interface where we define the types for our ButtonProps, and then read this interface into our component:

interface ButtonProps {
    count: number;
    onClick: () => void;
}

export default function Button({ count, onClick }: ButtonProps) {
    return (
        <button
            onClick={onClick}
            className="bg-blue-500 hover:bg-blue-700 rounded text-white font-bold px-4 py-2"
        >
            I have been clicked {count} times
        </button>
    );
}

The errors are gone and there you have it: a tiny intro to TypeScript!

Here let's make another commit with a message such as buttons with shared state.

Chapter 4: How to Add Both Pairs of Buttons to Our Site

Let's showcase both our buttons with shared and independent state, and deploy the application.

Let's rename our button.tsx to button-shared-state.tsx. Let's also rename the function, the interface, the import within app/page.tsx, as well as the component in app/page.tsx. And let's switch these to named exports using a function expression using const instead of a function declaration:

interface ButtonSharedStateProps {
    count: number;
    onClick: () => void;
}

export const ButtonSharedState = ({
    count,
    onClick,
}: ButtonSharedStateProps) => {
    return (
        <button
            onClick={onClick}
            className="bg-blue-500 hover:bg-blue-700 rounded text-white font-bold px-4 py-2"
        >
            I have been clicked {count} times
        </button>
    );
};

"use client";

import { useState } from "react";

import { ButtonSharedState } from "@/components/button-shared-state";

export default function Home() {
    const [count, setCount] = useState(0);

    function handleClick() {
        setCount(count + 1);
    }
    return (
        <main className="flex min-h-screen flex-col items-center p-24 gap-4">
            <h1>React Counter Button</h1>
            <ButtonSharedState count={count} onClick={handleClick} />
            <ButtonSharedState count={count} onClick={handleClick} />
        </main>
    );
}

Now let's create a file components/button-independent-state.tsx:

"use client";
import { useState } from "react";

export const ButtonIndependentState = () => {
    const [count, setCount] = useState(0);

    function handleClick() {
        setCount(count + 1);
    }

    return (
        <button
            className="bg-blue-500 hover:bg-blue-700 rounded text-white font-bold py-2 px-4"
            onClick={handleClick}
        >
            I have been clicked {count} times
        </button>
    );
};

What we've done here is similar to our logic in the beginning of this guide: we've located the state within the button component itself, so that each implementation of the button component creates and tracks its own independent state.

Let's import ButtonIndependentState into app/page.tsx:

"use client";

import { useState } from "react";

import { ButtonSharedState } from "@/components/button-shared-state";
import { ButtonIndependentState } from "@/components/button-independent-state";

export default function Home() {
    const [count, setCount] = useState(0);

    function handleClick() {
        setCount(count + 1);
    }
    return (
        <main className="flex min-h-screen flex-col items-center p-24 gap-4">
            <h1 className="text-3xl font-bold">React Counter Buttons</h1>
            <h2 className="text-xl">Buttons with shared state</h2>
            <ButtonSharedState count={count} onClick={handleClick} />
            <ButtonSharedState count={count} onClick={handleClick} />
            <h2 className="text-xl">Buttons with independent state</h2>
            <ButtonIndependentState />
            <ButtonIndependentState />
        </main>
    );
}

We have now showcased a set of buttons that have independent state, as well as buttons that have shared state. We added a tiny bit of CSS to make things look nicer as well.

Our finished project

Here let's add another commit with a message such as buttons with both shared and independent state.

Chapter 5: How to Deploy the Site to Netlify

Publish to GitHub

Let's deploy our application to the world to show it off. We are going to push our code to GitHub, and then deploy it to Netlify.

The first step is push our code to GitHub. If you don't have a GitHub account, create one first. In Visual Studio Code, you can push to GitHub from the command palette: open up the command palette by pressing ⇧⌘P , then type in publish to GitHub, and select publish to public GitHub repository.

Open your GitHub account and verify that the project has successfully been uploaded.

Deploy to Netlify

Once you've uploaded your project to GitHub, you can now deploy it to Netlify. Open up the Netlify website, and log in (or create an account if you don't have one).

Click add new site, and then import an existing project. When asked Let’s deploy your project with…, select GitHub.

Select the name of your repository from the list, then give the site a name under site name. You can leave the rest of the settings at their defaults and then click deploy [your site name].

If the project builds successfully, you will have a live link of your work!

Concluding Thoughts and Next Steps

In this project, you have learned fundamental concepts in React such as creating a functional component, importing and exporting modules, interpolating JavaScript within JSX using curly braces, working with state, and using React hooks.

You've also seen an introduction to using utility-based CSS techniques with Tailwind CSS, and you've gotten a tiny introduction into adding types to your JavaScript with TypeScript. Finally, you learned how to deploy your project to Netlify via GitHub.

Where can you go from here? One idea for expanding the project could be to create a "ticker": a counter that could be incremented and decremented (you would have one button that increases the number of the counter, and one that decreases it).

In the name of learning, one effective method for solidifying the concepts you've learned here would be to start a project completely fresh, and see if you can build everything in this tutorial without checking the tutorial. As you need to check in, you will identify which concepts benefit from further study and practice.

If you'd like to stay in touch, you can:

• Follow me on Twitter
• Follow me on LinkedIn

Please post about what you've made along with any questions or feedback you might have.

Happy coding!

By introducing a unidirectional data flow, Redux brings order and clarity to how data updates and interacts within your React components.

This article discusses the inner workings of Redux, specifically focusing on how data flows throughout your application. We'll explore core concepts like the Redux store, actions, reducers, and selectors, along with practical examples of how they work together to seamlessly manage your application state.

Table of Contents

1. What is Redux?
2. Why Use Redux for Data Management?
3. Core Concepts of Redux Data Flow
4. Unidirectional Data Flow
5. Benefits of Unidirectional Data Flow
6. State Management with Redux Store
7. What is the Redux Store?
8. Store Structure (State, Reducers, Actions)
9. Actions: Initiating State Changes
10. Action Creators (Functions to Create Actions)
11. Action Types (Identifying Different Actions)
12. How to Process State Changes
13. Pure Functions: Reducers at the Core
14. Characteristics of Pure Functions
15. Anatomy of a Reducer Function
16. Parameters: Previous State and Action Object
17. Return Value: Updated State
18. How to Handle Different Actions in Reducers
19. Using Switch Statements or Conditional Logic
20. Dispatching Actions: How to Update the Redux Store
21. The dispatch Function
22. Dispatching Actions from Components or Events
23. How to Access Specific Data from the Store
24. Creating Selector Functions
25. Memoization for Efficient Selector Usage
26. How to Connect React Components to Redux
27. The connect Function from react-redux Library
28. Mapping State and Dispatch to Props
29. Using Connected Components in Your Application
30. Advanced Redux Data Flow Techniques
31. Asynchronous Actions (Redux Thunk, Redux Saga)
32. Middleware for Extending Redux Functionality
33. Best Practices for Managing Data Flow in Redux
34. Conclusion

What is Redux?

Redux is a predictable state container for JavaScript applications, primarily used with libraries like React. It helps manage the application state in a centralized store, making it easier to manage and update state across your entire application.

In simple terms, Redux provides a way to store and manage the data that your application needs to work. It follows a strict pattern to ensure that state changes are predictable and manageable.

Why Use Redux for Data Management?

Using Redux for data management in your application offers several advantages:

Centralized State Management: Redux stores the application's state in a single store, making it easier to manage and debug compared to having scattered state across multiple components.

Predictable State Changes: State mutations are done through reducers, which are pure functions. This ensures that state changes are predictable and traceable, making it easier to understand how data flows through your application.

Easier Debugging: With a single source of truth, debugging becomes simpler. You can log state changes, track actions, and even implement time-travel debugging (via Redux DevTools) to replay actions and inspect state at any point in time.

Facilitates Testing: Since reducers are pure functions that depend only on their input and produce predictable output, testing becomes straightforward. You can easily test how reducers update the state in response to different actions.

Enforces Unidirectional Data Flow: Redux follows a strict unidirectional data flow pattern. Data flows in one direction: actions are dispatched, reducers update the state immutably, and components subscribe to the changes they're interested in. This pattern simplifies data management and reduces bugs related to inconsistent state.

Eases State Persistence: Redux makes it easier to persist your application state across sessions or store it locally, enhancing the user experience by preserving data between visits.

Scalability: Redux scales well with large applications because of its centralized state management. As your application grows, managing state becomes more manageable and less error-prone compared to using local component state or prop drilling.

Core Concepts of Redux Data Flow

Understanding the core concepts of Redux data flow is essential for mastering state management in modern JavaScript applications.

Unidirectional Data Flow

Redux follows a strict unidirectional data flow pattern, which means that data in your application moves in a single direction through a series of steps:

1. Actions: Actions are plain JavaScript objects that represent an intention to change the state. They are the only source of information for the store.
2. Reducers: Reducers are pure functions responsible for handling state transitions based on actions. They specify how the application's state changes in response to actions sent to the store.
3. Store: The store holds the application state. It allows access to the state via getState(), updates the state via dispatch(action), and registers listeners via subscribe(listener).
4. View: React components (or any other UI layer) subscribe to the store to receive updates when the state changes. They then re-render based on the updated state.

Here’s a simplified overview of how the unidirectional data flow works in Redux:

1. Action Dispatch: Components dispatch actions to the Redux store using store.dispatch(action). Actions are plain JavaScript objects with a type field that describes the type of action being performed.
2. Action Handling: The store passes the dispatched action to the root reducer. The reducer is a pure function that takes the current state and the action, computes the new state based on the action, and returns the updated state.
3. State Update: The Redux store updates its state based on the return value of the root reducer. It notifies all subscribed components of the state change.
4. Component Re-render: Components that are subscribed to the store receive the updated state as props. They re-render with the new data.

Benefits of Unidirectional Data Flow

Predictability: By enforcing a single direction for data flow, Redux makes state changes more predictable and easier to understand. Actions are explicit about what changes are happening, and reducers clearly define how the state transitions occur.

Debugging: Unidirectional data flow simplifies debugging because you can trace how state changes propagate through your application. Redux DevTools enhance this further by allowing you to track actions, inspect state changes over time, and even replay actions to reproduce bugs.

Maintainability: With a clear separation between data (state) and logic (reducers), Redux promotes cleaner, more maintainable code. It reduces the likelihood of bugs caused by inconsistent state mutations or side effects.

Scalability: As your application grows in size and complexity, unidirectional data flow helps manage state updates more effectively. It avoids the pitfalls of two-way data binding and ensures that changes to the state are controlled and manageable.

Testing: Since reducers are pure functions that take inputs and produce outputs without side effects, unit testing becomes straightforward. You can test reducers with different actions and state scenarios to ensure they behave as expected.

State Management with Redux Store

State management plays a pivotal role in modern web development, ensuring applications maintain consistent and predictable states across various components.

What is the Redux Store?

The Redux Store is the heart of Redux state management. It holds the entire state tree of your application. The store allows you to:

• Access the current state of your application via store.getState().
• Dispatch actions to change the state using store.dispatch(action).
• Subscribe to changes in the state so your components can update accordingly using store.subscribe(listener).

In essence, the Redux Store acts as a centralized repository for the state of your application, facilitating predictable data flow and making state management more manageable.

Store Structure (State, Reducers, Actions)

The state in Redux represents the entire state of your application. It is typically structured as a plain JavaScript object. The shape of the state is defined by the reducers. For example:

const initialState = {
  todos: [],
  visibilityFilter: 'SHOW_ALL',
};

In this example, todos and visibilityFilter are pieces of state managed by Redux.

Reducers are functions that specify how the application's state changes in response to actions dispatched to the store. They take the current state and an action as arguments, and return the new state based on the action type.

Reducers must be pure functions, meaning they produce the same output for the same input and do not modify the state directly.

const todosReducer = (state = [], action) => {
  switch (action.type) {
    case 'ADD_TODO':
      return [
        ...state,
        {
          id: action.id,
          text: action.text,
          completed: false
        }
      ];
    case 'TOGGLE_TODO':
      return state.map(todo =>
        (todo.id === action.id)
          ? { ...todo, completed: !todo.completed }
          : todo
      );
    default:
      return state;
  }
};

In this example, todosReducer manages the todos piece of state, handling actions like 'ADD_TODO' and 'TOGGLE_TODO' to add new todos or toggle their completion status.

Actions are plain JavaScript objects that describe what happened in your application. They are the only source of information for the store. Actions typically have a type field that indicates the type of action being performed, and they may also carry additional data necessary for the action.

const addTodo = (text) => ({
  type: 'ADD_TODO',
  id: nextTodoId++,
  text
});

const toggleTodo = (id) => ({
  type: 'TOGGLE_TODO',
  id
});

In this example, addTodo and toggleTodo are action creator functions that return actions to add a new todo and toggle the completion status of a todo, respectively.

The relationship between these elements in Redux is crucial for managing application state effectively:

• Actions describe events that occur in your application.
• Reducers specify how the application's state changes in response to actions.
• Store holds the application state and allows you to dispatch actions to update the state.

Together, these components form the core structure of Redux state management, providing a clear and predictable way to manage and update application state across your entire application.

Actions: Initiating State Changes

Managing state effectively lies at the core of creating dynamic and responsive applications. Actions, within the Redux architecture and similar state management libraries, serve as important elements for initiating state changes.

Action Creators (Functions to Create Actions)

Action creators in Redux are functions that create and return action objects. These action objects describe what happened in your application and are dispatched to the Redux store to initiate state changes.

Action creators encapsulate the logic of creating actions, making your code more modular and easier to test.

Here's an example of an action creator:

// Action creator function
const addTodo = (text) => ({
  type: 'ADD_TODO',
  id: nextTodoId++,
  text
});

// Usage of the action creator
const newTodoAction = addTodo('Buy groceries');

In this example:

• addTodo is an action creator function that takes text as a parameter and returns an action object.
• The action object has a type field ('ADD_TODO') that identifies the type of action and additional fields (id and text) that provide necessary data for the action.

Action creators simplify the process of creating actions, especially when actions require complex data or calculations before dispatching.

Action Types (Identifying Different Actions)

Action types in Redux are string constants that define the type of action being performed. They are used to identify and differentiate different actions that can be dispatched to the Redux store. By using string constants for action types, Redux ensures that action types are unique and easy to reference throughout your application.

Here's how action types are typically defined:

// Action types as constants
const ADD_TODO = 'ADD_TODO';
const TOGGLE_TODO = 'TOGGLE_TODO';
const SET_VISIBILITY_FILTER = 'SET_VISIBILITY_FILTER';

These constants (ADD_TODO, TOGGLE_TODO, SET_VISIBILITY_FILTER) represent different actions that can occur in your application, such as adding a todo, toggling the completion status of a todo, or setting a visibility filter for todos.

Action types are typically used in action objects created by action creators and are matched in reducers to determine how the state should change in response to each action.

// Example of using action types in a reducer
const todosReducer = (state = [], action) => {
  switch (action.type) {
    case ADD_TODO:
      return [
        ...state,
        {
          id: action.id,
          text: action.text,
          completed: false
        }
      ];
    case TOGGLE_TODO:
      return state.map(todo =>
        (todo.id === action.id)
          ? { ...todo, completed: !todo.completed }
          : todo
      );
    default:
      return state;
  }
};

In this example:

• ADD_TODO and TOGGLE_TODO are action types used in the todosReducer to handle different types of actions ('ADD_TODO' and 'TOGGLE_TODO').
• The action.type field in the switch statement ensures that the reducer responds appropriately to each dispatched action based on its type.

How to Process State Changes

At the heart of state management are reducers, pure functions designed to handle state transitions in a controlled and immutable manner.

Pure Functions: Reducers at the Core

Reducers in Redux are pure functions responsible for specifying how the application's state changes in response to actions dispatched to the store. They take the current state and an action as arguments, and return the new state based on the action type.

Here’s a breakdown of how reducers work and their role in managing state changes:

Pure Functions: Reducers are pure functions, which means they:

• Produce the same output for the same input every time they are called.
• Do not cause any side effects (such as modifying arguments or global variables).
• Do not mutate the state directly, but instead return a new state object.

Handling State Transitions: Reducers specify how the application's state changes in response to different types of actions. They use the current state and the action dispatched to compute and return the new state.

// Example of a todos reducer
const todosReducer = (state = [], action) => {
  switch (action.type) {
    case 'ADD_TODO':
      return [
        ...state,
        {
          id: action.id,
          text: action.text,
          completed: false
        }
      ];
    case 'TOGGLE_TODO':
      return state.map(todo =>
        (todo.id === action.id)
          ? { ...todo, completed: !todo.completed }
          : todo
      );
    default:
      return state;
  }
};

In this example:

• todosReducer is a pure function that takes state (current todos array) and action as arguments.
• Depending on the action.type, it computes and returns a new state (updated todos array).

Immutable State Updates: Reducers should never mutate the state directly. Instead, they create copies of the state and modify the copies to produce a new state object. This ensures that Redux can detect state changes and update components efficiently.

Single Responsibility Principle: Each reducer typically handles updates to a specific slice of the application state. This helps maintain a clear separation of concerns and makes reducers easier to understand, test, and maintain.

Characteristics of Pure Functions

Pure functions, including Redux reducers, have specific characteristics that make them well-suited for managing state changes:

Deterministic: A pure function always produces the same output for the same input. This predictability ensures that reducers behave consistently and are easier to reason about.

No Side Effects: Pure functions do not modify the input arguments or any external state. They only depend on their input parameters and produce an output without causing observable side effects.

Immutable Data: Pure functions do not mutate data. Instead, they create and return new data structures. In Redux, reducers produce a new state object without modifying the existing state, enabling efficient change detection and state management.

Referential Transparency: Pure functions can be replaced with their return values without affecting the correctness of the program. This property supports composability and makes it easier to test and reason about code.

Anatomy of a Reducer Function

A reducer function, at its core, defines how application state changes in response to dispatched actions. This function takes two parameters: the current state and an action object, determining the new state based on the type of action received.

Parameters: Previous State and Action Object

A reducer function in Redux is a pure function that takes two parameters: the previous state (state before the action is applied) and an action object. These parameters define how the reducer computes the next state of the application.

Previous State: This parameter represents the current state of the application before the action is dispatched. It is immutable and should not be modified directly within the reducer.

Action Object: An action object is a plain JavaScript object that describes what happened in your application. It typically has a type field that indicates the type of action being performed. Other fields in the action object may provide additional data necessary to update the state.

const action = {
  type: 'ADD_TODO',
  id: 1,
  text: 'Buy groceries'
};

In this example, action.type is 'ADD_TODO', indicating that we want to add a new todo item to the state.

Return Value: Updated State

The reducer function must return the updated state based on the previous state and the action object passed to it. The updated state is typically a new object that represents the application's state after applying the action.

Here’s the basic structure of a reducer function:

const initialState = {
  todos: [],
  visibilityFilter: 'SHOW_ALL'
};

const todoAppReducer = (state = initialState, action) => {
  switch (action.type) {
    case 'ADD_TODO':
      return {
        ...state,
        todos: [
          ...state.todos,
          {
            id: action.id,
            text: action.text,
            completed: false
          }
        ]
      };
    case 'TOGGLE_TODO':
      return {
        ...state,
        todos: state.todos.map(todo =>
          (todo.id === action.id)
            ? { ...todo, completed: !todo.completed }
            : todo
        )
      };
    case 'SET_VISIBILITY_FILTER':
      return {
        ...state,
        visibilityFilter: action.filter
      };
    default:
      return state;
  }
};

In this example:

• todoAppReducer is a reducer function that manages the state of todos and visibility filters.
• It takes state (previous state) and action as parameters.
• Depending on the action.type, it computes and returns a new state object that reflects the changes caused by the action.

Key Points:

Immutable Update: Reducers should never modify the previous state directly. Instead, they create a new state object by copying the previous state (...state) and applying changes to it.

Default Case: The default case in the switch statement returns the current state unchanged if the reducer doesn’t recognize the action type. This ensures that the reducer always returns a valid state object, even if no changes are made.

Single Responsibility: Each case in the switch statement corresponds to a specific action type and is responsible for updating a specific slice of the application state. This promotes a clear separation of concerns and makes reducers easier to understand and maintain.

How to Handle Different Actions in Reducers

In Redux, you can handle different actions in reducers using either switch statements or conditional logic. Both approaches aim to determine how the application state should change based on the type of action dispatched.

Using Switch Statements

Switch statements are commonly used in Redux reducers to handle different action types. Each case in the switch statement corresponds to a specific action type, and the reducer executes the corresponding logic based on the action type.

Here's an example of using switch statements in a reducer:

const initialState = {
  todos: [],
  visibilityFilter: 'SHOW_ALL'
};

const todoAppReducer = (state = initialState, action) => {
  switch (action.type) {
    case 'ADD_TODO':
      return {
        ...state,
        todos: [
          ...state.todos,
          {
            id: action.id,
            text: action.text,
            completed: false
          }
        ]
      };
    case 'TOGGLE_TODO':
      return {
        ...state,
        todos: state.todos.map(todo =>
          (todo.id === action.id)
            ? { ...todo, completed: !todo.completed }
            : todo
        )
      };
    case 'SET_VISIBILITY_FILTER':
      return {
        ...state,
        visibilityFilter: action.filter
      };
    default:
      return state;
  }
};

In this example:

• The todoAppReducer function uses a switch statement to handle different action types ('ADD_TODO', 'TOGGLE_TODO', 'SET_VISIBILITY_FILTER').
• Each case block specifies how the state should be updated in response to the corresponding action type.
• The default case returns the current state unchanged if the reducer doesn’t recognize the action type, ensuring that the reducer always returns a valid state object.

Using Conditional Logic

Alternatively, reducers can also use conditional logic (if-else statements) to determine how to update the state based on the action type. While less common than switch statements in Redux, conditional logic can be used similarly to handle actions.

Here's an example of using conditional logic in a reducer:

const todoAppReducer = (state = initialState, action) => {
  if (action.type === 'ADD_TODO') {
    return {
      ...state,
      todos: [
        ...state.todos,
        {
          id: action.id,
          text: action.text,
          completed: false
        }
      ]
    };
  } else if (action.type === 'TOGGLE_TODO') {
    return {
      ...state,
      todos: state.todos.map(todo =>
        (todo.id === action.id)
          ? { ...todo, completed: !todo.completed }
          : todo
      )
    };
  } else if (action.type === 'SET_VISIBILITY_FILTER') {
    return {
      ...state,
      visibilityFilter: action.filter
    };
  } else {
    return state;
  }
};

In this example:

• The todoAppReducer function uses if-else statements to check the action type (action.type) and execute different logic based on the type of action.
• Each condition specifies how the state should be updated for the corresponding action type.
• The final else block returns the current state unchanged if the action type is not recognized.

Choosing Between Switch Statements and Conditional Logic

1. Switch Statements:

• Advantages: Switch statements are typically more readable and maintainable when handling multiple action types in Redux reducers. They clearly separate different cases based on action types.
• Considerations: Ensure each action type has a corresponding case in the switch statement to handle updates correctly.

2. Conditional Logic:

• Advantages: Conditional logic (if-else statements) provides flexibility and can be easier to understand in certain scenarios where there are fewer action types.
• Considerations: Maintain consistency in handling action types and ensure each condition handles state updates correctly.

In practice, switch statements are the recommended approach in Redux reducers due to their clarity and convention within the Redux community. They help maintain a structured approach to managing state changes based on different action types, promoting consistency and predictability in Redux applications.

Dispatching Actions: How to Update the Redux Store

Dispatching actions in Redux is fundamental to managing state updates within your application. Redux, a predictable state container for JavaScript applications, relies on actions as payloads of information that send data from your application to the Redux store.

The dispatch function

In Redux, the dispatch function is a method provided by the Redux store. It is used to dispatch actions to trigger state changes in the application. When an action is dispatched, the Redux store calls the reducer function associated with it, computes the new state, and notifies all subscribers that the state has been updated.

Here's how you use the dispatch function:

import { createStore } from 'redux';

// Reducer function
const counterReducer = (state = { count: 0 }, action) => {
  switch (action.type) {
    case 'INCREMENT':
      return { ...state, count: state.count + 1 };
    case 'DECREMENT':
      return { ...state, count: state.count - 1 };
    default:
      return state;
  }
};

// Create Redux store
const store = createStore(counterReducer);

// Dispatch actions to update state
store.dispatch({ type: 'INCREMENT' });
store.dispatch({ type: 'DECREMENT' });

In this example:

• We create a Redux store using createStore and pass in the counterReducer function.
• The store.dispatch function is used to dispatch actions ({ type: 'INCREMENT' } and { type: 'DECREMENT' }) to update the state.
• Each dispatched action triggers the corresponding case in the reducer, updating the state as defined.

Dispatching Actions from Components or Events

In a typical Redux application, actions are often dispatched from React components in response to user interactions or other events.

To dispatch actions from components, you typically connect the component to the Redux store using React Redux's connect function or hooks like useDispatch.

Here's how you can dispatch actions from a React component using connect and mapDispatchToProps:

import React from 'react';
import { connect } from 'react-redux';

// Action creator functions
const increment = () => ({ type: 'INCREMENT' });
const decrement = () => ({ type: 'DECREMENT' });

// Component definition
const Counter = ({ count, increment, decrement }) => (
  <div>
    <p>Count: {count}</p>
    <button onClick={increment}>Increment</button>
    <button onClick={decrement}>Decrement</button>
  </div>
);

// Map state to props
const mapStateToProps = (state) => ({
  count: state.count
});

// Map dispatch to props
const mapDispatchToProps = {
  increment,
  decrement
};

// Connect component to Redux store
export default connect(mapStateToProps, mapDispatchToProps)(Counter);

In this example:

• increment and decrement are action creator functions that return actions ({ type: 'INCREMENT' } and { type: 'DECREMENT' }).
• The Counter component is connected to the Redux store using connect. It receives count from the Redux state as a prop, along with increment and decrement action creators.
• Clicking the "Increment" and "Decrement" buttons dispatches actions, which are handled by the reducer to update the Redux state.

Alternatively, you can use React Redux hooks (useDispatch) for dispatching actions in functional components:

import React from 'react';
import { useDispatch, useSelector } from 'react-redux';

const Counter = () => {
  const count = useSelector(state => state.count);
  const dispatch = useDispatch();

  const handleIncrement = () => {
    dispatch({ type: 'INCREMENT' });
  };

  const handleDecrement = () => {
    dispatch({ type: 'DECREMENT' });
  };

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={handleIncrement}>Increment</button>
      <button onClick={handleDecrement}>Decrement</button>
    </div>
  );
};

export default Counter;

In this functional component example:

• useSelector is used to select count from the Redux store state.
• useDispatch is used to get the dispatch function from the Redux store.
• handleIncrement and handleDecrement functions dispatch actions ({ type: 'INCREMENT' } and { type: 'DECREMENT' }) to update the Redux state when the buttons are clicked.

How to Access Specific Data from the Store

Accessing specific data from the store in Redux involves navigating through the application's state structure to retrieve precise information needed for rendering components or performing logic.

Creating Selector Functions

Selectors in Redux are functions that encapsulate the logic for retrieving specific pieces of data from the Redux store state. They help to decouple the components from the structure of the state and facilitate efficient data access and transformation.

Here’s how you can create selector functions:

// Example Redux state
const initialState = {
  todos: [
    { id: 1, text: 'Learn Redux', completed: false },
    { id: 2, text: 'Write Redux selectors', completed: true },
    // more todos...
  ],
  visibilityFilter: 'SHOW_COMPLETED'
};

// Selector function to get todos from state
const getTodos = (state) => state.todos;

// Selector function to filter todos based on visibility filter
const getVisibleTodos = (state) => {
  const todos = getTodos(state);
  const visibilityFilter = state.visibilityFilter;

  switch (visibilityFilter) {
    case 'SHOW_COMPLETED':
      return todos.filter(todo => todo.completed);
    case 'SHOW_ACTIVE':
      return todos.filter(todo => !todo.completed);
    case 'SHOW_ALL':
    default:
      return todos;
  }
};

In this example:

• getTodos is a selector function that retrieves the todos array from the Redux state.
• getVisibleTodos is a selector function that filters todos based on the visibilityFilter stored in the state.

Selectors can also be composed to create more complex selectors:

// Composed selector function to get visible todos
const getVisibleTodos = (state) => {
  const todos = getTodos(state);
  const visibilityFilter = state.visibilityFilter;

  switch (visibilityFilter) {
    case 'SHOW_COMPLETED':
      return getCompletedTodos(todos);
    case 'SHOW_ACTIVE':
      return getActiveTodos(todos);
    case 'SHOW_ALL':
    default:
      return todos;
  }
};

// Helper functions for filtering todos
const getCompletedTodos = (todos) => todos.filter(todo => todo.completed);
const getActiveTodos = (todos) => todos.filter(todo => !todo.completed);

Memoization for Efficient Selector Usage

Memoization is a technique used to optimize expensive computations by caching the results of function calls based on their input. In the context of Redux selectors, memoization can improve performance by ensuring that selectors only recalculate their results when their input (state) changes.

You can use libraries like reselect for memoization in Redux selectors:

npm install reselect

Example usage of reselect for memoization:

import { createSelector } from 'reselect';

// Selectors
const getTodos = (state) => state.todos;
const getVisibilityFilter = (state) => state.visibilityFilter;

// Memoized selector to get visible todos
const getVisibleTodos = createSelector(
  [getTodos, getVisibilityFilter],
  (todos, visibilityFilter) => {
    switch (visibilityFilter) {
      case 'SHOW_COMPLETED':
        return todos.filter(todo => todo.completed);
      case 'SHOW_ACTIVE':
        return todos.filter(todo => !todo.completed);
      case 'SHOW_ALL':
      default:
        return todos;
    }
  }
);

In this example:

• createSelector from reselect creates a memoized selector that takes getTodos and getVisibilityFilter as input selectors.
• The selector function computes the filtered todos based on the visibilityFilter and caches the result until the input selectors change.

How to Connect React Components to Redux

Connecting React components to Redux is a fundamental technique for managing application state efficiently within React-based projects. Redux serves as a centralized store that holds the entire state of your application, making it accessible to any component that needs it.

The connect Function from react-redux Library

In React applications using Redux for state management, the connect function from the react-redux library is used to connect React components to the Redux store. It provides a way to inject Redux state and action dispatching functions (dispatchers) into your components.

Here’s how you use connect:

import React from 'react';
import { connect } from 'react-redux';

// Define a React component
const Counter = ({ count, increment, decrement }) => (
  <div>
    <p>Count: {count}</p>
    <button onClick={increment}>Increment</button>
    <button onClick={decrement}>Decrement</button>
  </div>
);

// Map Redux state to component props
const mapStateToProps = (state) => ({
  count: state.count
});

// Map dispatching actions to component props
const mapDispatchToProps = {
  increment: () => ({ type: 'INCREMENT' }),
  decrement: () => ({ type: 'DECREMENT' })
};

// Connect component to Redux store
export default connect(mapStateToProps, mapDispatchToProps)(Counter);

Mapping State and Dispatch to Props

mapStateToProps: This function maps the Redux store's state to the props of your React component. It takes the Redux state as an argument and returns an object. Each field in the returned object will become a prop for the connected component.

mapDispatchToProps: This function maps dispatching actions to props of your React component. It can be an object where each field is an action creator function, or a function that receives dispatch as an argument and returns an object. Each action creator will be wrapped automatically with dispatch so they can be called directly.

In the example:

• mapStateToProps maps the count field from the Redux state (state.count) to the count prop of the Counter component.
• mapDispatchToProps maps the increment and decrement actions to props, so clicking the buttons in the Counter component will dispatch the corresponding actions ({ type: 'INCREMENT' } and { type: 'DECREMENT' }).

Using Connected Components in Your Application

Once a component is connected to the Redux store using connect, it can access Redux state and dispatch actions via props. Here’s how you can use connected components in your application:

import React from 'react';
import ReactDOM from 'react-dom';
import { Provider } from 'react-redux';
import { createStore } from 'redux';
import rootReducer from './reducers'; // Import your root reducer
import App from './App'; // Import your connected component

// Create Redux store with root reducer
const store = createStore(rootReducer);

// Render the App component inside the Provider
ReactDOM.render(
  <Provider store={store}>
    <App />
  </Provider>,
  document.getElementById('root')
);

In this setup:

• Provider is a component from react-redux that makes the Redux store available to any nested components that have been connected using connect.
• store is created using createStore and combined with a root reducer (rootReducer) that combines all your reducers into one.

By wrapping your top-level component (App in this case) with Provider and passing the Redux store as a prop, all connected components within your application can access the Redux store and interact with it through props (mapStateToProps and mapDispatchToProps mappings).

Advanced Redux Data Flow Techniques

Advanced Redux data flow techniques expand upon the fundamental principles of managing state in complex applications. These techniques go beyond basic actions and reducers, introducing concepts such as middleware, selectors, and asynchronous actions.

Asynchronous Actions (Redux Thunk, Redux Saga)

In Redux, handling asynchronous actions involves managing actions that have side effects, such as fetching data from a server or updating state asynchronously. Redux provides several middleware solutions to handle asynchronous actions effectively.

Redux Thunk

Redux Thunk is a middleware that allows you to write action creators that return a function instead of an action object. This function can then perform asynchronous operations and dispatch regular synchronous actions when the asynchronous operations complete.

Example of using Redux Thunk for asynchronous actions:

Setting up Redux Thunk Middleware:

import { createStore, applyMiddleware } from 'redux';
import thunk from 'redux-thunk';
import rootReducer from './reducers'; // Import your root reducer

// Create Redux store with thunk middleware
const store = createStore(rootReducer, applyMiddleware(thunk));

Async Action Creator using Redux Thunk:

// Action creator function using Redux Thunk
const fetchPosts = () => {
  return async (dispatch) => {
    dispatch({ type: 'FETCH_POSTS_REQUEST' });

    try {
      const response = await fetch('https://jsonplaceholder.typicode.com/posts');
      const posts = await response.json();
      dispatch({ type: 'FETCH_POSTS_SUCCESS', payload: posts });
    } catch (error) {
      dispatch({ type: 'FETCH_POSTS_FAILURE', error: error.message });
    }
  };
};

In this example:

• fetchPosts is an action creator that returns a function instead of an action object.
• Inside the function, you can perform asynchronous operations (like fetching data) and dispatch actions based on the result.
• Redux Thunk middleware intercepts functions returned by action creators, enabling asynchronous actions in Redux.

Redux Saga

Redux Saga is another middleware for handling side effects in Redux applications. It uses ES6 generators to make asynchronous code easier to read, write, and test.

Example of using Redux Saga for handling asynchronous actions:

Setting up Redux Saga Middleware:

import { createStore, applyMiddleware } from 'redux';
import createSagaMiddleware from 'redux-saga';
import rootReducer from './reducers'; // Import your root reducer
import rootSaga from './sagas'; // Import your root saga

// Create Redux Saga middleware
const sagaMiddleware = createSagaMiddleware();

// Create Redux store with Saga middleware
const store = createStore(rootReducer, applyMiddleware(sagaMiddleware));

// Run the root saga
sagaMiddleware.run(rootSaga);

Example Saga (rootSaga.js):

import { all, call, put, takeEvery } from 'redux-saga/effects';
import { fetchPostsSuccess, fetchPostsFailure } from './actions'; // Import your action creators

// Worker saga for fetching posts
function* fetchPostsSaga() {
  try {
    const response = yield call(fetch, 'https://jsonplaceholder.typicode.com/posts');
    const posts = yield call([response, 'json']);
    yield put(fetchPostsSuccess(posts));
  } catch (error) {
    yield put(fetchPostsFailure(error.message));
  }
}

// Watcher saga to listen for FETCH_POSTS_REQUEST action
function* watchFetchPosts() {
  yield takeEvery('FETCH_POSTS_REQUEST', fetchPostsSaga);
}

// Root saga
export default function* rootSaga() {
  yield all([
    watchFetchPosts()
    // Add more watchers if needed
  ]);
}

In this example:

• fetchPostsSaga is a worker saga that performs the asynchronous operation (fetching posts).
• watchFetchPosts is a watcher saga that listens for specific actions (FETCH_POSTS_REQUEST) and triggers the corresponding worker saga.
• rootSaga combines multiple sagas using all and runs them using sagaMiddleware.run.

Middleware for Extending Redux Functionality

Middleware in Redux provides a way to extend the Redux store's capabilities, such as logging actions, handling asynchronous operations, routing, and more. Middleware sits between dispatching an action and the moment it reaches the reducer, allowing interception and manipulation of actions.

Example of Custom Middleware:

const loggerMiddleware = store => next => action => {
  console.log('Dispatching action:', action);
  const result = next(action);
  console.log('New state:', store.getState());
  return result;
};

// Applying custom middleware to Redux store
import { createStore, applyMiddleware } from 'redux';
import rootReducer from './reducers'; // Import your root reducer

// Create Redux store with custom middleware
const store = createStore(rootReducer, applyMiddleware(loggerMiddleware));

In this example:

• loggerMiddleware is a custom middleware function that logs each dispatched action and the resulting state.
• next is a function provided by Redux that allows the action to continue to the next middleware or the reducer.
• Custom middleware enhances Redux functionality by intercepting actions, performing custom logic, and optionally dispatching new actions or modifying existing ones.

Best Practices for Managing Data Flow in Redux

Redux provides a structured way to manage state in JavaScript applications, but effective usage requires adhering to best practices. Here are my key recommendations for managing data flow in Redux:

Organizing Reducers and Actions

File Structure and Organization:

• Separate concerns: Keep actions, reducers, and selectors in separate files to maintain clarity and modularity.
• Feature-based structure: Group related actions and reducers together based on features rather than types.

src/
├── actions/
│   ├── todosActions.js
│   └── userActions.js
├── reducers/
│   ├── todosReducer.js
│   └── userReducer.js
├── selectors/
│   ├── todosSelectors.js
│   └── userSelectors.js
└── store.js

Action Types:

• Constants: Use constants or enums for action types to prevent typos and ensure consistency.

// Action types
export const ADD_TODO = 'ADD_TODO';
export const DELETE_TODO = 'DELETE_TODO';

Reducer Composition:

• Combine reducers: Use combineReducers from Redux to combine multiple reducers into a single root reducer.

import { combineReducers } from 'redux';
import todosReducer from './todosReducer';
import userReducer from './userReducer';

const rootReducer = combineReducers({
  todos: todosReducer,
  user: userReducer
});

export default rootReducer;

Immutable State Updates

Immutability with Spread Operator:

• Use spread operator (...): Create new objects or arrays when updating state to maintain immutability.

// Updating an array in Redux state
const todosReducer = (state = initialState, action) => {
  switch (action.type) {
    case ADD_TODO:
      return {
        ...state,
        todos: [
          ...state.todos,
          {
            id: action.id,
            text: action.text,
            completed: false
          }
        ]
      };
    case TOGGLE_TODO:
      return {
        ...state,
        todos: state.todos.map(todo =>
          (todo.id === action.id) ? { ...todo, completed: !todo.completed } : todo
        )
      };
    default:
      return state;
  }
};

Immutable Libraries:

• Immutable.js: Consider using libraries like Immutable.js for more complex data structures to enforce immutability and optimize performance.

import { Map, List } from 'immutable';

const initialState = Map({
  todos: List(),
  user: Map()
});

const todosReducer = (state = initialState, action) => {
  switch (action.type) {
    case ADD_TODO:
      return state.update('todos', todos => todos.push(Map({
        id: action.id,
        text: action.text,
        completed: false
      })));

    case TOGGLE_TODO:
      return state.update('todos', todos =>
        todos.map(todo =>
          (todo.get('id') === action.id) ? todo.set('completed', !todo.get('completed')) : todo
        )
      );

    default:
      return state;
  }
};

Testing Redux Applications

Unit Testing:

• Reducers: Test reducers to ensure they handle actions correctly and return the expected state.

describe('todosReducer', () => {
  it('should handle ADD_TODO', () => {
    const action = { type: 'ADD_TODO', id: 1, text: 'Test todo' };
    const initialState = { todos: [] };
    const expectedState = { todos: [{ id: 1, text: 'Test todo', completed: false }] };

    expect(todosReducer(initialState, action)).toEqual(expectedState);
  });
});

Integration Testing:

• Action Creators and Thunks: Test action creators and thunks to verify they dispatch the correct actions or handle asynchronous operations.

describe('fetchPosts action creator', () => {
  it('creates FETCH_POSTS_SUCCESS when fetching posts has been done', () => {
    const expectedActions = [
      { type: 'FETCH_POSTS_REQUEST' },
      { type: 'FETCH_POSTS_SUCCESS', payload: { /* mocked data */ } }
    ];

    const store = mockStore({ posts: [] });

    return store.dispatch(fetchPosts()).then(() => {
      expect(store.getActions()).toEqual(expectedActions);
    });
  });
});

Integration with Components:

• Connected Components: Test connected components using redux-mock-store to simulate Redux store behavior.

import configureStore from 'redux-mock-store';
import { Provider } from 'react-redux';
import { render } from '@testing-library/react';
import App from './App';

const mockStore = configureStore([]);

describe('<App />', () => {
  it('renders App component', () => {
    const store = mockStore({ /* mocked state */ });

    const { getByText } = render(
      <Provider store={store}>
        <App />
      </Provider>
    );

    expect(getByText('Welcome to Redux App')).toBeInTheDocument();
  });
});

Conclusion

Redux offers a powerful state management solution for JavaScript applications, providing a predictable and centralized way to manage application state.

Whether handling asynchronous operations with middleware like Redux Thunk or Redux Saga, or optimizing state management through immutable data practices, Redux empowers you to build scalable and maintainable applications.

By mastering these techniques, you can leverage Redux to streamline data flow, enhance application performance, and simplify the complexities of managing state in modern web development.

That's all for this article! If you'd like to continue the conversation or have questions, suggestions, or feedback, feel free to reach out to connect with me on LinkedIn. And if you enjoyed this content, consider buying me a coffee to support the creation of more developer-friendly contents.

You'll learn about:

1. The new React 19 feature, Actions
2. The new React 19 hooks, useActionState and useFormStatus
3. How to convert a React 18 form to a React 19 form

I also made a video version of this article if you'd like to learn from that as well.

Feature: React Actions

To understand Actions, let's first take a look at how we manage forms today. In React 18 and earlier, we submit forms using the handleSubmit function in a button. Here's a simple form that has one input field name:

// Form submission in React 18
console.info('React 18 form');

const [name, setName] = useState('');
const [isPending, setIsPending] = useState(false);

const handleChange = (event) => {
  setName(event.target.value);
};

const handleSubmit = (event) => {
  event.preventDefault();
  setIsPending(true);
  setTimeout(() => {
    // call API
    setIsPending(false);
  }, 500);
};

return (
  <form>
    <input type="text" name="name" onChange={handleChange} />
    {isPending ? <p>Loading...</p> : <p>Hello in React 18, {name}</p>}
    <button onClick={handleSubmit} disabled={isPending}>
      Update
    </button>
  </form>
);

In this code, we are doing the following:

1. Adding a loading state: We use a variable isPending to manually keep track of the loading state.
2. Form submission: The form is submitted using the handleSubmit event handler attached to the onClick event of the button.
3. Capturing the submitted value: The handleChange function captures the submitted value and stores it in state variables.

What Are React Actions?

With React 19, handling forms becomes easier with Actions, inspired by frameworks such as Remix. One key feature is the enhanced use of startTransition to manage pending states.

startTransition was introduced in React 18, allowing developers to mark certain updates as less urgent.

In React 19, startTransition can now handle async functions, making it even more powerful for managing asynchronous tasks and improving the user experience during form submissions.

const [isPending, startTransition] = useTransition();

const handleSubmit = () => {
  startTransition(async () => {
    const error = await updateName(name);
    if (error) {
      setError(error);
      return;
    }
    redirect('/path');
  });
};

This async function inside startTransition is called an Action. What makes actions cool is that they can be used directly to submit forms like so:

<form action="{actionFn}">...</form>

This format may look familiar if you are experienced with PHP.

How to Create a React Action

To create an async function, we can use a new hook introduced in React 19 called useActionState. We call this hook and pass in an action function and an initial state. This hook returns the updated state and a form action actionFn, which can be used to wire up a form.

const [state, actionFn] = useActionState(submitAction, { name: '' });

Now with this wired up with the form, we have the following:

<form action={actionFn}>
  <input type="text" name="name" />

  <button type="submit" disabled="{pending}">
    Update
  </button>
</form>

To add a loading state, we can use a new hook introduced in React 19 called useFormStatus.

const { pending, data, method, action } = useFormStatus();

This hook provides information on the status of the form. The pending state indicates whether the form is being submitted, and data is a FormData object containing the submitted data. We use this pending state to show a loader.

But there is one caveat: this hook can only be used in a child component, not in the form itself. So, we have to create child components SubmitButton and Loader to retrieve a pending state:

function Loader() {
  const { pending } = useFormStatus();
  return <div>{pending && "Loading..."}</div>;
}

function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      Update
    </button>
  );
}

....

return(
<form action={formAction}>
      <input type="text" name="name" />
      <Loader />
      <SubmitButton />
    </form>
)

We can also capture useful information about the data submitted to the form by retrieving it from the state returned from useActionState.

const [state, formAction] = useActionState(submitAction, { name: '' });

So here's the final form:

function Loader() {
  const { pending } = useFormStatus();
  return <div>{pending && 'Loading...'}</div>;
}

function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      Update
    </button>
  );
}

function Name({ name }) {
  return <p>Hello in 19 {name}</p>;
}

function App() {
  console.info('React 19 form');

  const [state, formAction] = useActionState(submitAction, { name: '' });

  return (
    <form action={formAction}>
      <input type="text" name="name" />
      <Loader />
      <SubmitButton />
      <Name name={state?.name} />
    </form>
  );
}

Compare this with the React 18 form at the top of this post to check the difference.

Conclusion

By utilizing actions along with hooks like useActionState and useFormStatus, we can easily manage form states, capture submitted data, and provide responsive feedback to users during form submissions to show pending states.

I am excited for this improved experience of handling forms in React 19, and I look forward to removing unnecessary handleSubmits, useStates, and pending states.

In my next article, I will discuss another exciting new React feature: the React Compiler. This tool automatically memoizes, eliminating the need for useMemo and useCallback. Stay updated and get the article directly in your inbox by joining my newsletter.

This user experience, designed to load new content on demand, uses a technique called infinite scrolling. This helps keep you hooked to these apps for hours.

Traditionally, these features would have you click "Next Page" to display new content. However, infinite scrolling reduces the load on the server by fetching less data at a time and thus, provides a much more engaging user experience.

In this post, we are going to implement the same feature in JavaScript. We'll use the Intersection Observer API to load data on demand, as the user is scrolling. We'll create a simple React application that displays posts similar to a social media feed.

How to Set Up the React App

Run create-react-app in your terminal or use a modern built tool like Vite to create your React app. Remove the existing boilerplate code. There is no need to install any additional dependencies. Run npm start command to start the project.

You can find the complete code of this tutorial on GitHub. Let's get started.

How to Create the Data Fetching Function

Create a separate file called services.js and write the following data fetching function.

We'll use the /posts API from JSONPlaceholder to get our data.

export const fetchPosts = async (page, limit) => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/posts?_page=${page}&_limit=${limit}`
  );
  const data = await response.json();
  return data;
};

Here, we have passed two params to the API:

• page indicates the part of data that is called. This increases each time the user scrolls and loads new data.

• limit indicates the amount of data that is called at a time. For infinite scrolling, we call just enough data that can be displayed on a single page.

How to Build the Infinite Scroll Component

Let's create a component PostsList for displaying a list of posts with infinite scrolling.

Let's create our state variables, fetch the data, and display it:

const PostsList = () => {
  const [posts, setPosts] = useState([]);
  const [page, setPage] = useState(1);
  const [loading, setLoading] = useState(false);

  return (
    <div>
      <h1>Your Feed</h1>
      <ul>
        {posts.map((post, index) => (
          <li
            key={post.id}
          >
            <h2>{post.title}</h2>
            <p>{post.body}</p>
          </li>
        ))}
      </ul>
      {loading && <p>Loading...</p>}

    </div>
  );
};

Here, we have defined the state variables for posts, page number and loading state. Note that the page number does not mean that we are adding pagination. It's just a parameter to load the next set of data.

Now, let's call our API with the current page number and set the loading states:

const loadMorePosts = async () => {
    setLoading(true);
    const newPosts = await fetchPosts(page, 10);
    setPosts((prevPosts) => [...prevPosts, ...newPosts]);
    setLoading(false);
  };

  useEffect(() => {
    loadMorePosts();
  }, [page]);

Until now, we have fetched the initial 10 posts on first load of the page. We want to load more data as the user scrolls down the page.

Next, we'll use the Intersection Observer API to detect when additional data should be loaded.

Before using it, let's first understand what this API is.

What is the Intersection Observer API?

The Intersection Observer API is a web API that allows you to asynchronously observe changes in the intersection of a target element with an ancestor element or the viewport.

In simpler terms, it enables you to detect when an element enters or exits in an area of another DOM element or the viewport. Using Intersection Observer provides us with following advantages:

• Reduces the need for attaching event listeners to every scroll event.

• Removes the need for manual calculations of the element's position and their event listeners, thus simplifying your code.

• Efficient for observing multiple events compared to scroll or resize event listeners.

Go through the MDN Docs to understand more about Intersection Observer.

How to Use the Intersection Observer API

To use this API, we'll need to create an observer object.

Here's how you create an observer object:

const observer = new IntersectionObserver(callback, options);

• callback is a function called when the observed element's visibility changes. This function takes two arguments: entries and the observer object itself. Each object in entries array is an IntersectionObserverEntry object that contains information about the observed element's intersection status.

• options is an optional argument to further configure the Observer.

How do we use this in our application? We'll define observer object as a ref:

  const observer = useRef();

Now, to set this observer object on an element and to detect whether that element is intersecting with the viewport, we use the following function, which is a callback ref:

const lastPostElementRef = useCallback(
    (node) => {
      if (loading) return;
      if (observer.current) observer.current.disconnect();

      observer.current = new IntersectionObserver((entries) => {
        if (entries[0].isIntersecting) {
          setPage((prevPage) => prevPage + 1); // trigger loading of new posts by chaging page no
        }
      });

      if (node) observer.current.observe(node);
    },
    [loading]
  );

Let's understand how this function works:

• We check if the data is still loading. If it is, then we do not execute the logic.

• To refer to the observer object, we use the ref's current property.

• If an element is already being observed, then disconnect it and create a new Observer that changes the page number, thus triggering the API call if the observed element intersects with the viewport.

• Since we are only observing one element at a time (such as the last element of the page) the size of entries is one.

• This new Observer will now watch the current element to which the ref is attached to, which is the last element on the page.

Since we only want to observe the last element on the page, we add this ref according to following condition:

{posts.map((post, index) => (
          <li
            key={post.id}
            ref={posts.length === index + 1 ? lastPostElementRef : null}
          >
            ...
          </li>
        ))}

Now, why are we using callback refs instead of the observer ref itself?

A ref gives us a direct reference to the element and sets the value of the ref object directly. It works well for elements that do not need to change reference dynamically.

A callback ref offers more control over the ref and can handle dynamic changes to reference more effectively. It is a function called with the element's instance, or its DOM Node when the component mounts and with null if it unmounts.

In our case, our reference changes dynamically since our last element gets updated as more data is loaded. We are also able to write some logic to observe and disconnect from a node, while setting our ref object.

We'll also wrap the lastPostElementRef function inside a useCallback hook to avoid it getting re-created on every re-render. We'll only create this function if the loading state changes when it's time to execute the function.

Run your app with npm start, go to http://localhost:3000, and open the Network Tab. As you scroll down, you'll see new API requests being made as you scroll down the page.

API requests for each new page

You can find the complete code on GitHub and similar tutorials in JavaScript and React.

Conclusion

When you implement infinite scrolling in your application, it provides a seamless and engaging user experience similar to what you see on popular social media apps. Instead of clicking through pages, users can effortlessly scroll through the content that loads dynamically.

In our example, we created a mock social media feed that loaded more content as the user scrolls down. We used the Intersection Observer API to detect the position of the last element according to which we loaded more data. It simplified our code and removed the need for attaching multiple event listeners.

I hope this helps you create similar features in your next web project and enables you to provide an engaging user experience. Please share your thoughts and feedback. Thank you!

One of the most common elements where you’ll need to apply user input validation is via a form. This could be a user sign up form, a contact us form, or a simple questionnaire.

Outcomes of the Tutorial

By the end of this article , you will be able to:

• Understand common issues with form validation.
• How to utilise the Yup schema validation library alongside the Formik form library.
• How to build a form in React with full validation (same principles apply for React Native, with different component syntax).

Contents

• What is Validation?
• The Object to Be Validated
• Introducing Yup and Formik
• How to Add Validation to a Form
• Conclusion

What is Validation?

Validation is defined as:

the action of checking or proving the validity or accuracy of something.

But what does that mean in computer speak? This could be a multitude of things, but the premise still stands. You could be validating a variable value or an object against a pre-determined set of rules or regulations.

Examples of validation rules could be:

• Password must be at least 8 characters and contain a special character.
• Username must be unique.
• Date of birth must be received as a string, in a particular format, for example ISO8601

Let’s use the example of a user registration form on a website.

The Object to Be Validated

The form will comprise of several inputs to form a UserRegistration object. Like so‌:

interface UserRegistration {
  firstName: string;
  surname: string;
  email: string;
  dob: string;
}

Above is an interface (contract) for a UserRegistration object. It simply defines some key user information which needs to be collected, with all values being a string value.

While languages like TypeScript are useful for ensuring that we pass the correct types to functions throughout our application, they do not inherently validate the actual content or values within those types. TypeScript guarantees that a variable is of a specific type, such as a string or a number, but it does not verify if the content of that string or number meets specific criteria or constraints.

What If We Didn't Validate the Values?

Ok, before we move onto how to validate, let's look at what could happen if we don't validate.

Without validation, a user could input the following values:

Firstname: 1231301‌
‌Surname: Hello##test_101‌
‌Email: user_123@@email.to@.com‌
‌DoB: 10+12+1909

These values may seem perfectly acceptable, and your front end might allow them to be submitted without any issues. And the API will likely accept these values initially.

But when the API attempts to parse these values (converting) during the request processing, it will encounter errors and fail to process the request correctly.

There are several negative consequences to this approach:

1. Increased Server Load: The front end is making multiple invalid requests to the server, which unnecessarily strains the server. This extra load could have been avoided.
2. Potentially Higher Costs: The cost of handling these invalid requests can increase significantly, depending on your hosting plan and server configuration. Each invalid request consumes server resources that could be used more efficiently.
3. Poor User Experience (UX): Users will likely become frustrated if they repeatedly enter details, submit the form, and then receive error messages indicating that their inputs are invalid. This can lead to a negative perception of the application.

To mitigate these issues and reduce the number of invalid requests, we can implement 'client-side validation' to ensure that the data meets the required criteria before sending the API request.

Introducing Yup and Formik

Yup and Formik are both libraries which you can add to any React or React Native application via npm or yarn.

Yup is a schema building library that allows you to build schemas for validation at runtime. It has a plethora of extension functions which can set rulesets, transform values, and return validation messages right out the box.

Let's take a look at an example of a Yup schema for our user form:‌

import * as Yup from 'yup';

// If using Typescript, you can utilise a wrapper function to enforce strict typing

const createYupSchema = <T extends object>(schema: Yup.ObjectSchema<T>): Yup.ObjectSchema<T> => schema;

export const userFormSchema = createYupSchema<UserInput>(
  Yup.object().shape({
    firstname: Yup.string().required('First name is required'),
    surname: Yup.string().required('Surname is required'),
    email: Yup.string().email('Invalid email format').required('Email is required'),
    dob: Yup.string().required('Date of Birth is required'),
  })
);

// JS Version
export const validationSchema = Yup.object({
  firstname: Yup.string().required('First name is required'),

  surname: Yup.string().required('Surname is required'),
  email: Yup.string().email('Invalid email format').required('Email is required'),
  dob: Yup.date().required('Date of Birth is required')
});

We're creating a Yup object (schema) which contains all of our Keys for our UserInput interface.

Schema Parts:

• key: the key which will be used later for the name of our element (as we're using TypeScript, this needs to match the object key name).
• ruleset: for all keys, apply a ruleset. A ruleset must start with a typing declaration, that is Yup.string() or Yup.number() and so on. You can then chain your other validation functions.

Using TypeScript ensures that we match the schema type to our interface types.

For example, if we try and do this:

firstname: Yup.date().required();

it will throw a TypeScript error complaining that firstname cannot be validated as if it was a date, as the type of firstname is a string.

How to Add Validation to a Form

This is where our Formik library comes in and makes things much easier than validating a form and implementing error handling manually.

Formik is a library which encapsulates a <Form/> component. It allows us to create richer forms in React and React Native, giving us access to features like form state, error handling, validation, and processing of form submissions much more efficiently.

You can access a pre-built version of a UserForm utilising Yup, Formik, and React (Vite) at my GitHub here. Simply clone the GitHub repository and follow the README.md instructions. ‌

<Formik
        initialValues={initialValues}
        validationSchema={userFormSchema}
        onSubmit={onSubmit}
      >
        {({ isValid, dirty, isSubmitting }) => (
          <Form>
            <div className="form-control">
              <label htmlFor="firstName">First Name</label>
              <Field type="text" id="firstName" name="firstName" />
              <ErrorMessage name="firstName" component="div" className="error" />
            </div>

            <div className="form-control">
              <label htmlFor="surname">Surname</label>
              <Field type="text" id="surname" name="surname" />
              <ErrorMessage name="surname" component="div" className="error" />
            </div>

            <div className="form-control">
              <label htmlFor="email">Email</label>
              <Field type="email" id="email" name="email" />
              <ErrorMessage name="email" component="div" className="error" />
            </div>

            <div className="form-control">
              <label htmlFor="dob">Date of Birth</label>
              <Field type="date" id="dob" name="dob" />
              <ErrorMessage name="dob" component="div" className="error" />
            </div>

            <button type="submit" disabled={isSubmitting || !isValid}>Submit</button>
          </Form>
        )}
      </Formik>

In this code, we've utilsed the <Formik/> library component, which wraps around our standard <Form/> element. We pass the following properties to the component:

• **initialValues** – these are the required initial values of your form (that is when the form renders what values your inputs will have).‌
• validationSchema – this is probably the most important for this tutorial. Bear in mind this is an optional property, as it's not needed to utilise the <Formik/> component, but for any validation it is. ‌
  ‌‌
  ‌We're going to import our userFormSchema we created in the previous step. This is going to tell the form, when validating inputs within this form utilise these schemas. ‌
• onSubmit – a straightforward function to run on clicking your button / submitting the form. The values of the form will automatically be passed to this function.‌

You can wrap the form within a "render prop" function also to utilise some of the exposed props from Formik within your form. You can learn about render props more here.

{({ isValid, isSubmitting }) => (

Note: This is not required if you don't want to utilise any of the underlying Formik properties within the form itself. You can simply remove and place your opening <Form> tag in its place. ‌
‌‌
‌But using this render prop allows you to access properties exposed from the Formik component within your <Form/> element. You can see that we are utilising theisValid and isSubmitting properties to control the state of our submit button.

Continuing on with analyzing the code:

• **isValid** – a boolean value which Formik controls based on our schema validation result.
• **isSubmitting** – A boolean flag indicating if a form is mid-submission. This flag is very useful when wanting to disable a button, to prevent multiple clicks meaning multiple submissions of the form.

We can use these values to control the enablement of the submit button like so:

<button type="submit" disabled={isSubmitting || !isValid}>Submit</button>

Input Fields

It's important to note that when using Formik and Yup, in order for the validation to work, the names of the input fields need to match the Yup schema keys exactly (case sensitive) – otherwise the validation rules won't be registered.

Example:‌

<Field type="email" id="email" name="email" />
<ErrorMessage name="email" component="div" className="error" />

We've defined this field is to be used for an email input, and given it the matching name of "email" to our a userFormSchema definition.

Underneath, we code our Formik <ErrorMessage/> component, again passing in the name of 'email', matching our schema. Using the name property we are able to link our input, error message, and validation schemas all together.

If there are any issues with validating the input field, the error message will show any defined error messages – otherwise it will fallback to a default message, e.g "firstname is a required field". This can be less user friendly, so I'd recommend always passing a custom message.

You'll also notice, that when we lose focus or when typing (after first validation has run), it will automatically run validation again. You can overwrite this functionality by setting the validateOnBlur and the validateOnChange flags (true / false).

As an example, it will look like this in its error state.:

Image: Invalid Formik form showing error state

‌Once we've entered values for all inputs, and our validation has passed (you can see the submit button is now enabled), we can submit.‌

Further Validation and Formik Features‌

You've now seen how easy Yup and Formik can make creating a form. It has full validation and even error handling, meaning you can have a fully functioning user friendly form built in just a few minutes.

But what if you want to add more complex validation to a much larger / complicated form? Well, let's look at an example:

Let's say we want to validate that the date of birth provided ensures that the user is over the age of 18. We will also add a password field, which will have rules of:

• minimum of 6 letters
• contain a number
• contain a special character

DoB Extra Requirements

We can do this by chaining the test() function onto the string() function of the dob object within our schema.

The test() function allows us to test against custom logic. Update the dob parameter within the userFormSchema to the following:‌

dob: Yup.string()
      .required('Date of Birth is required')
      .test('is-older-than-18', 'You must be at least 18 years old', (value) => {
        if (!value) return false;

        // try to parse the value to date
        const parsedDate = parse(value, 'yyyy-MM-dd', new Date());
        if (!isValid(parsedDate)) return false;

        const today = new Date();
        const eighteenYearsAgo = subYears(today, 18);

        // check if date provided is before or the same as 18 years ago.
        return parsedDate <= eighteenYearsAgo;
      })

We now get the following error when trying to submit a date that is less than 18 years ago. ‌

Image: Invalid input field due to failed date validation

Password Validation

For the password field validation, we can do something like this:‌

password: Yup.string()
    .required('This field is required')
    .min(6, 'Must be at least 6 characters')
    .matches(/[!@#$%^&*(),.?":{}|<>]/, 'Must contain at least one special character')
    .matches(/\d/, 'Must contain at least one number');

Here we use the matches() function, passing in a regular expression to assert against. You could combine these cases into one regular expression, but the benefit of keeping them separate is it allows you to pinpoint which validation rule is failing. It also allows for a more granular error message and maintenance should the rules change in the future.

Other Useful Methods:

• length() – asserts the length of the string / number
• positive() – asserts the number type is a positive number
• email() – asserts that it is a valid email address
• url() – asserts that it is a valid URL
• min() / max() – asserts that the number is at least 'x' and less than 'y'
• ensure() – transforms undefined and null values to an empty string along with setting the default to an empty string.

Conclusion

As you can see, the possibilities with Yup are vast. Then combine this with the Formik library, and you can have rich, efficient, and easy to use forms.

This ease of use makes it so much quicker to get a form up and running on your web or mobile application, allowing you to focus on user experience, design, and business logic.

As always feel free to reach and discuss this article with me on Twitter, and don't forget to drop me a follow to hear about future articles and dev tips.

Two key concepts that developers need to understand are controlled and uncontrolled components. These concepts define how form data is handled within a React component.

Controlled components rely on React state to manage the form data, while uncontrolled components use the DOM itself to handle form data.

In this article, we will explore the differences between controlled and uncontrolled components, how to implement them, and some best practices for using each approach in your React applications.

Table of Contents

1. What are Controlled Components?
2. How Controlled Components Work
3. Benefits of using Controlled Components
4. Examples of Controlled Components
5. What are Uncontrolled Components?
6. How Uncontrolled Components Work
7. When to use Uncontrolled Components
8. Limitations to Uncontrolled Components
9. Examples of Uncontrolled Components
10. Factors to Consider When Choosing Between Controlled and Uncontrolled Components
11. Conclusion

What are Controlled Components?

Controlled components are form elements (like input, textarea, or select) that are managed by React state. This means that the value of the form element is set and updated through React state, making React the "single source of truth" for the form data.

By controlling form elements via state, you gain more control over user interactions and can easily enforce validation, format data, and respond to changes.

Here's an example of a controlled component:

import React, { useState } from 'react';

function ControlledComponent() {
  const [value, setValue] = useState('');

  const handleChange = (event) => {
    setValue(event.target.value);
  };

  const handleSubmit = (event) => {
    event.preventDefault();
    alert('A name was submitted: ' + value);
  };

  return (
    <form onSubmit={handleSubmit}>
      <label>
        Name:
        <input type="text" value={value} onChange={handleChange} />
      </label>
      <button type="submit">Submit</button>
    </form>
  );
}

export default ControlledComponent;

In this example:

• The value state holds the current value of the input field.
• The handleChange function updates the state whenever the user types in the input field.
• The handleSubmit function handles the form submission, using the current state value.

How Controlled Components Work

Controlled components in React ensure that the form data is handled by the React state, providing a consistent and predictable way to manage user input.

Here’s a breakdown of how these components work, including state management in the parent component, passing values as props to child components, handling user input with event handlers, and updating state in the parent component.

State Management in the Parent Component

State management is often handled in the parent component, especially when multiple child components need to interact or share state. The parent component maintains the state and passes it down to child components via props.

import React, { useState } from 'react';
import ChildComponent from './ChildComponent';

function ParentComponent() {
  const [inputValue, setInputValue] = useState('');

  return (
    <div>
      <h1>Controlled Component Example</h1>
      <ChildComponent value={inputValue} setValue={setInputValue} />
    </div>
  );
}

export default ParentComponent;

Passing Values as Props to a Child Component

The parent component passes the state value and a state updater function to the child component as props. This allows the child component to display the current state and update it when needed.

import React from 'react';

function ChildComponent({ value, setValue }) {
  const handleChange = (event) => {
    setValue(event.target.value);
  };

  return (
    <form>
      <label>
        Name:
        <input type="text" value={value} onChange={handleChange} />
      </label>
    </form>
  );
}

export default ChildComponent;

Handling User Input with Event Handlers

Event handlers are used to manage user input. When the user types into the input field, the onChange event triggers the handleChange function, which updates the state in the parent component.

function ChildComponent({ value, setValue }) {
  const handleChange = (event) => {
    setValue(event.target.value);
  };

  return (
    <form>
      <label>
        Name:
        <input type="text" value={value} onChange={handleChange} />
      </label>
    </form>
  );
}

Updating State in a Parent Component

When the state updater function (setValue) is called in the child component, it updates the state in the parent component. This causes the parent component to re-render, which in turn re-renders the child component with the new state value.

function ParentComponent() {
  const [inputValue, setInputValue] = useState('');

  return (
    <div>
      <h1>Controlled Component Example</h1>
      <ChildComponent value={inputValue} setValue={setInputValue} />
    </div>
  );
}

Putting It All Together

Here's the complete example showing how controlled components work with state management in the parent component:

// ParentComponent.jsx
import React, { useState } from 'react';
import ChildComponent from './ChildComponent';

function ParentComponent() {
  const [inputValue, setInputValue] = useState('');

  return (
    <div>
      <h1>Controlled Component Example</h1>
      <ChildComponent value={inputValue} setValue={setInputValue} />
    </div>
  );
}

export default ParentComponent;

// ChildComponent.jsx
import React from 'react';

function ChildComponent({ value, setValue }) {
  const handleChange = (event) => {
    setValue(event.target.value);
  };

  return (
    <form>
      <label>
        Name:
        <input type="text" value={value} onChange={handleChange} />
      </label>
    </form>
  );
}

export default ChildComponent;

Controlled components in React provide a good way to manage form data by using React state as the single source of truth. This approach involves managing state in the parent component, passing values and state updater functions as props to child components, handling user input with event handlers, and updating state in the parent component.

This method ensures consistent and predictable form behavior, making it easier to implement validation, conditional rendering, and other interactive features.

Benefits of Using Controlled Components

Controlled components offer several advantages that can significantly improve the development experience and functionality of React applications. Here are the key benefits:

Predictable State Management

Using controlled components ensures that the form data is always in sync with the React state. This predictability comes from having a single source of truth for the data, which is the state itself.

Since the state drives the UI, any change in the state immediately reflects in the form elements and vice versa. This makes it easier to debug and understand how data flows through your application.

Example:

import React, { useState } from 'react';

function PredictableForm() {
  const [name, setName] = useState('');

  const handleChange = (event) => {
    setName(event.target.value);
  };

  return (
    <div>
      <input type="text" value={name} onChange={handleChange} />
      <p>Current value: {name}</p>
    </div>
  );
}

In this example, the input field and the displayed text are always synchronized, providing a predictable behavior.

Easier Form Validation

Controlled components make it straightforward to implement form validation. Since the form data is stored in the component state, you can easily validate it before updating the state or on form submission. This approach allows you to provide real-time feedback to users as they interact with the form.

Example:

import React, { useState } from 'react';

function ValidatedForm() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState('');

  const handleChange = (event) => {
    const value = event.target.value;
    setEmail(value);

    if (!value.includes('@')) {
      setError('Invalid email address');
    } else {
      setError('');
    }
  };

  return (
    <div>
      <input type="email" value={email} onChange={handleChange} />
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </div>
  );
}

Here, the validation logic runs on every change, providing immediate feedback to the user if the input is invalid.

Integration with Complex UI Libraries

Controlled components integrate seamlessly with complex UI libraries and frameworks, such as Redux for state management or Formik for handling forms.

By managing form data in the component state, you can easily connect your forms to these libraries and benefit from their advanced features like global state management, asynchronous data fetching, and more.

Example with Formik:

import React from 'react';
import { Formik, Form, Field, ErrorMessage } from 'formik';
import * as Yup from 'yup';

const SignupForm = () => (
  <Formik
    initialValues={{ email: '' }}
    validationSchema={Yup.object({
      email: Yup.string().email('Invalid email address').required('Required'),
    })}
    onSubmit={(values, { setSubmitting }) => {
      setTimeout(() => {
        alert(JSON.stringify(values, null, 2));
        setSubmitting(false);
      }, 400);
    }}
  >
    {({ isSubmitting }) => (
      <Form>
        <label htmlFor="email">Email</label>
        <Field type="email" name="email" />
        <ErrorMessage name="email" component="div" />
        <button type="submit" disabled={isSubmitting}>
          Submit
        </button>
      </Form>
    )}
  </Formik>
);

export default SignupForm;

In this example, Formik handles form state and validation, demonstrating how controlled components can be part of more complex setups.

Controlled components provide predictable state management, easier form validation, and seamless integration with complex UI libraries.

By keeping the form data in the React state, you ensure consistency and control over your application's behavior, making it easier to build and maintain interactive and dynamic user interfaces.

Examples of Controlled Components

Controlled components are fundamental in React for handling form inputs in a predictable and manageable way.

Here are some examples of how you can implement controlled components for various types of form inputs, including text fields, email fields, password fields, select menus, checkboxes, and radio buttons.

Input Fields (Text, Email, Password)

Text Input

import React, { useState } from 'react';

function TextInput() {
  const [text, setText] = useState('');

  const handleChange = (event) => {
    setText(event.target.value);
  };

  return (
    <div>
      <label>
        Text:
        <input type="text" value={text} onChange={handleChange} />
      </label>
      <p>Entered Text: {text}</p>
    </div>
  );
}

export default TextInput;

Email Input

import React, { useState } from 'react';

function EmailInput() {
  const [email, setEmail] = useState('');

  const handleChange = (event) => {
    setEmail(event.target.value);
  };

  return (
    <div>
      <label>
        Email:
        <input type="email" value={email} onChange={handleChange} />
      </label>
      <p>Entered Email: {email}</p>
    </div>
  );
}

export default EmailInput;

Password Input

import React, { useState } from 'react';

function PasswordInput() {
  const [password, setPassword] = useState('');

  const handleChange = (event) => {
    setPassword(event.target.value);
  };

  return (
    <div>
      <label>
        Password:
        <input type="password" value={password} onChange={handleChange} />
      </label>
      <p>Entered Password: {password}</p>
    </div>
  );
}

export default PasswordInput;

Select Menus

import React, { useState } from 'react';

function SelectMenu() {
  const [option, setOption] = useState('option1');

  const handleChange = (event) => {
    setOption(event.target.value);
  };

  return (
    <div>
      <label>
        Choose an option:
        <select value={option} onChange={handleChange}>
          <option value="option1">Option 1</option>
          <option value="option2">Option 2</option>
          <option value="option3">Option 3</option>
        </select>
      </label>
      <p>Selected Option: {option}</p>
    </div>
  );
}

export default SelectMenu;

Checkboxes

import React, { useState } from 'react';

function Checkbox() {
  const [isChecked, setIsChecked] = useState(false);

  const handleChange = (event) => {
    setIsChecked(event.target.checked);
  };

  return (
    <div>
      <label>
        Accept Terms:
        <input type="checkbox" checked={isChecked} onChange={handleChange} />
      </label>
      <p>Checked: {isChecked ? 'Yes' : 'No'}</p>
    </div>
  );
}

export default Checkbox;

Radio Buttons

import React, { useState } from 'react';

function RadioButton() {
  const [selectedOption, setSelectedOption] = useState('option1');

  const handleChange = (event) => {
    setSelectedOption(event.target.value);
  };

  return (
    <div>
      <label>
        <input
          type="radio"
          value="option1"
          checked={selectedOption === 'option1'}
          onChange={handleChange}
        />
        Option 1
      </label>
      <label>
        <input
          type="radio"
          value="option2"
          checked={selectedOption === 'option2'}
          onChange={handleChange}
        />
        Option 2
      </label>
      <label>
        <input
          type="radio"
          value="option3"
          checked={selectedOption === 'option3'}
          onChange={handleChange}
        />
        Option 3
      </label>
      <p>Selected Option: {selectedOption}</p>
    </div>
  );
}

export default RadioButton;

Controlled components provide a clear and consistent way to handle form inputs in React. By using React state to manage the values of input fields, select menus, checkboxes, and radio buttons, you ensure that the UI remains in sync with the state.

This approach simplifies validation, makes data handling predictable, and facilitates integration with complex UI libraries.

What are Uncontrolled Components?

Uncontrolled components in React manage their own state internally rather than relying on React state. This approach is useful for simple forms where you don't need to manipulate the input data through React state updates.

Example:

import React, { Component } from 'react';

class UncontrolledComponent extends Component {
  constructor(props) {
    super(props);
    // Create a ref to hold the input DOM element
    this.inputRef = React.createRef();
  }

  handleSubmit = () => {
    // Access the input value using the ref
    console.log(this.inputRef.current.value);
  }

  render() {
    return (
      <div>
        {/* Use ref attribute to attach the ref to the input element */}
        <input 
          type="text" 
          ref={this.inputRef} 
        />
        <button onClick={this.handleSubmit}>Submit</button>
      </div>
    );
  }
}

• Ref Usage: In uncontrolled components, we use the ref attribute to create a reference (this.inputRef) to the DOM node of the input field.
• Handling Input: When the user enters data and clicks "Submit", this.inputRef.current.value allows us to directly access the current value of the input field without involving React state.
• Advantages: Uncontrolled components can be simpler and faster for basic form handling. They are often used when the form data is not needed in React state for any processing or validation.

Key Points:

• Internal State: Uncontrolled components manage their state internally with the help of refs, not with React state updates.
• Direct DOM Access: Accessing form data is done directly through DOM refs (this.inputRef.current.value).
• Simplicity: They are straightforward for simple forms where real-time validation or complex form interactions are not necessary.

Uncontrolled components are handy in scenarios where you want a lightweight approach to handling form data without the overhead of managing state in React.

How Uncontrolled Components Work

Uncontrolled components manage their state internally using DOM refs (useRef hook in functional components or React.createRef() in class components) to access form element values directly.

Unlike controlled components, where form data is managed through React state and updated via setState, uncontrolled components bypass React's state management for handling form inputs.

Direct DOM Access with useRef Hook

In functional components, the useRef hook allows us to create a mutable reference that persists across renders. We can use this ref to directly access DOM nodes, such as input fields.

Example:

import React, { useRef } from 'react';

function UncontrolledComponent() {
  const inputRef = useRef(null); // Create a ref to hold the input DOM element

  const handleSubmit = () => {
    // Access the input value using the ref
    console.log(inputRef.current.value);
  };

  return (
    <div>
      <input type="text" ref={inputRef} />
      <button onClick={handleSubmit}>Submit</button>
    </div>
  );
}

export default UncontrolledComponent;

Accessing an Element's Value on Submit

In the example above:

• Creating a Ref: const inputRef = useRef(null); initializes a ref named inputRef to hold the reference to the input DOM element.
• Handling Submit: When the "Submit" button is clicked (onClick={handleSubmit}), the handleSubmit function retrieves the current value of the input field using inputRef.current.value.

Key Points:

• DOM Access: The useRef hook allows direct access to DOM elements, enabling us to interact with them without updating React state.
• Form Submission: On form submission (onClick={handleSubmit}), the function accesses the current value of the input field through inputRef.current.value.
• Simplicity: Uncontrolled components are straightforward for basic form handling scenarios where direct DOM manipulation suffices, avoiding the need for managing state updates in React.

Using uncontrolled components with useRef is particularly useful for handling forms where real-time validation or complex interactions aren't necessary, focusing instead on simplicity and performance.

When to Use Uncontrolled Components

Uncontrolled components are ideal in specific scenarios where simplicity and direct DOM manipulation are advantageous over managing state with React.

Here are the key situations when using uncontrolled components is beneficial:

1. Simple Forms with Limited Interactions

Uncontrolled components shine in scenarios where:

• The Forms Arent' That Complex: The form is straightforward with minimal input fields and does not require complex validation or dynamic updates based on other form inputs.
• Performance is Important: Directly accessing form values via DOM refs (useRef or React.createRef()) can be more performant than updating React state for each input change, especially in large forms.
• You want Simplicity: When you prefer a simpler implementation without managing state updates and re-renders for form inputs.

2. Focus Management (Selecting Text)

In some cases, you might need to manage user interaction such as selecting text within an input field or programmatically focusing on a specific input without triggering React state updates unnecessarily.

Uncontrolled components allow you to:

• Directly manipulate the DOM: Use DOM methods like select() on the input element directly via refs to manage focus or text selection.
• Handling focus and text selection directly with refs: This can be more efficient and straightforward compared to triggering state updates and managing focus state in React components.

Example Use Case:

import React, { useRef } from 'react';

function UncontrolledComponent() {
  const inputRef = useRef(null); // Create a ref to hold the input DOM element

  const handleFocus = () => {
    inputRef.current.select(); // Selects all text in the input field
  };

  return (
    <div>
      <input type="text" ref={inputRef} defaultValue="Initial Value" />
      <button onClick={handleFocus}>Select Text</button>
    </div>
  );
}

export default UncontrolledComponent;

In this example, clicking the "Select Text" button calls inputRef.current.select() to select all text within the input field directly, without involving React state updates. This is a simple yet effective use of uncontrolled components for managing focus and text selection.

Limitations of Uncontrolled Components

Using uncontrolled components in React can offer simplicity and performance benefits in certain scenarios, but they also come with limitations that are important to consider:

Difficulty in Form Validation:

• Uncontrolled components can make form validation more challenging compared to controlled components. Since the form data is managed internally by the DOM rather than React state, validating and ensuring data consistency across multiple inputs can be complex.
• Validation logic often involves accessing and checking each input's value directly through refs (ref.current.value). This approach can lead to more manual and error-prone validation code, especially in forms with complex validation requirements.

Less Predictable State Management:

• Uncontrolled components bypass React's state management, which can lead to less predictable state handling in complex applications. Changes in form data are not automatically synchronized with React's state updates or other component state, potentially leading to inconsistencies.
• This lack of synchronization can make it challenging to maintain a single source of truth for form data across different components or when integrating with other state management solutions like Redux or Context API.

Limited React Ecosystem Integration:

• Uncontrolled components may not fully leverage React's ecosystem features, such as state persistence, time-travel debugging (with Redux), or seamless integration with third-party libraries designed for controlled components.
• Components relying on React state benefit from these features, enhancing developer productivity and application maintainability.

Examples of Uncontrolled Components

Uncontrolled components in React are particularly useful for handling input fields and textarea elements where direct DOM manipulation suffices, and React state management isn't necessary.

Here are examples of how uncontrolled components can be applied:

1. Input Fields (Read-only or Pre-filled Data)

Uncontrolled components can be used when you need to display read-only or pre-filled data in an input field without managing its state in React.

Example:

import React, { useRef } from 'react';

function UncontrolledInput() {
  const initialValue = 'Hello, World!';
  const inputRef = useRef(null); // Create a ref to hold the input DOM element

  const handleFocus = () => {
    inputRef.current.select(); // Selects all text in the input field on focus
  };

  return (
    <div>
      {/* Using defaultValue for pre-filled data */}
      <input type="text" ref={inputRef} defaultValue={initialValue} readOnly />
      <button onClick={handleFocus}>Select Text</button>
    </div>
  );
}

export default UncontrolledInput;

In this example:

• The defaultValue attribute sets the initial value of the input field.
• readOnly attribute prevents users from editing the input field, making it read-only.
• useRef hook manages focus and selection of text within the input field using inputRef.current.

2. Textarea Elements

Uncontrolled components are also applicable to textarea elements, especially when dealing with multiline text input where immediate state updates are not necessary.

Example:

import React, { useRef } from 'react';

function UncontrolledTextarea() {
  const initialText = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';
  const textareaRef = useRef(null); // Create a ref to hold the textarea DOM element

  const handleClear = () => {
    textareaRef.current.value = ''; // Clear textarea content directly
  };

  return (
    <div>
      {/* Using defaultValue for pre-filled content */}
      <textarea ref={textareaRef} defaultValue={initialText} rows={4} cols={50} />
      <button onClick={handleClear}>Clear Text</button>
    </div>
  );
}

export default UncontrolledTextarea;

In this example:

• The defaultValue attribute sets the initial content of the textarea.
• useRef hook manages direct manipulation of textarea content using textareaRef.current.
• rows and cols attributes define the dimensions of the textarea.

Key points:

• Direct DOM Access: Uncontrolled components leverage useRef to directly manipulate DOM elements for managing input fields and textarea content.
• Performance: Suitable for scenarios where real-time updates or complex state management aren't required, enhancing performance by avoiding unnecessary state updates.
• Simplicity: Provides a straightforward approach to handling form elements with default or read-only values, maintaining simplicity in component logic.

These examples demonstrate how uncontrolled components can handle input fields and textarea elements effectively in React applications, focusing on simplicity and direct DOM manipulation for specific use cases.

Factors to Consider When Choosing Between Controlled and Uncontrolled Components

When deciding between controlled and uncontrolled components in React, several factors should be considered to determine which approach best suits your application's requirements. Here are key considerations for each factor:

1. Complexity of Form

Controlled Components:

• Advantages: Suitable for complex forms where you need precise control over the form state and its interaction with other components.
• Usage: Use controlled components when form inputs depend on each other, require validation, or when you need to synchronize form state across multiple components or pages.

Uncontrolled Components:

• Advantages: Simplify implementation for basic forms with minimal interactivity or where direct DOM manipulation suffices.
• Usage: Ideal for simple forms without complex validation or when managing form state in React isn't necessary for your use case.

2. Need for Form Validation

Controlled Components:

• Advantages: Easier integration with form validation libraries (for example, Formik, Yup) since form state is managed within React state.
• Usage: Use controlled components when implementing complex validation rules, such as conditional validation or asynchronous validation logic.

Uncontrolled Components:

• Challenges: Handling form validation can be more manual and less integrated, as form data is managed directly through DOM manipulation.
• Usage: Consider uncontrolled components for simple forms where validation requirements are minimal or where custom validation logic can be managed without relying heavily on React state updates.

3. Integration with External Libraries

Controlled Components:

• Advantages: Seamlessly integrates with external state management solutions like Redux or React's Context API for managing global application state.
• Usage: Prefer controlled components when your application requires integration with third-party libraries or when leveraging advanced React ecosystem features (for example, time-travel debugging with Redux).

Uncontrolled Components:

• Considerations: May require additional effort to integrate with external libraries that assume controlled component behavior.
• Usage: Use uncontrolled components when external state management isn't necessary, focusing on lightweight implementation and minimizing dependencies.

Additional Considerations:

Performance:

Controlled components may incur overhead due to frequent state updates, whereas uncontrolled components can offer better performance for simple forms by reducing re-renders.

Developer Preference:

Consider team familiarity and preferences with React state management patterns when deciding between controlled and uncontrolled components.

Summary:

Choose Controlled Components for complex forms, robust validation needs, and seamless integration with external state management and validation libraries.

Opt for Uncontrolled Components for simpler forms, minimal validation requirements, and when direct DOM manipulation provides sufficient functionality without the need for managing form state in React.

Conclusion

The choice between controlled and uncontrolled components in React hinges on several critical factors that determine the optimal approach for form management within your application.

Ultimately, the decision should align with your project's specific needs, considering factors such as form complexity, validation requirements, integration with external libraries, and developer preferences.

By carefully assessing these factors, you can implement the most effective form handling strategy in React that balances functionality, performance, and ease of maintenance.

Connect with me on LinkedIn.

In this article, you'll learn how to optimize embedded links in your front-end development projects to meet your desired specifications.

The inspiration for this article came from a problem I encountered while creating a portfolio site and having issues embedding external sites—until I discovered an efficient tool to help.

To fully grasp this tutorial, there are some of the prerequisites:

• A good knowledge of JavaScript.
• Familiarity with React JS and npm package installation.
• Proficiency in CSS.

Let's get started!

The Concept of Micro-linking

Micro-linking entails embedding a link to an external website within a default web page. Embedding links are different from the default HTML “alt href” attributes commonly used by web developers.

This concept also entails extracting relevant site metadata, information and relevant images from the embedded external site link. This contributes to providing more knowledge about the external website in question.

This feature isn’t all new as it's commonly used among high-end blog posts, video streaming sites and e-commerce sites. This feature is also utilized by site owners to customize how their site information is viewed when embedded in advertisement sites.

How Does Micro-linking Work?

Ordinarily, embedding a URL using plain HTML code doesn’t generate any image or text preview. However, this isn’t the case for micro-links. This occurs due to the use of an application programming interface to extract relevant info from the site being referenced and then outputting it to the developer in JSON format for easy customization and usage.

There are quite a lot of micro-linking services available commercially. Some examples are Embedly, Open Graph protocol, microlink.io, and so on.

Introduction to the Microlink Package

In this tutorial, we'll create a site that uses a Node package known as Microlink to generate previews. Details regarding URL customization will also be illustrated.

This is customization allows developers to easily extract relevant link previews from the Microlink site, skipping the hassle of interacting with the website interface.

For further learning, the library has a rich documentation site which can be accessed here.

How to Set Up Your Project

To build the link preview site, we'll utilize the React Vite tool. Entering the command npm create-vite-app@latest links immediately spins up a folder named latest links which we'll use in building this project.

Also, the microlink package needs to be installed. To do that, navigate to the command line and run the npm i @microlinks/react command.

Demo Project

First of all, we'll be create the default JSX functional component for this project.

function App() {
return (
<>
</>
)
}
export default App

Next, we'll be import and initialize the installed microlink library:

import Microlink from '@microlink/react'

After that, we can initialize the package within the App function:

return (
<>
<Microlink
url= " https://tobilyn77.hashnode.dev/nodejs-clustering-and-load-balancing-comprehensive-overview "  />
</>
)

The URL variable I included is a link to an external site I intend to preview on my local site. This can be changed to whichever site you would like to preview.

On running this, you should see something similar to this.

microlink project webpage

We have successfully set up a micro-link in our application. But that’s not all, the power of the package is enormous, providing a level of flexibility in controlling the layout and size of the micro-links.

Size Tweaking

Size tweaking simply involves adjusting the size or dimensions of a variable to suit different specifications. In this case, we'll adjust the size of the embedded links.

<Microlink
url= "https://tobilyn77.hashnode.dev/nodejs-clustering-and-load-balancing-comprehensive-overview" />
<p></p>
<Microlink
url= "https://tobilyn77.hashnode.dev/nodejs-clustering-and-load-balancing-comprehensive-overview"  size="small"/>
<p></p>

micro-links with different sizes

The code above specifies the size of the micro-link to be rendered. If the size is indicated to be small, the dimension of the micro-link gets altered. It also allows for large and medium sizes, and by default, the medium size is what is usually seen when no size dimension is specified.

Also, the microlink self-enclosing tag allows for CSS styling. This can be achieved by including the style variable within the microlink tag.

<Microlink
url= "https://tobilyn77.hashnode.dev/nodejs-clustering-and-load-balancing-comprehensive-overview"
style= {{color: 'red'}} />

micro-link with the color set to red

As you can see in the code above, the microlink was styled with the color red and that reflected in the output. Other CSS styling can also be applied to give users an aesthetic feel to your site.

Conclusion

With this, we have come to the end of the tutorial. We hope you’ve learned link previewing via the microlink package.

Feel free to drop any questions or comments in the comment box below. You can also interact with me on my blog and check out my other articles here. Till next time, keep on coding!

It's a no-brainer that humans love beautiful things. We all love products that look easy on the eyes.

In this article, we're going to learn how to create animations that wow users with the use of Framer motion and React-Router-Dom.

Prerequisites

To be able to follow what we're doing in this article, you should have some knowledge of React, Framer motion and React-Router-DOM.

To learn Framer motion better, you can study their documentation.

Node.js should also be installed on your system, and you should have a working code editor. I'll be using VS Code.

How to Set Up the Project

To set up our project we're going to use Vite to set up our React development environment.

1. Open the terminal in VScode. You can use Ctrl + backtick(`)

2. In your terminal, enter the following command:

npm create vite@latest

3. Follow the prompts to name your project and choose your desired framework. In our case, we're using React. This will be a JavaScript project.

4. Go to your project directory and use npm i in the terminal.

5. To start your project use npm run dev.

6. Remember to clean your project by removing the code in App.js and your CSS files in the src folder.

How to Initialize Framer Motion and React-Router-Dom

1. To install Framer-motion in your project open the terminal and enter:

npm i framer-motion

2. To install React-Router-DOM in your project open the terminal and enter:

npm i react-router-dom

How to Set Up Components and Basic Routing with React-Router-DOM

Let's set up our components and the pages we'll be routing to for this project.

1. In src, create a new folder named components.

2. We'll add four files in this folder named Home.jsx, About.jsx, Projects.jsx and Navbar.jsx.

3. Inside the first three, we're going to create a React functional component. Change the content of the h1 tag in each component:

const Home = () => {
 return (
    <div>
     <h1>Home</h1>
    </div>
 )
 }

 export default Home

4. In the Navbar, we need to import Link from React-Router-DOM to create anchor elements. We then need to create a container housing our logo and nav links. The logo will link the points to our index page.

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

const Navbar () => {
 return (
     <div className="nav">
      <div className="logo">
         <Link className="nav-link" to="/">Lennythedev</Link>
     </div>
     <div>
        <div className="nav-links">
           <div className="nav-item">
            <Link className="nav-link" to="/">Home</Link>
           </div>
           <div className="nav-item">
            <Link className="nav-link" to="/">About</Link>
           </div>
           <div className="nav-item">
            <Link className="nav-link" to="/">Projects</Link>
           </div>
     </div>
     </div>
     </div>
  )
 }

5. Now let's go to our index.js or main.js file. The goal is to wrap our entire app with BrowserRouter which will enable routing within our application.

import React from "react"
import ReactDOM from 'react-dom/client'
import App from './App.jsx'
import './index.css'
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <Router>
      <Routes>
        <Route path='/*' element={<App />} />
      </Routes>
    </Router>
  </React.StrictMode>,
)

6. Now in App.js, we're going to complete the final step of our configuration. We'll import our components, and some features from React-Router-DOM and render our components. By using useLocation feature from React-Router-DOM, we can set the current location of the routes by setting the key to the current path.

import './App.css'
import { Routes, Route, useLocation } from 'react-router-dom'
import NavBar from './components/NavBar';
import Home from './components/Home';
import Projects from './components/Projects';
import About from './components/About';

function App() {
  const location = useLocation();
  return (
    <>
       <NavBar />
       <AnimatePresence mode='wait'>
       <Routes location={location} key={location.pathname}>
        <Route index element={<Home />} />
        <Route path='/projects' element={<Projects />}/>
        <Route path='/about' element={<About />}/>
       </Routes>
       </AnimatePresence>
    </>
  )
}

export default App

7. Now we can add our styling in App.css:

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
  color: white;
  font-family: "Fira Sans Condensed", sans-serif;
}

html,
body {
  font-family: "Fira Sans Condensed", sans-serif;
  background: rgb(0, 162, 255);
}

.nav {
  position: fixed;
  width: 100%;
  display: flex;
  justify-content: space-between;
}

.nav-links {
  display: flex;
  cursor: pointer;
}

.logo, .nav-item {
  margin: 2em;
  font-weight: 400;
  font-size: 1.5vw;
}

h1{
  width: 80%;
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  text-align: center;
  font-weight: 500;
  font-size: 10vw;
  line-height: 1;
  text-transform: uppercase;
}

a {
  text-decoration: none;
  font-weight: 500;
}

8. After following all the steps your app should look like this:

styled webpage without animation

How to Create Transitions Using Framer Motion

Finally let's create our animation for transitions between pages.

1. Create a file in components named Box.jsx and import motion from framer-motion.

2. We can then return two divs, with classNames of slide-in and slide-out one for sliding in and another for sliding out.

3. We insert our animation in these divs with the help of framer-motion:

import { motion } from "framer-motion"

export default function Box() {
  return(
    <div>
     <motion.div
        className="slide-in"
        initial={{ scaleY: 0 }}
        animate={{ scaleY: 0 }}
        exit={{ scaleY: 1 }}
        transition={{ duration: 1, ease: [0.22, 1, 0.36, 1] }}
     />
     <motion.div
     className="slide-out"
        initial={{ scaleY: 1 }}
        animate={{ scaleY: 0 }}
        exit={{ scaleY: 0 }}
        transition={{ duration: 1, ease: [0.22, 1, 0.36, 1] }}
     />
    </div>
  )
}

4. Next, we add our styling in our CSS file for slide-in and slide-out in our App.css

.slide-in {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100vh;
  background: #0f0f0f;
  transform-origin: bottom;
}

.slide-out {
  position: fixed;
  top: 0;
  left: 0;
  height: 100vh;
  background: #0f0f0f;
  transform-origin: top;
}

5. Finally, the last step is to use AnimatePresence from framer-motion in our App.js file and wrap the entire App in AnimatePresence and set the mode as wait. If you want to learn more about a AnimatePresence visit the framer-motion docs.

import './App.css'
import { Routes, Route, useLocation } from 'react-router-dom'
import NavBar from './components/NavBar';
import Home from './components/Home';
import Projects from './components/Projects';
import About from './components/About';
import { AnimatePresence } from 'framer-motion';

function App() {
  const location = useLocation();
  return (
    <>
       <NavBar />
       <AnimatePresence mode='wait'>
       <Routes location={location} key={location.pathname}>
        <Route index element={<Home />} />
        <Route path='/projects' element={<Projects />}/>
        <Route path='/about' element={<About />}/>
       </Routes>
       </AnimatePresence>
    </>
  )
}

export default App

6. Finally, our work should look the same as the video below:

Conclusion

Creating multi-page animations with Framer Motion and React-Router-Dom enhances user experience by providing smooth transitions.

This integration leverages the power of Framer Motion's animation capabilities with React-Router-Dom's routing features, resulting in dynamic, interactive web applications.

The virtual DOM is a lightweight copy of the real DOM that allows React to manage changes more efficiently by minimizing the direct manipulation required on the real DOM. This process significantly enhances the performance of web apps.

Understanding the virtual DOM is essential for developers who want to get the best out of React. It plays a key role in how React updates the UI, ensuring that changes are applied quickly without unnecessary re-renders.

In this article, you'll learn:

• What the virtual DOM is and how it works
• How the virtual DOM compares to the real DOM
• Benefits of using the virtual DOM
• How React uses the virtual DOM
• How the virtual DOM compares to the shadow DOM
• Common misconceptions about the virtual DOM

What Is the Virtual DOM and How Does It Work?

The virtual DOM is an in-memory representation of the real DOM elements. Instead of interacting directly with the real DOM, which can be slow and costly in terms of performance, React creates a virtual representation of the UI components. This virtual representation is a lightweight JavaScript object that mirrors the structure of the real DOM.

Here's a step-by-step process of how the virtual DOM works:

1. Step 1 – Initial Rendering: when the app starts, the entire UI is represented as a Virtual DOM. React elements are created and rendered into the virtual structure.
2. Step 2 – State and Props Changes: as the states and props change in the app, React re-renders the affected components in the virtual DOM. These changes do not immediately impact the real DOM.
3. Step 3 – Comparison Using Diff Algorithm: React then uses a diffing algorithm to compare the current version of the Virtual DOM with the previous version. This process identifies the differences (or "diffs") between the two versions.
4. Step 4 – Reconciliation Process: based on the differences identified, React determines the most efficient way to update the real DOM. Only the parts of the real DOM that need to be updated are changed, rather than re-rendering the entire UI. This selective updating is quick and performant.
5. Step 5 – Update to the Real DOM: finally, React applies the necessary changes to the real DOM. This might involve adding, removing, or updating elements based on the differences detected in step 3.

For example, let's say we have the following counter functionality in the App component:

import React, { useState } from 'react';

function App() {
 const [count, setCount] = useState(0);

 return (
   <div>
     <h1>Counter: {count}</h1>
     <button onClick={() => setCount(count + 1)}>Increment</button>
   </div>
 );
}

export default App;

The virtual DOM representation will look like this:

{
 "type": "div",
 "props": {},
 "children": [
   {
     "type": "h1",
     "props": {},
     "children": [
       {
         "type": "TEXT_ELEMENT",
         "props": {
           "nodeValue": "Counter: 0"
         }
       }
     ]
   },
   {
     "type": "button",
     "props": {
       "onClick": "setCount(count + 1)"
     },
     "children": [
       {
         "type": "TEXT_ELEMENT",
         "props": {
           "nodeValue": "Increment"
         }
       }
     ]
   }
 ]
}

When the Increase button is clicked once, only the h1 element is changed:

{
 "type": "h1",
 "props": {},
 "children": [
   {
     "type": "TEXT_ELEMENT",
     "props": {
       "nodeValue": "Counter: 1"
     }
   }
 ]
}

Comparing the Virtual DOM to the Real DOM

To see the advantages of the virtual DOM, it's important to understand how it differs from the real DOM. The real DOM and the virtual DOM serve similar purposes but operate in distinct ways with significant implications for performance and efficiency.

The real DOM is a built-in standard interface in browsers that represents and interacts with HTML elements, from Doctype declaration and the root html element to every other element in it.

This real DOM represents the whole HTML document as a tree structure and allows JavaScript to manipulate and change HTML documents. Sometimes when those changes occur, the whole document might re-render.

This is in contrast to the virtual DOM, which uses a diff algorithm to compare the current and previous versions of updates to the DOM. It only re-renders the parts of the UI that have changed, instead of the whole thing.

Benefits of Using the Virtual DOM in Web Development

Simplified Development

The Virtual DOM lets you write code in a more declarative style. This means that instead of writing detailed instructions on how to update the UI, you can simply describe what the UI should look like, and React takes care of the rest. This is made possible by React's declarative syntax and its component-based architecture.

Improved Performance

One of the major advantages of using the virtual DOM is the significant performance improvement it offers. Direct manipulation of the real DOM is slow and can lead to performance issues, especially in complex applications.

Enhanced User Experience

The Virtual DOM contributes to a better UX by ensuring that UI updates are smooth, responsive, and without full-page refreshes. Users are less likely to experience lag or jank, resulting in a more seamless interaction with the app.

Cross-platform Development

The principles of the Virtual DOM are not limited to web development only. React Native – a version of React for building cross-platform mobile apps – uses a similar approach. This increases productivity and reduces development time because you can reuse code across web and mobile platforms

Common Misconceptions About the Virtual DOM

There are a few misconceptions about the virtual DOM. Let's look at five of these misconceptions and the realities of each of them.

The Virtual DOM Is a Browser Feature

Reality: the virtual DOM is an abstraction implemented by React, not a browser feature. Browsers have the real DOM, which is the standard way to represent and interact with HTML documents. The virtual DOM exists solely in memory within React and is used to optimize updates to the real DOM.

The Virtual DOM Replaces the Real DOM

Reality: The virtual DOM acts as an intermediary between React and the browser, not a replacement for the real DOM. The real DOM is still what the browser uses to render the UI, but the updates to it are managed through the Virtual DOM.

React is the Only Library and Framework that Uses the Virtual DOM

Reality: React only popularized the concept of the virtual DOM, it is not the only library or framework that uses it. Other frameworks like VueJS and SolidJS also use the virtual DOM to update the UI.

The Virtual DOM Solves All Performance Problems

Reality: The virtual DOM can significantly improve performance, but it is not a magical solution to all problems. Poor coding practices, unnecessary renders, and large component trees can still lead to performance issues.

The Virtual DOM and Shadow DOM Are the Same

Reality: The virtual DOM and shadow DOM are not the same thing. The virtual DOM is a lightweight copy of the Real DOM with which React optimize UI updates. On the other hand, shadow DOM is a browser technology used to encapsulate the styles and structure of web components.

Real DOM vs Virtual DOM vs Shadow DOM

Now that we've established that the virtual DOM, shadow DOM, and real DOM are not the same, let's look at the differences between the three of them.