DEV Community: Abanoub Kerols

Server-Side Rendering (SSR) and Hydration: How Modern Web Applications Become Fast and Interactive

Abanoub Kerols — Sat, 03 Oct 2026 21:11:04 +0000

Modern frontend frameworks have changed dramatically.

Applications that once rendered everything in the browser can now render HTML on the server, send meaningful content to the user immediately, and then transform that static HTML into a fully interactive application.

Two concepts are at the center of this architecture:

Server-Side Rendering (SSR)
Hydration

They are often mentioned together, but they solve different problems.

Understanding how they work internally is important if you work with Angular, React, Next.js, Nuxt, or modern full-stack applications.

In this article, we will build the concepts from first principles, understand the browser lifecycle, compare CSR vs SSR, understand hydration, explore common problems, and finally build a complete SSR + hydration project.

1. The Traditional Client-Side Rendering Model

Before understanding SSR, let's start with the traditional approach.

In a typical Client-Side Rendering (CSR) application:

Browser
   |
   | GET /
   v
Server
   |
   | HTML + JavaScript bundles
   v
Browser
   |
   | Download JS
   v
JavaScript executes
   |
   v
Application renders UI
   |
   v
User sees the page

For example, the server might initially return:

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>

<body>
  <div id="root"></div>

  <script src="/assets/main.js"></script>
</body>
</html>

The important part is:

<div id="root"></div>

There isn't much actual application content in the initial HTML.

JavaScript must execute before the user gets the real UI.

2. What Happens During CSR?

Let's imagine this Angular/React-style application:

function App() {
  return (
    <main>
      <h1>Hello World</h1>
      <p>Welcome to my application.</p>
    </main>
  );
}

The browser initially receives:

<div id="root"></div>

Then:

Download JavaScript
       ↓
Parse JavaScript
       ↓
Execute JavaScript
       ↓
Create components
       ↓
Fetch data
       ↓
Render DOM
       ↓
User sees content

This can be perfectly fine.

But there is a problem.

The browser has to do a lot of work before the user sees meaningful content.

This becomes especially noticeable on:

slow networks
low-end mobile devices
large JavaScript applications
content-heavy websites
SEO-sensitive applications

3. The Idea Behind Server-Side Rendering

SSR changes the responsibility.

Instead of asking the browser to construct the initial HTML, we ask the server to render the application first.

The architecture becomes:

Browser
   |
   | GET /
   v
Application Server
   |
   | Render application
   v
HTML
   |
   | Send HTML
   v
Browser
   |
   | Display HTML immediately
   v
User sees content

For example, instead of:

<div id="root"></div>

the browser receives:

<div id="root">
  <main>
    <h1>Hello World</h1>
    <p>Welcome to my application.</p>
  </main>
</div>

The browser can display this content immediately.

But there is another problem.

The HTML is visible...

but is it interactive?

Not necessarily.

That brings us to hydration.

4. SSR Is Not the Same as Hydration

This distinction is extremely important.

SSR answers:

Who generates the initial HTML?

Answer:

The server.

Hydration answers:

How does the browser turn server-generated HTML into an interactive application?

Answer:

Client-side JavaScript attaches to the existing HTML.

So:

SSR
 ↓
Generate HTML on server
 ↓
Send HTML to browser
 ↓
Browser displays HTML
 ↓
Hydration
 ↓
JavaScript takes over
 ↓
Application becomes interactive

SSR and hydration are complementary concepts.

5. A Simple Analogy

Think about a restaurant.

CSR

The restaurant gives you:

Ingredients + recipe

You must cook the meal yourself.

SSR

The restaurant gives you:

A finished meal

You can immediately eat it.

But the restaurant still needs to give you:

Fork + knife

so you can interact with it.

That's hydration.

SSR = prepare the meal

Hydration = make the meal usable

6. What Exactly Is Hydration?

Suppose the server sends:

<button id="increment">
  Count: 0
</button>

The browser can display the button.

But the browser doesn't automatically know:

button.onclick = incrementCounter;

The server generated HTML.

The client application must now connect its JavaScript behavior to that existing DOM.

Conceptually:

Server HTML
     |
     v
<button>Count: 0</button>
     |
     | Hydration
     v
Existing DOM + JavaScript behavior
     |
     v
Interactive application

The framework doesn't necessarily throw away the existing DOM and recreate everything.

Instead, it attempts to reuse the server-rendered DOM.

7. SSR + Hydration Lifecycle

A simplified lifecycle looks like this:

             SERVER
               |
               v
        Application Code
               |
               v
        Render Components
               |
               v
           HTML Output
               |
               |
        HTTP Response
               |
               v
             BROWSER
               |
               v
        Parse HTML
               |
               v
       Display Content
               |
               v
       Download JS
               |
               v
          Hydration
               |
               v
       Attach Behavior
               |
               v
      Fully Interactive App

This is the fundamental architecture.

8. Why SSR Improves Perceived Performance

Imagine an application that takes:

HTML request             100ms
JavaScript download      500ms
JavaScript execution     300ms
API requests              300ms
Rendering                 100ms

With pure CSR, the user may wait for several of these stages before meaningful content appears.

With SSR, the server can generate the initial HTML:

Request
  ↓
Server renders HTML
  ↓
HTML arrives
  ↓
User sees content

JavaScript still needs to load.

But the user doesn't necessarily stare at an empty page while waiting.

This can improve metrics such as:

First Contentful Paint (FCP)
Largest Contentful Paint (LCP)
perceived performance

However, SSR is not automatically faster in every situation.

The server now has more work to perform.

9. SSR vs CSR

Let's compare them.

Feature	CSR	SSR
Initial HTML	Mostly empty shell	Meaningful HTML
Rendering	Browser	Server
Initial JS dependency	High	Lower for initial display
SEO	Can be harder	Usually easier
Server workload	Lower	Higher
Initial content	Usually later	Usually earlier
Hydration	Not applicable	Usually required
Scalability concerns	Mostly client-side	Server rendering required

A common misconception is:

SSR means there is no client-side JavaScript.

That's false.

Modern SSR applications are usually:

Server-rendered
+
Client-enhanced

10. The Most Important Concept: The Same UI Must Exist on Both Sides

Consider this component:

function App() {
  return <h1>Hello World</h1>;
}

The server renders:

<h1>Hello World</h1>

The browser then loads the client application.

The client expects:

<h1>Hello World</h1>

Everything matches.

Hydration can proceed normally.

But imagine the server renders:

<h1>Hello World</h1>

while the browser expects:

<h1>Hello Abanoub</h1>

Now we have a mismatch.

This is called a:

Hydration Mismatch

11. Hydration Mismatches

Hydration mismatches occur when the server-generated HTML doesn't match what the client expects.

For example:

function App() {
  return (
    <p>
      {Math.random()}
    </p>
  );
}

The server might generate:

<p>0.3214</p>

The browser might calculate:

<p>0.8421</p>

The DOM no longer matches.

Another common example:

const now = new Date();

return <p>{now.toLocaleTimeString()}</p>;

The server and browser may execute at different times.

Result:

Server:
10:30:01

Client:
10:30:02

Mismatch.

12. Browser-Only APIs Can Also Cause Problems

Consider:

const width = window.innerWidth;

The browser has:

window
document
localStorage
navigator

But the server doesn't have a browser DOM.

So this can fail during SSR:

window.innerWidth

or:

localStorage.getItem("theme");

or:

document.querySelector(...)

SSR code must distinguish between:

Server environment

and:

Browser environment

Modern frameworks provide APIs for handling this safely.

13. Data Fetching Is Another SSR Challenge

Suppose your application displays:

Product: MacBook Pro
Price: $1999

The server needs the data before rendering.

So:

Browser
   |
   | GET /products/1
   v
Server
   |
   | Fetch product
   v
Database / API
   |
   v
Product data
   |
   v
Render HTML
   |
   v
Browser

The generated HTML could contain:

<h1>MacBook Pro</h1>
<p>$1999</p>

This is excellent for the initial render.

But now we have another question:

Does the browser need to fetch the same data again during hydration?

Ideally, we want to avoid unnecessary duplicate requests.

14. Server-to-Client Data Transfer

A sophisticated SSR application often transfers server-fetched state to the client.

Conceptually:

Server

Fetch API
   ↓
Product data
   ↓
Render HTML
   ↓
Transfer state
   ↓
Browser
   ↓
Hydrate
   ↓
Reuse existing data

Without state transfer:

Server → API
Browser → API

The same data might be fetched twice.

With state transfer:

Server → API
        ↓
     Transfer
        ↓
     Browser

The browser can reuse the result.

This concept appears in different forms across frameworks.

15. Angular SSR

Angular provides first-class support for SSR.

A traditional Angular application might be rendered entirely in the browser:

Browser
  ↓
Angular Bootstrap
  ↓
Components
  ↓
DOM

With SSR:

Node.js Server
      ↓
Angular Application
      ↓
Rendered HTML
      ↓
Browser
      ↓
Angular Hydration
      ↓
Interactive Application

Modern Angular applications can use:

ng add @angular/ssr

This configures the project for server-side rendering.

16. A Complete Angular SSR Example

Let's create a small product application.

angular-ssr-demo/
│
├── src/
│   ├── app/
│   │   ├── app.ts
│   │   ├── app.html
│   │   └── product.service.ts
│   │
│   ├── main.ts
│   └── main.server.ts
│
├── server.ts
├── angular.json
└── package.json

The application will display:

Product Catalog

MacBook Pro
$1999

Add to Cart

17. Create the Application

Start with:

ng new angular-ssr-demo

Then:

cd angular-ssr-demo

Add SSR:

ng add @angular/ssr

Angular will configure the required server-side infrastructure.

18. Create a Product Service

import { Injectable } from '@angular/core';

export interface Product {
  id: number;
  name: string;
  price: number;
}

@Injectable({
  providedIn: 'root'
})
export class ProductService {

  getProduct(): Product {
    return {
      id: 1,
      name: 'MacBook Pro',
      price: 1999
    };
  }
}

19. Create the Component

import { Component, inject } from '@angular/core';
import { ProductService } from './product.service';

@Component({
  selector: 'app-root',
  template: `
    <main>
      <h1>Product Catalog</h1>

      <section>
        <h2>{{ product.name }}</h2>

        <p>
          Price: ${{ product.price }}
        </p>

        <button (click)="addToCart()">
          Add to Cart
        </button>

        <p>{{ message }}</p>
      </section>
    </main>
  `
})
export class AppComponent {

  private productService = inject(ProductService);

  product = this.productService.getProduct();

  message = '';

  addToCart() {
    this.message = 'Product added to cart!';
  }
}

Now notice something important.

The server can render:

<h1>Product Catalog</h1>

<h2>MacBook Pro</h2>

<p>Price: $1999</p>

<button>Add to Cart</button>

The user can see the content before the client application becomes interactive.

20. What Happens During Hydration?

The server produces:

<button>Add to Cart</button>

The browser displays it.

Then Angular loads.

Angular sees the existing DOM:

<button>Add to Cart</button>

and hydrates it.

Conceptually:

Existing DOM
     |
     v
Angular
     |
     v
Match component structure
     |
     v
Attach event behavior
     |
     v
Interactive button

Now when the user clicks:

Click
 ↓
Angular event handler
 ↓
addToCart()
 ↓
message changes
 ↓
UI updates

This is the transition from:

Static HTML

to:

Interactive application

21. Hydration Does Not Mean "Render Everything Again"

This is one of the most important mental models.

A naive mental model would be:

Server HTML
   ↓
Delete it
   ↓
Render application again

Modern hydration aims to do:

Server HTML
   ↓
Keep existing DOM
   ↓
Connect framework runtime
   ↓
Reuse DOM
   ↓
Interactive application

The goal is to avoid unnecessary DOM reconstruction.

22. Hydration and Event Handlers

Consider:

<button>
  Add to Cart
</button>

Before hydration:

Visible: YES
Interactive: NO

After hydration:

Visible: YES
Interactive: YES

This creates an important performance concept:

Time to Interactive

There can be a period where the user sees the application but JavaScript hasn't finished loading and hydrating.

For example:

0ms
 |
 | HTML arrives
 v
100ms
 |
 | User sees content
 v
300ms
 |
 | JavaScript downloaded
 v
500ms
 |
 | Hydration
 v
600ms
 |
 | Application interactive

The application can look ready before it is actually ready.

This is sometimes called the:

Hydration Gap

23. The Hydration Gap

Suppose the user sees:

[ Add to Cart ]

and immediately clicks it.

But hydration hasn't completed yet.

The click might not be handled.

This creates a UX problem.

Modern frameworks have developed techniques to reduce this problem.

One important approach is:

Partial Hydration

Instead of hydrating the entire application immediately, hydrate only the parts that need to become interactive.

24. Partial Hydration

Imagine a page:

------------------------------------------------
Header
------------------------------------------------
Hero Section
------------------------------------------------
Article Content
------------------------------------------------
Comments Widget
------------------------------------------------
Shopping Cart
------------------------------------------------
Footer
------------------------------------------------

Only these components may need JavaScript:

Comments Widget
Shopping Cart

Why hydrate the entire page?

Instead:

Static HTML
     |
     +---- Header
     |
     +---- Article
     |
     +---- Footer
     |
     +---- Hydrate Comments
     |
     +---- Hydrate Cart

This can significantly reduce client-side JavaScript work.

25. Angular Hydration Concepts

Angular supports hydration so that the server-rendered DOM can be reused on the client.

A typical setup uses:

provideClientHydration()

For example:

import {
  ApplicationConfig
} from '@angular/core';

import {
  provideClientHydration
} from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [
    provideClientHydration()
  ]
};

The exact generated configuration depends on the Angular version and SSR setup, but the fundamental idea is:

Server rendering
      +
Client hydration
      =
Fast initial HTML + interactivity

26. SSR Architecture in Production

A production SSR architecture might look like:

                 ┌──────────────┐
                 │    Browser   │
                 └──────┬───────┘
                        │
                        │ HTTP
                        ▼
                ┌───────────────┐
                │     Nginx     │
                └───────┬───────┘
                        │
                        ▼
                ┌───────────────┐
                │ Node.js SSR   │
                │    Server     │
                └───────┬───────┘
                        │
            ┌───────────┴───────────┐
            ▼                       ▼
      ┌───────────┐           ┌───────────┐
      │   API     │           │ Database  │
      └───────────┘           └───────────┘

The server:

receives the request
loads required data
renders the application
returns HTML
browser displays it
client JavaScript loads
hydration occurs
application becomes interactive

27. SSR With a Backend API

A common architecture is:

Browser
   |
   | GET /
   v
Angular SSR Server
   |
   | GET /api/products
   v
Node.js API
   |
   v
PostgreSQL

The SSR server receives the product data and generates:

<h1>Products</h1>

<article>
  <h2>MacBook Pro</h2>
  <p>$1999</p>
</article>

The browser gets meaningful HTML.

Then:

Angular JS
    ↓
Hydration
    ↓
Existing DOM reused
    ↓
Interactive application

28. SSR Is Not Free

SSR provides benefits, but it introduces costs.

The server now needs to render every request.

For CSR:

Server:
Return static assets

For SSR:

Server:
Execute application
Fetch data
Render HTML
Return response

Therefore SSR can increase:

CPU usage
memory usage
server response complexity
infrastructure cost

This is why architecture matters.

29. SSR and Caching

Caching becomes extremely important.

Suppose 10,000 users request:

/products/123

Rendering the exact same page 10,000 times may be wasteful.

You can introduce caching:

Browser
   |
   v
CDN / Cache
   |
   +---- Cache HIT → HTML
   |
   +---- Cache MISS
             |
             v
          SSR Server

This allows SSR and caching to work together.

30. SSR + CDN

A powerful architecture can look like:

                 Browser
                    |
                    v
                  CDN
               /       \
              /         \
       Cache HIT       Cache MISS
          |                |
          v                v
        HTML           SSR Server
                           |
                           v
                          API

The first request may require server rendering.

Later requests can potentially receive cached HTML.

This gives you:

SSR benefits
+
CDN performance

31. SSR and SEO

One of the major reasons SSR became popular is SEO.

Search engines need to understand your content.

A CSR application might initially return:

<div id="root"></div>

while SSR can return:

<h1>Best Programming Courses</h1>

<p>
  Learn Angular, React, Node.js and TypeScript.
</p>

The content exists directly in the initial HTML.

This is especially useful for:

blogs
documentation
e-commerce
news websites
landing pages
content platforms

However, SEO is more complicated than simply saying:

SSR = good SEO.

Modern search engines can execute JavaScript.

SSR mainly helps by making meaningful content available earlier and more reliably.

32. SSR vs SSG

SSR is not the only server-rendering strategy.

There is also:

Static Site Generation

SSG generates HTML during the build process.

Build Time
   ↓
Generate HTML
   ↓
Deploy static files
   ↓
CDN
   ↓
User

SSR:

Request Time
   ↓
Render HTML
   ↓
Response

SSG:

Build Time
   ↓
Generate HTML
   ↓
Serve HTML

33. SSR vs SSG vs CSR

Strategy	Rendering Time	Best For
CSR	Browser	Dashboards, internal apps
SSR	Request	Dynamic content
SSG	Build	Blogs, documentation
ISR / Revalidation	Periodically	Large content sites

For example:

Admin Dashboard

CSR

because SEO is usually irrelevant.

Blog

SSG

because articles don't change every second.

E-commerce Product Page

SSR / ISR

because product information can be dynamic.

34. SSR + Hydration + API Data

Let's design a complete flow.

Suppose the user visits:

/products/123

The process becomes:

                Browser
                   |
                   | GET /products/123
                   v
              SSR Server
                   |
                   | Fetch product
                   v
                Backend
                   |
                   v
               Database
                   |
                   v
             Product Data
                   |
                   v
            Render Angular
                   |
                   v
                 HTML
                   |
                   v
                Browser
                   |
                   v
             Display HTML
                   |
                   v
          Download JavaScript
                   |
                   v
              Hydration
                   |
                   v
         Interactive Product

This is the architecture you should have in mind when thinking about SSR.

35. A More Realistic Product Example

Imagine the server receives:

GET /products/123

The API returns:

{
  "id": 123,
  "name": "MacBook Pro",
  "price": 1999,
  "description": "Powerful laptop for developers"
}

SSR generates:

<article>
  <h1>MacBook Pro</h1>

  <p>$1999</p>

  <p>
    Powerful laptop for developers
  </p>

  <button>
    Add to Cart
  </button>
</article>

The user immediately sees:

MacBook Pro
$1999
Powerful laptop for developers

[ Add to Cart ]

Then hydration connects:

button click
     ↓
Angular event listener
     ↓
addToCart()
     ↓
application state
     ↓
UI update

36. Common SSR Mistakes

Mistake #1: Using `window` Everywhere

Bad:

const width = window.innerWidth;

During server rendering:

window = undefined

Use platform-aware APIs or execute browser-only logic after the application is running in the browser.

Mistake #2: Using `localStorage` During SSR

Bad:

const token = localStorage.getItem('token');

The server doesn't have browser localStorage.

You need a server-safe strategy.

Mistake #3: Random Values

Bad:

const id = Math.random();

The server and client can produce different values.

Mistake #4: Current Time

Bad:

new Date()

when its result becomes part of rendered markup.

The server and client can disagree.

Mistake #5: Different Data

Server:

{
  "price": 100
}

Client:

{
  "price": 110
}

The DOM can mismatch.

37. How to Think About SSR Code

When writing code for SSR, ask:

Can this code execute on a server?

If the answer is no, isolate it.

Examples:

window
document
localStorage
sessionStorage
navigator
geolocation
Web APIs

These are browser-specific capabilities.

The application should have a clear boundary between:

Universal Code

and:

Browser-only Code

38. The Universal JavaScript Model

SSR applications often follow this model:

             Application Code
                    |
           ┌────────┴────────┐
           │                 │
           ▼                 ▼
        Server             Browser
           │                 │
           ▼                 ▼
        Render             Hydrate
           │                 │
           └────────┬────────┘
                    ▼
              Same Application

The same application logic can participate in two environments.

That's why SSR applications are sometimes described as:

Isomorphic / Universal Applications

39. Hydration Mismatch Debugging Strategy

When you see a hydration error, don't immediately blame the framework.

Check these first:

1. Random values

Math.random()

2. Dates

new Date()

3. Browser APIs

window
document
localStorage

4. Conditional rendering

if (window.innerWidth > 768)

5. Different API results

Server data ≠ Client data

6. Invalid HTML

For example, invalid nesting can cause browsers to normalize the DOM differently.

40. SSR Security Considerations

SSR also introduces security concerns.

Never blindly inject server data into HTML.

Be careful with:

User-generated content
HTML injection
XSS
serialized application state
cookies
authentication data

For example, if server state is serialized into the page:

<script>
  window.__DATA__ = {...}
</script>

that data must be safely serialized.

Never expose secrets such as:

Database passwords
API private keys
Internal credentials
Server-only environment variables

SSR code runs on the server, so you must carefully separate:

PUBLIC configuration

from:

SERVER-ONLY secrets

41. Performance Optimization Strategy

A good SSR architecture should optimize more than rendering.

Consider:

                SSR Performance
                       |
        ┌──────────────┼──────────────┐
        │              │              │
        ▼              ▼              ▼
     Server          Network        Client
      │                │              │
      ▼                ▼              ▼
   Rendering          CDN         Hydration
      │                │              │
      ▼                ▼              ▼
    Caching         Compression    JS Size

Optimize:

server rendering
API latency
database queries
HTML size
JavaScript bundle size
hydration cost
caching
CDN delivery

SSR isn't a magic performance switch.

It changes where the work happens.

42. The Deeper Architecture

The evolution looks like this:

                 Web Application Evolution

CSR
 │
 │ Browser renders everything
 ▼
SSR
 │
 │ Server renders initial HTML
 ▼
SSR + Hydration
 │
 │ Server HTML + client interactivity
 ▼
Partial / Selective Hydration
 │
 │ Hydrate only what needs JavaScript
 ▼
Streaming / Progressive Rendering
 │
 │ Send HTML progressively
 ▼
Modern Full-Stack Rendering

The goal isn't:

"Move everything to the server."

The goal is:

Put each piece of work where it is most efficient.

43. A Complete Mental Model

When a user opens an SSR application:

1. Browser sends HTTP request
          ↓
2. Server receives request
          ↓
3. Application executes on server
          ↓
4. Server fetches required data
          ↓
5. Components render to HTML
          ↓
6. Server sends HTML
          ↓
7. Browser parses HTML
          ↓
8. User sees content
          ↓
9. Browser downloads JavaScript
          ↓
10. Framework starts
          ↓
11. Hydration begins
          ↓
12. Existing DOM is reused
          ↓
13. Event handlers become active
          ↓
14. Application becomes interactive

If you understand these 14 steps, you understand the core of SSR + hydration.

44. The Key Difference in One Diagram

CSR

Request
   ↓
HTML Shell
   ↓
Download JS
   ↓
Execute JS
   ↓
Render UI
   ↓
Interactive

SSR

Request
   ↓
Server Render
   ↓
HTML
   ↓
Display UI
   ↓
Download JS
   ↓
Hydration
   ↓
Interactive

The critical difference is:

CSR:
Render → Browser

SSR:
Render → Server

And hydration bridges:

Server HTML
     ↓
Client JavaScript
     ↓
Interactive DOM

45. When Should You Use SSR?

SSR is especially useful when you care about:

SEO
+
Initial rendering
+
Content discoverability
+
Social previews
+
Performance on slower devices

Good candidates include:

e-commerce
blogs
documentation
marketing websites
news platforms
public product pages
content platforms

46. When CSR May Be Better

SSR isn't always necessary.

For example:

Admin Dashboard
Internal CRM
Back-office application
Private analytics platform

These applications often don't need SEO.

CSR can be simpler:

Browser
   ↓
JavaScript
   ↓
Application

Sometimes simplicity is more valuable than SSR.

47. SSR Is an Architectural Decision

Don't add SSR simply because:

"SSR is faster."

Ask instead:

Do I need SEO?
Do I need fast initial content?
Is my content dynamic?
Can my server handle rendering?
Do I have caching?
How large is my client bundle?
How expensive is hydration?

The answer determines whether SSR is appropriate.

48. Final Architecture

A modern application can look like:

                         USER
                          |
                          v
                       Browser
                          |
                          v
                         CDN
                          |
                 ┌────────┴────────┐
                 │                 │
              Cache HIT         Cache MISS
                 │                 │
                 v                 v
                HTML          SSR Server
                                   |
                     ┌─────────────┼─────────────┐
                     │             │             │
                     v             v             v
                   API          Database       Cache
                     |
                     v
                 Application
                     |
                     v
                Render HTML
                     |
                     v
                  Browser
                     |
                     v
                JavaScript
                     |
                     v
                 Hydration
                     |
                     v
              Interactive UI

This is the architecture behind many modern web applications.

49. Final Takeaways

If you remember only a few things from this article, remember these:

1. CSR

The browser renders the application.

Browser → JavaScript → UI

2. SSR

The server renders the initial HTML.

Server → HTML → Browser

3. Hydration

The client connects JavaScript behavior to the server-rendered HTML.

HTML + JavaScript → Interactive UI

4. SSR does not eliminate JavaScript

It moves the responsibility for the initial render.

5. Hydration should reuse the server DOM

The goal is to avoid unnecessarily rendering the same UI twice.

6. Server and client must agree

Different output can cause hydration mismatches.

7. Browser APIs require special attention

window
document
localStorage
navigator

may not exist on the server.

8. SSR has a cost

You trade some client-side rendering work for server-side rendering work.

9. Caching matters

SSR + CDN + caching can produce a powerful architecture.

10. Modern rendering is not simply CSR vs SSR

Modern frameworks increasingly combine:

SSR
+
Hydration
+
Partial Hydration
+
Streaming
+
Caching
+
Client-side Interactivity

The real goal is to decide where and when each piece of work should happen.

Conclusion

Server-Side Rendering and Hydration are not just framework features.

They represent a fundamental architectural shift in how web applications are delivered.

Instead of forcing the browser to build everything from scratch:

JavaScript
   ↓
Render
   ↓
UI

we can let the server produce meaningful HTML first:

Server
   ↓
HTML
   ↓
Browser

and then use hydration to transform that HTML into a fully interactive application:

Server-rendered HTML
        +
Client JavaScript
        ↓
     Hydration
        ↓
Interactive Application

Once you understand this model, technologies such as Angular SSR, React Server Components, Next.js, Nuxt, streaming SSR, partial hydration, and modern full-stack rendering architectures become much easier to understand.

The most important idea is not simply:

"SSR makes websites faster."

It is:

SSR decides where the initial UI is rendered, while hydration connects that server-rendered UI to the client-side application.

That distinction is the foundation for understanding modern web rendering.

🚀 What to Learn Next

If you're building serious Angular/React applications, the natural progression after SSR and hydration is:

CSR
 ↓
SSR
 ↓
Hydration
 ↓
Transfer State
 ↓
Streaming SSR
 ↓
Partial / Selective Hydration
 ↓
Islands Architecture
 ↓
React Server Components
 ↓
Server Actions
 ↓
Edge Rendering
 ↓
Modern Full-Stack Architecture

Understanding this progression gives you a much deeper understanding of how modern frontend frameworks actually work under the hood.

Building a Production-Ready Authentication System with Next.js

Abanoub Kerols — Wed, 30 Sep 2026 21:37:08 +0000

Authentication is one of those topics that looks simple at first.

You create a login form:

Email + Password
       ↓
     Login
       ↓
   User authenticated

But a real authentication system is much more than checking whether a password is correct.

A production authentication system needs to answer questions such as:

How do we securely store passwords?
Where should authentication tokens live?
How does the server know that a request belongs to an authenticated user?
How do we keep users logged in?
How do we refresh expired access tokens?
How do we log users out?
How do we protect routes?
How do we distinguish authentication from authorization?
How do we prevent token theft and replay attacks?
How does this work with Next.js Server Components and Client Components?
How should the architecture change when the application grows?

This article builds an authentication system from the ground up using Next.js, while focusing on the architectural ideas behind it rather than simply copying an authentication library.

1. Authentication vs Authorization

Before writing code, we need to understand two different concepts.

Authentication

Authentication answers:

Who are you?

For example:

Email: abanoub@example.com
Password: ********

The server verifies the credentials and identifies the user:

User ID: 123
Email: abanoub@example.com

Authorization

Authorization answers:

What are you allowed to do?

For example:

User
 ├── Read posts
 ├── Create posts
 └── Delete own posts

Admin
 ├── Read posts
 ├── Create posts
 ├── Delete posts
 └── Manage users

So:

Authentication → Identity

Authorization → Permissions

This distinction becomes extremely important when designing the backend.

2. The Authentication Architecture

Let's imagine that we have a Next.js application.

A simplified architecture can look like this:

                    Browser
                       │
                       │ HTTPS
                       ▼
                ┌──────────────┐
                │   Next.js    │
                │ Application  │
                └──────┬───────┘
                       │
             ┌─────────┴─────────┐
             │                   │
             ▼                   ▼
        Authentication       Application
           Logic                Logic
             │                   │
             └─────────┬─────────┘
                       ▼
                   Database

The authentication system will be responsible for:

Register
Login
Logout
Session validation
Token refresh
Password hashing
Password reset
Email verification
Authorization

3. The User Model

At the database level, we need a user.

A simplified model might look like:

User {
  id
  name
  email
  passwordHash
  role
  emailVerified
  createdAt
  updatedAt
}

Notice something important:

We don't store:

password

We store:

passwordHash

This is a fundamental security rule.

4. Never Store Plain-Text Passwords

Suppose the user creates:

Password:

MySecretPassword123

We should never save:

password = "MySecretPassword123"

Instead:

Password
   ↓
Hashing Algorithm
   ↓
Password Hash
   ↓
Database

For example:

MySecretPassword123
        ↓
$argon2id$v=19$...

The important property is that hashing is one-way.

We don't decrypt the password during login.

Instead:

Login Password
      ↓
Hash/Verify
      ↓
Compare with stored hash

A modern password hashing algorithm such as Argon2id is a strong choice for password storage.

5. Registration Flow

Let's design the registration process.

The browser sends:

POST /api/auth/register

with:

{
  "name": "Abanoub",
  "email": "abanoub@example.com",
  "password": "MySecretPassword123"
}

The server performs:

Receive request
      ↓
Validate input
      ↓
Normalize email
      ↓
Check existing user
      ↓
Hash password
      ↓
Create user
      ↓
Create authentication state
      ↓
Return response

6. Input Validation

Never trust input coming from the browser.

For example:

const schema = z.object({
  name: z.string().min(2).max(100),

  email: z
    .string()
    .email(),

  password: z
    .string()
    .min(8)
});

Then:

const result = schema.safeParse(body);

if (!result.success) {
  return Response.json(
    {
      message: "Invalid input"
    },
    {
      status: 400
    }
  );
}

The client-side validation improves UX.

The server-side validation provides security and correctness.

You need both.

7. Normalize Email Addresses

Authentication systems should usually normalize emails before querying the database.

For example:

const email = input.email
  .trim()
  .toLowerCase();

Without normalization:

Abanoub@example.com
abanoub@example.com
ABANOUB@example.com

could accidentally be treated as different values depending on the database and application rules.

Ideally, the database should also enforce a unique constraint.

8. Login Flow

Now let's look at login.

The browser sends:

POST /api/auth/login

{
  "email": "abanoub@example.com",
  "password": "MySecretPassword123"
}

The server performs:

Validate input
      ↓
Find user
      ↓
Verify password
      ↓
Create authentication state
      ↓
Set secure cookie
      ↓
Return response

The browser doesn't need to know the user's password after authentication.

9. How Does the Server Remember the User?

This is the core authentication problem.

HTTP is stateless.

For example:

Request 1
GET /dashboard

Request 2
GET /profile

Request 3
GET /orders

Each request is independent.

The server needs some form of authentication state to understand:

These requests belong to user 123.

There are two major approaches:

Session-based authentication
JWT-based authentication

10. Session-Based Authentication

With sessions, the server stores authentication state.

For example:

Database

Session
-------------------------
sessionId
userId
expiresAt
createdAt

The browser receives:

sessionId

inside a cookie.

Then:

Browser
   │
   │ Cookie: sessionId=abc123
   ▼
Next.js
   │
   │ lookup session
   ▼
Database
   │
   ▼
User 123

This is a very clean model for traditional web applications.

11. JWT-Based Authentication

Another approach is JSON Web Tokens.

A JWT contains claims such as:

{
  "sub": "123",
  "role": "user",
  "exp": 1790000000
}

The token is cryptographically signed.

The server can verify:

Signature
Expiration
Issuer
Audience
Claims

without necessarily querying the database for every request.

12. Access Token vs Refresh Token

A common production architecture separates authentication into two tokens.

Access Token
+
Refresh Token

The access token is short-lived.

For example:

Access Token
Expires in 15 minutes

The refresh token lives longer:

Refresh Token
Expires in days/weeks

The idea is:

                Login
                  │
          ┌───────┴────────┐
          ▼                ▼
    Access Token      Refresh Token
      short-lived       long-lived

13. Why Not Use a Long-Lived Access Token?

Imagine:

Access Token
Expires in 30 days

If an attacker steals it:

Attacker
   ↓
Stolen token
   ↓
30 days of access

A short-lived access token reduces the lifetime of a stolen credential.

The refresh mechanism then allows legitimate users to obtain a new access token.

14. Where Should Tokens Be Stored?

This is one of the most important authentication design decisions.

A common mistake is:

localStorage.setItem(
  "accessToken",
  token
);

This can expose the token to JavaScript running in the page.

If an XSS vulnerability exists, malicious JavaScript could potentially read the token.

A common safer browser architecture is:

HttpOnly Cookie
Secure Cookie
SameSite Cookie

For example:

Set-Cookie:
refreshToken=...
HttpOnly;
Secure;
SameSite=Lax;
Path=/api/auth;

The HttpOnly flag means JavaScript cannot access the cookie through:

document.cookie

15. Cookie Security

A production authentication cookie should generally consider:

HttpOnly
Secure
SameSite
Path
Expiration

For example:

cookies().set(
  "refreshToken",
  refreshToken,
  {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    path: "/api/auth",
    maxAge: 60 * 60 * 24 * 30
  }
);

The exact configuration depends on your architecture and deployment environment.

16. SameSite Is Not a Complete CSRF Strategy

A common misconception is:

HttpOnly completely solves authentication security.

It doesn't.

HttpOnly primarily prevents JavaScript from reading the cookie.

It does not automatically solve every CSRF scenario.

That's why authentication systems should consider:

SameSite cookies
+
CSRF protection where necessary
+
Origin checking
+
Secure application design

Especially when the application performs state-changing requests.

17. The Authentication Request Lifecycle

Let's put everything together.

Suppose the user requests:

GET /dashboard

The browser automatically sends:

Cookie: session=abc123

or:

Cookie: refreshToken=...

The server:

Request
   ↓
Read cookie
   ↓
Validate authentication
   ↓
Identify user
   ↓
Check authorization
   ↓
Execute business logic
   ↓
Return response

This is the central lifecycle of authentication.

18. Authentication Helper

Instead of repeating authentication logic everywhere, create a reusable function.

For example:

async function getCurrentUser() {
  const cookieStore = await cookies();

  const token = cookieStore.get(
    "accessToken"
  )?.value;

  if (!token) {
    return null;
  }

  try {
    const payload = await verifyToken(token);

    return await getUserById(payload.sub);
  } catch {
    return null;
  }
}

Now application code can simply do:

const user = await getCurrentUser();

if (!user) {
  // unauthenticated
}

This is much cleaner than implementing token parsing in every route.

19. Authentication in Next.js

Next.js introduces an interesting architectural distinction:

Server Components
Client Components
Route Handlers
Middleware
Server Actions

Authentication logic should be placed carefully according to what it needs to do.

For example, if you need to read an HttpOnly cookie, server-side code is a natural place.

A Server Component can retrieve authentication information and render accordingly.

20. Protecting Server Components

Imagine:

export default async function DashboardPage() {
  const user = await getCurrentUser();

  if (!user) {
    redirect("/login");
  }

  return (
    <main>
      <h1>
        Welcome {user.name}
      </h1>
    </main>
  );
}

The important idea is:

Server
  ↓
Read authentication state
  ↓
Validate user
  ↓
Render protected content

The browser doesn't need to decide whether the user is authenticated.

21. Middleware

Middleware can be useful for early route protection.

For example:

/dashboard
/profile
/settings
/admin

could be protected.

Conceptually:

export async function middleware(request) {
  const token =
    request.cookies.get("accessToken");

  if (!token) {
    return Response.redirect(
      new URL("/login", request.url)
    );
  }

  return NextResponse.next();
}

But middleware should not automatically become the only authorization layer.

Why?

Because authorization must also happen at the point where sensitive data or operations are accessed.

22. Never Trust Middleware Alone

Suppose:

POST /api/users/delete

is protected by middleware.

An attacker may still try to call the underlying endpoint directly.

Therefore:

Middleware
   ↓
Early protection

Route Handler / Server Action
   ↓
Actual authorization

The sensitive operation itself should verify permissions.

For example:

const user = await getCurrentUser();

if (!user) {
  return unauthorized();
}

if (user.role !== "admin") {
  return forbidden();
}

23. Authentication vs Authorization in Code

A clean structure is:

const user = await requireUser();

requireRole(user, "admin");

Conceptually:

requireUser()
      ↓
Is authenticated?

requireRole()
      ↓
Is authorized?

This separation makes the system easier to understand and test.

24. Role-Based Access Control

Suppose our application has:

type Role =
  | "user"
  | "admin"
  | "manager";

Then:

User
 ├── View profile
 └── Create orders

Manager
 ├── View reports
 └── Manage orders

Admin
 ├── Manage users
 ├── Manage roles
 └── Manage system settings

Authorization becomes:

if (user.role !== "admin") {
  return forbidden();
}

But real systems can go beyond roles.

25. Permissions

Instead of:

role = admin

we can model permissions:

users:read
users:create
users:update
users:delete
orders:read
orders:create
orders:update

Then:

hasPermission(
  user,
  "users:delete"
);

This becomes useful when the application becomes more complex.

26. Logout

Logout should invalidate the authentication state.

For a cookie-based architecture:

User clicks Logout
        ↓
POST /api/auth/logout
        ↓
Invalidate session/token
        ↓
Clear cookie
        ↓
Redirect to login

For example:

cookies().delete("refreshToken");

If using server-side sessions, you should also invalidate the session in the database.

27. Refresh Token Rotation

A stronger refresh-token architecture uses rotation.

Suppose:

Refresh Token A

is used.

The server returns:

Refresh Token B

and invalidates A.

So:

Token A
   ↓
Refresh
   ↓
Token B
   ↓
Token A invalid

This can reduce the impact of stolen refresh tokens.

You can also detect token reuse.

28. Refresh Token Storage

For a high-security architecture, don't necessarily store the raw refresh token in the database.

Instead:

Refresh Token
      ↓
Hash
      ↓
Database

The database stores something like:

tokenHash
userId
expiresAt
revokedAt
createdAt

Then the server hashes the presented token and looks up the hash.

This follows the same general principle:

Don't store sensitive credentials in recoverable plain text when you don't need to.

29. Session-Based Architecture Can Be Even Simpler

For many Next.js applications, a server-side session architecture is extremely practical:

Browser
   │
   │ session cookie
   ▼
Next.js
   │
   │ session lookup
   ▼
Database / Redis

The browser stores only an opaque identifier.

For example:

session_id = 7f3a...

The server knows:

7f3a...
   ↓
User 123

This gives the server direct control over session revocation.

30. JWT Does Not Automatically Mean "More Secure"

JWT is a technology, not a security strategy.

A poorly designed JWT system can be vulnerable.

For example:

JWT in localStorage
+
Long expiration
+
No rotation
+
No revocation strategy
+
Weak secret management

is not automatically better than sessions.

The correct question is:

What authentication model fits the architecture and security requirements of the application?

31. Password Reset

Authentication isn't complete without password recovery.

A typical flow is:

User clicks:
Forgot Password
        ↓
Enter email
        ↓
Server creates reset token
        ↓
Email sent
        ↓
User clicks link
        ↓
Validate token
        ↓
Set new password

The reset token should be:

random
short-lived
single-use

And ideally the database stores only a hash of the reset token.

32. Email Verification

Registration can also require email verification.

Flow:

Register
   ↓
Create user
   ↓
emailVerified = false
   ↓
Generate verification token
   ↓
Send email
   ↓
User clicks link
   ↓
Verify token
   ↓
emailVerified = true

Then sensitive operations can require:

if (!user.emailVerified) {
  // require verification
}

33. Brute-Force Protection

Imagine an attacker sends:

10,000 login attempts

against:

POST /api/auth/login

The authentication endpoint should be rate-limited.

For example:

IP
+
Email
+
Time Window

could be used to detect excessive attempts.

A production system might use:

Redis

to implement distributed rate limiting.

Conceptually:

login:ip:1.2.3.4
login:user:abanoub@example.com

34. Account Enumeration

Be careful with error messages.

Avoid:

User does not exist.

and:

Wrong password.

because this can allow attackers to determine whether an email address is registered.

A generic response can be:

Invalid email or password.

Similarly, password-reset requests often use generic responses so attackers cannot easily discover registered accounts.

35. Secrets and Environment Variables

Authentication secrets should never be hardcoded.

Bad:

const secret = "my-secret-123";

Better:

AUTH_SECRET=...
DATABASE_URL=...

Then:

process.env.AUTH_SECRET

Also:

.env.local

should not be committed to Git.

36. HTTPS

Authentication should be performed over HTTPS in production.

Why?

Because credentials, cookies, and authentication tokens must be protected while traveling between:

Browser
    ↕
Internet
    ↕
Server

Without transport encryption, an attacker positioned on the network could potentially intercept sensitive data.

37. Secure Cookies

In production:

Secure = true

means the cookie should only be transmitted over HTTPS.

A typical production cookie might look conceptually like:

HttpOnly
Secure
SameSite=Lax

Again, the correct SameSite policy depends on whether your application uses cross-site authentication flows.

38. Database Constraints Are Part of Security

Application-level checks are not enough.

For example:

if (existingUser) {
  throw new Error("Email already exists");
}

is useful.

But the database should also enforce:

UNIQUE(email)

Why?

Because two requests could arrive at almost the same time:

Request A ─┐
           ├── Check email
Request B ─┘

Both might see:

No user exists

and then both try to insert.

The database constraint provides the final guarantee.

39. Race Conditions

Authentication systems contain many opportunities for race conditions.

Examples:

Two registration requests
Two password reset requests
Two refresh requests
Two logout requests
Two email verification requests

Good architecture considers these cases explicitly.

For refresh-token rotation, for example, concurrent refresh requests require careful handling.

40. CSRF

If authentication relies on cookies, the browser automatically sends them with requests.

That creates a CSRF consideration.

Imagine:

Attacker Website
       ↓
POST /api/change-email
       ↓
Browser automatically sends auth cookie

Depending on the cookie and request configuration, the server may receive an authenticated request.

Possible defenses include:

SameSite cookies
CSRF tokens
Origin validation
Same-origin architecture

The correct strategy depends on the application.

41. XSS

Authentication security also depends on preventing XSS.

For example, never render untrusted HTML without sanitization.

An XSS vulnerability can allow malicious JavaScript to perform actions as the user, even when HttpOnly cookies prevent direct token theft.

Therefore:

Authentication Security
        ≠
Token Security Only

It is an application-wide concern.

42. A Better Next.js Project Structure

A growing application might use a structure such as:

src/
├── app/
│   ├── (auth)/
│   │   ├── login/
│   │   ├── register/
│   │   └── forgot-password/
│   │
│   ├── dashboard/
│   ├── profile/
│   │
│   └── api/
│       └── auth/
│           ├── login/
│           ├── register/
│           ├── logout/
│           ├── refresh/
│           └── reset-password/
│
├── lib/
│   ├── auth/
│   │   ├── session.ts
│   │   ├── password.ts
│   │   ├── tokens.ts
│   │   └── authorization.ts
│   │
│   ├── db/
│   └── validation/
│
├── components/
│
└── middleware.ts

The exact structure isn't important.

The separation of responsibilities is.

43. Authentication Service

Instead of mixing everything into route handlers:

export async function login(
  email: string,
  password: string
) {
  const user = await findUserByEmail(email);

  if (!user) {
    throw new AuthenticationError();
  }

  const valid = await verifyPassword(
    password,
    user.passwordHash
  );

  if (!valid) {
    throw new AuthenticationError();
  }

  return createSession(user);
}

Then the route handler becomes thin:

export async function POST(request: Request) {
  const body = await request.json();

  const result = await login(
    body.email,
    body.password
  );

  return Response.json(result);
}

This makes the authentication logic reusable and testable.

44. The Thin Controller Principle

A good API layer should ideally do:

Request
   ↓
Validation
   ↓
Service
   ↓
Response

Instead of:

Route Handler
 ├── validate
 ├── query DB
 ├── hash password
 ├── generate token
 ├── create session
 ├── send email
 ├── authorization
 ├── business logic
 └── response

The second approach becomes difficult to maintain.

45. A Complete Login Architecture

Let's summarize the complete login process.

                 Browser
                    │
                    │ POST /login
                    ▼
              Next.js Route
                    │
                    ▼
             Validate Input
                    │
                    ▼
             Find User
                    │
                    ▼
            Verify Password
                    │
                    ▼
           Create Session
                    │
                    ▼
          Set HttpOnly Cookie
                    │
                    ▼
               Response

Then:

Browser
   │
   │ Cookie
   ▼
Next.js
   │
   ▼
Validate Session
   │
   ▼
Identify User
   │
   ▼
Authorization
   │
   ▼
Business Logic

46. The Mental Model

The most important mental model is this:

Credentials
    ↓
Identity
    ↓
Authentication State
    ↓
Authenticated Request
    ↓
Authorization
    ↓
Business Operation

For example:

Email + Password
       ↓
User #123
       ↓
Session #ABC
       ↓
GET /dashboard
       ↓
Authenticated User
       ↓
Permission: dashboard:read
       ↓
Dashboard Data

Once you understand this flow, authentication stops being a collection of random APIs and becomes a system.

47. Production Authentication Checklist

Before considering an authentication system production-ready, ask:

Passwords

[ ] Are passwords hashed with a password-specific algorithm?
[ ] Are password hashes never exposed through APIs?
[ ] Is password validation performed server-side?

Cookies

[ ] Are sensitive cookies HttpOnly?
[ ] Is Secure enabled in production?
[ ] Is SameSite configured correctly?
[ ] Is the cookie scope as narrow as practical?

Tokens / Sessions

[ ] Do authentication credentials expire?
[ ] Can sessions be revoked?
[ ] Are refresh tokens rotated where appropriate?
[ ] Are refresh tokens protected?
[ ] Is token reuse detectable where required?

APIs

[ ] Are authentication endpoints rate-limited?
[ ] Are inputs validated?
[ ] Are authorization checks performed server-side?
[ ] Are sensitive errors generic enough to avoid account enumeration?

Infrastructure

[ ] Is HTTPS enabled?
[ ] Are secrets stored in environment/secret management?
[ ] Are database constraints enforced?
[ ] Are logs free from passwords and tokens?

Application Security

[ ] Is CSRF considered?
[ ] Is XSS considered?
[ ] Are permissions checked at the resource boundary?
[ ] Are authentication and authorization separated?

48. The Most Important Architectural Lesson

Authentication is not:

Login Page
+
JWT
+
Middleware

Authentication is a complete security boundary.

A useful architecture looks like:

                 ┌───────────────────────┐
                 │       Browser         │
                 └───────────┬───────────┘
                             │
                             ▼
                    ┌────────────────┐
                    │    Next.js     │
                    │                │
                    │ Route Handlers │
                    │ Server Actions │
                    │ Server Comps   │
                    │ Middleware     │
                    └───────┬────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
         Auth Service   Authorization   Business
              │             │             │
              └─────────────┼─────────────┘
                            ▼
                       Database
                            │
                            ▼
                     Session / User

The goal isn't simply to make the login button work.

The goal is to establish a trustworthy chain:

Who is this user?
        ↓
How do we know?
        ↓
Is their authentication state valid?
        ↓
What are they allowed to do?
        ↓
Can we safely execute the operation?

That's the real meaning of building an authentication system.

Conclusion

Building authentication with Next.js is an excellent exercise because it forces you to combine several areas of software engineering:

HTTP
Cookies
Cryptography
Databases
API Design
Security
Authorization
Server-side Rendering
Client-side Applications
Middleware
Distributed Systems

The most important thing to learn is not a specific library or token format.

It's the architecture.

Once you understand:

Authentication
        ↓
Session / Token
        ↓
Request
        ↓
Identity
        ↓
Authorization
        ↓
Business Logic

you can apply the same concepts whether you're building a Next.js application, an Angular + Node.js system, a mobile backend, or a distributed API.

A good authentication system should make it difficult for an attacker to impersonate a user, limit the impact of stolen credentials, provide clear authorization boundaries, and give the server reliable control over access.

That is what turns a simple login feature into a production authentication system.

Redux Explained: Concepts, Architecture, Examples, and Real-World Patterns

Abanoub Kerols — Wed, 23 Sep 2026 21:16:07 +0000

Redux is more than a state management library. It is a predictable architecture for managing application state through explicit actions, pure state transitions, and a centralized store.

If you have worked with React, Angular, or modern frontend applications, you have probably encountered problems such as:

Multiple components needing the same state
State being passed through many layers of components
Difficult-to-debug state changes
Complex asynchronous operations
Inconsistent application state
Business logic scattered across components

Redux was designed to solve these problems by introducing a predictable and structured approach to state management.

In this article, we will go from the fundamentals to practical Redux development, including:

What Redux is
Why Redux exists
Core Redux concepts
Store
Actions
Reducers
Dispatch
Selectors
Immutability
Redux data flow
Middleware
Async operations
Redux Toolkit
RTK Query
Entity management
Real-world architecture
Common mistakes
A complete example

1. What Is Redux?

Redux is a predictable state management library.

The basic idea is simple:

UI
 ↓
Dispatch Action
 ↓
Reducer
 ↓
New State
 ↓
Store
 ↓
UI Updates

Instead of allowing components to modify application state however they want, Redux creates a controlled flow.

For example:

dispatch({
  type: "counter/increment"
});

The action reaches a reducer:

function counterReducer(state, action) {
  if (action.type === "counter/increment") {
    return {
      ...state,
      value: state.value + 1
    };
  }

  return state;
}

The reducer produces the next state.

2. Why Do We Need Redux?

Consider a large application.

You may have:

App
 ├── Header
 │    └── UserMenu
 │         └── UserProfile
 │
 ├── Dashboard
 │    ├── Statistics
 │    ├── Orders
 │    └── Notifications
 │
 └── Sidebar

Suppose the logged-in user is needed by:

Header
UserMenu
Dashboard
Sidebar
Notifications

Without centralized state management, you may end up passing:

App
 ↓
Header
 ↓
UserMenu
 ↓
UserProfile

This is commonly called prop drilling.

Redux provides a centralized store:

             Redux Store
          /       |       \
         ↓        ↓        ↓
      Header   Dashboard  Sidebar

Components can subscribe to the state they need.

3. Redux Core Principles

Redux is based on several important principles.

3.1 Single Source of Truth

Application state is stored in one centralized store.

{
  user: {
    id: 1,
    name: "Abanoub"
  },
  cart: {
    items: []
  },
  products: [],
  ui: {
    theme: "dark"
  }
}

Instead of having unrelated copies of important state throughout the application, Redux provides a central source.

4. State Is Read-Only

Components should not directly modify Redux state.

Incorrect:

state.counter.value++;

Instead, dispatch an action:

dispatch({
  type: "counter/increment"
});

The reducer determines how the state changes.

5. Changes Are Made Through Pure Functions

Reducers are responsible for calculating the next state.

Conceptually:

Previous State + Action = Next State

Example:

const previousState = {
  value: 10
};

const action = {
  type: "increment"
};

const nextState = {
  value: 11
};

The reducer:

function reducer(state, action) {
  switch (action.type) {
    case "increment":
      return {
        ...state,
        value: state.value + 1
      };

    default:
      return state;
  }
}

6. The Redux Store

The store contains the application state.

With modern Redux, the recommended approach is Redux Toolkit.

import { configureStore } from "@reduxjs/toolkit";

const store = configureStore({
  reducer: {
    counter: counterReducer
  }
});

Conceptually:

Store
│
├── counter
├── user
├── products
├── cart
└── notifications

7. Actions

An action describes what happened.

Example:

{
  type: "counter/increment"
}

Another example:

{
  type: "cart/addItem",
  payload: {
    id: 10,
    name: "Keyboard"
  }
}

The action does not directly modify state.

It describes an event.

8. Action Types

An action type is usually a string.

{
  type: "user/login"
}

Examples:

user/login
user/logout
cart/addItem
cart/removeItem
products/load
products/delete

A useful naming convention is:

feature/event

For example:

cart/addItem

9. Payload

The payload contains additional information.

{
  type: "cart/addItem",
  payload: {
    id: 1,
    name: "Laptop",
    price: 1200
  }
}

Another example:

{
  type: "user/setUser",
  payload: {
    id: 5,
    name: "John"
  }
}

10. Reducers

A reducer receives:

Current State
+
Action

and returns:

Next State

Example:

function counterReducer(state = { value: 0 }, action) {
  switch (action.type) {
    case "increment":
      return {
        ...state,
        value: state.value + 1
      };

    case "decrement":
      return {
        ...state,
        value: state.value - 1
      };

    default:
      return state;
  }
}

A reducer should be:

Predictable
Pure
Deterministic
Free of side effects

11. What Does "Pure Function" Mean?

A pure function:

Produces the same output for the same input.
Does not modify external state.
Does not perform side effects.

Example:

function add(a, b) {
  return a + b;
}

This is pure.

But:

let total = 0;

function add(value) {
  total += value;
}

This is not pure because it modifies external state.

Reducers should follow the pure-function principle.

12. Dispatch

Dispatch sends an action to Redux.

dispatch({
  type: "counter/increment"
});

The flow becomes:

Component
   ↓
dispatch(action)
   ↓
Redux
   ↓
Reducer
   ↓
New State
   ↓
Store
   ↓
Subscribed Components

13. Selectors

Selectors read data from the Redux store.

For example:

const selectCount = state => state.counter.value;

Then:

const count = useSelector(selectCount);

Selectors help keep components independent from the exact shape of the state.

Instead of:

state.counter.value

everywhere, you can use:

selectCount(state)

14. Redux Data Flow

Redux follows a predictable one-way data flow.

┌─────────────┐
│     UI      │
└──────┬──────┘
       │
       │ dispatch()
       ↓
┌─────────────┐
│   Action    │
└──────┬──────┘
       ↓
┌─────────────┐
│   Reducer   │
└──────┬──────┘
       ↓
┌─────────────┐
│    Store    │
└──────┬──────┘
       ↓
┌─────────────┐
│     UI      │
└─────────────┘

This predictable flow is one of Redux's biggest advantages.

15. A Simple Redux Example

Let's create a counter.

With Redux Toolkit:

import { createSlice, configureStore } from "@reduxjs/toolkit";

const counterSlice = createSlice({
  name: "counter",

  initialState: {
    value: 0
  },

  reducers: {
    increment(state) {
      state.value += 1;
    },

    decrement(state) {
      state.value -= 1;
    },

    incrementByAmount(state, action) {
      state.value += action.payload;
    }
  }
});

Export the actions:

export const {
  increment,
  decrement,
  incrementByAmount
} = counterSlice.actions;

Create the store:

const store = configureStore({
  reducer: {
    counter: counterSlice.reducer
  }
});

Now:

store.dispatch(increment());

Or:

store.dispatch(incrementByAmount(10));

16. Why Does Redux Toolkit Allow Mutation?

You might notice:

state.value += 1;

Earlier we said Redux state should not be mutated.

So why does this work?

Redux Toolkit uses Immer internally.

Immer allows you to write:

state.value += 1;

while internally producing an immutable state update.

Conceptually:

Your Code
   ↓
Immer
   ↓
Immutable Update
   ↓
Redux State

This gives developers simpler syntax while preserving Redux's immutability model.

17. createSlice

createSlice() is one of the most important Redux Toolkit APIs.

It combines:

State
Reducers
Action creators
Action types

Instead of manually writing:

const INCREMENT = "counter/increment";

function increment() {
  return {
    type: INCREMENT
  };
}

function reducer(state, action) {
  ...
}

you can write:

const counterSlice = createSlice({
  name: "counter",

  initialState: {
    value: 0
  },

  reducers: {
    increment(state) {
      state.value++;
    }
  }
});

Redux Toolkit generates the action creator automatically.

18. Payload Actions

Suppose we want to add a product.

const cartSlice = createSlice({
  name: "cart",

  initialState: {
    items: []
  },

  reducers: {
    addItem(state, action) {
      state.items.push(action.payload);
    }
  }
});

Dispatch:

dispatch(
  addItem({
    id: 1,
    name: "Laptop",
    price: 1200
  })
);

The action becomes conceptually:

{
  type: "cart/addItem",
  payload: {
    id: 1,
    name: "Laptop",
    price: 1200
  }
}

19. Redux With React

Redux itself is independent of React.

To integrate Redux with React, we commonly use React-Redux.

First create the store:

const store = configureStore({
  reducer: {
    counter: counterReducer
  }
});

Then provide it to React:

import { Provider } from "react-redux";

<Provider store={store}>
  <App />
</Provider>

Now components can access Redux.

20. useSelector

useSelector() reads data.

import { useSelector } from "react-redux";

function Counter() {
  const count = useSelector(
    state => state.counter.value
  );

  return <h1>{count}</h1>;
}

When the selected state changes, the component can re-render.

21. useDispatch

useDispatch() allows a component to dispatch actions.

import { useDispatch } from "react-redux";
import { increment } from "./counterSlice";

function CounterButton() {
  const dispatch = useDispatch();

  return (
    <button onClick={() => dispatch(increment())}>
      Increment
    </button>
  );
}

22. Complete React + Redux Example

function Counter() {
  const count = useSelector(
    state => state.counter.value
  );

  const dispatch = useDispatch();

  return (
    <div>
      <h1>{count}</h1>

      <button
        onClick={() => dispatch(increment())}
      >
        +
      </button>

      <button
        onClick={() => dispatch(decrement())}
      >
        -
      </button>
    </div>
  );
}

The component does not directly change:

state.counter.value

Instead:

Button
 ↓
dispatch(increment())
 ↓
Reducer
 ↓
New State
 ↓
useSelector
 ↓
Component Re-render

23. Local State vs Redux State

Not every piece of state belongs in Redux.

For example:

const [isOpen, setIsOpen] = useState(false);

This is usually local UI state.

Redux is more appropriate for state that needs to be shared or coordinated across different parts of an application.

Local State

Examples:

Modal open/closed
Input value
Dropdown state
Temporary UI state

Global State

Examples:

Authenticated user
Shopping cart
Permissions
Global notifications
Shared application configuration
Cached server data

24. Redux Is Not Always Necessary

A common mistake is:

"Every React application should use Redux."

Not true.

For a small application:

React
+
useState
+
useContext

may be enough.

Redux becomes more valuable as state complexity increases.

A useful question is:

Is the complexity of shared state becoming harder to manage than the complexity of introducing Redux?

25. Middleware

Middleware sits between:

dispatch()
   ↓
Middleware
   ↓
Reducer

It can:

Log actions
Perform asynchronous operations
Dispatch additional actions
Handle side effects
Integrate external services

Conceptually:

dispatch(action)
       ↓
   Middleware
       ↓
     Reducer
       ↓
      Store

26. Why Do We Need Middleware?

Reducers should be pure.

Therefore, things like:

fetch()

should not normally happen inside reducers.

Incorrect:

function reducer(state, action) {
  fetch("/api/products");

  return state;
}

Instead, asynchronous work should happen outside reducers, commonly through middleware.

27. Redux Thunk

Redux Toolkit includes thunk middleware by default.

A thunk allows you to dispatch a function-like async workflow.

Example:

const fetchUsers = () => async dispatch => {
  dispatch(usersLoading());

  try {
    const response = await fetch("/api/users");

    const users = await response.json();

    dispatch(usersLoaded(users));
  } catch (error) {
    dispatch(usersFailed(error.message));
  }
};

Then:

dispatch(fetchUsers());

The flow becomes:

Component
   ↓
dispatch(fetchUsers())
   ↓
Thunk
   ↓
API Request
   ↓
dispatch(usersLoaded())
   ↓
Reducer
   ↓
Store

28. createAsyncThunk

Redux Toolkit provides createAsyncThunk() to simplify common async workflows.

export const fetchUsers = createAsyncThunk(
  "users/fetchUsers",

  async () => {
    const response = await fetch("/api/users");

    return response.json();
  }
);

Then handle the lifecycle:

const usersSlice = createSlice({
  name: "users",

  initialState: {
    data: [],
    loading: false,
    error: null
  },

  extraReducers: builder => {
    builder
      .addCase(fetchUsers.pending, state => {
        state.loading = true;
      })

      .addCase(fetchUsers.fulfilled, (state, action) => {
        state.loading = false;
        state.data = action.payload;
      })

      .addCase(fetchUsers.rejected, (state, action) => {
        state.loading = false;
        state.error = action.error.message;
      });
  }
});

Now Redux automatically provides:

pending
fulfilled
rejected

29. Handling API State

A common pattern is:

{
  data: [],
  loading: false,
  error: null
}

The state transitions are:

Initial
 ↓
loading = true
 ↓
API Request
 ↓
 ┌───────────────┐
 │               │
Success        Failure
 │               │
 ↓               ↓
data          error

This makes asynchronous state explicit.

30. RTK Query

For server data, Redux Toolkit provides RTK Query.

RTK Query is designed specifically for:

Fetching data
Caching
Refetching
Loading states
Error states
Request deduplication
Cache invalidation

Example:

const api = createApi({
  reducerPath: "api",

  baseQuery: fetchBaseQuery({
    baseUrl: "/api"
  }),

  endpoints: builder => ({
    getUsers: builder.query({
      query: () => "/users"
    })
  })
});

Then:

const {
  data,
  isLoading,
  error
} = useGetUsersQuery();

This removes a lot of manual async-state management.

31. Redux Toolkit vs Traditional Redux

Traditional Redux often required:

Action Types
Action Creators
Reducers
Store
Middleware
Selectors

with a lot of boilerplate.

Modern Redux recommends Redux Toolkit.

Instead of:

const INCREMENT = "INCREMENT";

const increment = () => ({
  type: INCREMENT
});

function reducer(state, action) {
  switch (action.type) {
    ...
  }
}

you can use:

const counterSlice = createSlice({
  name: "counter",

  initialState: {
    value: 0
  },

  reducers: {
    increment(state) {
      state.value++;
    }
  }
});

Redux Toolkit is now the recommended way to write Redux applications.

32. Normalizing State

Suppose you have:

{
  users: [
    {
      id: 1,
      name: "John"
    },
    {
      id: 2,
      name: "Sarah"
    }
  ]
}

As applications grow, searching and updating entities can become inefficient.

Normalized state can look like:

{
  users: {
    ids: [1, 2],

    entities: {
      1: {
        id: 1,
        name: "John"
      },

      2: {
        id: 2,
        name: "Sarah"
      }
    }
  }
}

Redux Toolkit provides:

createEntityAdapter()

for this use case.

33. createEntityAdapter

Example:

const usersAdapter = createEntityAdapter();

const initialState =
  usersAdapter.getInitialState();

You can then use generated reducers and selectors to manage entities efficiently.

This is especially useful for:

Users
Products
Orders
Messages
Notifications

34. Selectors in Large Applications

Instead of exposing state structure everywhere:

state.products.entities

create selectors:

const selectProducts =
  state => state.products.entities;

Then components use:

const products = useSelector(selectProducts);

This improves maintainability.

35. Derived State

Sometimes you don't need to store everything.

For example, suppose Redux contains:

{
  products: [
    { price: 100 },
    { price: 200 },
    { price: 300 }
  ]
}

You don't necessarily need:

{
  products: [...],
  totalPrice: 600
}

You can derive it:

const selectTotalPrice = state =>
  state.products.reduce(
    (total, product) => total + product.price,
    0
  );

This avoids duplicated state.

36. Memoized Selectors

For expensive calculations, selectors can be memoized.

Redux Toolkit works well with Reselect-style selectors.

Example:

const selectCompletedTodos = createSelector(
  [selectTodos],

  todos =>
    todos.filter(todo => todo.completed)
);

The selector can avoid recalculating when its inputs haven't changed.

37. Redux Architecture

A scalable Redux application can be organized by features:

src/
│
├── app/
│   └── store.js
│
├── features/
│   ├── auth/
│   │   ├── authSlice.js
│   │   ├── authSelectors.js
│   │   └── authApi.js
│   │
│   ├── products/
│   │   ├── productsSlice.js
│   │   ├── productsSelectors.js
│   │   └── productsApi.js
│   │
│   └── cart/
│       ├── cartSlice.js
│       └── cartSelectors.js
│
└── components/

This is called feature-based organization.

It scales much better than organizing everything by technical type.

38. Real-World Example: E-Commerce

Imagine an e-commerce application.

We might have:

Redux Store
│
├── auth
│
├── cart
│
├── products
│
├── orders
│
└── ui

Example:

{
  auth: {
    user: null,
    token: null
  },

  cart: {
    items: []
  },

  products: {
    ids: [],
    entities: {}
  },

  orders: {
    ids: [],
    entities: {}
  },

  ui: {
    sidebarOpen: false
  }
}

39. Adding a Product to the Cart

User clicks:

Add to Cart

The component dispatches:

dispatch(
  addToCart({
    productId: 10,
    quantity: 1
  })
);

Redux flow:

Product Component
       ↓
addToCart()
       ↓
Action
       ↓
Cart Reducer
       ↓
Cart State Updated
       ↓
Cart Icon
       ↓
UI Updated

The cart icon can now select:

const itemCount = useSelector(
  selectCartItemCount
);

40. Authentication Example

Suppose a user logs in.

The UI dispatches:

dispatch(
  loginSuccess({
    id: 1,
    name: "John"
  })
);

The reducer updates:

{
  user: {
    id: 1,
    name: "John"
  },
  isAuthenticated: true
}

Other components can react to this state.

For example:

const user = useSelector(selectCurrentUser);

41. Redux DevTools

One of Redux's biggest advantages is debugging.

Redux DevTools can show:

Action
   ↓
Previous State
   ↓
Action Payload
   ↓
Next State

For example:

cart/addItem

You can inspect:

{
  productId: 10,
  quantity: 2
}

and then compare the previous and next state.

This makes complex state transitions easier to debug.

42. Time-Travel Debugging

Because Redux state transitions are explicit:

State 0
 ↓
Action A
 ↓
State 1
 ↓
Action B
 ↓
State 2
 ↓
Action C
 ↓
State 3

development tools can replay state transitions.

This is one of the conceptual reasons Redux became popular.

43. Common Redux Mistakes

Mistake 1: Putting Everything in Redux

Don't put every UI detail into Redux.

Avoid:

{
  modalIsOpen: true,
  inputValue: "hello",
  hoverState: true
}

unless there is a genuine reason for global access.

Mistake 2: Mutating State Outside Immer

Do not do:

const user = store.getState().user;

user.name = "New Name";

State should be changed through Redux actions and reducers.

Mistake 3: Putting API Calls in Reducers

Avoid:

function reducer(state, action) {
  fetch("/api/users");

  return state;
}

Reducers should remain pure.

Mistake 4: Duplicating Derived Data

Avoid storing:

{
  items: [...],
  itemCount: 5
}

if itemCount can simply be calculated from items.

Mistake 5: Huge Global Slice

Avoid creating:

appSlice.js

with hundreds of unrelated responsibilities.

Prefer:

authSlice
cartSlice
productsSlice
ordersSlice
notificationsSlice

44. Redux vs Context API

React Context and Redux solve related but different problems.

Context

Good for:

Theme
Locale
Authentication context
Simple global configuration

Redux

Useful when you have:

Complex state
Many state transitions
Multiple consumers
Complex async workflows
Need for powerful debugging
Normalized entities
Large application state

Context is not automatically a replacement for Redux.

45. Redux vs useState

useState is excellent for local state.

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

Redux becomes useful when state needs to be shared and the update logic becomes complex.

Think:

Simple local state
      ↓
useState

versus:

Complex shared application state
      ↓
Redux

46. Redux vs Zustand

Redux and Zustand are both state management solutions.

Redux provides a more structured architecture:

Actions
 ↓
Reducers
 ↓
Store

Zustand generally provides a simpler API with less ceremony.

Redux is often preferred when:

The application is large
A standardized architecture matters
Teams need predictable conventions
Advanced Redux tooling is valuable
Existing ecosystem integrations are important

Zustand can be attractive when simplicity and minimal boilerplate are priorities.

47. A Practical Redux Mental Model

If you remember only one model, remember this:

STATE
  ↑
REDUCER
  ↑
ACTION
  ↑
DISPATCH
  ↑
UI

Or:

User Interaction
      ↓
    Action
      ↓
    Reducer
      ↓
  New State
      ↓
     UI

48. Complete Mini Project

Let's combine the concepts.

Store

import { configureStore } from "@reduxjs/toolkit";
import cartReducer from "./cartSlice";

export const store = configureStore({
  reducer: {
    cart: cartReducer
  }
});

Slice

import { createSlice } from "@reduxjs/toolkit";

const cartSlice = createSlice({
  name: "cart",

  initialState: {
    items: []
  },

  reducers: {
    addItem(state, action) {
      const existingItem = state.items.find(
        item => item.id === action.payload.id
      );

      if (existingItem) {
        existingItem.quantity += 1;
      } else {
        state.items.push({
          ...action.payload,
          quantity: 1
        });
      }
    },

    removeItem(state, action) {
      state.items = state.items.filter(
        item => item.id !== action.payload
      );
    },

    clearCart(state) {
      state.items = [];
    }
  }
});

export const {
  addItem,
  removeItem,
  clearCart
} = cartSlice.actions;

export default cartSlice.reducer;

Selector

export const selectCartItems =
  state => state.cart.items;

export const selectCartCount =
  state =>
    state.cart.items.reduce(
      (total, item) => total + item.quantity,
      0
    );

Component

function Cart() {
  const items = useSelector(selectCartItems);
  const count = useSelector(selectCartCount);

  const dispatch = useDispatch();

  return (
    <div>
      <h1>Cart ({count})</h1>

      {items.map(item => (
        <div key={item.id}>
          {item.name}

          <button
            onClick={() =>
              dispatch(removeItem(item.id))
            }
          >
            Remove
          </button>
        </div>
      ))}

      <button
        onClick={() => dispatch(clearCart())}
      >
        Clear Cart
      </button>
    </div>
  );
}

This is already a realistic Redux pattern.

49. The Most Important Redux APIs

Modern Redux development commonly revolves around:

configureStore()
createSlice()
createAsyncThunk()
createEntityAdapter()
createSelector()
createApi()
fetchBaseQuery()

React integration commonly uses:

Provider
useSelector()
useDispatch()

You do not need to memorize everything immediately.

Understand the architecture first.

50. Redux in One Diagram

                         ┌──────────────┐
                         │     UI       │
                         └──────┬───────┘
                                │
                         dispatch(action)
                                │
                                ↓
                         ┌──────────────┐
                         │ Middleware   │
                         └──────┬───────┘
                                │
                                ↓
                         ┌──────────────┐
                         │   Reducer    │
                         └──────┬───────┘
                                │
                         New Immutable State
                                │
                                ↓
                         ┌──────────────┐
                         │    Store     │
                         └──────┬───────┘
                                │
                          subscribe/select
                                │
                                ↓
                         ┌──────────────┐
                         │     UI       │
                         └──────────────┘

Conclusion

Redux is fundamentally about predictable state transitions.

The most important concepts are:

Store
Actions
Reducers
Dispatch
Selectors
Middleware
Immutability

Modern Redux development should generally use Redux Toolkit rather than manually writing the older Redux boilerplate.

The key mental model is:

UI
 ↓
dispatch(Action)
 ↓
Middleware
 ↓
Reducer
 ↓
New State
 ↓
Store
 ↓
Selectors
 ↓
UI

Once you understand this flow, advanced Redux concepts such as asynchronous actions, RTK Query, entity adapters, memoized selectors, and large-scale Redux architecture become much easier to understand.

Redux isn't simply a place to put variables.

It is an architecture for making state changes explicit, predictable, traceable, and easier to manage as an application grows.

Why React & Next.js Users Get `ChunkLoadError` After Deployment — And How to Fix It

Abanoub Kerols — Sun, 20 Sep 2026 21:14:25 +0000

Imagine this:

You have a React or Next.js application running in production.

You deploy a new version.

New visitors can use the website normally.

But some users who already had the website open suddenly see:

ChunkLoadError
Failed to load chunk
Failed to fetch dynamically imported module
Loading chunk failed

Then they refresh the page...

And everything works again.

So what's happening?

Is the solution really to force every user to refresh?

No.

The refresh may recover the application, but it doesn't solve the underlying deployment problem.

The real issue is usually a version mismatch between the application running in the user's browser and the assets available on the server after deployment.

In this article, we'll understand why this happens and how production deployments should handle it.

The Problem
What Happens When a User Opens the Application?
What Changes During a Deployment?
Why Does the Old User Break?
Why Does Refreshing Fix It?
Understanding JavaScript Chunks
The Real Solution
Immutable Assets
Versioned Releases
Atomic Deployments
Rolling Deployments
Caching Strategy
What About Automatic Refresh?
A Production Architecture
The Interview Answer
Final Takeaway

The Problem

Let's start with a simple scenario.

A user opens your application:

https://example.com

At that moment, the production application is:

Version 1

The browser downloads the HTML and JavaScript assets required by that version.

For example:

app-ABC123.js
dashboard-XYZ456.js
profile-111.js

The user keeps the tab open.

After a few hours, you deploy a new version.

Now the server is running:

Version 2

The new build generates different assets:

app-DEF789.js
dashboard-QWE321.js
profile-222.js

Now we have:

Browser
   |
   | Version 1
   | Old runtime
   | Old chunks
   |
   v
--------------------
      Server
--------------------
   |
   | Version 2
   | New runtime
   | New chunks

This is where things can go wrong.

What Happens When a User Opens the Application?

A modern frontend application is usually not one giant JavaScript file.

The browser may load:

HTML
 |
 +-- main JavaScript
 |
 +-- framework/runtime
 |
 +-- feature chunks
 |
 +-- dynamically loaded chunks

For example:

flowchart TD
    A[Browser requests HTML] --> B[Application Runtime]
    B --> C[Initial JavaScript]
    B --> D[Dashboard Chunk]
    B --> E[Profile Chunk]
    B --> F[Other Dynamic Chunks]

Some chunks may only be loaded when the user navigates to a particular feature.

For example:

User opens application
        |
        v
Loads main application
        |
        v
User opens Dashboard
        |
        v
Browser requests dashboard chunk

This is one of the reasons modern frontend applications can be fast.

The browser doesn't necessarily download everything immediately.

What Changes During a Deployment?

Now imagine we change the Dashboard.

Version 1 contains:

dashboard-ABC123.js

After rebuilding the application:

Version 2 contains:

dashboard-DEF456.js

The new version is deployed.

If the deployment process removes the old asset:

dashboard-ABC123.js

then an existing browser session may still expect it.

That's the key problem.

Why Does the Old User Break?

Let's follow the request.

The user opened Version 1 earlier.

Their browser is still running the old runtime.

The old runtime says:

"I need dashboard-ABC123.js"

The browser requests:

GET /assets/dashboard-ABC123.js

But the deployment has already deleted it.

The server responds:

404 Not Found

The frontend may then produce:

ChunkLoadError

or:

Failed to fetch dynamically imported module

The sequence looks like this:

sequenceDiagram
    participant Browser
    participant Server

    Browser->>Server: Request old chunk
    Server-->>Browser: 404 Not Found
    Browser->>Browser: ChunkLoadError

The important point is:

The browser isn't necessarily broken. The deployment made the asset that its current runtime needs unavailable.

Why Does Refreshing Fix It?

This is the interesting part.

When the user refreshes the page, the browser requests the current application again.

Now the server returns Version 2.

The browser receives:

Version 2 HTML
       |
       v
Version 2 Runtime
       |
       v
Version 2 Chunks

Everything matches.

So the application works.

That's why a refresh appears to "fix" the problem.

But the refresh is only recovering the user by replacing the old application version with the new one.

It doesn't solve the deployment strategy.

The Real Problem: Version Mismatch

We can summarize the problem as:

Old Runtime
     +
Missing/Incompatible Old Assets
     =
Chunk Loading Failure

Or:

Browser Version
       !=
Available Server Assets

This is the mental model I use when debugging these issues.

Understanding JavaScript Chunks

Modern frontend build systems use techniques such as:

Code splitting
Lazy loading
Dynamic imports
Route-based splitting

Instead of generating:

application.js

the build may produce:

main-ABC123.js
dashboard-DEF456.js
profile-GHI789.js
settings-JKL012.js

The browser loads the chunks it needs.

For example:

const Dashboard = lazy(() => import("./Dashboard"));

The exact implementation differs between React, Next.js, bundlers, and deployment environments, but the important concept is the same:

The runtime needs to know where to find the correct assets for its build.

If those assets disappear during deployment, existing sessions can fail.

The Real Solution

So what should we do?

Not:

Deploy
   ↓
Delete everything old
   ↓
Hope existing users refresh

Instead, we want:

Build
  ↓
Create new release
  ↓
Publish new assets
  ↓
Validate release
  ↓
Switch traffic
  ↓
Keep old assets temporarily
  ↓
Cleanup later

This leads to several important concepts:

Immutable assets
Versioned releases
Atomic deployments
Rolling deployments
Correct caching
Controlled recovery

Let's look at each one.

Immutable Assets

One of the most important ideas is immutable assets.

Suppose Version 1 generates:

app-A1B2C3.js

Version 2 generates:

app-D4E5F6.js

Instead of modifying the old file, we keep both:

/assets/

app-A1B2C3.js
app-D4E5F6.js

Version 1 users can still request:

app-A1B2C3.js

Version 2 users can request:

app-D4E5F6.js

Both can coexist.

flowchart LR
    A[Old Users] --> B[Old Assets]
    C[New Users] --> D[New Assets]

    B --> E[Release 1]
    D --> F[Release 2]

This is much safer than replacing the contents of the same filename.

Why Do Asset Hashes Help?

Production builds commonly generate content-based filenames.

For example:

app-a82f91.js

If the code changes:

app-b91d72.js

The filename changes.

This gives us a very useful property:

If the filename contains the content hash, changing the content produces a different asset.

That means we can safely cache a particular asset for a long time because that exact file is not expected to change.

Versioned Releases

Another useful strategy is to treat every deployment as a separate release.

For example:

/releases/

release-101/
release-102/
release-103/

Each release contains its own application build.

Conceptually:

release-101/
    build/
    assets/
    server/

release-102/
    build/
    assets/
    server/

Then we have a pointer to the active release:

current -> release-102

When we deploy:

current -> release-103

The old release doesn't have to disappear immediately.

This gives existing users time to finish their current session.

Atomic Deployments

A dangerous deployment might look like:

Stop application
      ↓
Delete old build
      ↓
Copy new build
      ↓
Start application

This creates a period where the application may be partially unavailable.

A safer approach is:

Build new release
      ↓
Upload new release
      ↓
Validate it
      ↓
Switch traffic
      ↓
Keep old release
      ↓
Cleanup later

The switch between releases should be as atomic as possible.

For example:

flowchart TD
    A[Load Balancer / Nginx] --> B[Current Release]

    B --> C[Release 101]
    B --> D[Release 102]

    D --> E[New Release]

After validation:

Current → Release 102

Then Release 101 can remain available until it is safe to remove.

Rolling Deployments

If your application runs multiple instances, another option is a rolling deployment.

Suppose we start with:

Server 1 → Version 1
Server 2 → Version 1
Server 3 → Version 1

We deploy Version 2 gradually:

Server 1 → Version 2
Server 2 → Version 1
Server 3 → Version 1

Then:

Server 1 → Version 2
Server 2 → Version 2
Server 3 → Version 1

Finally:

Server 1 → Version 2
Server 2 → Version 2
Server 3 → Version 2

Health checks and a load balancer can help ensure traffic is only sent to healthy instances.

This reduces the chance of taking the entire application offline during deployment.

Caching Strategy

Caching is another important part of this problem.

We normally have two very different categories of resources:

HTML

and:

Hashed static assets

They should not necessarily have the same caching strategy.

For hashed assets:

app-a82f91.js

we can often use long-lived caching:

Cache-Control: public, max-age=31536000, immutable

because if the application changes, the build generates another filename.

For example:

Old:
app-a82f91.js

New:
app-b91d72.js

The old file doesn't need to be overwritten.

What About HTML?

HTML is different.

The HTML document references the assets belonging to a particular application version.

For example:

<script src="/assets/app-a82f91.js"></script>

A new deployment may produce:

<script src="/assets/app-b91d72.js"></script>

Therefore, caching HTML indefinitely can cause users to receive stale references.

A common high-level strategy is:

HTML
→ Revalidate more frequently

Hashed JS/CSS
→ Cache for a long time

The exact configuration depends on your framework, CDN, reverse proxy, and hosting architecture.

What About Next.js?

Next.js uses generated build assets under paths such as:

/_next/static/

A production deployment should treat the build as a coherent release.

The important principle is not:

"Never delete .next."

The important principle is:

Don't make assets required by an active application version disappear before that version is no longer needed.

How you achieve that depends on the deployment architecture.

For example, you might use:

Release 101
    |
    +-- .next
    +-- server
    +-- static assets

Release 102
    |
    +-- .next
    +-- server
    +-- static assets

Then switch the active release after the new version is ready.

What About React?

The same general concept applies to React applications.

For example, a Vite production build may generate:

dist/

assets/
    index-A1B2C3.js
    Dashboard-D4E5F6.js
    index-G7H8I9.css

After another build:

assets/
    index-J1K2L3.js
    Dashboard-M4N5O6.js
    index-P7Q8R9.css

The deployment should not blindly destroy assets that an existing application version may still require.

The exact files and runtime behavior depend on the build tool and architecture, but the deployment principle remains the same.

What About Automatic Refresh?

Now we can answer the original interview question.

Could we detect:

ChunkLoadError

and reload the page?

Yes.

A recovery mechanism could conceptually do:

ChunkLoadError
      ↓
Detect error
      ↓
Reload once
      ↓
Load current release

This can be useful.

But:

Automatic reload is a fallback, not the primary deployment solution.

If your deployment consistently deletes assets required by active sessions, adding window.location.reload() doesn't fix the architecture.

It only hides the symptom.

Why Blindly Reloading Can Be Dangerous

Imagine a user is filling out a form:

Name: John
Email: john@example.com
Phone: 01012345678

Then a chunk-loading error occurs.

If your application automatically executes:

window.location.reload();

the user may lose unsaved state.

There is another possible problem.

If the deployment is still broken:

ChunkLoadError
      ↓
Reload
      ↓
ChunkLoadError
      ↓
Reload
      ↓
ChunkLoadError

You can create a reload loop.

So if automatic recovery is implemented, it should be controlled carefully.

A Production-Oriented Architecture

A simplified architecture could look like this:

flowchart TD
    U[Users] --> CDN[CDN / Nginx]
    CDN --> LB[Load Balancer]

    LB --> R1[Current Release]
    LB --> R2[Previous Release]

    R1 --> A1[New Immutable Assets]
    R2 --> A2[Old Immutable Assets]

    R2 --> C[Cleanup Later]

The key idea is that the old assets don't disappear immediately.

Eventually:

Old users finish their sessions
        ↓
Old release is no longer needed
        ↓
Old assets can be cleaned up

A Complete Deployment Flow

A good mental model is:

Developer pushes code
        ↓
CI/CD builds application
        ↓
Create versioned release
        ↓
Generate hashed assets
        ↓
Publish assets
        ↓
Run tests / health checks
        ↓
Deploy new application version
        ↓
Switch traffic
        ↓
Keep old assets/release temporarily
        ↓
Users naturally move to new version
        ↓
Cleanup old release

This approach is much more robust than:

Delete old files
      ↓
Copy new files
      ↓
Hope everyone refreshes

Is This Only a Next.js Problem?

No.

You can encounter similar deployment problems in applications built with:

React
Next.js
Angular
Vue
Nuxt
Vite-based applications
Other applications using code splitting and dynamically loaded assets

The exact error message may differ.

But the underlying idea is often:

Client is running Version N
        +
Server/CDN is serving Version N+1
        +
Required old assets are unavailable
        =
Application failure

The Interview Answer

If an interviewer asks:

"Why do users who already have the website open get errors after we deploy a new React/Next.js version?"

A strong answer could be:

"It's usually caused by a version mismatch between the application runtime already running in the user's browser and the assets available after the deployment.

An existing user may still be running the old JavaScript runtime, which references a chunk from the previous build. If that chunk was removed during deployment, the browser gets a 404 and the application can throw a ChunkLoadError or fail to load a dynamic module.

I wouldn't solve this simply by forcing users to refresh. I'd use immutable, versioned assets and an atomic or rolling deployment strategy. Old assets should remain available long enough for existing sessions to drain, while new users receive the new release.

I'd also configure caching appropriately: hashed static assets can be cached for a long time, while HTML needs a different caching strategy.

An automatic reload can be used as a fallback recovery mechanism, but it shouldn't be the primary deployment solution."

That answer demonstrates that you understand more than React itself.

You understand the relationship between:

Frontend
   +
Build System
   +
Browser
   +
Caching
   +
CDN
   +
Deployment
   +
Infrastructure

Final Takeaway

The problem isn't simply:

"The user needs to refresh."

The deeper problem is:

A user can continue running an older version of a frontend application after the server has already deployed a newer version.

If the old runtime needs assets that the new deployment has removed, the application can fail.

The solution is to design deployments around version compatibility.

The key concepts are:

Immutable Assets
        +
Versioned Releases
        +
Atomic / Rolling Deployments
        +
Proper Cache Strategy
        +
Temporary Retention of Old Assets
        +
Controlled Recovery

Once you understand this model, ChunkLoadError is no longer just a mysterious React or Next.js error.

It's a client/server deployment consistency problem.

And that's the real answer to the interview question.

One More Thing

The next time someone answers this interview question with:

"Just force the user to refresh."

ask:

"What happens to the JavaScript chunks that the existing browser session is already using?"

That question gets you much closer to the real problem.

NgRx in Angular: A Practical Guide to State Management, Architecture, and Real-World Patterns

Abanoub Kerols — Thu, 17 Sep 2026 21:33:16 +0000

NgRx is more than a store. It is an architecture for managing complex application state in Angular using predictable state transitions, reactive programming, and unidirectional data flow.

Modern Angular applications can start simple, but as the application grows, state management becomes increasingly difficult.

You may eventually have:

Components sharing the same data
Multiple API requests updating the same state
Complex loading and error states
Data that must survive navigation
Business logic spread across components
Race conditions between asynchronous operations
Difficult-to-debug state changes

This is where NgRx becomes useful.

In this article, we will build the concepts from the ground up and gradually move toward real-world patterns.

What Is State Management?
Why Do We Need NgRx?
What Is NgRx?
NgRx Architecture
The Unidirectional Data Flow
Store
Actions
Reducers
Selectors
Effects
Dispatching Actions
Reading State
Complete CRUD Example
Async Operations
Loading and Error States
Entity State
NgRx Entity
Feature-Based State
ComponentStore vs Store
Facades
Immutability
Common NgRx Patterns
Common Mistakes
Performance
Testing
When Should You Use NgRx?
Final Architecture

1. What Is State Management?

Before understanding NgRx, we need to understand state.

State is simply the data that describes the current condition of your application.

For example:

interface User {
  id: number;
  name: string;
  email: string;
}

Your application might have:

interface AppState {
  user: User | null;
  isLoading: boolean;
  error: string | null;
}

At a particular moment:

{
  user: {
    id: 1,
    name: 'John',
    email: 'john@example.com'
  },
  isLoading: false,
  error: null
}

This is application state.

2. Local State vs Global State

Not every piece of state needs NgRx.

Consider a button:

isMenuOpen = false;

This is usually local component state.

You probably don't need a global store for it.

But consider:

Authentication
Products
Shopping Cart
User Profile
Notifications
Permissions
Orders

These may be shared by many parts of the application.

For example:

Navbar
   ↓
User Authentication State
   ↑
Profile Page
   ↑
Checkout
   ↑
Orders

When many components depend on the same state, centralized state management becomes useful.

3. What Is NgRx?

NgRx is a collection of Angular libraries inspired by Redux and built around reactive programming with RxJS.

The core idea is:

Component
   ↓
Action
   ↓
Reducer / Effect
   ↓
Store
   ↓
Selector
   ↓
Component

Instead of allowing components to modify shared state directly, state changes happen through actions.

This creates predictable state transitions.

4. NgRx Architecture

The main pieces are:

                ┌─────────────┐
                │  Component  │
                └──────┬──────┘
                       │
                    dispatch
                       │
                       ▼
                ┌─────────────┐
                │   Action    │
                └──────┬──────┘
                       │
             ┌─────────┴─────────┐
             │                   │
             ▼                   ▼
        ┌──────────┐        ┌──────────┐
        │ Reducer  │        │  Effect  │
        └────┬─────┘        └────┬─────┘
             │                   │
             │                   ▼
             │              HTTP / API
             │                   │
             │                   ▼
             │               Action
             │                   │
             └─────────┬─────────┘
                       ▼
                 ┌──────────┐
                 │  Store   │
                 └────┬─────┘
                      │
                   select
                      │
                      ▼
                ┌─────────────┐
                │  Component  │
                └─────────────┘

There are five concepts you should understand extremely well:

Actions
Reducers
Store
Selectors
Effects

5. The Unidirectional Data Flow

NgRx follows a unidirectional data flow.

That means data moves in a predictable direction.

UI
 ↓
Action
 ↓
State Transition
 ↓
Store
 ↓
Selector
 ↓
UI

For example:

this.store.dispatch(
  increment()
);

The component does not directly change:

count = count + 1;

Instead, it describes what happened:

increment()

The reducer determines how the state should change.

6. The Store

The Store is the centralized state container.

Imagine:

interface AppState {
  counter: number;
  user: User | null;
  products: Product[];
}

Conceptually:

Store
├── counter
├── user
└── products

The Store itself is observable.

You read state reactively:

counter$ = this.store.select(selectCounter);

Then:

<p>{{ counter$ | async }}</p>

7. Actions

An Action describes something that happened.

Example:

import { createAction } from '@ngrx/store';

export const increment = createAction(
  '[Counter] Increment'
);

Another:

export const loadProducts = createAction(
  '[Products Page] Load Products'
);

The string:

[Products Page] Load Products

is the action type.

A good action describes an event.

Prefer:

[Login Page] Login Submitted

over:

[Auth] Set User

Why?

Because the first describes what happened, while the second describes an implementation detail.

8. Actions With Payloads

Actions can carry data.

export const addToCart = createAction(
  '[Cart] Add Product',
  props<{ productId: number }>()
);

Dispatch:

this.store.dispatch(
  addToCart({ productId: 10 })
);

Another example:

export const login = createAction(
  '[Login Page] Login Submitted',
  props<{
    email: string;
    password: string;
  }>()
);

Then:

this.store.dispatch(
  login({
    email: 'john@example.com',
    password: '123456'
  })
);

9. Reducers

Reducers determine how state changes in response to actions.

Example:

import { createReducer, on } from '@ngrx/store';

export const initialState = 0;

export const counterReducer = createReducer(
  initialState,

  on(increment, state => state + 1)
);

The important concept is:

Action
   +
Current State
   ↓
New State

For example:

State = 5

Action = increment

Reducer

5 + 1

New State = 6

10. Reducers Must Be Pure

A reducer should be:

Predictable
Synchronous
Pure
Free from side effects

Don't do this inside a reducer:

on(loadProducts, state => {
  http.get('/products');
  return state;
});

Reducers should not perform HTTP requests.

They should only calculate the next state.

11. Immutable State

NgRx relies heavily on immutability.

Bad:

state.user.name = 'John';

return state;

Good:

return {
  ...state,
  user: {
    ...state.user,
    name: 'John'
  }
};

The idea is to create a new state reference instead of mutating the existing one.

12. Selectors

Selectors are used to read data from the Store.

Suppose:

interface CounterState {
  count: number;
}

Create a feature selector:

export const selectCounterState =
  createFeatureSelector<CounterState>('counter');

Then:

export const selectCount = createSelector(
  selectCounterState,
  state => state.count
);

Component:

count$ = this.store.select(selectCount);

Template:

<h1>
  {{ count$ | async }}
</h1>

13. Why Selectors Are Important

You might ask:

Why not simply get the entire state?

Because selectors provide:

Encapsulation

Components don't need to know how state is structured.

Memoization

Selectors can avoid unnecessary recalculations.

Reusability

Multiple components can use the same selector.

Performance

Components subscribe only to the data they need.

14. Derived State

One of the most powerful selector features is derived state.

Suppose:

interface CartState {
  items: CartItem[];
}

You can calculate:

export const selectCartTotal = createSelector(
  selectCartItems,
  items =>
    items.reduce(
      (total, item) => total + item.price * item.quantity,
      0
    )
);

The total does not need to be stored separately.

Instead:

Cart Items
    ↓
Selector
    ↓
Cart Total

This avoids duplicated state.

15. Effects

Effects handle side effects.

Examples:

HTTP Requests
Local Storage
Analytics
Navigation
WebSocket interactions
External APIs

Suppose:

User clicks Load Products
        ↓
loadProducts action
        ↓
Effect
        ↓
HTTP request
        ↓
API response
        ↓
loadProductsSuccess
        ↓
Reducer
        ↓
Store

This is the main purpose of NgRx Effects.

16. Example Effect

@Injectable()
export class ProductsEffects {

  loadProducts$ = createEffect(() =>
    this.actions$.pipe(

      ofType(loadProducts),

      switchMap(() =>
        this.productsService.getProducts().pipe(

          map(products =>
            loadProductsSuccess({ products })
          ),

          catchError(error =>
            of(loadProductsFailure({ error }))
          )

        )
      )

    )
  );

  constructor(
    private actions$: Actions,
    private productsService: ProductsService
  ) {}
}

The effect listens for:

loadProducts

Then performs:

productsService.getProducts()

And dispatches:

loadProductsSuccess

or:

loadProductsFailure

17. The Complete Request Flow

Let's visualize it:

User
 │
 ▼
Products Component
 │
 │ dispatch()
 ▼
loadProducts
 │
 ▼
Products Effect
 │
 │ HTTP
 ▼
Backend API
 │
 ▼
Response
 │
 ▼
loadProductsSuccess
 │
 ▼
Products Reducer
 │
 ▼
Store
 │
 ▼
selectProducts
 │
 ▼
Products Component

This is one of the most important NgRx flows to understand.

18. Loading and Error State

A realistic application needs more than data.

For example:

interface ProductsState {
  products: Product[];
  loading: boolean;
  error: string | null;
}

Initial state:

const initialState: ProductsState = {
  products: [],
  loading: false,
  error: null
};

When loading starts:

on(loadProducts, state => ({
  ...state,
  loading: true,
  error: null
}))

Success:

on(loadProductsSuccess, (state, { products }) => ({
  ...state,
  products,
  loading: false
}))

Failure:

on(loadProductsFailure, (state, { error }) => ({
  ...state,
  loading: false,
  error
}))

19. Complete Products Example

Actions

export const loadProducts = createAction(
  '[Products Page] Load Products'
);

export const loadProductsSuccess = createAction(
  '[Products API] Load Products Success',
  props<{ products: Product[] }>()
);

export const loadProductsFailure = createAction(
  '[Products API] Load Products Failure',
  props<{ error: string }>()
);

Reducer

export interface ProductsState {
  products: Product[];
  loading: boolean;
  error: string | null;
}

export const initialState: ProductsState = {
  products: [],
  loading: false,
  error: null
};

export const productsReducer = createReducer(
  initialState,

  on(loadProducts, state => ({
    ...state,
    loading: true,
    error: null
  })),

  on(loadProductsSuccess, (state, { products }) => ({
    ...state,
    products,
    loading: false
  })),

  on(loadProductsFailure, (state, { error }) => ({
    ...state,
    loading: false,
    error
  }))
);

Selectors

export const selectProductsState =
  createFeatureSelector<ProductsState>('products');

export const selectProducts = createSelector(
  selectProductsState,
  state => state.products
);

export const selectLoading = createSelector(
  selectProductsState,
  state => state.loading
);

export const selectError = createSelector(
  selectProductsState,
  state => state.error
);

Component

products$ = this.store.select(selectProducts);
loading$ = this.store.select(selectLoading);
error$ = this.store.select(selectError);

loadProducts() {
  this.store.dispatch(loadProducts());
}

Template

<button (click)="loadProducts()">
  Load Products
</button>

@if (loading$ | async) {
  <p>Loading...</p>
}

@if (error$ | async; as error) {
  <p>{{ error }}</p>
}

@for (product of products$ | async; track product.id) {
  <article>
    <h2>{{ product.name }}</h2>
    <p>{{ product.price }}</p>
  </article>
}

20. NgRx Entity

Imagine you have:

Product[]

with thousands of products.

You frequently need:

Find product by ID
Add product
Remove product
Update product
Select all products

Managing arrays manually becomes repetitive.

NgRx Entity provides utilities for normalized collections.

Conceptually:

Entity State

ids:
[1, 2, 3]

entities:
{
  1: Product,
  2: Product,
  3: Product
}

Instead of:

products.find(p => p.id === id);

the entity adapter can provide selectors and operations for you.

21. Entity Adapter

Example:

const adapter = createEntityAdapter<Product>();

Initial state:

const initialState =
  adapter.getInitialState({
    loading: false,
    error: null
  });

Add products:

adapter.addMany(products, state);

Update:

adapter.updateOne(
  {
    id: product.id,
    changes: product
  },
  state
);

Remove:

adapter.removeOne(productId, state);

This becomes extremely useful for large collections.

22. Feature-Based Architecture

A large Angular application should not have one giant Store file.

Instead:

src/app/
│
├── core/
│
├── shared/
│
└── features/
    │
    ├── auth/
    │   ├── store/
    │   │   ├── auth.actions.ts
    │   │   ├── auth.reducer.ts
    │   │   ├── auth.effects.ts
    │   │   └── auth.selectors.ts
    │   │
    │   └── pages/
    │
    ├── products/
    │   ├── store/
    │   │   ├── products.actions.ts
    │   │   ├── products.reducer.ts
    │   │   ├── products.effects.ts
    │   │   └── products.selectors.ts
    │
    └── cart/
        ├── store/
        │   ├── cart.actions.ts
        │   ├── cart.reducer.ts
        │   ├── cart.effects.ts
        │   └── cart.selectors.ts

This keeps features isolated.

23. NgRx Facade Pattern

Some teams don't want components to know about NgRx directly.

Instead, introduce a facade.

@Injectable({
  providedIn: 'root'
})
export class ProductsFacade {

  products$ = this.store.select(selectProducts);

  loading$ = this.store.select(selectLoading);

  constructor(
    private store: Store
  ) {}

  loadProducts() {
    this.store.dispatch(loadProducts());
  }
}

Component:

constructor(
  private productsFacade: ProductsFacade
) {}

products$ = this.productsFacade.products$;

loadProducts() {
  this.productsFacade.loadProducts();
}

Now the component doesn't know about:

Actions
Selectors
Store

It only knows:

ProductsFacade

This can be useful in large applications.

24. RxJS and NgRx

NgRx relies heavily on RxJS.

For example:

this.store.select(selectProducts)

returns an Observable.

Effects also use RxJS operators:

ofType()
switchMap()
mergeMap()
concatMap()
exhaustMap()
map()
catchError()

Understanding RxJS is therefore extremely valuable when working with NgRx.

25. Choosing the Correct Flattening Operator

This is a common interview topic.

switchMap

Cancels the previous request.

Useful for:

Search
Autocomplete

Example:

actions$.pipe(
  ofType(searchProducts),
  switchMap(...)
);

concatMap

Queues requests.

Request 1
   ↓
Request 2
   ↓
Request 3

Useful when order matters.

mergeMap

Runs requests concurrently.

Request 1 ────────┐
Request 2 ────────┤
Request 3 ────────┘

Useful when requests are independent.

exhaustMap

Ignores new requests while one is running.

Useful for:

Login
Submit button
Payment

For example:

actions$.pipe(
  ofType(login),
  exhaustMap(...)
);

If the user clicks Login multiple times quickly, subsequent clicks are ignored until the first request completes.

26. NgRx vs Services

You don't need NgRx for every Angular application.

A simple service may be enough:

@Injectable({
  providedIn: 'root'
})
export class CartService {

  private cartSubject =
    new BehaviorSubject<CartItem[]>([]);

  cart$ = this.cartSubject.asObservable();

  add(item: CartItem) {
    const current = this.cartSubject.value;

    this.cartSubject.next([
      ...current,
      item
    ]);
  }
}

This can work perfectly well for a small application.

NgRx becomes more valuable when state transitions and interactions become complex.

27. NgRx vs ComponentStore

NgRx Store is designed for centralized application state.

ComponentStore is better suited for localized state.

Example:

Global Application State
        ↓
      Store

Feature-local state
        ↓
  ComponentStore

You don't necessarily need to choose one exclusively.

A large application can use both.

28. What Should NOT Go Into NgRx?

A common mistake is putting everything into the Store.

Don't automatically store:

isDropdownOpen
hoveredItem
temporary input values
modal visibility
simple UI flags

unless there is a real reason.

Ask:

Does this state need to be shared, persisted, coordinated, or observed across multiple parts of the application?

If not, local state may be better.

29. Avoid Duplicated State

Suppose you have:

products: Product[];
selectedProduct: Product;

You may be duplicating information.

Instead, consider:

products: Product[];
selectedProductId: number | null;

Then:

export const selectSelectedProduct = createSelector(
  selectProducts,
  selectSelectedProductId,
  (products, id) =>
    products.find(product => product.id === id) ?? null
);

Now there is one source of truth.

30. Keep Business Logic Out of Components

Bad:

loadProducts() {

  this.loading = true;

  this.http.get('/products')
    .subscribe(products => {

      this.products = products;

      this.loading = false;
    });
}

This mixes:

UI
HTTP
State
Loading
Error handling

With NgRx:

loadProducts() {
  this.store.dispatch(loadProducts());
}

The component becomes much simpler.

31. Smart vs Presentational Components

NgRx works well with the separation between container and presentational components.

Container

Responsible for state interaction.

products$ = this.facade.products$;

Presentational

Receives data:

@Input()
products: Product[] = [];

and emits events:

@Output()
productSelected = new EventEmitter<number>();

Architecture:

Container
   │
   ├── Store
   │
   └── Presentational Component
             │
             └── UI

32. Router Store

NgRx can also integrate router state.

This can allow application state to react to route changes.

Conceptually:

URL
 ↓
Router
 ↓
Router Store
 ↓
Selectors
 ↓
Application

This can be useful when route parameters influence application state.

33. DevTools

One of the major advantages of NgRx is debugging.

With Redux DevTools, you can inspect:

Action
 ↓
Previous State
 ↓
Next State

For example:

[Cart] Add Product

Previous:
items: []

Next:
items: [Product 1]

This makes complex state transitions much easier to understand.

34. Time-Travel Debugging

Because state changes are represented as actions, you can conceptually replay state transitions.

Action 1
Action 2
Action 3
Action 4

Instead of debugging:

"Something changed somewhere."

you can investigate:

"Which action caused the state transition?"

This is one of the architectural strengths of Redux-style state management.

35. Testing Reducers

Reducers are easy to test because they are pure functions.

Example:

it('should increment counter', () => {

  const state = counterReducer(
    5,
    increment()
  );

  expect(state).toBe(6);
});

No HTTP request.

No browser.

No asynchronous operation.

Just:

Input
 ↓
Reducer
 ↓
Output

36. Testing Selectors

Selectors can also be tested independently.

For example:

const state = {
  products: [
    { id: 1, price: 100 },
    { id: 2, price: 200 }
  ]
};

Then verify:

expect(selectProducts.projector(
  state.products
)).toEqual(state.products);

Selectors are another reason to keep business calculations outside components.

37. Testing Effects

Effects require testing asynchronous behavior.

Conceptually:

Input Action
     ↓
Effect
     ↓
Mock API
     ↓
Output Action

You can verify:

loadProducts
       ↓
API called
       ↓
loadProductsSuccess

or:

loadProducts
       ↓
API error
       ↓
loadProductsFailure

38. Common NgRx Mistakes

Mistake 1 — Putting everything in Store

Not every variable belongs in global state.

Mistake 2 — Mutating state

Bad:

state.products.push(product);
return state;

Good:

return {
  ...state,
  products: [
    ...state.products,
    product
  ]
};

Mistake 3 — HTTP inside reducers

Never.

Use Effects or another appropriate side-effect mechanism.

Mistake 4 — Huge selectors

Selectors should remain focused and composable.

Mistake 5 — Components containing business logic

If your component becomes:

500+ lines

and heavily interacts with Store, consider extracting logic.

Mistake 6 — Overusing Effects

Effects are for side effects.

Don't create an effect just to transform simple state synchronously when a reducer or selector is enough.

39. NgRx and Angular Signals

Modern Angular applications increasingly use Signals.

You can bridge Store Observables into Signals.

For example:

products = this.store.selectSignal(selectProducts);

Then in the template:

@for (product of products(); track product.id) {
  <p>{{ product.name }}</p>
}

This gives you a more signal-oriented component API while still using NgRx for centralized state management.

40. A Real-World E-Commerce Architecture

Imagine an e-commerce application.

We could structure the state as:

Application Store
│
├── Auth
│   ├── user
│   ├── token
│   └── loading
│
├── Products
│   ├── entities
│   ├── filters
│   ├── loading
│   └── error
│
├── Cart
│   ├── items
│   └── total
│
├── Orders
│   ├── entities
│   ├── loading
│   └── error
│
└── UI
    ├── notifications
    └── theme

The flow could be:

User
 │
 ▼
Angular Component
 │
 ▼
Action
 │
 ├──────────────┐
 ▼              ▼
Reducer        Effect
 │              │
 ▼              ▼
Store          API
 │              │
 │              ▼
 │         Success Action
 │              │
 └──────────────┘
        │
        ▼
     Selector
        │
        ▼
    Component

This architecture scales significantly better than putting all application logic into components.

41. When Should You Use NgRx?

NgRx is a good choice when your application has:

Complex shared state
Multiple features depending on the same data
Many asynchronous workflows
Complex state transitions
Large teams
Strong debugging requirements
Event-driven architecture
Need for predictable state changes
Significant business logic

Examples:

E-commerce
Banking dashboards
Admin platforms
CRM systems
Large SaaS applications
Enterprise applications
Real-time applications

42. When Should You Avoid NgRx?

For a small application:

5 components
2 API calls
simple forms
little shared state

NgRx may introduce unnecessary complexity.

A simple:

Component
   ↓
Service
   ↓
HTTP

architecture might be better.

The goal is not:

"Use NgRx because NgRx is powerful."

The goal is:

"Use the simplest architecture that can reliably manage the application's complexity."

43. The Most Important Mental Model

If you remember only one thing, remember this:

Action = What happened?

Reducer = How does state change?

Effect = What side effect should happen?

Selector = What state does the UI need?

Store = Where is application state centralized?

For example:

User clicks "Add to Cart"

Action:
[Product Page] Add To Cart

        ↓

Reducer:
Add product to cart state

        ↓

Effect:
Maybe synchronize cart with backend

        ↓

Store:
Updated cart

        ↓

Selector:
Calculate cart count

        ↓

UI:
Cart: 3 items

That is NgRx.

44. Final Architecture

A mature Angular + NgRx application can look like:

                    Angular UI
                        │
                        ▼
                  Component / Facade
                        │
                        ▼
                     Action
                        │
             ┌──────────┴──────────┐
             │                     │
             ▼                     ▼
          Reducer                Effect
             │                     │
             │                  HTTP/API
             │                     │
             │                     ▼
             │               Success/Failure
             │                     │
             └──────────┬──────────┘
                        ▼
                      Store
                        │
                        ▼
                    Selectors
                        │
                        ▼
                  Component / UI

This architecture gives you:

Predictable state transitions
Centralized state
Reactive data flow
Testable business logic
Clear separation of concerns
Better debugging
Scalable feature architecture

Conclusion

NgRx is not simply a library for storing variables.

It is a state-management architecture built around a very clear philosophy:

Events
  ↓
Actions
  ↓
State Transitions
  ↓
Store
  ↓
Selectors
  ↓
UI

Effects extend this architecture by handling asynchronous operations and other side effects.

The real power of NgRx appears when an application becomes complex enough that managing state manually starts becoming difficult.

The key is not to memorize APIs.

Understand the architecture first:

Actions
Reducers
Selectors
Effects
Store

Once those concepts are clear, the NgRx APIs become much easier to learn.

And the most important practical rule is:

Don't introduce NgRx because your application is Angular. Introduce it because your application's state management has become complex enough to justify it.

RxJS in Practice: Reactive Programming, Operators, Patterns, and Real-World Examples

Abanoub Kerols — Tue, 15 Sep 2026 21:01:42 +0000

RxJS is not just a library of operators. It is a different way of thinking about asynchronous data.

If you work with Angular, Node.js, React, or any application that deals with asynchronous operations, you will eventually encounter problems involving:

HTTP requests
User input
WebSockets
Events
Timers
State changes
Multiple asynchronous operations
Cancellation
Race conditions
Retries
Error handling

RxJS provides a powerful model for solving these problems through Reactive Programming.

In this article, we will move from the theory to practical examples and finally build a realistic Angular-style application using RxJS.

1. What Is RxJS?

RxJS (Reactive Extensions for JavaScript) is a library for composing asynchronous and event-based programs using Observables.

Instead of thinking:

"I have a function that will eventually return a value."

You start thinking:

"I have a stream of values that may arrive over time."

For example:

const observable$ = new Observable(subscriber => {
  subscriber.next(1);
  subscriber.next(2);
  subscriber.next(3);
});

The observable represents a stream:

1 ───> 2 ───> 3 ───> complete

But an Observable doesn't have to emit only three values.

It could represent:

User clicks
   ↓
click
   ↓
click
   ↓
click
   ↓
...

Or:

HTTP Request
     ↓
Response
     ↓
Complete

Or:

WebSocket
   ↓
Message
   ↓
Message
   ↓
Message
   ↓
Message
   ↓
...

This is the fundamental idea behind RxJS.

2. What Is Reactive Programming?

Reactive programming is a programming paradigm based on:

Reacting to changes and events over time.

Traditional imperative programming often looks like:

const value = getValue();

console.log(value);

You ask for a value and receive it.

Reactive programming looks more like:

value$.subscribe(value => {
  console.log(value);
});

You are saying:

"Whenever a value arrives, execute this logic."

This becomes extremely powerful when dealing with asynchronous systems.

3. The Core RxJS Concepts

RxJS revolves around several important concepts:

Observable
    ↓
Subscribe
    ↓
Receive values
    ↓
Operators
    ↓
Transform / Filter / Combine
    ↓
Observer

The most important concepts are:

Observable
Observer
Subscriber
Subscription
Operators
Subject
Schedulers

Let's understand them.

4. Observable

An Observable represents a stream of values over time.

Example:

import { Observable } from 'rxjs';

const observable$ = new Observable<number>(subscriber => {
  subscriber.next(10);
  subscriber.next(20);
  subscriber.next(30);

  subscriber.complete();
});

Subscribe:

observable$.subscribe(value => {
  console.log(value);
});

Output:

10
20
30

The $ suffix is a common naming convention:

users$
products$
orders$
searchResults$

It usually means:

"This variable represents an Observable."

It is a convention, not a language requirement.

5. Observable Lifecycle

An Observable can emit three kinds of notifications:

next
error
complete

Example:

const observable$ = new Observable<number>(subscriber => {
  subscriber.next(1);
  subscriber.next(2);
  subscriber.next(3);

  subscriber.complete();
});

Conceptually:

next(1)
   ↓
next(2)
   ↓
next(3)
   ↓
complete()

An Observable can also fail:

const observable$ = new Observable<number>(subscriber => {
  subscriber.next(1);

  subscriber.error(
    new Error('Something went wrong')
  );
});

Then:

next(1)
   ↓
error

Once an Observable sends either:

complete()

or:

error(...)

the stream terminates.

6. Observer

An Observer defines what should happen when the Observable emits values, errors, or completes.

observable$.subscribe({
  next: value => {
    console.log('Value:', value);
  },

  error: error => {
    console.error('Error:', error);
  },

  complete: () => {
    console.log('Completed');
  }
});

This is more explicit than:

observable$.subscribe(value => {
  console.log(value);
});

For production code, the object form is often easier to maintain when error or completion handling matters.

7. Subscription

When you subscribe:

const subscription = observable$.subscribe({
  next: value => console.log(value)
});

you receive a Subscription.

You can unsubscribe:

subscription.unsubscribe();

This matters for long-lived streams such as:

WebSockets
DOM events
intervals
Subjects
application-wide streams

Example:

const subscription = interval(1000).subscribe(value => {
  console.log(value);
});

setTimeout(() => {
  subscription.unsubscribe();
}, 5000);

The interval stops after approximately five seconds.

8. Cold Observables

A cold Observable starts its producer separately for each subscriber.

Example:

const observable$ = new Observable<number>(subscriber => {
  console.log('Producer started');

  subscriber.next(Math.random());
});

Subscribe twice:

observable$.subscribe(value => {
  console.log('Subscriber 1:', value);
});

observable$.subscribe(value => {
  console.log('Subscriber 2:', value);
});

The producer runs twice.

Conceptually:

Subscriber 1
     ↓
Producer A

Subscriber 2
     ↓
Producer B

Each subscriber gets its own execution.

9. Hot Observables

A hot Observable represents a shared source.

For example:

WebSocket
   ↓
   ├── Subscriber A
   ├── Subscriber B
   └── Subscriber C

The source exists independently of individual subscribers.

This concept becomes especially important when using:

Subject
share()
shareReplay()

10. Operators

Operators are one of the most important parts of RxJS.

They allow you to transform and control streams.

For example:

source$
  .pipe(
    map(value => value * 2),
    filter(value => value > 10)
  )
  .subscribe(value => {
    console.log(value);
  });

Think of an RxJS pipeline as:

Source
  ↓
map
  ↓
filter
  ↓
subscribe

11. `map`

map transforms every emitted value.

of(1, 2, 3)
  .pipe(
    map(value => value * 10)
  )
  .subscribe(console.log);

Output:

10
20
30

Conceptually:

1 → map → 10
2 → map → 20
3 → map → 30

A very common example is extracting data from an HTTP response:

this.http.get<ApiResponse<User[]>>('/api/users')
  .pipe(
    map(response => response.data)
  );

Now the consumer receives only:

User[]

instead of the complete response object.

12. `filter`

filter allows only values matching a condition.

of(1, 2, 3, 4, 5)
  .pipe(
    filter(value => value % 2 === 0)
  )
  .subscribe(console.log);

Output:

2
4

Think:

1 ❌
2 ✅
3 ❌
4 ✅
5 ❌

13. `tap`

tap allows you to perform side effects without changing the emitted value.

users$
  .pipe(
    tap(users => {
      console.log('Users:', users);
    })
  )
  .subscribe();

tap is useful for:

Logging
Debugging
Analytics
Updating external state
Observing the pipeline

Avoid using tap to secretly transform data.

Bad:

tap(user => {
  user.name = 'Changed';
})

Prefer transformations through operators such as:

map(user => ({
  ...user,
  name: 'Changed'
}))

14. `debounceTime`

One of the most practical RxJS operators.

Imagine a search box.

Without debouncing:

c
ca
cat
cats

You might send four HTTP requests.

With:

debounceTime(300)

the application waits until the user stops typing for 300ms.

searchTerm$
  .pipe(
    debounceTime(300)
  )

Conceptually:

c
ca
cat
cats
         ↓ 300ms
       "cats"

Only "cats" continues through the pipeline.

15. `distinctUntilChanged`

This operator prevents consecutive duplicate values.

of(
  'Angular',
  'Angular',
  'React',
  'React',
  'Vue'
)
.pipe(
  distinctUntilChanged()
)
.subscribe(console.log);

Output:

Angular
React
Vue

Very useful for:

Search inputs
Filters
Route parameters
State changes

16. `switchMap`

switchMap is one of the most important RxJS operators.

Imagine:

User searches:
Angular
Angular RxJS
Angular RxJS operators

Each search creates an HTTP request.

You usually don't want an old request to overwrite the latest result.

switchMap solves this by switching to the newest inner Observable and unsubscribing from the previous one.

searchTerm$
  .pipe(
    switchMap(term => this.searchApi(term))
  )

Conceptually:

Search A
   ↓
Request A

Search B
   ↓
Cancel/Unsubscribe A
   ↓
Request B

Search C
   ↓
Cancel/Unsubscribe B
   ↓
Request C

This makes switchMap ideal for:

Search
Autocomplete
Route parameter changes
Refreshing data
User-driven queries

17. `mergeMap`

mergeMap subscribes to inner Observables concurrently.

ids$
  .pipe(
    mergeMap(id => this.getUser(id))
  );

Conceptually:

ID 1 → Request 1
ID 2 → Request 2
ID 3 → Request 3

All can run concurrently.

Use it when previous operations should not be cancelled.

Typical use cases:

Independent HTTP requests
Processing multiple items
Concurrent operations

18. `concatMap`

concatMap queues inner Observables and runs them sequentially.

actions$
  .pipe(
    concatMap(action => this.save(action))
  );

Conceptually:

Action A
   ↓
Request A
   ↓
Complete

Action B
   ↓
Request B
   ↓
Complete

Action C
   ↓
Request C

Use it when order matters.

For example:

Create record A
      ↓
Update A
      ↓
Delete A

You may not want these operations running concurrently.

19. `exhaustMap`

exhaustMap ignores new emissions while the current inner Observable is running.

Example:

submitClick$
  .pipe(
    exhaustMap(() => this.submitForm())
  );

Imagine the user double-clicks:

Click
 ↓
Request starts

Click
 ↓
IGNORED

Click
 ↓
IGNORED

Request completes

This is extremely useful for preventing duplicate submissions.

20. The Four Important Mapping Operators

A useful mental model:

Operator	Behavior
`switchMap`	Cancel previous
`mergeMap`	Run concurrently
`concatMap`	Queue sequentially
`exhaustMap`	Ignore while busy

Think about them like this:

switchMap
Latest wins

mergeMap
Everything runs

concatMap
One by one

exhaustMap
First wins while busy

Choosing the correct flattening operator is one of the most important RxJS skills.

21. `catchError`

Errors are inevitable.

RxJS provides:

catchError()

Example:

this.http.get<User[]>('/api/users')
  .pipe(
    catchError(error => {
      console.error(error);

      return of([]);
    })
  );

Instead of terminating the application flow unexpectedly, the stream returns an empty array.

However, error handling should reflect the application's requirements.

Sometimes you should recover:

catchError(() => of([]))

Sometimes you should rethrow:

catchError(error => {
  return throwError(() => error);
})

22. `retry`

Transient failures can sometimes be retried.

this.http.get('/api/data')
  .pipe(
    retry(3)
  );

Conceptually:

Request
 ↓
Fail
 ↓
Retry
 ↓
Fail
 ↓
Retry
 ↓
Fail
 ↓
Retry

But blindly retrying everything is a bad idea.

For example, retrying a validation error won't usually solve anything.

Retries are more appropriate for transient failures.

23. `finalize`

finalize runs when the Observable terminates because of completion, error, or unsubscription.

Example:

this.loading = true;

this.http.get('/api/users')
  .pipe(
    finalize(() => {
      this.loading = false;
    })
  )
  .subscribe();

This is useful for cleanup:

Start request
   ↓
loading = true
   ↓
HTTP request
   ↓
complete/error/unsubscribe
   ↓
loading = false

24. Creating Observables

RxJS provides many creation functions.

`of`

of(1, 2, 3)

Emits:

1
2
3

`from`

from([1, 2, 3])

Also emits:

1
2
3

But from can convert many iterable or Promise-like sources.

For example:

from(fetch('/api/users'))

25. `interval`

Creates periodic emissions.

interval(1000)
  .subscribe(value => {
    console.log(value);
  });

Output:

0
1
2
3
4
...

This Observable does not naturally complete.

Therefore, long-lived subscriptions should be managed carefully.

26. `timer`

timer(2000)

Emits after two seconds.

You can also create repeated emissions:

timer(0, 1000)

Conceptually:

0
 ↓ 1 sec
1
 ↓ 1 sec
2
 ↓ 1 sec
3
...

27. Subjects

A Subject is both:

an Observable
an Observer

Example:

const subject$ = new Subject<number>();

subject$.subscribe(value => {
  console.log('A:', value);
});

subject$.subscribe(value => {
  console.log('B:', value);
});

subject$.next(10);
subject$.next(20);

Output:

A: 10
B: 10

A: 20
B: 20

The Subject multicasts values to its subscribers.

28. BehaviorSubject

BehaviorSubject requires an initial value and stores the latest value.

const user$ = new BehaviorSubject<User | null>(null);

When a new subscriber arrives, it immediately receives the current value.

Current value = User A

Subscriber joins
       ↓
Receives User A

This makes BehaviorSubject useful for representing state.

Example:

private currentUserSubject =
  new BehaviorSubject<User | null>(null);

currentUser$ =
  this.currentUserSubject.asObservable();

Then:

this.currentUserSubject.next(user);

29. ReplaySubject

ReplaySubject can replay previous emissions.

const subject$ = new ReplaySubject<number>(2);

subject$.next(1);
subject$.next(2);
subject$.next(3);

subject$.subscribe(value => {
  console.log(value);
});

Output:

2
3

because we configured it to replay the last two values.

30. `combineLatest`

Sometimes you need the latest value from multiple streams.

Example:

combineLatest([
  user$,
  settings$,
  permissions$
])

Conceptually:

User ────────┐
             │
Settings ────┼──> combineLatest
             │
Permissions ─┘

It emits when one source emits, after every source has emitted at least once.

Useful for:

Filters
UI state
User preferences
Multiple dependent inputs

31. `forkJoin`

forkJoin waits for all supplied Observables to complete and then emits their final values.

Perfect for independent HTTP requests:

forkJoin({
  users: this.getUsers(),
  products: this.getProducts(),
  orders: this.getOrders()
})

Conceptually:

Users ────────┐
Products ─────┼──> forkJoin → result
Orders ───────┘

Important distinction:

forkJoin is generally for "wait until all complete."

combineLatest is generally for "react whenever the latest values change."

32. `withLatestFrom`

Sometimes one Observable should trigger the operation while reading the latest value from another.

Example:

submit$
  .pipe(
    withLatestFrom(formValue$)
  )

Think:

submit$ ────────────────┐
                        ↓
                    withLatestFrom
                        ↑
formValue$ ─────────────┘

The submit event is the trigger.

33. RxJS and Angular

RxJS is deeply integrated into Angular.

Common examples include:

HttpClient
ActivatedRoute
Router events
Reactive Forms
Event streams
NgRx
WebSockets

For example:

this.route.params
  .pipe(
    switchMap(params =>
      this.userService.getUser(params['id'])
    )
  );

This is a classic Angular pattern.

34. Real-World Search Example

Let's build a search pipeline.

We have:

searchControl = new FormControl('');

Then:

searchResults$ = this.searchControl.valueChanges.pipe(
  debounceTime(300),

  distinctUntilChanged(),

  filter(term => !!term && term.length >= 2),

  switchMap(term =>
    this.searchService.search(term)
  )
);

Let's understand the pipeline:

User types
   ↓
valueChanges
   ↓
debounceTime
   ↓
distinctUntilChanged
   ↓
filter
   ↓
switchMap
   ↓
HTTP request
   ↓
results

This is a real RxJS use case.

35. Why `switchMap` Matters Here

Imagine:

User types: angular

Request A starts

Then:

User types: angular rxjs

Request B starts

The old search is no longer relevant.

With:

switchMap()

the pipeline switches to the newest request.

Without the correct concurrency strategy, an older response could potentially create stale UI state depending on how the requests are managed.

36. Preventing Duplicate Form Submissions

Consider:

submit$
  .pipe(
    exhaustMap(() => this.api.submitForm())
  )
  .subscribe();

If the user clicks:

Submit
Submit
Submit

while the first request is running:

Submit #1 → Request
Submit #2 → ignored
Submit #3 → ignored

This is one of the clearest real-world uses for exhaustMap.

37. Sequential API Operations

Suppose we need:

Create Order
     ↓
Create Payment
     ↓
Send Confirmation

You may need sequential execution.

For a stream of operations:

operations$
  .pipe(
    concatMap(operation =>
      this.execute(operation)
    )
  );

concatMap preserves order by waiting for the previous inner Observable to complete.

38. Parallel Requests

If operations are independent:

ids$
  .pipe(
    mergeMap(id => this.loadUser(id))
  );

Requests can execute concurrently.

If you need to limit concurrency, mergeMap also accepts a concurrency parameter:

mergeMap(
  id => this.loadUser(id),
  3
)

Now at most three inner subscriptions run concurrently.

39. RxJS Pipeline Thinking

One of the biggest improvements in RxJS comes from learning to think in pipelines.

Instead of:

let result = input;

result = transform(result);

if (condition) {
  result = anotherTransform(result);
}

send(result);

You can model the process as:

input$
  .pipe(
    transform(),
    filter(),
    anotherTransform(),
    tap(),
    ...
  )
  .subscribe();

The stream becomes a data-processing pipeline.

40. Avoid Nested Subscriptions

A common beginner pattern is:

this.userService.getUser().subscribe(user => {

  this.orderService.getOrders(user.id).subscribe(orders => {

    console.log(orders);

  });

});

This can become difficult to maintain.

Instead:

this.userService.getUser()
  .pipe(
    switchMap(user =>
      this.orderService.getOrders(user.id)
    )
  )
  .subscribe(orders => {
    console.log(orders);
  });

This is often called:

Flattening Observables

and it is one of the main reasons higher-order mapping operators exist.

41. Higher-Order Observables

Suppose:

Observable<User>

is normal.

But:

Observable<Observable<User>>

is a higher-order Observable.

For example:

users$
  .pipe(
    map(user => this.getUserDetails(user.id))
  );

Now the result becomes conceptually:

Observable
   ↓
Observable<User>

This is where flattening operators become important:

switchMap
mergeMap
concatMap
exhaustMap

They turn:

Observable<Observable<T>>

into something like:

Observable<T>

while applying different concurrency behavior.

42. `shareReplay`

Suppose multiple components need the same HTTP result.

Without sharing:

users$ = this.http.get<User[]>('/api/users');

Depending on how it is consumed, multiple subscriptions can trigger multiple HTTP executions.

A common caching/sharing pattern is:

users$ = this.http.get<User[]>('/api/users')
  .pipe(
    shareReplay({ bufferSize: 1, refCount: true })
  );

Conceptually:

             ┌── Component A
HTTP Request ─┼── Component B
             └── Component C

The shared result can be replayed to later subscribers while the shared subscription is active.

Be deliberate with caching semantics, especially for data that can become stale.

43. Memory Leaks

Long-lived streams can cause memory leaks when subscriptions remain active unnecessarily.

Potential examples:

interval(...)
fromEvent(...)
WebSocket streams
Subjects

Modern Angular provides tools such as:

takeUntilDestroyed()

For example:

this.events$
  .pipe(
    takeUntilDestroyed(this.destroyRef)
  )
  .subscribe();

This ties the subscription lifetime to the Angular destruction lifecycle.

The important principle is:

Subscription lifetime should match the lifetime of the work you actually need.

44. `take`

You can limit the number of emissions:

interval(1000)
  .pipe(
    take(3)
  )
  .subscribe(console.log);

Output:

0
1
2

Then the Observable completes.

45. `takeUntil`

Another common pattern:

source$
  .pipe(
    takeUntil(destroy$)
  )
  .subscribe();

When:

destroy$.next();

the subscription terminates.

In modern Angular applications, Angular's destruction utilities can often provide a cleaner alternative.

46. Error Handling Strategy

A production RxJS pipeline might look like:

this.api.getUsers()
  .pipe(
    retry(2),

    catchError(error => {
      this.logger.error(error);

      return of([]);
    }),

    finalize(() => {
      this.loading = false;
    })
  )
  .subscribe(users => {
    this.users = users;
  });

Notice the responsibilities:

retry
 ↓
Transient failure handling

catchError
 ↓
Recovery

finalize
 ↓
Cleanup

Each operator has a specific responsibility.

47. RxJS Architecture

A clean Angular application might have:

Component
    ↓
Facade / State Layer
    ↓
Service
    ↓
HttpClient
    ↓
Backend API

RxJS can flow through all these layers.

For example:

Component
    ↓
users$
    ↓
UserService
    ↓
HTTP Observable
    ↓
Backend

The component does not necessarily need to manually manage every asynchronous operation.

48. Async Pipe

Angular's async pipe can subscribe to an Observable in the template.

Example:

users$ = this.userService.getUsers();

Template:

<ul>
  @for (user of users$ | async; track user.id) {
    <li>{{ user.name }}</li>
  }
</ul>

The async pipe handles subscription and cleanup for the template binding.

This can reduce manual subscription management.

49. Observable vs Promise

Promises represent one eventual result:

Promise
   ↓
one result

Observables can represent:

Observable
   ↓
0
1
2
3
...

A Promise:

fetch('/api/users')
  .then(response => response.json());

Observable:

this.http.get<User[]>('/api/users')

Observables also provide rich operators for:

Transformation
Filtering
Cancellation
Combination
Concurrency
Retrying
Error handling
Composition

50. Cancellation

One major difference is cancellation.

Promises do not natively provide the same compositional cancellation model as RxJS subscriptions.

With an Observable:

const subscription = source$.subscribe();

subscription.unsubscribe();

This gives RxJS a powerful way to model work that should stop when it is no longer needed.

This becomes particularly useful with:

Search
Navigation
Live streams
Polling
User interactions

51. RxJS Mental Model

A useful mental model is:

Observable
    ↓
Source of values

Operator
    ↓
Transforms or controls values

Subscription
    ↓
Starts/owns the execution

Observer
    ↓
Consumes values

Think:

SOURCE
  ↓
  ↓
map
  ↓
filter
  ↓
switchMap
  ↓
catchError
  ↓
finalize
  ↓
SUBSCRIBER

Once this mental model becomes natural, RxJS becomes much easier.

52. A Complete Real-World Example

Let's combine everything.

Imagine an Angular product search page.

Requirements:

User enters a search term.
Wait 300ms.
Ignore duplicate terms.
Ignore short terms.
Cancel previous searches.
Retry temporary failures.
Show loading state.
Return an empty result if the request fails.

Implementation:

searchResults$ = this.searchControl.valueChanges.pipe(

  debounceTime(300),

  distinctUntilChanged(),

  map(term => term?.trim() ?? ''),

  filter(term => term.length >= 2),

  tap(() => {
    this.loading = true;
  }),

  switchMap(term =>
    this.productService.search(term).pipe(

      retry(2),

      catchError(error => {
        console.error('Search failed:', error);

        return of([]);
      }),

      finalize(() => {
        this.loading = false;
      })
    )
  )
);

This pipeline represents a complete reactive workflow:

User Input
    ↓
debounce
    ↓
remove duplicates
    ↓
normalize
    ↓
validate
    ↓
loading = true
    ↓
switchMap
    ↓
HTTP
    ↓
retry
    ↓
catchError
    ↓
finalize
    ↓
Results

This is where RxJS becomes much more than just syntax.

53. How to Choose the Correct Operator

When you see an asynchronous problem, ask:

Do I need to transform values?

Use:

map

Do I need to remove values?

Use:

filter

Do I need to wait for user input to settle?

Use:

debounceTime

Do I need to ignore consecutive duplicates?

Use:

distinctUntilChanged

Do I need only the newest request?

Use:

switchMap

Do I need concurrent operations?

Use:

mergeMap

Do I need sequential operations?

Use:

concatMap

Do I need to ignore new triggers while busy?

Use:

exhaustMap

Do I need all requests to finish?

Use:

forkJoin

Do I need the latest values from multiple streams?

Use:

combineLatest

Do I need error recovery?

Use:

catchError

Do I need retries?

Use:

retry

Do I need cleanup?

Use:

finalize

54. The Most Important RxJS Skill

The hardest part of RxJS is not memorizing operators.

It is understanding time and concurrency.

For example:

User Event A
      ↓
Request A

User Event B
      ↓
Request B

What should happen to Request A?

Different answers produce different operators:

Cancel A        → switchMap

Keep A + B      → mergeMap

Wait A → B      → concatMap

Ignore B        → exhaustMap

Once you understand this question, choosing the operator becomes much easier.

55. Common RxJS Mistakes

Mistake 1: Nested subscriptions

Avoid:

a$.subscribe(a => {
  b$.subscribe(b => {
    ...
  });
});

Prefer composition:

a$
  .pipe(
    switchMap(a => b$)
  )
  .subscribe();

Mistake 2: Using `subscribe` everywhere

Don't subscribe just to pass data to another Observable.

Instead of:

this.userService.getUser().subscribe(user => {
  this.user$ = of(user);
});

prefer:

this.user$ = this.userService.getUser();

Mistake 3: Choosing `switchMap` automatically

switchMap is not always the correct operator.

If every operation must complete:

concatMap

may be better.

If operations are independent:

mergeMap

may be better.

If duplicate clicks should be ignored:

exhaustMap

may be better.

Mistake 4: Ignoring subscription lifetime

Long-running subscriptions should have intentional lifecycle management.

Mistake 5: Overusing Subjects

Subjects are useful, but not every Observable needs to become a Subject.

Prefer simple Observable composition when possible.

56. RxJS in One Diagram

The entire philosophy can be summarized as:

                    RxJS
                     │
                     ▼
                Observable
                     │
                     ▼
              Stream of values
                     │
          ┌──────────┴──────────┐
          ▼                     ▼
      Operators             Subscription
          │                     │
          ▼                     ▼
 Transform / Filter       Start / Cleanup
 Combine / Control             │
          │                     │
          └──────────┬──────────┘
                     ▼
                  Observer
                     │
                     ▼
              Application Logic

57. Final Takeaways

RxJS becomes much easier when you stop thinking about it as:

"A huge library with hundreds of operators."

Instead, think of it as:

A way to model values and events over time.

The most important concepts to master are:

Observable
Observer
Subscription
Operators
Subjects
Higher-order Observables
Concurrency
Error handling
Cancellation

And the operators you should know particularly well are:

map
filter
tap
debounceTime
distinctUntilChanged

switchMap
mergeMap
concatMap
exhaustMap

catchError
retry
finalize

combineLatest
forkJoin
withLatestFrom

take
takeUntil
share
shareReplay

If you truly understand:

switchMap
mergeMap
concatMap
exhaustMap

you already understand one of the most important parts of practical RxJS.

The goal is not to memorize every operator.

The goal is to look at a problem and ask:

"How should these values behave over time?"

Once you can answer that question, the RxJS operator usually becomes obvious.

Conclusion

RxJS is powerful because asynchronous behavior is rarely just:

request → response

Real applications contain:

events
requests
cancellation
retries
multiple streams
user interactions
state changes
concurrency
errors

RxJS gives us a unified model for composing all of them.

And that's why RxJS remains such an important skill for modern Angular and reactive JavaScript development.

Don't learn RxJS by memorizing operators. Learn it by understanding streams, time, cancellation, and concurrency.

Using Next.js as a Backend for Frontend (BFF)

Abanoub Kerols — Fri, 11 Sep 2026 21:34:10 +0000

When building a modern web application, the frontend often needs to communicate with multiple backend services:

Browser
   │
   ├── Auth Service
   ├── Product Service
   ├── Order Service
   └── Notification Service

This works, but it makes the frontend tightly coupled to the backend architecture.

A better approach in some systems is to introduce a Backend for Frontend (BFF).

Browser
   │
   ▼
Next.js BFF
   │
   ├── Auth Service
   ├── Product Service
   ├── Order Service
   └── Notification Service

What is a BFF?

A BFF is a backend layer specifically designed for a particular frontend.

Instead of exposing all backend services directly to the browser, the frontend communicates with the BFF, and the BFF communicates with the internal services.

This gives us a place to handle:

Authentication
Authorization
Request validation
API aggregation
Response transformation
Caching
Hiding internal service URLs

Next.js as a BFF

Next.js can implement a BFF using Route Handlers.

For example:

app/
└── api/
    └── products/
        └── route.ts

// app/api/products/route.ts

export async function GET() {
  const response = await fetch(
    `${process.env.PRODUCT_SERVICE_URL}/products`
  );

  if (!response.ok) {
    return Response.json(
      { message: "Failed to fetch products" },
      { status: 500 }
    );
  }

  const products = await response.json();

  return Response.json(products);
}

Now the browser calls:

GET /api/products

Instead of directly calling:

GET http://product-service:3002/products

The architecture becomes:

Browser
   │
   │ GET /api/products
   ▼
Next.js BFF
   │
   │ GET /products
   ▼
Product Service

The internal service URL remains server-side.

API Aggregation

One of the most useful BFF features is aggregation.

Imagine a dashboard needs data from four different services:

User Service
Order Service
Notification Service
Recommendation Service

Instead of making four requests from the browser:

Browser
 ├── GET /users/me
 ├── GET /orders
 ├── GET /notifications
 └── GET /recommendations

The BFF can expose a single endpoint:

GET /api/dashboard

And fetch the data in parallel:

// app/api/dashboard/route.ts

export async function GET() {
  const [
    user,
    orders,
    notifications,
    recommendations,
  ] = await Promise.all([
    fetch(`${process.env.USER_SERVICE_URL}/me`)
      .then(res => res.json()),

    fetch(`${process.env.ORDER_SERVICE_URL}/orders`)
      .then(res => res.json()),

    fetch(`${process.env.NOTIFICATION_SERVICE_URL}/notifications`)
      .then(res => res.json()),

    fetch(`${process.env.RECOMMENDATION_SERVICE_URL}/recommendations`)
      .then(res => res.json()),
  ]);

  return Response.json({
    user,
    orders,
    notifications,
    recommendations,
  });
}

Now the browser only needs:

GET /api/dashboard

The BFF handles the complexity behind the scenes.

Response Transformation

The BFF can also transform backend responses into a format that is better suited for the frontend.

For example, a backend might return:

{
  "id": 15,
  "first_name": "Abanoub",
  "last_name": "Kerols",
  "internal_role_id": 7
}

But the frontend may only need:

{
  "id": 15,
  "name": "Abanoub Kerols"
}

The BFF can perform this transformation:

return Response.json({
  id: user.id,
  name: `${user.first_name} ${user.last_name}`,
});

This prevents the frontend from becoming dependent on internal backend models.

Authentication

A BFF can also be useful for authentication.

For example:

Browser
   │
   │ HttpOnly Cookie
   ▼
Next.js BFF
   │
   │ Authorization: Bearer <token>
   ▼
Backend Service

The BFF can read the server-side authentication state and attach the appropriate credentials when calling internal services.

This can help keep sensitive tokens away from client-side JavaScript.

The Important Architectural Boundary

Using Next.js as a BFF does not mean moving all business logic into Next.js.

A good separation is:

             Next.js
        ┌───────────────┐
        │ UI            │
        │ BFF           │
        │ Authentication│
        │ Aggregation   │
        │ Transformation│
        └───────┬───────┘
                │
                ▼
        Backend Services
        ┌───────────────┐
        │ Business Logic│
        │ Domain Rules  │
        │ Data Access   │
        └───────────────┘

The BFF should mainly adapt backend capabilities to the needs of the frontend, while important domain logic remains in the backend services.

Final Architecture

                    Browser
                       │
                       │ HTTPS
                       ▼
              ┌─────────────────┐
              │     Next.js      │
              │       BFF        │
              │                 │
              │ Auth            │
              │ Validation      │
              │ Aggregation     │
              │ Transformation  │
              │ Caching         │
              └────────┬────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
       Auth API    Product API   Order API
          │            │            │
          ▼            ▼            ▼
       Database     Database     Database

The key idea

Next.js doesn't have to replace your backend. It can become the backend layer specifically designed for your frontend.

That's the core idea behind using Next.js as a Backend for Frontend (BFF).

Dependency Injection in Angular: From Constructor Injection to Modern DI

Abanoub Kerols — Thu, 10 Sep 2026 18:12:21 +0000

Dependency Injection (DI) is one of the most important concepts in Angular.

If you understand Angular DI deeply, you understand much more than how to inject a service into a component. You understand how Angular creates objects, controls their lifetime, chooses implementations, scopes dependencies, handles configuration, supports testing, and builds hierarchical application architecture.

And Angular DI has evolved significantly.

We started with:

constructor(private userService: UserService) {}

Then Angular introduced:

private userService = inject(UserService);

Modern Angular goes even further with:

EnvironmentInjector
InjectionToken
useValue
useClass
useFactory
useExisting
multi
providedIn
providers
viewProviders
Optional
Self
SkipSelf
Host
forwardRef
runInInjectionContext
functional guards and resolvers
provider functions such as provideRouter() and provideHttpClient()
environment-level providers
hierarchical scopes
tree-shakable providers
advanced library DI patterns

This article explains the old Angular DI model, the modern model, and how everything fits together, then builds a complete application that uses these concepts in practice.

1. What Is Dependency Injection?

Before Angular, imagine this service:

export class UserService {
  getUser() {
    return {
      id: 1,
      name: 'Abanoub'
    };
  }
}

Now a component needs it.

A naive approach is:

export class UserComponent {

  private userService = new UserService();

}

This works, but it creates strong coupling.

The component decides:

which implementation to use
how the dependency is created
when it is created
how its dependencies are created

The component is doing too much.

Instead, we want:

export class UserComponent {

  constructor(private userService: UserService) {}

}

The component says:

"I need a UserService."

It does not say:

"I will create a UserService."

That distinction is the foundation of Dependency Injection.

Angular's DI system is responsible for providing dependencies to components, directives, services, functions, and other framework-managed code.

2. Dependency Injection vs Dependency Inversion

These concepts are related but not identical.

Dependency Injection

DI is a mechanism/pattern for supplying dependencies from outside a class.

constructor(private logger: LoggerService) {}

Dependency Inversion

Dependency Inversion is a broader architectural principle.

High-level modules should depend on abstractions rather than concrete implementations.

For example:

export abstract class PaymentGateway {
  abstract pay(amount: number): Promise<void>;
}

Then:

@Injectable()
export class StripePaymentGateway implements PaymentGateway {
  async pay(amount: number) {
    // Stripe implementation
  }
}

Angular DI can connect them:

providers: [
  {
    provide: PaymentGateway,
    useClass: StripePaymentGateway
  }
]

Now the application depends on:

PaymentGateway

rather than:

StripePaymentGateway

This is where Angular DI becomes an architectural tool rather than simply a convenience.

3. What Is a Dependency?

A dependency is anything a class needs to perform its job.

It doesn't have to be a service.

A dependency can be:

class

or:

object

or:

string

or:

number

or:

function

or:

configuration

For example:

class UserService {

  constructor(
    private http: HttpClient,
    private config: AppConfig
  ) {}

}

Both are dependencies.

Angular's DI system can provide services, values, functions, configuration objects, and other JavaScript values.

4. The Three Important DI Concepts

Most Angular DI problems become much easier once you understand these three terms:

Token
   ↓
Provider
   ↓
Injector

For example:

providers: [
  {
    provide: UserService,
    useClass: UserService
  }
]

Here:

Token

UserService

The token identifies what we want.

Provider

{
  provide: UserService,
  useClass: UserService
}

The provider tells Angular how to create or obtain it.

Injector

The injector stores provider information and resolves dependencies when requested.

Conceptually:

Component
    |
    | "Give me UserService"
    ↓
Injector
    |
    | finds provider
    ↓
Provider
    |
    | creates/returns instance
    ↓
UserService

5. The Old Angular DI Model

Before modern Angular patterns became common, you typically saw:

@Injectable({
  providedIn: 'root'
})
export class UserService {}

and:

@Component({
  selector: 'app-user',
  template: `...`
})
export class UserComponent {

  constructor(
    private userService: UserService
  ) {}

}

This is still valid.

It is not an obsolete API.

The major change is that Angular now gives developers another, often cleaner, way to inject dependencies.

6. Constructor Injection

The classic Angular DI syntax is constructor injection:

@Injectable({
  providedIn: 'root'
})
export class UserService {

  getUser() {
    return {
      id: 1,
      name: 'Abanoub'
    };
  }

}

Then:

@Component({
  selector: 'app-user',
  template: `
    <h1>{{ user.name }}</h1>
  `
})
export class UserComponent {

  constructor(
    private userService: UserService
  ) {}

  user = this.userService.getUser();

}

Angular sees:

UserService

and asks the DI system to resolve it.

Why constructor injection was popular

It has several advantages:

explicit dependencies
easy to understand
works naturally with TypeScript
dependencies are available when the class is created
excellent for traditional Angular codebases

But it also has limitations.

For example:

constructor(
  private http: HttpClient,
  private auth: AuthService,
  private router: Router,
  private logger: LoggerService,
  private config: ConfigService
) {}

Large constructors can become noisy.

There are also limitations around TypeScript's decorator metadata and modern standard decorators.

Angular therefore introduced the inject() API as a modern alternative. Angular's migration tooling can convert constructor-based injection to inject().

7. Modern Angular DI: `inject()`

Today you will frequently see:

import { Component, inject } from '@angular/core';

@Component({
  selector: 'app-user',
  template: `...`
})
export class UserComponent {

  private userService = inject(UserService);

}

This is dependency injection too.

Angular resolves:

UserService

from the currently active injector.

The important thing is:

inject(UserService)

does not mean:

new UserService()

Angular still controls the dependency lifecycle and provider resolution.

The inject() function is supported in injection contexts such as constructors, field initializers, provider factories, and other framework-managed DI contexts.

8. Constructor Injection vs `inject()`

Old style

export class DashboardComponent {

  constructor(
    private userService: UserService,
    private router: Router
  ) {}

}

Modern style

export class DashboardComponent {

  private userService = inject(UserService);
  private router = inject(Router);

}

Both are valid.

A practical modern Angular style is:

private userService = inject(UserService);
private router = inject(Router);

because dependencies are declared close to where they are used and TypeScript can infer types naturally.

However, constructor injection remains perfectly legitimate, especially in existing applications and when working with patterns that depend on constructor parameters. Angular's own guidance explicitly supports both approaches.

9. The Injection Context

This is one of the most important modern Angular DI concepts.

You cannot call:

inject(UserService)

anywhere.

This is invalid:

export class UserComponent {

  ngOnInit() {

    const service = inject(UserService); // ❌

  }

}

Why?

Because ngOnInit() executes after the object has already been created.

Angular's DI context is available during class creation/initialization and specific framework-managed contexts, not arbitrary later callbacks.

10. Valid Places for `inject()`

Field initializer

export class UserComponent {

  private userService = inject(UserService);

}

Constructor

export class UserComponent {

  constructor() {

    const service = inject(UserService);

  }

}

Provider factory

{
  provide: UserService,
  useFactory: () => {

    const logger = inject(LoggerService);

    return new UserService(logger);

  }
}

InjectionToken factory

const API_URL = new InjectionToken<string>(
  'API_URL',
  {
    providedIn: 'root',

    factory: () => {

      const config = inject(AppConfig);

      return config.apiUrl;

    }
  }
);

Functional route guard

export const authGuard = () => {

  const auth = inject(AuthService);

  return auth.isAuthenticated();

};

Angular documents functional guards and similar framework APIs as injection contexts.

11. Why `inject()` Fails in Async Code

This is a common mistake:

async loadUser() {

  await delay(1000);

  const userService = inject(UserService); // ❌

}

After the await, you are no longer inside the original synchronous injection context.

Instead:

private userService = inject(UserService);

async loadUser() {

  await delay(1000);

  this.userService.getUser();

}

Capture dependencies while you are inside the injection context.

12. `runInInjectionContext()`

Sometimes you genuinely need to execute a function inside an injection context.

Angular provides:

runInInjectionContext()

Example:

import {
  EnvironmentInjector,
  inject,
  runInInjectionContext
} from '@angular/core';

@Injectable({
  providedIn: 'root'
})
export class DynamicService {

  private injector = inject(EnvironmentInjector);

  execute() {

    runInInjectionContext(
      this.injector,
      () => {

        const logger = inject(LoggerService);

        logger.log('Hello');

      }
    );

  }

}

This creates a temporary injection context for the callback.

Use this when you actually need dynamic DI.

Do not use it as a replacement for normal injection.

13. `Injector`

Angular also exposes the injector itself.

private injector = inject(Injector);

You can then resolve dependencies manually:

const service = this.injector.get(UserService);

This can be useful when the dependency needs to be resolved later.

For example:

private injector = inject(Injector);

loadLater() {

  setTimeout(() => {

    const userService =
      this.injector.get(UserService);

    userService.getUser();

  }, 1000);

}

Angular's debugging guidance recommends capturing dependencies normally where possible and using Injector.get() for deferred retrieval when necessary.

14. `@Injectable()`

The classic way to declare an injectable service is:

@Injectable()
export class UserService {}

However, this alone doesn't necessarily make the service globally available.

You need a provider.

For example:

@Component({
  providers: [
    UserService
  ]
})
export class UserComponent {}

Or:

bootstrapApplication(AppComponent, {
  providers: [
    UserService
  ]
});

15. `providedIn`

The most common modern approach is:

@Injectable({
  providedIn: 'root'
})
export class UserService {}

This tells Angular that the service belongs to the root injector.

It is also tree-shakable.

That means Angular's build system can remove unused injectable definitions from the final bundle when they are not referenced.

For most application-wide services:

@Injectable({
  providedIn: 'root'
})

is the default choice.

16. `providedIn: 'root'`

@Injectable({
  providedIn: 'root'
})
export class AuthService {}

This normally gives the application a single instance associated with the root environment injector.

Every component requesting:

inject(AuthService)

will resolve the same root-scoped instance unless a closer provider overrides it.

17. `providedIn: 'platform'`

Historically Angular also supported:

@Injectable({
  providedIn: 'platform'
})

This places the service in the platform-level injector rather than the application root.

It is useful for special scenarios involving multiple Angular applications sharing a platform.

It is not something you should use by default.

18. The Historical `providedIn: 'any'`

Older Angular versions supported:

providedIn: 'any'

This had special behavior with lazy-loaded injectors.

Modern Angular documentation marks 'any' as deprecated.

So if you see:

providedIn: 'any'

in older code, understand what it does before changing it, but don't treat it as the preferred modern pattern.

19. `providedIn: NgModule`

You may also encounter:

@Injectable({
  providedIn: SomeModule
})

This belongs to the older NgModule-oriented DI model.

The modern Angular architecture favors environment providers and standalone APIs.

Angular's current documentation marks providedIn: NgModule as deprecated for InjectionToken configuration, and modern applications generally prefer environment-based provider configuration.

20. Manual Providers

Instead of:

@Injectable({
  providedIn: 'root'
})
export class UserService {}

you can manually provide:

providers: [
  UserService
]

For example:

@Component({
  selector: 'app-profile',
  providers: [
    UserService
  ],
  template: `...`
})
export class ProfileComponent {}

Now the service belongs to this component's injector.

21. Component-Level Providers

This is extremely important.

Consider:

@Component({
  providers: [
    CounterService
  ]
})
export class CounterComponent {

  private counter = inject(CounterService);

}

Every instance of CounterComponent gets its own CounterService.

For example:

<app-counter></app-counter>
<app-counter></app-counter>

Conceptually:

CounterComponent #1
   |
   └── CounterService #1

CounterComponent #2
   |
   └── CounterService #2

This is completely different from:

@Injectable({
  providedIn: 'root'
})

where both components normally resolve the same root instance.

Angular's component providers configure the component's ElementInjector, and that instance is destroyed with the component.

22. The Provider Shorthand

This:

providers: [
  UserService
]

is effectively a shorthand for:

providers: [
  {
    provide: UserService,
    useClass: UserService
  }
]

This leads us to one of the most important DI concepts:

Provider Recipes

Angular supports several provider strategies.

23. `useClass`

providers: [
  {
    provide: LoggerService,
    useClass: ConsoleLoggerService
  }
]

Whenever something asks for:

LoggerService

Angular creates:

ConsoleLoggerService

This is extremely useful for abstraction.

For example:

abstract class PaymentGateway {

  abstract pay(amount: number): Promise<void>;

}

Production:

providers: [
  {
    provide: PaymentGateway,
    useClass: StripePaymentGateway
  }
]

Testing:

providers: [
  {
    provide: PaymentGateway,
    useClass: FakePaymentGateway
  }
]

The consumer doesn't change.

24. `useValue`

Sometimes you don't need Angular to create an object.

You already have the value.

Use:

useValue

Example:

export const API_URL =
  new InjectionToken<string>('API_URL');

bootstrapApplication(AppComponent, {

  providers: [
    {
      provide: API_URL,
      useValue: 'https://api.example.com'
    }
  ]

});

Then:

export class ApiService {

  private apiUrl = inject(API_URL);

}

useValue can provide strings, numbers, objects, arrays, functions, configuration, and other static values.

25. Why You Need `InjectionToken`

This won't work:

export interface AppConfig {
  apiUrl: string;
}

and:

constructor(private config: AppConfig) {}

Why?

Because interfaces disappear during TypeScript compilation.

At runtime:

AppConfig

doesn't exist.

Angular needs a runtime token.

That's what InjectionToken provides.

26. `InjectionToken`

export interface AppConfig {

  apiUrl: string;
  production: boolean;

}

export const APP_CONFIG =
  new InjectionToken<AppConfig>('APP_CONFIG');

Provide:

providers: [
  {
    provide: APP_CONFIG,

    useValue: {
      apiUrl: 'https://api.example.com',
      production: false
    }
  }
]

Inject:

private config = inject(APP_CONFIG);

Now:

this.config.apiUrl

is strongly typed.

Angular recommends InjectionToken for dependencies that do not have a runtime representation, such as interfaces, functions, arrays, and parameterized types.

27. InjectionToken Identity Matters

This is a subtle but important bug.

Don't do this:

const API_URL =
  new InjectionToken<string>('API_URL');

in one file and:

const API_URL =
  new InjectionToken<string>('API_URL');

in another.

Even though the names are identical, these are two different objects.

Angular compares token identity, not the description string.

Always export one token:

export const API_URL =
  new InjectionToken<string>('API_URL');

and import that same token everywhere.

28. `useFactory`

Factories are useful when the dependency must be dynamically constructed.

Example:

export const API_CLIENT_PROVIDER = {

  provide: ApiClient,

  useFactory: () => {

    const http = inject(HttpClient);
    const config = inject(APP_CONFIG);

    return new ApiClient(
      http,
      config.apiUrl
    );

  }

};

Now Angular executes the factory when it needs the dependency.

Factories are excellent for:

runtime configuration
environment-dependent implementations
complex initialization
combining multiple dependencies
library configuration

Angular supports both useFactory providers and factory-based injection tokens.

29. Factory Dependencies with `deps`

The older explicit style is:

{
  provide: ApiClient,

  useFactory: (
    http: HttpClient,
    config: AppConfig
  ) => {

    return new ApiClient(
      http,
      config.apiUrl
    );

  },

  deps: [
    HttpClient,
    APP_CONFIG
  ]
}

Modern Angular code can often use inject() directly inside the factory:

{
  provide: ApiClient,

  useFactory: () => {

    const http = inject(HttpClient);
    const config = inject(APP_CONFIG);

    return new ApiClient(
      http,
      config.apiUrl
    );

  }
}

30. `useExisting`

This is one of the most misunderstood provider types.

Suppose:

class NewLogger {}

class OldLogger {}

You can alias:

providers: [
  NewLogger,

  {
    provide: OldLogger,
    useExisting: NewLogger
  }
]

Now:

inject(NewLogger)

and:

inject(OldLogger)

return the same instance.

31. `useExisting` vs `useClass`

This distinction matters.

`useClass`

{
  provide: Logger,
  useClass: ConsoleLogger
}

Angular creates an instance of:

ConsoleLogger

`useExisting`

{
  provide: LegacyLogger,
  useExisting: ConsoleLogger
}

Angular returns the already-existing ConsoleLogger instance.

Conceptually:

useClass

Logger ───────> ConsoleLogger #1


useExisting

Logger ───────┐
              ├──> ConsoleLogger #1
LegacyLogger ─┘

Angular's documentation explicitly distinguishes these behaviors.

32. `multi: true`

Sometimes you don't want one implementation.

You want many.

For example:

export const LOG_HANDLERS =
  new InjectionToken<LogHandler[]>(
    'LOG_HANDLERS'
  );

Then:

providers: [

  {
    provide: LOG_HANDLERS,
    useClass: ConsoleLogHandler,
    multi: true
  },

  {
    provide: LOG_HANDLERS,
    useClass: RemoteLogHandler,
    multi: true
  },

  {
    provide: LOG_HANDLERS,
    useClass: AnalyticsLogHandler,
    multi: true
  }

]

Now:

private handlers = inject(LOG_HANDLERS);

returns an array.

LOG_HANDLERS
     |
     ├── ConsoleLogHandler
     ├── RemoteLogHandler
     └── AnalyticsLogHandler

This pattern is heavily used in extensible Angular architecture.

33. `providers` vs `viewProviders`

These look similar:

providers

and:

viewProviders

but they have an important difference.

Consider:

<app-parent>

  <app-child />

</app-parent>

and:

<app-parent>

  <ng-content />

</app-parent>

providers can be visible to projected content.

viewProviders restricts the provider to the component's own view.

Example:

@Component({
  providers: [
    ThemeService
  ]
})

The service can be available to projected content.

But:

@Component({
  viewProviders: [
    ThemeService
  ]
})

keeps it within the component's own view.

Angular recommends providers by default unless you specifically need the isolation behavior of viewProviders.

34. Angular's Injector Hierarchy

This is where Angular DI becomes really powerful.

Modern Angular has two major injector hierarchies:

EnvironmentInjector hierarchy

        Root
         |
    Environment
         |
    Feature / Route

and:

ElementInjector hierarchy

Component
   |
Child Component
   |
Grandchild Component

Angular documents these as the EnvironmentInjector and ElementInjector hierarchies.

35. EnvironmentInjector

The EnvironmentInjector is used for application/environment-level providers.

For example:

bootstrapApplication(AppComponent, {
  providers: [
    UserService
  ]
});

Or:

@Injectable({
  providedIn: 'root'
})
export class AuthService {}

These belong to the environment hierarchy.

This is the modern standalone Angular replacement for many things developers historically configured through NgModule.providers.

36. ElementInjector

Angular also creates an injector associated with elements/components.

For example:

@Component({
  providers: [
    CounterService
  ]
})
export class CounterComponent {}

This configures the component's ElementInjector.

Angular creates these element-level injectors implicitly, and they are empty unless providers are configured on components or directives.

37. How Angular Resolves a Dependency

Suppose:

@Component({
  providers: [
    UserService
  ]
})
export class ChildComponent {

  private user = inject(UserService);

}

Angular roughly searches:

Child ElementInjector
        ↓
Parent ElementInjector
        ↓
Ancestor ElementInjectors
        ↓
EnvironmentInjector hierarchy
        ↓
Root

The important rule is:

Angular uses the closest matching provider.

If a child defines its own provider, it can override the parent.

Angular's documented resolution process first walks the relevant element injector hierarchy and then falls back to the environment hierarchy.

38. Provider Override

Imagine:

@Injectable({
  providedIn: 'root'
})
export class LoggerService {

  name = 'Global Logger';

}

Then:

@Component({
  providers: [
    {
      provide: LoggerService,
      useValue: {
        name: 'Local Logger'
      }
    }
  ]
})
export class FeatureComponent {}

Inside:

FeatureComponent

you get:

Local Logger

while another component outside that subtree still gets:

Global Logger

This is dependency scoping.

39. `Self`

Sometimes you want Angular to search only the current injector.

With inject():

inject(UserService, {
  self: true
});

Conceptually:

Current Injector
      |
      X
Parent
      |
      X
Root

If the dependency isn't available locally, Angular fails.

This is useful when you explicitly require a local provider.

40. `SkipSelf`

skipSelf does the opposite.

inject(UserService, {
  skipSelf: true
});

Angular skips the current injector and starts searching from the parent.

Conceptually:

Current Injector  ← skipped

Parent Injector   ← start here
       ↓
Grandparent
       ↓
Root

This is useful when a child provider overrides a parent provider but you specifically need the parent instance.

41. `Optional`

Sometimes a dependency is optional.

Instead of throwing an error:

inject(AnalyticsService);

use:

inject(AnalyticsService, {
  optional: true
});

Now Angular can return:

null

if the provider doesn't exist.

Example:

private analytics =
  inject(AnalyticsService, {
    optional: true
  });

track() {

  this.analytics?.track('click');

}

42. `Host`

host limits the DI search according to the host boundary.

inject(UserService, {
  host: true
});

This becomes particularly important with:

component boundaries
directives
viewProviders
content projection

It is an advanced DI modifier and should be used when you actually need control over the resolution boundary. Angular's hierarchical DI documentation provides detailed examples of how host, skipSelf, and viewProviders interact.

43. Combining DI Modifiers

You can combine options.

For example:

inject(UserService, {
  skipSelf: true,
  optional: true
});

Meaning roughly:

"Don't use the current injector. Search the parents, but don't throw if nothing is found."

You can also use:

inject(UserService, {
  host: true,
  skipSelf: true,
  optional: true
});

These combinations become useful in advanced component/library architectures.

44. The Old Decorator Modifiers

In constructor injection, you may see:

constructor(
  @Optional()
  private analytics: AnalyticsService
) {}

or:

constructor(
  @Self()
  private service: LocalService
) {}

or:

constructor(
  @SkipSelf()
  private service: ParentService
) {}

or:

constructor(
  @Host()
  private service: HostService
) {}

You may also see:

@Inject(TOKEN)

These are older constructor-oriented APIs.

Modern inject() expresses the same concepts through options:

inject(TOKEN, {
  optional: true
});

45. `@Inject()`

Suppose the dependency isn't represented by a class:

export const API_URL =
  new InjectionToken<string>('API_URL');

Old style:

constructor(
  @Inject(API_URL)
  private apiUrl: string
) {}

Modern:

private apiUrl = inject(API_URL);

The modern syntax is usually much cleaner.

46. `forwardRef()`

Sometimes Angular needs to reference something before the TypeScript runtime declaration is available.

Example:

@Component({
  providers: [
    {
      provide: ParentComponent,
      useExisting: forwardRef(
        () => ChildComponent
      )
    }
  ]
})
export class ChildComponent {}

forwardRef() allows Angular to resolve a reference later.

It is mostly useful for circular references and unusual declaration-order scenarios.

Angular documents forwardRef() specifically for resolving references that cannot yet be directly referenced because of declaration order or circular relationships.

47. NgModule-Based DI

Older Angular applications commonly looked like:

@NgModule({
  declarations: [
    AppComponent
  ],

  imports: [
    BrowserModule
  ],

  providers: [
    UserService
  ],

  bootstrap: [
    AppComponent
  ]
})
export class AppModule {}

The application started with:

platformBrowserDynamic()
  .bootstrapModule(AppModule);

This architecture is still supported.

But modern Angular applications increasingly use:

bootstrapApplication()

with standalone components and environment providers.

48. Modern Standalone DI

Modern Angular:

bootstrapApplication(
  AppComponent,
  {
    providers: [
      UserService
    ]
  }
);

You can also use Angular's provider functions:

bootstrapApplication(
  AppComponent,
  {
    providers: [
      provideRouter(routes),
      provideHttpClient()
    ]
  }
);

This is one of the biggest architectural changes from the older NgModule era.

49. Provider Functions

Modern Angular libraries frequently expose APIs such as:

provideRouter(...)

and:

provideHttpClient(...)

Instead of asking developers to manually understand dozens of providers, the library exposes a single configuration function.

You can build the same pattern yourself.

Example:

export interface AnalyticsConfig {
  trackingId: string;
}

const ANALYTICS_CONFIG =
  new InjectionToken<AnalyticsConfig>(
    'ANALYTICS_CONFIG'
  );

export function provideAnalytics(
  config: AnalyticsConfig
) {

  return [
    {
      provide: ANALYTICS_CONFIG,
      useValue: config
    },

    AnalyticsService
  ];

}

Consumer:

bootstrapApplication(AppComponent, {

  providers: [
    provideAnalytics({
      trackingId: 'GA-123'
    })
  ]

});

This provideX() pattern is especially useful for Angular libraries because it encapsulates implementation details and makes configuration composable.

50. Feature Functions: `withX()`

Modern Angular libraries also use patterns such as:

provideSomething(
  withCaching(),
  withLogging(),
  withRetry()
)

You can implement the same architecture.

Example:

export function withLogging(): AnalyticsFeature {

  return {
    providers: [
      LoggingAnalyticsHandler
    ]
  };

}

Then:

provideAnalytics(
  config,
  withLogging()
);

This gives libraries a clean, composable API.

51. `InjectionToken` with a Factory

An InjectionToken can provide its own factory.

Example:

export const API_URL =
  new InjectionToken<string>(
    'API_URL',
    {
      providedIn: 'root',

      factory: () => {
        return 'https://api.example.com';
      }
    }
  );

Now you don't need:

providers: [
  {
    provide: API_URL,
    useValue: ...
  }
]

The token knows how to create itself.

This is another tree-shakable DI pattern.

52. DI and Testing

One of the biggest reasons DI exists is testability.

Without DI:

class UserService {

  private api =
    new RealApiClient();

}

Testing becomes difficult.

With DI:

class UserService {

  private api =
    inject(ApiClient);

}

Test:

TestBed.configureTestingModule({

  providers: [

    UserService,

    {
      provide: ApiClient,

      useClass: FakeApiClient
    }

  ]

});

Now the real API doesn't need to be called.

This is Dependency Injection's architectural value.

53. DI and Mocking

Suppose:

export abstract class PaymentGateway {

  abstract pay(
    amount: number
  ): Promise<boolean>;

}

Production:

{
  provide: PaymentGateway,
  useClass: StripePaymentGateway
}

Testing:

{
  provide: PaymentGateway,
  useClass: FakePaymentGateway
}

Your business logic doesn't know which implementation it received.

That's dependency inversion + DI.

54. DI and SOLID

Angular DI strongly supports SOLID principles.

Single Responsibility

A component doesn't need to create its dependencies.

Open/Closed

You can replace implementations without modifying consumers.

Liskov Substitution

Abstractions can be backed by interchangeable implementations.

Interface Segregation

Smaller tokens/interfaces can define focused contracts.

Dependency Inversion

High-level services can depend on abstractions.

DI doesn't automatically make an architecture SOLID, but it provides an excellent mechanism for implementing these principles.

55. DI Is Not a Global Singleton System

This is a common misconception.

People often say:

"Angular services are singletons."

That's not always true.

Consider:

@Injectable({
  providedIn: 'root'
})
export class CartService {}

This is normally application-wide.

But:

@Component({
  providers: [
    CartService
  ]
})
export class CheckoutComponent {}

creates a different scoped instance.

You can therefore have:

Root CartService
        |
        ├── Component A → root instance
        |
        └── Checkout → local instance

Angular DI is fundamentally about scope and resolution, not simply singletons.

56. Service Lifetime

Where you provide a dependency influences its lifetime.

Root provider

providedIn: 'root'

Usually lives for the application lifetime.

Component provider

@Component({
  providers: [CartService]
})

Lives with that component's injector.

When the component is destroyed, its scoped service can be destroyed as well.

This makes component-level DI extremely useful for isolated state.

57. A Perfect Use Case: Local Component State

Imagine:

@Injectable()
export class WizardState {

  currentStep = 1;

  next() {
    this.currentStep++;
  }

}

Then:

@Component({
  selector: 'app-checkout-wizard',

  providers: [
    WizardState
  ],

  template: `...`
})
export class CheckoutWizard {

  state = inject(WizardState);

}

Now every checkout wizard gets independent state.

You don't need:

WizardState #1
WizardState #2
WizardState #3

manually.

Angular's injector gives you the correct scoped instance.

58. Route-Level Providers

Modern Angular also allows providers to be associated with routes.

Conceptually:

export const routes: Routes = [

  {
    path: 'admin',

    providers: [
      AdminService
    ],

    loadComponent: () =>
      import('./admin.component')
        .then(m => m.AdminComponent)
  }

];

This is powerful because you can scope dependencies to a feature.

For example:

Application
   |
   ├── Public area
   |
   └── Admin route
          |
          └── AdminService

The admin dependency doesn't have to become globally available.

59. DI in Functional Guards

Older Angular:

@Injectable()
export class AuthGuard
  implements CanActivate {

  constructor(
    private auth: AuthService
  ) {}

  canActivate() {
    return this.auth.isAuthenticated();
  }

}

Modern Angular can use:

export const authGuard: CanActivateFn = () => {

  const auth =
    inject(AuthService);

  return auth.isAuthenticated();

};

This is a great example of how inject() enables functional Angular APIs.

60. DI in Functional Resolvers

The same principle applies to resolvers:

export const userResolver: ResolveFn<User> =
  () => {

    const userService =
      inject(UserService);

    return userService.getCurrentUser();

  };

No class is required.

Angular supplies the injection context.

61. DI and Directives

DI isn't only for components.

@Directive({
  selector: '[appHighlight]'
})
export class HighlightDirective {

  private element =
    inject(ElementRef);

}

Angular can inject framework-provided tokens such as:

ElementRef

and application services.

Angular documents DI as available to directives and components because they participate in the Angular DI system.

62. DI and Pipes

Injectable dependencies can also be used in pipes.

For example:

@Pipe({
  name: 'currencyFormat'
})
export class CurrencyFormatPipe {

  private config =
    inject(AppConfig);

  transform(value: number) {

    return `${this.config.currency}${value}`;

  }

}

63. DI and Interceptors

Modern functional interceptors are another excellent example:

export const authInterceptor:
  HttpInterceptorFn = (req, next) => {

    const auth =
      inject(AuthService);

    const token =
      auth.getToken();

    return next(
      req.clone({
        setHeaders: {
          Authorization: `Bearer ${token}`
        }
      })
    );

  };

The function itself doesn't receive AuthService as a parameter.

Angular creates the injection context in which the interceptor runs.

64. DI and Environment Configuration

A professional Angular application often needs:

API_URL

APP_NAME

FEATURE_FLAGS

DEFAULT_PAGE_SIZE

Instead of hardcoding these everywhere, define tokens.

export interface AppConfig {

  apiUrl: string;

  appName: string;

  features: {
    analytics: boolean;
    darkMode: boolean;
  };

}

Then:

export const APP_CONFIG =
  new InjectionToken<AppConfig>(
    'APP_CONFIG'
  );

Provide it once:

bootstrapApplication(AppComponent, {

  providers: [

    {
      provide: APP_CONFIG,

      useValue: {
        apiUrl: 'https://api.example.com',
        appName: 'Task Manager',

        features: {
          analytics: true,
          darkMode: true
        }
      }

    }

  ]

});

Now every service can consume strongly typed configuration.

65. Complete Project: Task Management Application

Let's build a realistic Angular architecture that demonstrates DI from beginning to end.

Our application will contain:

Task Management App

├── Configuration
├── Authentication
├── Logging
├── API Client
├── Task Repository
├── Task Service
├── Feature-specific providers
├── Payment abstraction
└── Testing implementation

66. Project Structure

src/
└── app/

    ├── core/
    │   ├── config/
    │   │   └── app-config.ts
    │   │
    │   ├── logging/
    │   │   ├── logger.ts
    │   │   └── console-logger.ts
    │   │
    │   ├── auth/
    │   │   └── auth.service.ts
    │   │
    │   └── api/
    │       └── api-client.ts
    │
    ├── tasks/
    │   ├── task.model.ts
    │   ├── task.repository.ts
    │   ├── task.service.ts
    │   └── task-list.component.ts
    │
    ├── app.component.ts
    ├── app.config.ts
    └── main.ts

67. Application Configuration

Create:

// core/config/app-config.ts

import { InjectionToken } from '@angular/core';

export interface AppConfig {

  apiUrl: string;

  appName: string;

  features: {
    analytics: boolean;
  };

}

export const APP_CONFIG =
  new InjectionToken<AppConfig>(
    'APP_CONFIG'
  );

68. Provide Configuration

// app.config.ts

import {
  ApplicationConfig
} from '@angular/core';

import {
  APP_CONFIG
} from './core/config/app-config';

export const appConfig:
  ApplicationConfig = {

  providers: [

    {
      provide: APP_CONFIG,

      useValue: {
        apiUrl: 'https://api.example.com',

        appName: 'Task Manager',

        features: {
          analytics: true
        }
      }
    }

  ]

};

69. Logger Abstraction

Create:

// core/logging/logger.ts

export abstract class Logger {

  abstract info(
    message: string
  ): void;

  abstract error(
    message: string
  ): void;

}

Now the application depends on:

Logger

not:

ConsoleLogger

70. Logger Implementation

// core/logging/console-logger.ts

import { Injectable } from '@angular/core';

import {
  Logger
} from './logger';

@Injectable()
export class ConsoleLogger
  implements Logger {

  info(message: string) {

    console.log(
      `[INFO] ${message}`
    );

  }

  error(message: string) {

    console.error(
      `[ERROR] ${message}`
    );

  }

}

71. Connect the Abstraction

In app.config.ts:

providers: [

  {
    provide: Logger,
    useClass: ConsoleLogger
  }

]

Now:

inject(Logger)

returns:

ConsoleLogger

The consumer doesn't care about the implementation.

72. Authentication Service

@Injectable({
  providedIn: 'root'
})
export class AuthService {

  private token =
    'fake-jwt-token';

  isAuthenticated(): boolean {

    return !!this.token;

  }

  getToken(): string {

    return this.token;

  }

}

Because it is root-provided, the application can share the service.

73. API Client

@Injectable({
  providedIn: 'root'
})
export class ApiClient {

  private http =
    inject(HttpClient);

  private config =
    inject(APP_CONFIG);

  get<T>(path: string) {

    return this.http.get<T>(
      `${this.config.apiUrl}${path}`
    );

  }

}

Now this service demonstrates DI with:

ApiClient
   |
   ├── HttpClient
   |
   └── APP_CONFIG

Angular constructs the dependency graph.

74. Task Repository

Define:

export abstract class TaskRepository {

  abstract getTasks():
    Observable<Task[]>;

}

Production implementation:

@Injectable()
export class HttpTaskRepository
  implements TaskRepository {

  private api =
    inject(ApiClient);

  getTasks() {

    return this.api.get<Task[]>(
      '/tasks'
    );

  }

}

75. Connect Repository to DI

providers: [

  {
    provide: TaskRepository,

    useClass: HttpTaskRepository
  }

]

Now:

inject(TaskRepository)

returns:

HttpTaskRepository

This is dependency inversion in practice.

76. Task Service

@Injectable({
  providedIn: 'root'
})
export class TaskService {

  private repository =
    inject(TaskRepository);

  getTasks() {

    return this.repository.getTasks();

  }

}

Notice the architecture:

TaskService
     |
     ↓
TaskRepository
     |
     ↓
HttpTaskRepository
     |
     ↓
ApiClient
     |
     ↓
HttpClient

The TaskService does not know how HTTP works.

That's good architecture.

77. Component

@Component({
  selector: 'app-task-list',

  template: `

    <h1>Tasks</h1>

    @for (task of tasks(); track task.id) {

      <article>

        <h2>{{ task.title }}</h2>

        <p>{{ task.description }}</p>

      </article>

    }

  `
})
export class TaskListComponent {

  private taskService =
    inject(TaskService);

  tasks = signal<Task[]>([]);

  constructor() {

    this.taskService
      .getTasks()
      .subscribe(tasks => {

        this.tasks.set(tasks);

      });

  }

}

Now the component doesn't know anything about:

HTTP
URLs
authentication
repositories
configuration

It only knows:

TaskService

That's exactly what DI should help you achieve.

78. Full Dependency Graph

The final graph looks like:

                    AppConfig
                       │
                       ↓
HttpClient ───────→ ApiClient
                       │
                       ↓
              HttpTaskRepository
                       │
                       ↓
                TaskRepository
                       │
                       ↓
                  TaskService
                       │
                       ↓
                TaskListComponent

Angular's DI system resolves this graph.

You don't manually write:

new ApiClient(...)
new HttpTaskRepository(...)
new TaskService(...)

Angular handles construction and provider resolution.

79. Replacing the Repository

Imagine tomorrow you replace REST with GraphQL.

Create:

@Injectable()
export class GraphQLTaskRepository
  implements TaskRepository {

  getTasks() {

    // GraphQL implementation

  }

}

Change the provider:

{
  provide: TaskRepository,

  useClass:
    GraphQLTaskRepository
}

The following code doesn't change:

TaskService

or:

TaskListComponent

That's the real power of abstraction + DI.

80. Adding a Fake Repository for Testing

@Injectable()
export class FakeTaskRepository
  implements TaskRepository {

  getTasks() {

    return of([
      {
        id: 1,
        title: 'Learn Angular DI',
        description:
          'Understand providers and injectors'
      }
    ]);

  }

}

Test configuration:

providers: [

  {
    provide: TaskRepository,

    useClass:
      FakeTaskRepository
  }

]

Now the entire application can run without a backend.

81. Factory-Based API Client

Suppose development and production require different API clients.

You can create:

export const API_CLIENT_PROVIDER = {

  provide: ApiClient,

  useFactory: () => {

    const http =
      inject(HttpClient);

    const config =
      inject(APP_CONFIG);

    const logger =
      inject(Logger);

    return new ApiClient(
      http,
      config,
      logger
    );

  }

};

This is useful when object construction requires multiple dependencies or runtime decisions.

82. Multiple Log Handlers

Let's make logging extensible.

export const LOG_HANDLERS =
  new InjectionToken<LogHandler[]>(
    'LOG_HANDLERS'
  );

Provide:

providers: [

  {
    provide: LOG_HANDLERS,
    useClass: ConsoleLogHandler,
    multi: true
  },

  {
    provide: LOG_HANDLERS,
    useClass: RemoteLogHandler,
    multi: true
  }

]

Then:

@Injectable({
  providedIn: 'root'
})
export class LoggerService {

  private handlers =
    inject(LOG_HANDLERS);

  info(message: string) {

    for (const handler
      of this.handlers) {

      handler.info(message);

    }

  }

}

Now adding another logging destination requires adding another provider rather than changing LoggerService.

83. Building a `provideTasks()` API

We can package the entire feature.

export function provideTasks(): Provider[] {

  return [

    {
      provide: TaskRepository,

      useClass:
        HttpTaskRepository
    },

    TaskService

  ];

}

Then:

bootstrapApplication(
  AppComponent,
  {
    providers: [
      provideTasks()
    ]
  }
);

For a real library, you would typically return an appropriate provider configuration and may compose optional features.

This is the same architectural idea behind Angular's provider-function APIs.

84. Advanced `provideX()` Architecture

A more sophisticated API can look like:

provideTasks(
  withCaching(),
  withLogging(),
  withRetry()
)

Internally:

export function provideTasks(
  ...features: TaskFeature[]
): Provider[] {

  return [

    TaskService,

    ...features.flatMap(
      feature => feature.providers
    )

  ];

}

This pattern is excellent for reusable Angular libraries.

85. `viewProviders` in Real Applications

Consider a reusable component:

@Component({
  selector: 'app-data-table',

  viewProviders: [
    TableState
  ],

  template: `
    <table>
      ...
    </table>

    <ng-content />
  `
})
export class DataTableComponent {}

If TableState is an internal implementation detail, viewProviders can prevent projected content from accidentally depending on it.

This is a real architectural reason to use viewProviders.

86. Lightweight Injection Tokens

Angular libraries sometimes want a parent component to communicate with a child without forcing a hard runtime dependency on the concrete component class.

For example:

export abstract class HeaderToken {

  abstract close(): void;

}

Then:

@Component({
  selector: 'app-header',

  providers: [
    {
      provide: HeaderToken,
      useExisting: HeaderComponent
    }
  ]
})
export class HeaderComponent
  extends HeaderToken {

  close() {
    // ...
  }

}

Consumers depend on:

HeaderToken

instead of:

HeaderComponent

Angular documents this as a lightweight injection-token pattern useful for library design and tree-shaking.

87. DI and Circular Dependencies

Sometimes you accidentally create:

A → B
↑   ↓
└───┘

For example:

ServiceA → ServiceB
ServiceB → ServiceA

This can produce DI errors.

The correct solution is usually architectural:

remove the circular dependency
introduce an abstraction
move shared behavior to another service
restructure the dependency graph

Don't immediately reach for forwardRef().

forwardRef() solves declaration/reference problems; it is not a general solution for bad architecture.

88. Common DI Error: NullInjectorError

You may see:

NullInjectorError:
No provider for UserService!

Usually this means:

inject(UserService)

was called but Angular couldn't find a provider in the available injector hierarchy.

Possible solutions:

@Injectable({
  providedIn: 'root'
})

or:

providers: [
  UserService
]

or:

bootstrapApplication(AppComponent, {
  providers: [
    UserService
  ]
});

But don't blindly add:

providedIn: 'root'

just to make the error disappear.

First determine the intended scope.

89. Common DI Error: Wrong Scope

Suppose:

@Component({
  providers: [
    CartService
  ]
})
export class CheckoutComponent {}

Then another unrelated parent tries:

inject(CartService)

and fails.

Why?

Because the service exists inside the checkout component's injector, not globally.

The solution isn't necessarily moving it to root.

The real question is:

Where should this dependency live?

That's the architectural question DI forces you to answer.

90. Common Error: `inject()` Outside Context

This:

ngOnInit() {

  const service =
    inject(UserService);

}

causes:

NG0203

because ngOnInit() is not an injection context.

Fix:

private service =
  inject(UserService);

Then:

ngOnInit() {

  this.service.load();

}

Angular explicitly documents NG0203 as the error produced when inject() is used outside a valid injection context.

91. Common Error: Two InjectionTokens

Wrong:

const CONFIG =
  new InjectionToken<AppConfig>(
    'CONFIG'
  );

Provider file:

const CONFIG =
  new InjectionToken<AppConfig>(
    'CONFIG'
  );

These are different tokens.

Correct:

// config.token.ts

export const CONFIG =
  new InjectionToken<AppConfig>(
    'CONFIG'
  );

Then:

import { CONFIG }
  from './config.token';

everywhere.

92. Common Error: Confusing `useClass` and `useExisting`

If you want:

same instance

use:

useExisting

If you want Angular to create an implementation from a class:

useClass

Remember:

useClass    → implementation
useExisting → alias

93. Common Error: Making Everything `providedIn: 'root'`

This is probably the most common architectural mistake.

Developers write:

@Injectable({
  providedIn: 'root'
})

for every service.

But some services should be scoped:

@Component({
  providers: [
    FormStateService
  ]
})

Others may belong to:

feature
route
environment
application
component

A good Angular architecture chooses scope intentionally.

94. How to Decide Provider Scope

Ask:

Should every part of the application share one instance?

Use:

providedIn: 'root'

Should every instance of a component have independent state?

Use:

@Component({
  providers: [...]
})

Should a feature have its own dependency?

Consider route/environment providers.

Should the dependency be configurable?

Use:

InjectionToken

Should different implementations be interchangeable?

Use:

abstract class / InjectionToken
+
useClass

Should multiple implementations contribute?

Use:

multi: true

Should an existing provider be exposed under another token?

Use:

useExisting

Does creation require runtime logic?

Use:

useFactory

95. DI in Modern Angular vs Old Angular

Concept	Traditional Angular	Modern Angular
Injection	Constructor	`inject()` + constructor
Application architecture	NgModules	Standalone
Global providers	`AppModule.providers`	`ApplicationConfig` / `providedIn`
Feature providers	NgModules	Environment/route providers
Guards	Class-based	Functional guards
Resolvers	Class-based	Functional resolvers
Configuration	`InjectionToken`	`InjectionToken`
Provider factories	`useFactory`	`useFactory` + `inject()`
Library APIs	NgModule configuration	`provideX()` / `withX()`
Scope	Module/component	Environment/element/route/component

The important point is that Angular did not throw away DI.

Instead, Angular evolved the way DI is configured and consumed.

96. What You Should Learn for an Angular Interview

If an interviewer asks:

"Explain Dependency Injection in Angular."

Don't answer only:

"Angular injects services into components."

A strong answer is:

Angular's Dependency Injection system manages the creation and delivery of dependencies using tokens, providers, and injectors. A provider defines how a token should be resolved, while an injector performs the resolution and controls scope and lifetime. Modern Angular supports both constructor injection and the inject() function. Providers can be configured through providedIn, application/environment providers, routes, components, and directives. Angular also supports provider strategies such as useClass, useValue, useFactory, useExisting, and multi, while hierarchical injectors allow dependencies to be scoped and overridden at different levels.

Then explain:

Token
Provider
Injector
Scope
Resolution

That demonstrates real understanding.

97. The Mental Model You Should Remember

Whenever Angular sees:

inject(SomeDependency)

think:

What token is being requested?
          ↓
Which injector is currently active?
          ↓
Where is the nearest provider?
          ↓
What provider recipe is configured?
          ↓
Does Angular create or reuse an instance?
          ↓
What is the dependency's scope/lifetime?

For example:

inject(TaskRepository)

becomes:

TaskRepository
      ↓
Current Injector
      ↓
Find Provider
      ↓
useClass: HttpTaskRepository
      ↓
Create/Reuse HttpTaskRepository
      ↓
Resolve its dependencies
      ↓
Return instance

That is Angular DI.

98. The Complete Picture

Angular DI can be understood as five layers:

                    ┌──────────────────────┐
                    │       Consumer       │
                    │  Component/Service   │
                    └──────────┬───────────┘
                               │
                               │ inject(Token)
                               ↓
                    ┌──────────────────────┐
                    │       Injector       │
                    │   Resolve dependency │
                    └──────────┬───────────┘
                               │
                               ↓
                    ┌──────────────────────┐
                    │       Provider       │
                    │ useClass/useValue/   │
                    │ useFactory/useExisting│
                    └──────────┬───────────┘
                               │
                               ↓
                    ┌──────────────────────┐
                    │      Dependency      │
                    │ Service/Object/etc.  │
                    └──────────────────────┘

And the injector itself exists within a hierarchy:

                 EnvironmentInjector
                         │
             ┌───────────┴───────────┐
             │                       │
        Application              Feature/Route
             │                       │
             └───────────┬───────────┘
                         │
                  ElementInjector
                         │
                    Component
                         │
                   Child Component
                         │
                  Grandchild Component

99. Best Practices

1. Prefer `providedIn: 'root'` for true application-wide services

@Injectable({
  providedIn: 'root'
})

2. Use component providers for isolated state

@Component({
  providers: [
    FormState
  ]
})

3. Prefer `inject()` for modern Angular code

private service = inject(MyService);

4. Keep constructor injection when it makes sense

You don't need to rewrite every existing Angular application.

5. Use `InjectionToken` for interfaces and configuration

new InjectionToken<AppConfig>()

6. Use abstractions when implementations may change

abstract class PaymentGateway {}

7. Use `useExisting` when you need an alias to the same instance

8. Use `multi` for extensible collections

9. Don't make every service global

Scope dependencies intentionally.

10. Don't use `runInInjectionContext()` unnecessarily

Normal DI should remain the default.

11. Don't create duplicate `InjectionToken` instances

Export one token and reuse it.

12. Use Angular DevTools when debugging injector problems

Angular DevTools can visualize injector hierarchies, provider lists, and resolution paths, which is extremely useful when debugging complex DI behavior.

100. Final Cheat Sheet

// Root service
@Injectable({
  providedIn: 'root'
})
export class UserService {}

// Modern injection
private userService = inject(UserService);

// Classic injection
constructor(
  private userService: UserService
) {}

// Value
{
  provide: API_URL,
  useValue: 'https://api.example.com'
}

// Class
{
  provide: Logger,
  useClass: ConsoleLogger
}

// Alias
{
  provide: LegacyLogger,
  useExisting: Logger
}

// Factory
{
  provide: ApiClient,
  useFactory: () => {

    const http = inject(HttpClient);

    return new ApiClient(http);

  }
}

// Multiple providers
{
  provide: HANDLERS,
  useClass: ConsoleHandler,
  multi: true
}

// Optional
inject(Service, {
  optional: true
});

// Parent
inject(Service, {
  skipSelf: true
});

// Current injector only
inject(Service, {
  self: true
});

// Host boundary
inject(Service, {
  host: true
});

// InjectionToken
const CONFIG =
  new InjectionToken<AppConfig>(
    'CONFIG'
  );

// Component scope
@Component({
  providers: [
    LocalState
  ]
})

// Component view-only scope
@Component({
  viewProviders: [
    InternalService
  ]
})

// Modern application providers
bootstrapApplication(
  AppComponent,
  {
    providers: [
      provideRouter(routes),
      provideHttpClient()
    ]
  }
);

// Custom provider API
provideAnalytics({
  trackingId: '123'
});

Conclusion

Angular Dependency Injection is much more than:

constructor(private service: Service) {}

That syntax is only the visible surface.

Underneath it is a complete dependency-resolution system built around:

Tokens
   ↓
Providers
   ↓
Injectors
   ↓
Hierarchies
   ↓
Scopes
   ↓
Lifetimes
   ↓
Implementations

The evolution from:

constructor(...)

to:

inject(...)

didn't replace Angular DI.

It made DI usable in a much broader range of modern Angular APIs, including functional guards, resolvers, provider factories, standalone applications, environment providers, and library configuration.

The most important concepts to master are:

Dependency Injection
       ↓
Token
       ↓
Provider
       ↓
Injector
       ↓
EnvironmentInjector
       ↓
ElementInjector
       ↓
Hierarchical Resolution
       ↓
Provider Scope
       ↓
useClass
useValue
useFactory
useExisting
multi
       ↓
InjectionToken
       ↓
inject()
       ↓
Injection Context
       ↓
Self / SkipSelf / Host / Optional
       ↓
Standalone + provideX()
       ↓
Testing + Architecture

Once you understand these concepts, Angular DI stops being a collection of decorators and APIs.

You start seeing it as what it really is:

A runtime dependency-resolution and scoping system that allows Angular applications to separate what a component needs from how that dependency is created.

And that separation is one of the foundations of maintainable, testable, scalable Angular architecture.

References

Angular Dependency Injection Guide — Angular DI Documentation
Angular Hierarchical Injectors — Hierarchical Dependency Injection
Angular Provider Configuration — Defining Dependency Providers
Angular Injection Context — Injection Context
Angular inject() API — inject() API
Angular DevTools Injector Tree — Angular DevTools Injectors

DOM in Angular: Understanding the Document Object Model with Practical Examples

Abanoub Kerols — Sun, 06 Sep 2026 08:06:30 +0000

Angular applications are built around components, templates, data binding, directives, and a powerful rendering system.

But underneath all of that, your application still runs inside a browser, and the browser ultimately renders HTML elements through the DOM — Document Object Model.

Understanding how Angular interacts with the DOM is essential if you want to write efficient Angular applications, understand rendering behavior, work with browser APIs, and avoid common performance and security problems.

In this article, we will explore:

What the DOM is
How Angular interacts with the DOM
Angular's rendering model
ElementRef
Renderer2
ViewChild
ViewChildren
HostListener
HostBinding
DOCUMENT
Direct DOM manipulation
DOM events
Dynamic DOM changes
Angular lifecycle and the DOM
Change detection and DOM updates
SSR and hydration
Performance considerations
Security considerations
Real-world examples

1. What Is the DOM?

DOM stands for:

Document Object Model

When the browser receives HTML like:

<div>
  <h1>Hello Angular</h1>
  <button>Click Me</button>
</div>

The browser converts the HTML document into a tree-like structure.

Conceptually:

Document
└── html
    └── body
        └── div
            ├── h1
            │   └── "Hello Angular"
            └── button
                └── "Click Me"

Each HTML element becomes a DOM node.

JavaScript can interact with these nodes.

For example:

const button = document.querySelector('button');

button.textContent = 'Clicked';

The JavaScript code directly modifies the DOM.

2. The DOM in Angular

Angular adds another layer on top of the browser DOM.

Instead of manually manipulating HTML, Angular encourages you to describe what the UI should look like based on application state.

For example:

export class AppComponent {
  title = 'Hello Angular';
}

Template:

<h1>{{ title }}</h1>

Angular takes the component state:

title = "Hello Angular"

and renders:

<h1>Hello Angular</h1>

The browser then creates the corresponding DOM node.

Conceptually:

Component State
      ↓
Angular Template
      ↓
Angular Rendering Engine
      ↓
DOM
      ↓
Browser Screen

This is one of the most important concepts to understand.

3. Angular Does Not Mean "Never Touch the DOM"

You will often hear:

"Never manipulate the DOM directly in Angular."

This is an oversimplification.

The better rule is:

Avoid unnecessary direct DOM manipulation and prefer Angular abstractions when possible.

Angular provides APIs such as:

ElementRef
Renderer2
ViewChild
ViewChildren
HostListener
HostBinding
DOCUMENT

These allow Angular applications to interact with the DOM in a controlled way.

4. ElementRef

ElementRef provides access to the native DOM element associated with an Angular element.

Example:

import { Component, ElementRef, ViewChild } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <input #usernameInput placeholder="Enter username">
    <button (click)="focusInput()">Focus</button>
  `
})
export class ExampleComponent {

  @ViewChild('usernameInput')
  usernameInput!: ElementRef<HTMLInputElement>;

  focusInput() {
    this.usernameInput.nativeElement.focus();
  }
}

Here:

this.usernameInput.nativeElement

represents the actual browser element.

The DOM looks approximately like:

<input placeholder="Enter username">

5. Why ElementRef Can Be Dangerous

The problem is that nativeElement gives you direct access to the DOM.

For example:

this.usernameInput.nativeElement.style.color = 'red';

or:

this.usernameInput.nativeElement.innerHTML = userInput;

The second example can create security problems if the content is untrusted.

For example:

element.nativeElement.innerHTML = userInput;

If userInput contains malicious HTML, you may create an XSS vulnerability.

Therefore, avoid using ElementRef for general DOM manipulation when Angular provides a safer abstraction.

6. Renderer2

Angular provides Renderer2 for DOM manipulation.

Example:

import {
  Component,
  ElementRef,
  Renderer2
} from '@angular/core';

@Component({
  selector: 'app-box',
  template: `
    <div #box>Angular Box</div>
    <button (click)="changeColor()">Change Color</button>
  `
})
export class BoxComponent {

  constructor(
    private renderer: Renderer2,
    private elementRef: ElementRef
  ) {}

  changeColor() {
    const box = this.elementRef.nativeElement.querySelector('div');

    this.renderer.setStyle(
      box,
      'background-color',
      'blue'
    );
  }
}

Instead of:

box.style.backgroundColor = 'blue';

we use:

this.renderer.setStyle(
  box,
  'background-color',
  'blue'
);

7. Why Renderer2 Exists

Angular applications don't necessarily run only in a traditional browser DOM environment.

Angular can support environments such as:

Browser
Server-side rendering
Different rendering environments
Custom rendering implementations

Direct DOM APIs such as:

document.querySelector()

assume that a browser DOM exists.

Renderer2 gives Angular a more abstract mechanism for rendering operations.

Therefore:

Renderer2

is generally preferable to manually manipulating DOM APIs.

8. Renderer2 Common Operations

Set Attribute

this.renderer.setAttribute(
  element,
  'aria-label',
  'Close'
);

Remove Attribute

this.renderer.removeAttribute(
  element,
  'disabled'
);

Add Class

this.renderer.addClass(
  element,
  'active'
);

Remove Class

this.renderer.removeClass(
  element,
  'active'
);

Set Style

this.renderer.setStyle(
  element,
  'color',
  'red'
);

Remove Style

this.renderer.removeStyle(
  element,
  'color'
);

Create Element

const div = this.renderer.createElement('div');

Create Text

const text = this.renderer.createText(
  'Hello Angular'
);

Append Child

this.renderer.appendChild(
  parent,
  child
);

9. ViewChild

ViewChild is one of the most commonly used Angular APIs for accessing elements inside a component template.

Example:

<input #emailInput>

<button (click)="focusEmail()">
  Focus
</button>

Component:

@ViewChild('emailInput')
emailInput!: ElementRef<HTMLInputElement>;

focusEmail() {
  this.emailInput.nativeElement.focus();
}

The #emailInput syntax creates a template reference variable.

10. ViewChild With Components

ViewChild is not limited to DOM elements.

You can use it to access another Angular component.

Child:

@Component({
  selector: 'app-child',
  template: `
    <p>Child Component</p>
  `
})
export class ChildComponent {

  reset() {
    console.log('Child reset');
  }
}

Parent:

<app-child></app-child>
<button (click)="resetChild()">
  Reset
</button>

Parent component:

@ViewChild(ChildComponent)
child!: ChildComponent;

resetChild() {
  this.child.reset();
}

This is an important distinction:

@ViewChild('input')

can access an element.

While:

@ViewChild(ChildComponent)

can access a component instance.

11. AfterViewInit

If you need to access a DOM element through ViewChild, you need to understand Angular lifecycle timing.

Example:

import {
  AfterViewInit,
  Component,
  ElementRef,
  ViewChild
} from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <input #input>
  `
})
export class ExampleComponent
  implements AfterViewInit {

  @ViewChild('input')
  input!: ElementRef<HTMLInputElement>;

  ngAfterViewInit() {
    this.input.nativeElement.focus();
  }
}

Why?

Because Angular needs to create the component's view before the DOM element exists.

Lifecycle:

Constructor
     ↓
Angular creates component
     ↓
Template rendered
     ↓
View initialized
     ↓
ngAfterViewInit()

Therefore, DOM-related initialization often belongs in:

ngAfterViewInit()

12. ViewChildren

ViewChildren allows you to access multiple elements or components.

Example:

<input #input>
<input #input>
<input #input>

Component:

@ViewChildren('input')
inputs!: QueryList<ElementRef<HTMLInputElement>>;

You can iterate:

this.inputs.forEach(input => {
  console.log(input.nativeElement);
});

13. DOM Events in Angular

Normally, you don't need to manually attach DOM event listeners.

Angular provides event binding.

Example:

<button (click)="handleClick()">
  Click Me
</button>

Component:

handleClick() {
  console.log('Button clicked');
}

This is preferable to:

document
  .querySelector('button')
  ?.addEventListener('click', () => {});

Angular handles the event binding for you.

14. Event Object

You can also access the browser event.

<button (click)="handleClick($event)">
  Click
</button>

TypeScript:

handleClick(event: MouseEvent) {
  console.log(event);
}

For keyboard events:

<input (keydown)="handleKeyDown($event)">

handleKeyDown(event: KeyboardEvent) {
  console.log(event.key);
}

15. HostListener

HostListener allows a directive or component to listen to events.

Example:

import {
  Directive,
  HostListener
} from '@angular/core';

@Directive({
  selector: '[appHighlight]'
})
export class HighlightDirective {

  @HostListener('mouseenter')
  onMouseEnter() {
    console.log('Mouse entered');
  }

  @HostListener('mouseleave')
  onMouseLeave() {
    console.log('Mouse left');
  }
}

HTML:

<div appHighlight>
  Hover over me
</div>

Angular connects the events to the directive.

16. HostBinding

HostBinding allows you to bind a property, attribute, or class to the host element.

Example:

@HostBinding('class.active')
isActive = false;

Then:

toggle() {
  this.isActive = !this.isActive;
}

The host element automatically receives:

<div class="active">

when:

isActive === true

17. Renderer2 + HostListener Example

Let's create a reusable hover directive.

import {
  Directive,
  HostListener,
  Renderer2
} from '@angular/core';

@Directive({
  selector: '[appHover]'
})
export class HoverDirective {

  constructor(private renderer: Renderer2) {}

  @HostListener('mouseenter')
  onEnter() {
    this.renderer.setStyle(
      this.element,
      'transform',
      'scale(1.05)'
    );
  }

  @HostListener('mouseleave')
  onLeave() {
    this.renderer.removeStyle(
      this.element,
      'transform'
    );
  }

  private get element(): HTMLElement {
    return this.el.nativeElement;
  }

  constructor(
    private renderer: Renderer2,
    private el: ElementRef
  ) {}
}

The example demonstrates an important Angular pattern:

HostListener
      ↓
Event
      ↓
Renderer2
      ↓
DOM update

18. Angular Template Binding vs Direct DOM Manipulation

Consider this:

this.element.nativeElement.textContent = this.username;

Angular's preferred approach is:

<p>{{ username }}</p>

Why?

Because Angular can track application state and update the UI accordingly.

For example:

username = 'Abanoub';

changeName() {
  this.username = 'John';
}

Template:

<h2>{{ username }}</h2>

When the value changes, Angular updates the relevant DOM.

19. Property Binding

Angular provides property binding:

<button [disabled]="isLoading">
  Submit
</button>

Instead of:

button.disabled = isLoading;

Angular manages the relationship between state and DOM.

This is one of the fundamental ideas of Angular:

State
  ↓
Binding
  ↓
DOM

20. Attribute Binding

You can bind HTML attributes:

<button
  [attr.aria-label]="label">
  Save
</button>

You can also conditionally remove an attribute:

<div [attr.aria-hidden]="isHidden ? 'true' : null">
</div>

When the value is null, Angular removes the attribute.

21. Class Binding

Instead of manipulating:

element.classList.add('active');

you can use:

<div [class.active]="isActive">
</div>

Multiple classes can be controlled with:

<div
  [class.active]="isActive"
  [class.disabled]="isDisabled">
</div>

22. Style Binding

Example:

<div
  [style.color]="textColor"
  [style.font-size.px]="fontSize">
  Hello
</div>

Component:

textColor = 'red';
fontSize = 20;

Angular updates the DOM when these values change.

23. Structural Changes and the DOM

Angular can dynamically add and remove DOM nodes.

For example:

@if (isLoggedIn) {
  <p>Welcome back!</p>
}

When:

isLoggedIn = false;

the paragraph isn't rendered.

When:

isLoggedIn = true;

Angular creates the required DOM structure.

Conceptually:

isLoggedIn = false

DOM
└── No <p>


isLoggedIn = true

DOM
└── <p>Welcome back!</p>

24. @for and DOM Creation

Angular's modern control flow also provides:

@for (user of users; track user.id) {
  <div>
    {{ user.name }}
  </div>
}

Suppose:

users = [
  { id: 1, name: 'John' },
  { id: 2, name: 'Sarah' }
];

Angular creates DOM elements corresponding to these records.

The important part is:

track user.id

It gives Angular a stable identity for each item.

25. Why Tracking Matters

Imagine:

User 1
User 2
User 3
User 4

If you add:

User 5

Angular doesn't necessarily need to recreate every DOM element.

With stable tracking:

@for (user of users; track user.id)

Angular can efficiently identify which DOM nodes correspond to which data.

This becomes especially important with large lists.

26. Angular Change Detection and the DOM

Angular applications are usually driven by state changes.

For example:

count = 0;

increment() {
  this.count++;
}

Template:

<p>{{ count }}</p>

<button (click)="increment()">
  Increment
</button>

When the user clicks:

click
 ↓
increment()
 ↓
count++
 ↓
Angular detects changes
 ↓
Template binding evaluated
 ↓
DOM updated

Angular doesn't blindly rebuild the entire page.

It updates the parts of the rendered view that need to change.

27. Signals and DOM Updates

Modern Angular provides Signals.

Example:

import { signal } from '@angular/core';

count = signal(0);

increment() {
  this.count.update(value => value + 1);
}

Template:

<p>{{ count() }}</p>

<button (click)="increment()">
  Increment
</button>

The relationship becomes:

Signal
  ↓
Template dependency
  ↓
Angular knows what depends on the signal
  ↓
Relevant view update
  ↓
DOM

This makes Signals an important part of understanding modern Angular rendering.

28. Direct document Access

You can inject the browser Document using Angular's DOCUMENT token.

import {
  Component,
  Inject
} from '@angular/core';

import { DOCUMENT } from '@angular/common';

@Component({
  selector: 'app-example',
  template: `
    <button (click)="changeTitle()">
      Change Title
    </button>
  `
})
export class ExampleComponent {

  constructor(
    @Inject(DOCUMENT)
    private document: Document
  ) {}

  changeTitle() {
    this.document.title = 'Angular Application';
  }
}

This is useful for operations involving the document itself.

29. Why document.querySelector() Is Usually Not Recommended

You could write:

document.querySelector('#myElement');

But in Angular this is often the wrong abstraction.

Problems include:

1. Tight coupling

Your component becomes tightly coupled to a specific DOM structure.

2. Testing

Direct browser APIs can make testing more complicated.

3. SSR

The server doesn't have a normal browser DOM.

4. Maintainability

Angular template APIs are easier to reason about in many cases.

Prefer:

#myElement

and:

@ViewChild('myElement')

when you need access to an element in your component view.

30. Server-Side Rendering and the DOM

This becomes extremely important with Angular SSR.

In a normal browser:

document.querySelector(...)

works because a browser DOM exists.

On the server:

Node.js
   ↓
Angular SSR
   ↓
No normal browser DOM

Therefore, code like:

document.querySelector('button');

can fail during server rendering.

This is one reason Angular applications should avoid unnecessary direct browser APIs.

31. Browser-Only Code

If something genuinely requires browser APIs, Angular provides mechanisms to determine the execution environment.

For example:

import {
  Component,
  inject
} from '@angular/core';

import {
  isPlatformBrowser
} from '@angular/common';

import { PLATFORM_ID } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `...`
})
export class ExampleComponent {

  private platformId = inject(PLATFORM_ID);

  constructor() {
    if (isPlatformBrowser(this.platformId)) {
      // Browser-specific logic
    }
  }
}

This prevents browser-only logic from executing in a server environment.

32. DOM and Hydration

With SSR and hydration, Angular can first render HTML on the server.

Conceptually:

Server
  ↓
Angular SSR
  ↓
HTML
  ↓
Browser
  ↓
Existing DOM
  ↓
Hydration
  ↓
Interactive Angular Application

This means your Angular application needs to be careful about manually modifying the DOM before or during hydration.

Unexpected DOM changes can interfere with Angular's ability to match the server-rendered structure with the client-side application.

33. DOM Manipulation and Performance

DOM operations can be expensive.

For example, repeatedly doing:

element.style.width = ...
element.style.height = ...
element.style.left = ...
element.style.top = ...

inside a high-frequency event such as:

mousemove

can cause performance problems.

Better approaches include:

CSS classes
CSS animations
Angular bindings
Signals
requestAnimationFrame
minimizing DOM operations
avoiding unnecessary layout reads/writes

34. Layout Thrashing

A common browser performance problem is layout thrashing.

For example:

element.style.width = '500px';

const height = element.offsetHeight;

element.style.height = height + 'px';

Writing to the DOM and immediately reading layout information can force the browser to recalculate layout.

Repeated operations can become expensive.

Conceptually:

DOM Write
   ↓
Layout calculation
   ↓
DOM Read
   ↓
Layout calculation
   ↓
DOM Write
   ↓
...

Avoid unnecessary cycles like this.

35. Example: Better DOM Interaction

Instead of:

element.style.display = 'none';

Angular can often use:

@if (isVisible) {
  <div>
    Content
  </div>
}

Or class binding:

<div [class.hidden]="!isVisible">
  Content
</div>

This makes the UI declarative.

36. DOM vs Angular View

This distinction is important.

The DOM is the browser's representation of the document.

Angular's view is Angular's representation of the UI generated from:

Components
Templates
Directives
Bindings
Angular rendering instructions

Conceptually:

Angular Application
        │
        ├── Component
        │
        ├── Template
        │
        ├── Bindings
        │
        └── Directives
               │
               ↓
       Angular Rendering
               │
               ↓
             DOM
               │
               ↓
            Browser

Therefore, Angular developers should generally manipulate application state and templates, rather than treating the DOM as the primary source of truth.

37. Real-World Example: Auto Focus

Suppose you have:

<input #searchInput>

<button (click)="focusSearch()">
  Search
</button>

Component:

@ViewChild('searchInput')
searchInput!: ElementRef<HTMLInputElement>;

focusSearch() {
  this.searchInput.nativeElement.focus();
}

This is a legitimate use case for direct DOM access.

Why?

Because focusing an input is inherently a browser interaction.

38. Real-World Example: Dynamic CSS Class

Instead of:

this.renderer.addClass(element, 'selected');

Angular can often handle this declaratively:

<div [class.selected]="isSelected">
  Product
</div>

Component:

isSelected = false;

select() {
  this.isSelected = true;
}

This is usually simpler.

39. Real-World Example: Tooltip Directive

A directive can listen to mouse events:

@Directive({
  selector: '[appTooltip]'
})
export class TooltipDirective {

  @Input()
  appTooltip = '';

  @HostListener('mouseenter')
  showTooltip() {
    console.log(this.appTooltip);
  }

  @HostListener('mouseleave')
  hideTooltip() {
    console.log('Hide tooltip');
  }
}

HTML:

<button appTooltip="Delete this item">
  Delete
</button>

The directive interacts with the host element without requiring:

document.querySelector(...)

40. DOM Security

One of the most important rules when working with the DOM is:

Never blindly insert untrusted HTML into the DOM.

Avoid patterns such as:

element.innerHTML = userInput;

Especially when:

userInput

comes from:

User input
URL parameters
API responses
External content
Query strings

Angular provides security mechanisms and sanitization for many template scenarios.

Be especially careful with:

[innerHTML]="htmlContent"

and APIs such as:

DomSanitizer

Bypassing Angular's security mechanisms should only be done when you fully understand and trust the content.

41. innerHTML in Angular

Angular allows:

<div [innerHTML]="content"></div>

For example:

content = '<strong>Hello Angular</strong>';

Angular processes the value according to its security model.

However, don't assume that every value is safe just because you're using Angular.

Avoid blindly doing:

this.sanitizer.bypassSecurityTrustHtml(userInput);

This method does not magically make malicious content safe.

It tells Angular:

"I trust this value."

Therefore, the developer becomes responsible for that trust decision.

42. Common Mistakes

Mistake 1 — Excessive querySelector

Avoid:

document.querySelector(...)

for normal component interactions.

Prefer:

ViewChild

or template bindings.

Mistake 2 — Excessive ElementRef

Avoid using:

elementRef.nativeElement

for every UI operation.

Prefer:

[class.active]="isActive"

over:

element.classList.add('active');

Mistake 3 — Manipulating DOM Instead of State

Bad approach:

element.textContent = 'Loading...';

Better:

isLoading = true;

Template:

@if (isLoading) {
  <span>Loading...</span>
}

Mistake 4 — Ignoring SSR

This can be problematic:

window.localStorage.getItem('token');

when code may execute on the server.

Browser-only APIs should be handled appropriately in SSR applications.

43. When Should You Manipulate the DOM?

Direct DOM interaction is appropriate when the operation is inherently DOM-related.

Examples:

Focus

input.focus();

Measuring an element

element.getBoundingClientRect();

Integrating a third-party DOM library

For example:

Charting library
Rich text editor
Map library
Animation library

Low-level browser interaction

For example:

Selection API
Clipboard API
ResizeObserver
IntersectionObserver

However, use Angular abstractions where they make sense.

44. Angular DOM Best-Practice Hierarchy

A useful mental model is:

Level 1 — Template syntax

Prefer:

{{ value }}

[class.active]="isActive"

[disabled]="isLoading"

Level 2 — Angular APIs

Use:

ViewChild
ViewChildren
HostListener
HostBinding
Renderer2

when appropriate.

Level 3 — Native DOM APIs

Use:

nativeElement
document
window
querySelector

only when you genuinely need lower-level browser functionality.

The general idea:

Declarative Angular API
        ↓
Angular DOM abstraction
        ↓
Native DOM API

Use the highest level that solves the problem correctly.

45. Interview Question: What Is the DOM?

A strong answer:

The DOM, or Document Object Model, is the browser's object-based representation of an HTML document. It represents elements as a tree of nodes that JavaScript and other APIs can interact with. In Angular, templates and bindings are used to declaratively generate and update the DOM.

46. Interview Question: Should We Manipulate the DOM Directly in Angular?

A good answer:

Generally, Angular encourages declarative UI development through templates, bindings, directives, and component state. Direct DOM manipulation should be minimized because it can make applications harder to maintain, complicate SSR, and bypass Angular's rendering model. When DOM interaction is required, Angular APIs such as Renderer2, ViewChild, and HostListener can provide better integration.

47. Interview Question: ElementRef vs Renderer2

ElementRef

Provides access to the underlying native element:

elementRef.nativeElement

Useful for cases such as:

focus()

Renderer2

Provides an abstraction for DOM operations:

renderer.setStyle(...)
renderer.addClass(...)
renderer.setAttribute(...)

A simplified rule:

Need direct element interaction?
        ↓
ElementRef

Need DOM manipulation?
        ↓
Prefer Renderer2

48. Interview Question: Why Avoid document.querySelector()?

Because it:

couples code to DOM structure
bypasses Angular abstractions
can cause problems with SSR
makes components harder to test
can lead to maintainability problems

Instead, Angular provides:

ViewChild

ViewChildren

Renderer2

and template bindings.

49. Interview Question: When Is ngAfterViewInit Used?

ngAfterViewInit() runs after Angular has initialized the component's view.

It is useful when code needs access to view-related elements.

Example:

@ViewChild('input')
input!: ElementRef<HTMLInputElement>;

ngAfterViewInit() {
  this.input.nativeElement.focus();
}

The important concept is:

Component created
      ↓
Template rendered
      ↓
View initialized
      ↓
ngAfterViewInit

50. The Big Picture

If you want to understand DOM manipulation in Angular deeply, don't think about Angular as simply:

HTML + TypeScript

Instead, think:

Application State
       ↓
Angular Component
       ↓
Angular Template
       ↓
Bindings / Directives
       ↓
Angular Rendering System
       ↓
DOM
       ↓
Browser Rendering
       ↓
Pixels

When the state changes:

State Change
     ↓
Angular detects the relevant change
     ↓
View updates
     ↓
DOM changes
     ↓
Browser renders the result

This mental model is much more useful than thinking of Angular as a collection of DOM manipulation APIs.

Conclusion

The DOM is still the foundation of every Angular application's browser UI, but Angular gives developers a higher-level way to work with it.

The most important principles are:

Prefer Angular templates over manual DOM manipulation.
Use property, attribute, class, and style bindings whenever possible.
Use ViewChild when you need to access a specific element or component.
Use Renderer2 when you need programmatic DOM manipulation.
Use HostListener and HostBinding for reusable directive behavior.
Be careful with ElementRef.nativeElement.
Avoid unnecessary document.querySelector() usage.
Consider SSR and hydration when using browser APIs.
Avoid unsafe HTML manipulation and unnecessary sanitization bypasses.
Keep application state as the source of truth whenever possible.

The most important mindset is:

In Angular, don't ask "How do I manipulate this DOM element?" first. Ask "What state should my UI represent?"

Once you understand that distinction, Angular's rendering model, change detection, Signals, directives, lifecycle hooks, SSR, and DOM APIs become much easier to understand.

Building a Call Campaign Simulator with TypeScript

Abanoub Kerols — Wed, 02 Sep 2026 08:58:27 +0000

When building a system that manages automated phone campaigns, the problem is much more complicated than simply looping through a list of phone numbers and calling them.

A real campaign system needs to answer questions such as:

When is a customer allowed to be called?
How many calls can run simultaneously?
What happens when a call fails?
When should a failed call be retried?
How many minutes can we spend calling customers per day?
What happens when the campaign is paused?
How do we handle different timezones?
How can we test time-dependent behavior without waiting for real time?

This article explains how to design and implement a Call Campaign Simulator using TypeScript.

The goal is not only to implement the feature, but also to understand the software engineering concepts behind it.

1. What Is a Call Campaign Simulator?

A call campaign simulator receives a list of customers and attempts to call them according to a set of business rules.

For example:

Customers:
    555-0001
    555-0002
    555-0003
    555-0004

Working Hours:
    09:00 → 17:00

Maximum Concurrent Calls:
    3

Daily Call Limit:
    120 minutes

Maximum Retries:
    2

The system needs to coordinate all of these constraints.

Conceptually:

                 ┌────────────────────┐
                 │   Customer Queue   │
                 └─────────┬──────────┘
                           │
                           ▼
                 ┌────────────────────┐
                 │ Campaign Scheduler │
                 └─────────┬──────────┘
                           │
             ┌─────────────┼─────────────┐
             │             │             │
             ▼             ▼             ▼
          Call #1       Call #2       Call #3
             │             │             │
             └─────────────┼─────────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │ Call Result     │
                  └────────┬────────┘
                           │
                 ┌─────────┴─────────┐
                 │                   │
               Success              Failure
                 │                   │
                 ▼                   ▼
             Processed             Retry
                                     │
                                     ▼
                              Retry Scheduler

The important part is that the system is essentially a scheduler + state machine + concurrency controller.

2. Core Requirements

Our simulator supports the following features:

Sequential Processing

Customers are processed in the order they appear in the list.

[
  "555-0001",
  "555-0002",
  "555-0003"
]

The system should not randomly reorder customers.

Working Hours

Calls are only allowed during a configured time window.

Example:

09:00 → 17:00

If the current time is:

08:30

the campaign must wait.

If the current time is:

18:00

the campaign must also wait until the next valid working period.

Concurrency Control

Suppose:

maxConcurrentCalls = 3;

The system can have at most three active calls:

Call A → active
Call B → active
Call C → active

Call D → waiting
Call E → waiting

This is a classic concurrency limiting problem.

Daily Call Limit

Suppose:

maxDailyMinutes = 120;

The campaign cannot consume more than 120 minutes of call time during a calendar day.

For example:

Call 1 = 30 minutes
Call 2 = 40 minutes
Call 3 = 20 minutes
Call 4 = 30 minutes

Total:

30 + 40 + 20 + 30 = 120 minutes

The daily limit has been reached.

3. Why This Problem Is Interesting

At first glance, the implementation seems simple:

for (const customer of customers) {
    await call(customer);
}

But this ignores almost every important requirement.

We need to coordinate:

Time
   +
Concurrency
   +
Retries
   +
Daily Limits
   +
Pause / Resume
   +
Timezone
   +
State Management

This makes the problem a good example of asynchronous system design.

4. State Machine

One of the most important concepts in the project is the campaign state.

The campaign can have states such as:

type CampaignState =
  | "idle"
  | "running"
  | "paused"
  | "completed";

The state machine looks like:

             start()
                │
                ▼
             ┌───────┐
             │ idle  │
             └───┬───┘
                 │
                 ▼
             ┌─────────┐
       ┌────▶│ running │──────┐
       │     └────┬────┘      │
       │          │           │
    resume()   pause()     completed
       │          │           │
       │          ▼           ▼
       └──────┌────────┐   ┌───────────┐
              │ paused │   │ completed │
              └────────┘   └───────────┘

This is a Finite State Machine (FSM).

The important idea is that not every operation should be allowed from every state.

For example:

idle → start()       valid

running → pause()    valid

paused → resume()    valid

completed → resume() invalid

This prevents invalid transitions.

5. Data Model

The configuration can be represented using an interface.

export interface CampaignConfig {
  customerList: string[];

  startTime: string;
  endTime: string;

  maxConcurrentCalls: number;

  maxDailyMinutes: number;

  maxRetries?: number;

  retryDelayMs?: number;

  timezone?: string;
}

The configuration describes the rules of the campaign.

6. Call Handler

The campaign should not know how the actual call is performed.

Instead, we inject a function.

export type CallHandler = (
  phoneNumber: string
) => Promise<{
  answered: boolean;
  durationMs: number;
}>;

This is an important software design principle:

Separate business logic from infrastructure logic.

The Campaign class manages:

Scheduling
Concurrency
Retries
Limits
State

The CallHandler manages:

Actual call operation

This is similar to the Dependency Inversion Principle.

7. Why Dependency Injection Is Useful Here

Imagine we directly write:

class Campaign {
  async makeCall(phoneNumber: string) {
    // real telephony API
  }
}

Testing becomes difficult because every test would depend on the external telephony system.

Instead:

class Campaign {
  constructor(
    private callHandler: CallHandler
  ) {}
}

Now tests can inject:

const fakeCallHandler: CallHandler = async () => ({
  answered: true,
  durationMs: 5000
});

This gives us deterministic tests.

8. The Clock Abstraction

Time is another dependency.

A naive implementation might use:

Date.now();
setTimeout(...);
clearTimeout(...);

everywhere.

That makes testing time-dependent behavior difficult.

Instead, we define:

export interface IClock {
  now(): number;

  setTimeout(
    callback: () => void,
    delayMs: number
  ): number;

  clearTimeout(id: number): void;
}

The campaign now depends on an abstraction instead of directly depending on real system time.

9. Injected Clock

Production code can use the real clock:

const clock: IClock = {
  now: () => Date.now(),

  setTimeout: (callback, delayMs) =>
    setTimeout(callback, delayMs) as unknown as number,

  clearTimeout: (id) =>
    clearTimeout(id)
};

But tests can provide a fake clock.

For example:

class FakeClock implements IClock {
  private currentTime = 0;

  now(): number {
    return this.currentTime;
  }

  setTimeout(callback: () => void, delayMs: number): number {
    return 1;
  }

  clearTimeout(id: number): void {}
}

Now tests don't have to wait for real time.

10. Working Hours

Suppose:

startTime = "09:00";
endTime = "17:00";

We need to determine whether the current time is inside the allowed interval.

Conceptually:

function isWithinWorkingHours(
  currentTime: Date
): boolean {
  // convert current time to configured timezone

  // extract hours and minutes

  // compare against startTime and endTime
}

For example:

08:59 → false
09:00 → true
12:30 → true
16:59 → true
17:00 → false

Boundary conditions are important.

11. Waiting Until Working Hours

Suppose the campaign starts at:

07:30

and working hours are:

09:00 → 17:00

The campaign should not immediately call a customer.

Instead:

07:30
  │
  │ wait
  ▼
09:00
  │
  ▼
Start calling

The scheduler needs to calculate:

delay = nextWorkingStart - currentTime;

Then:

clock.setTimeout(
  () => processNext(),
  delay
);

12. Concurrency Control

Concurrency is one of the most important parts of the system.

Suppose:

maxConcurrentCalls = 2;

and we have:

Customer A
Customer B
Customer C
Customer D

The system should produce:

Time →

A ────────────────
B ──────────
C       ───────────────
D             ──────────

But never:

A ───────
B ───────
C ───────   ❌

because that would mean three simultaneous calls.

13. Concurrency Counter

A simple mechanism is:

private activeCalls = 0;

Before starting a call:

if (
  this.activeCalls >=
  this.config.maxConcurrentCalls
) {
  return;
}

When the call starts:

this.activeCalls++;

When it finishes:

this.activeCalls--;

This gives us a basic semaphore-like mechanism.

14. Semaphore Concept

A semaphore controls access to a limited resource.

If we have:

3 permits

then only three operations can execute simultaneously.

Initially:

Available permits = 3

Call A:

Available = 2

Call B:

Available = 1

Call C:

Available = 0

Call D:

WAIT

When A finishes:

Available = 1

D can now start.

This is exactly the type of resource management our campaign needs.

15. Daily Cap

Suppose:

maxDailyMinutes = 120;

We maintain:

private dailyMinutesUsed = 0;

When a call finishes:

const minutes =
  durationMs / 60000;

this.dailyMinutesUsed += minutes;

Before starting another call, we need to verify that the daily limit hasn't been reached.

16. Important Question: When Do We Count Call Minutes?

This is a business-rule decision.

Consider:

Remaining capacity = 5 minutes

and a call lasts:

10 minutes

There are several possible policies.

Policy A — Allow the call

Start the call and count the actual duration afterward.

Policy B — Reject the call

Don't start a call that could exceed the daily limit.

Policy C — Allow but cap accounting

Count only the remaining available minutes.

For a simulator, the cleanest approach is usually to clearly define the behavior in the requirements and implement it consistently.

This illustrates an important engineering principle:

Business rules should be explicit rather than hidden inside implementation details.

17. Daily Reset

The daily cap is not permanent.

For example:

Monday:
120 minutes used

Tuesday:
0 minutes used

So the system needs to know when a new calendar day begins.

This becomes more complicated when timezones are introduced.

18. Why Timezones Matter

Imagine:

timezone = "America/New_York";

The application server might actually be running in:

UTC

The campaign's business rules should still use:

New York time

For example:

Server:
14:00 UTC

New York:
10:00

If working hours are:

09:00 → 17:00

the call is allowed.

Therefore, we should never blindly use server-local time.

19. IANA Timezones

The project uses IANA timezone identifiers.

Examples:

America/New_York
Europe/London
Asia/Tokyo
Africa/Cairo

These identifiers allow the application to correctly interpret local time.

A library such as Luxon makes this easier.

Example:

import { DateTime } from "luxon";

const now = DateTime.now()
  .setZone("America/New_York");

console.log(now.toISO());

20. DST — Daylight Saving Time

Timezone handling becomes even more interesting with DST.

For example, some countries change their clocks during the year.

A hardcoded offset such as:

UTC-5

is therefore dangerous.

The correct approach is to use:

America/New_York

instead of manually calculating:

UTC - 5

The timezone database can determine the correct offset.

This is one reason timezone-aware libraries are useful.

21. Retry Logic

Calls can fail.

For example:

Customer A → success
Customer B → failed
Customer C → success

The system shouldn't necessarily permanently fail Customer B.

Instead:

Attempt 1
   │
   ▼
Failed
   │
   ▼
Wait
   │
   ▼
Attempt 2

If it fails again:

Attempt 2
   │
   ▼
Failed
   │
   ▼
Attempt 3

After the maximum retry count:

Permanently Failed

22. Retry Configuration

The configuration contains:

maxRetries: 2,
retryDelayMs: 3600000

This means the system can retry a failed call according to the configured retry policy.

The delay:

3600000 ms

equals:

1 hour

because:

1000 ms = 1 second

60 seconds = 1 minute

60 minutes = 1 hour

Therefore:

1000 × 60 × 60 = 3,600,000 ms

23. Retry Queue

Instead of immediately retrying:

await retry();

we can schedule it:

clock.setTimeout(
  () => retryCustomer(customer),
  retryDelayMs
);

The system can maintain:

private pendingRetries = 0;

When a retry is scheduled:

this.pendingRetries++;

When the retry starts:

this.pendingRetries--;

24. Exponential Backoff

A more advanced retry strategy is exponential backoff.

Instead of:

1 hour
1 hour
1 hour

we could use:

1 minute
2 minutes
4 minutes
8 minutes

The formula is:

delay =
  baseDelay * Math.pow(2, attempt);

For example:

attempt 0 → 1 minute
attempt 1 → 2 minutes
attempt 2 → 4 minutes
attempt 3 → 8 minutes

This is commonly used in distributed systems.

25. Pause and Resume

The campaign supports:

campaign.pause();

and:

campaign.resume();

The important business rule is:

Pausing the campaign does not necessarily cancel active calls.

For example:

Call A ────────────────► finishes
Call B ───────────► finishes

Campaign
         pause()
           │
           ▼
       PAUSED

Existing calls can finish while new calls should not be started.

26. Pause vs Cancellation

These concepts are different.

Pause

Stops starting new work.

Cancellation

Attempts to terminate existing work.

For example:

Pause:

Existing calls → continue
New calls      → blocked

Whereas cancellation could mean:

Existing calls → terminate if possible
New calls      → blocked

This distinction is important when designing asynchronous systems.

27. Campaign Status

The system exposes:

interface CampaignStatus {
  state:
    | "idle"
    | "running"
    | "paused"
    | "completed";

  totalProcessed: number;

  totalFailed: number;

  activeCalls: number;

  pendingRetries: number;

  dailyMinutesUsed: number;
}

This gives the outside world a snapshot of the campaign.

Example:

const status = campaign.getStatus();

console.log(status);

Possible output:

{
  state: "running",
  totalProcessed: 25,
  totalFailed: 2,
  activeCalls: 3,
  pendingRetries: 1,
  dailyMinutesUsed: 87.5
}

28. The Campaign Class

The central class can look conceptually like this:

export class Campaign {
  constructor(
    private config: CampaignConfig,
    private callHandler: CallHandler,
    private clock: IClock
  ) {}

  start(): void {
    // start campaign
  }

  pause(): void {
    // pause campaign
  }

  resume(): void {
    // resume campaign
  }

  getStatus(): CampaignStatus {
    // return campaign state
  }
}

This keeps the public API small.

29. Internal State

The campaign needs internal state such as:

private state: CampaignState = "idle";

private currentIndex = 0;

private activeCalls = 0;

private totalProcessed = 0;

private totalFailed = 0;

private pendingRetries = 0;

private dailyMinutesUsed = 0;

These variables represent the current state of the campaign.

30. Processing the Customer Queue

A basic processing function might look like:

private processNext(): void {
  if (this.state !== "running") {
    return;
  }

  if (
    this.activeCalls >=
    this.config.maxConcurrentCalls
  ) {
    return;
  }

  if (
    this.currentIndex >=
    this.config.customerList.length
  ) {
    this.checkCompletion();
    return;
  }

  const customer =
    this.config.customerList[
      this.currentIndex
    ];

  this.currentIndex++;

  this.executeCall(customer);
}

The important idea is that every condition acts as a gate.

31. The Scheduling Pipeline

Before starting a call, we conceptually check:

Is campaign running?
        │
        ▼
Are we inside working hours?
        │
        ▼
Is concurrency available?
        │
        ▼
Is daily capacity available?
        │
        ▼
Start call

This can be represented as:

                 ┌───────────────┐
                 │ Campaign      │
                 │ running?      │
                 └───────┬───────┘
                         │ yes
                         ▼
                 ┌───────────────┐
                 │ Working       │
                 │ hours?        │
                 └───────┬───────┘
                         │ yes
                         ▼
                 ┌───────────────┐
                 │ Concurrency   │
                 │ available?    │
                 └───────┬───────┘
                         │ yes
                         ▼
                 ┌───────────────┐
                 │ Daily cap     │
                 │ available?    │
                 └───────┬───────┘
                         │ yes
                         ▼
                    START CALL

This is effectively a scheduling decision tree.

32. Executing a Call

The call itself can be handled asynchronously:

private async executeCall(
  phoneNumber: string
): Promise<void> {
  this.activeCalls++;

  try {
    const result =
      await this.callHandler(phoneNumber);

    this.handleCallResult(
      phoneNumber,
      result
    );
  } finally {
    this.activeCalls--;
    this.processAvailableCalls();
  }
}

The finally block is particularly important.

Whether the call succeeds or fails:

this.activeCalls--;

must happen.

Otherwise the campaign could become permanently stuck.

33. Why `finally` Matters

Bad implementation:

try {
  await call();
  activeCalls--;
} catch {
  // activeCalls never decremented
}

If the call throws an exception:

activeCalls = 1

call throws

activeCalls stays 1

Eventually the system may believe that the concurrency limit has been reached forever.

Better:

try {
  await call();
} finally {
  activeCalls--;
}

This is a classic resource-cleanup pattern.

34. Handling Success

Suppose the call result is:

{
  answered: true,
  durationMs: 120000
}

We can calculate:

const minutes =
  durationMs / 60000;

Then:

this.dailyMinutesUsed += minutes;
this.totalProcessed++;

The customer is now considered successfully processed.

35. Handling Failure

Suppose:

{
  answered: false,
  durationMs: 5000
}

The business rule can decide that the call should be retried.

Conceptually:

if (attempt < maxRetries) {
  scheduleRetry();
} else {
  totalFailed++;
}

This creates two possible paths:

Failure
   │
   ├── retries remaining → Retry
   │
   └── no retries → Permanent failure

36. Attempt Tracking

Each customer needs retry information.

For example:

private retryAttempts =
  new Map<string, number>();

When a customer fails:

const attempts =
  this.retryAttempts.get(phoneNumber) ?? 0;

this.retryAttempts.set(
  phoneNumber,
  attempts + 1
);

This allows the system to know how many times a particular customer has already been attempted.

37. Important Design Question: Customer Identity

Using the phone number as a key is convenient:

Map<string, number>

But in a real system, phone numbers might not be unique or stable.

A production system would usually have:

customerId
phoneNumber

For example:

interface Customer {
  id: string;
  phoneNumber: string;
}

Then retry state can use:

Map<CustomerId, RetryState>

This is more robust.

38. Sequential Processing vs Concurrent Execution

The requirement says:

Process the customer list sequentially.

This does not necessarily mean:

await customer1;
await customer2;
await customer3;

because that would make concurrency impossible.

Instead, sequential processing usually means:

Customers are selected from the queue in order, while multiple selected calls may execute concurrently up to the configured limit.

For example:

Queue:

A
B
C
D
E

maxConcurrent = 2

A ──────────
B ─────────────

C       ─────────
D       ────────

E             ─────────

The selection order remains:

A → B → C → D → E

while execution overlaps.

This distinction is very important.

39. Completion Detection

The campaign should only become:

"completed"

when there is no more work.

That usually means:

Customer queue empty
+
Active calls = 0
+
Pending retries = 0

Therefore:

if (
  currentIndex >= customerList.length &&
  activeCalls === 0 &&
  pendingRetries === 0
) {
  state = "completed";
}

This avoids declaring completion too early.

40. Example Scenario

Consider:

const config: CampaignConfig = {
  customerList: [
    "555-0001",
    "555-0002",
    "555-0003",
    "555-0004"
  ],

  startTime: "09:00",

  endTime: "17:00",

  maxConcurrentCalls: 2,

  maxDailyMinutes: 60,

  maxRetries: 2,

  retryDelayMs: 60000,

  timezone: "America/New_York"
};

Suppose:

09:00

The campaign starts.

41. Initial Execution

Concurrency limit:

So:

Call 555-0001
Call 555-0002

are started.

The remaining customers wait:

555-0003
555-0004

42. First Call Finishes

Suppose:

555-0001
answered = true
duration = 10 minutes

Now:

dailyMinutesUsed = 10
activeCalls = 1

The scheduler can start:

555-0003

Now:

555-0002 → active
555-0003 → active

43. Failed Call

Suppose:

555-0002
answered = false

The system schedules a retry:

retry in 60 seconds

Status:

pendingRetries = 1

The campaign can continue processing other customers if capacity allows.

44. Retry

After the delay:

555-0002 → retry

If successful:

totalProcessed++

If it fails again:

attempt = 2

and the system checks whether another retry is allowed.

45. Daily Cap Reached

Suppose:

dailyMinutesUsed = 58

and a call finishes with:

duration = 5 minutes

Now:

dailyMinutesUsed = 63

The campaign has exceeded the configured limit if the system permits the call to finish.

At this point, the campaign should stop scheduling additional calls until the next applicable calendar day, according to the chosen business rule.

46. Why Luxon?

JavaScript's native Date API can become difficult to work with when implementing complex timezone behavior.

Luxon provides a cleaner API.

For example:

import { DateTime } from "luxon";

const now = DateTime.now()
  .setZone("Europe/London");

console.log(now.hour);
console.log(now.minute);

We can also calculate the start of the day:

const startOfDay =
  now.startOf("day");

And the next day:

const nextDay =
  now.plus({ days: 1 })
     .startOf("day");

This is useful for daily cap calculations.

47. Calendar Day vs 24 Hours

An important distinction:

Daily cap

usually means a calendar day, not:

rolling 24-hour window

For example:

Monday 23:50 → Tuesday 00:10

A calendar-day implementation treats these as different days.

A rolling-window implementation would treat them as part of the same 24-hour period.

The requirements explicitly describe:

maximum total call minutes per calendar day

Therefore the reset should happen at local midnight in the configured timezone.

48. Testing Time-Dependent Systems

One of the hardest things to test is code like:

setTimeout(() => {
  // retry after one hour
}, 3600000);

A normal test would have to wait one hour.

Obviously, that's unacceptable.

This is why dependency injection is so useful.

Instead of directly using:

Date.now()

we use:

clock.now()

Instead of:

setTimeout()

we use:

clock.setTimeout()

Now tests can control the clock.

49. Deterministic Testing

Suppose we want to test:

Retry after 1 hour

With a fake clock:

clock.advanceBy(60 * 60 * 1000);

We can simulate one hour instantly.

The test becomes:

Start
  ↓
Failure
  ↓
Schedule retry
  ↓
Advance clock 1 hour
  ↓
Retry executes

No real waiting is necessary.

This is an example of deterministic testing.

50. Testing Concurrency

We should test that:

activeCalls <= maxConcurrentCalls

at all times.

For:

maxConcurrentCalls = 3

we should never observe:

activeCalls = 4

A test can use a controlled call handler:

let active = 0;
let maximumObserved = 0;

const handler: CallHandler =
  async () => {
    active++;

    maximumObserved =
      Math.max(
        maximumObserved,
        active
      );

    // simulated work

    active--;

    return {
      answered: true,
      durationMs: 1000
    };
  };

Then assert:

expect(maximumObserved)
  .toBeLessThanOrEqual(3);

51. Testing Working Hours

Important test cases include:

08:59 → should not call
09:00 → should call
12:00 → should call
16:59 → should call
17:00 → should stop

Boundary conditions are often where scheduling bugs occur.

52. Testing Pause and Resume

Example:

Campaign starts
      ↓
Calls start
      ↓
pause()
      ↓
No new calls
      ↓
Active calls finish
      ↓
resume()
      ↓
New calls continue

The test should verify that pause does not accidentally create duplicate processing.

53. Testing Retries

A good retry test might simulate:

Attempt 1 → fail
Attempt 2 → fail
Attempt 3 → success

and verify:

totalProcessed === 1
totalFailed === 0

Another test:

Attempt 1 → fail
Attempt 2 → fail
Attempt 3 → fail

should produce:

totalProcessed === 0
totalFailed === 1

assuming the configured retry policy allows those attempts.

54. Testing Timezones

Timezone tests are particularly important.

For example:

Timezone:
America/New_York

Working hours:
09:00 → 17:00

The test should verify that UTC time is correctly converted into New York local time.

DST transition dates should also be tested.

This is one of the strongest reasons to abstract time and use a timezone-aware library.

55. A Complete Usage Example

The public API can remain simple:

import { Campaign } from "./solution";

import {
  IClock,
  CallHandler,
  CampaignConfig
} from "./interfaces";

const clock: IClock = {
  now: () => Date.now(),

  setTimeout: (callback, delayMs) =>
    setTimeout(
      callback,
      delayMs
    ) as unknown as number,

  clearTimeout: (id) =>
    clearTimeout(id)
};

const callHandler: CallHandler =
  async (phoneNumber) => {

    console.log(
      `Calling ${phoneNumber}`
    );

    return {
      answered:
        Math.random() > 0.2,

      durationMs:
        Math.random() * 600000
    };
  };

const config: CampaignConfig = {
  customerList: [
    "555-0001",
    "555-0002",
    "555-0003",
    "555-0004"
  ],

  startTime: "09:00",

  endTime: "17:00",

  maxConcurrentCalls: 3,

  maxDailyMinutes: 120,

  maxRetries: 2,

  retryDelayMs: 3600000,

  timezone: "America/New_York"
};

const campaign =
  new Campaign(
    config,
    callHandler,
    clock
  );

campaign.start();

Then we can inspect the status:

setInterval(() => {
  const status =
    campaign.getStatus();

  console.log({
    state: status.state,

    processed:
      status.totalProcessed,

    failed:
      status.totalFailed,

    activeCalls:
      status.activeCalls,

    pendingRetries:
      status.pendingRetries,

    dailyMinutes:
      status.dailyMinutesUsed
  });
}, 1000);

56. Architectural View

The project can be viewed as several logical components:

                    Campaign
                       │
       ┌───────────────┼────────────────┐
       │               │                │
       ▼               ▼                ▼
  Scheduler        Call Handler      State
       │               │                │
       ▼               ▼                ▼
 Working Hours      External API     Metrics
 Concurrency
 Daily Cap
 Retries
 Timezone

The Campaign orchestrates the system.

57. Separation of Concerns

A good implementation should avoid putting everything into one giant function.

Instead, separate responsibilities.

For example:

isWithinWorkingHours()

handles working hours.

getNextWorkingTime()

handles scheduling.

executeCall()

handles call execution.

scheduleRetry()

handles retries.

checkDailyLimit()

handles daily capacity.

checkCompletion()

handles completion.

This makes the code easier to understand and test.

58. Common Mistakes

Mistake 1 — Using `Promise.all()`

A naive implementation:

await Promise.all(
  customers.map(call)
);

can create hundreds or thousands of simultaneous calls.

That violates:

maxConcurrentCalls

Mistake 2 — Using Recursive Calls Without Guards

Something like:

processNext();

inside multiple asynchronous paths can accidentally create duplicate processing.

A scheduler should carefully control when the next task can start.

Mistake 3 — Forgetting `finally`

As discussed earlier:

activeCalls++;

must eventually be paired with:

activeCalls--;

even when an exception occurs.

Mistake 4 — Using Server Time for Business Rules

This is dangerous:

new Date();

without considering the configured campaign timezone.

Business time should be calculated using:

configured timezone

Mistake 5 — Treating Retry as a New Customer

A retry should not incorrectly increment:

totalProcessed

until the customer actually succeeds.

Retry attempts and successfully processed customers are different metrics.

59. Metrics vs Events

Another useful distinction is between:

Attempts

and:

Processed Customers

Suppose:

Customer A:
Attempt 1 → failed
Attempt 2 → failed
Attempt 3 → success

The system made:

3 attempts

but successfully processed:

1 customer

These should not be confused.

A production system might expose:

totalAttempts
totalProcessed
totalFailed

instead of only two counters.

60. What Happens if the Process Crashes?

The current simulator is primarily an in-memory system.

That means state such as:

currentIndex
activeCalls
dailyMinutesUsed
retryAttempts

can disappear if the Node.js process crashes.

A production campaign platform would need persistent state.

For example:

Campaign Service
       │
       ▼
   PostgreSQL
       │
       ├── campaigns
       ├── customers
       ├── call_attempts
       └── retry_jobs

Or possibly:

Redis

for short-lived scheduling state.

61. Production Architecture

A more advanced architecture could look like:

                    API
                     │
                     ▼
             Campaign Service
                     │
          ┌──────────┴──────────┐
          │                     │
          ▼                     ▼
      Database                Queue
                                │
                  ┌─────────────┼─────────────┐
                  │             │             │
                  ▼             ▼             ▼
               Worker        Worker        Worker
                  │             │             │
                  └─────────────┼─────────────┘
                                │
                                ▼
                         Telephony Provider

The simulator's concurrency limit becomes a distributed worker problem.

62. Queue-Based Architecture

For a real system, instead of keeping all work inside one process, we could use a message queue.

For example:

Campaign
   │
   ▼
Queue
   │
   ├── Job 1
   ├── Job 2
   ├── Job 3
   └── Job 4

Workers consume jobs.

Concurrency can then be controlled by:

Number of workers
+
Per-worker concurrency

This architecture scales much better.

63. Idempotency

Distributed systems introduce another important problem:

What happens if the same call job is processed twice?

For example:

Worker A:
starts call

Network failure

Queue thinks job failed

Worker B:
starts same job

Now the customer might receive two calls.

A production system therefore needs an idempotency strategy.

For example:

idempotencyKey =
  `${campaignId}:${customerId}:${attempt}`;

Before starting the call, the system can check whether that attempt was already executed.

64. Race Conditions

Concurrency introduces race conditions.

Consider:

Daily limit remaining:
5 minutes

Two workers check simultaneously:

Worker A → sees 5 minutes
Worker B → sees 5 minutes

Both decide:

Allowed

Then both consume:

5 minutes

Now the system has exceeded its intended capacity.

This is a classic check-then-act race condition.

A production system would need synchronization, transactions, atomic operations, or another coordination mechanism.

65. Why the Simulator Is Valuable

Although this project is called a simulator, it demonstrates several real backend concepts:

Async Programming
Concurrency
Scheduling
State Machines
Dependency Injection
Retry Strategies
Resource Limits
Timezones
Testing
Race Conditions
Queue Processing
Fault Tolerance

These are not merely theoretical concepts.

They appear in:

Job schedulers
Email systems
Payment processing
Notification services
Data pipelines
Background workers
Distributed systems
Call centers
IoT platforms

66. Complexity

Suppose there are:

N customers

Each customer is processed a finite number of times based on retry configuration.

If:

R = maximum retries

the maximum number of attempts is approximately:

N × (R + 1)

For example:

100 customers
2 retries

Maximum attempts:

100 × 3 = 300

The scheduler therefore needs to handle potentially much more work than the number of customers.

67. Memory Complexity

If we maintain retry state for each customer:

Map<CustomerId, RetryState>

the memory requirement is approximately:

O(N)

where N is the number of customers.

Other queues and state structures may also contribute to memory usage.

68. Concurrency Complexity

The system limits active calls to:

where:

C = maxConcurrentCalls

Therefore the number of simultaneously active operations is bounded by:

O(C)

rather than:

O(N)

This is one of the primary purposes of the concurrency control mechanism.

69. Key Design Principles

This project demonstrates several important principles.

Single Responsibility

Each part of the system should have one main responsibility.

Dependency Inversion

Depend on:

IClock
CallHandler

rather than concrete implementations.

Separation of Concerns

Scheduling logic should not be mixed with call-provider implementation.

Explicit State

Campaign state should be represented explicitly.

Deterministic Testing

Inject time and external dependencies.

Defensive Resource Management

Always release resources using patterns such as:

finally

70. Complete Mental Model

The easiest way to understand the entire system is:

                CUSTOMER LIST
                      │
                      ▼
                QUEUE / INDEX
                      │
                      ▼
              ┌───────────────┐
              │   Scheduler   │
              └───────┬───────┘
                      │
          ┌───────────┼───────────┐
          │           │           │
          ▼           ▼           ▼
       Time        Capacity     State
          │           │           │
          └───────────┼───────────┘
                      │
                      ▼
                 CALL HANDLER
                      │
             ┌────────┴────────┐
             │                 │
          Success            Failure
             │                 │
             ▼                 ▼
        Update stats        Retry?
             │                 │
             │          ┌──────┴──────┐
             │          │             │
             │         Yes            No
             │          │             │
             │          ▼             ▼
             │       Schedule       Failed
             │        retry
             │          │
             └──────────┴─────────────┐
                                      │
                                      ▼
                              Check Completion
                                      │
                                      ▼
                                  COMPLETED

71. Final Takeaways

Building a call campaign simulator is a great exercise because it looks simple but contains many real-world backend problems.

The main lessons are:

1. Concurrency must be controlled

Don't start unlimited asynchronous operations.

maxConcurrentCalls

defines the resource boundary.

2. Time should be abstracted

Instead of tightly coupling the application to:

Date.now()
setTimeout()

inject a clock.

3. Timezones are business logic

Working hours and daily limits should be evaluated in the campaign's configured timezone.

4. Retries need explicit policies

A retry system should define:

maximum attempts
delay
backoff strategy
permanent failure behavior

5. State machines simplify lifecycle management

Explicit states such as:

idle
running
paused
completed

make the campaign's behavior predictable.

6. Testing asynchronous systems requires control

Injected clocks and fake call handlers allow tests to run quickly and deterministically.

7. In-memory solutions are different from production systems

A simulator can keep state in memory.

A production system usually needs:

Database
Queue
Workers
Idempotency
Transactions
Distributed locking
Monitoring

Conclusion

The Call Campaign Simulator is more than a TypeScript exercise.

It is a compact example of how backend systems coordinate:

Time
+
Concurrency
+
Retries
+
Resource Limits
+
State
+
External Dependencies

The most important lesson is that asynchronous programming is not only about using async and await.

Real asynchronous systems require coordination.

You need to answer:

Who is allowed to execute?

When are they allowed to execute?

How many can execute simultaneously?

What happens when execution fails?

What happens when time changes?

What happens when the process pauses?

How do we know the system has actually completed?

Once you start thinking about these questions, the problem moves from simply writing code to designing a reliable system.

And that's exactly why this type of task is valuable for understanding backend engineering and distributed-system concepts.

Source Code

Interested in exploring the implementation?

👉 View the complete Call Campaign Simulator on GitHub

The repository contains the complete TypeScript implementation, including concurrency control, retry logic, scheduling, daily limits, timezone support, and an injected clock for testability.

Delivery Slot Allocation: Designing a Safe and Concurrent Booking System

Abanoub Kerols — Mon, 31 Aug 2026 07:33:45 +0000

When building an e-commerce, food delivery, logistics, or appointment-booking system, one common problem appears again and again:

How can we allocate a limited resource to multiple customers without overbooking it?

A delivery slot is a perfect example of a shared resource.

Imagine that a delivery slot can handle only 5 orders:

10:00 - 12:00
Capacity: 5
Booked: 4

There is only one remaining position.

If two customers try to book the slot at exactly the same time, our backend must guarantee that only one of them gets the final position.

This article explains how to design such a system using:

Capacity management
Availability checking
Atomic database operations
Race-condition prevention
Alternative slot selection
Transactions and rollback
Concurrent request handling
Idempotency
Error handling

1. Understanding the Problem

Let's start with the delivery slot model.

A slot contains:

Slot
├── id
├── startTime
├── endTime
├── capacity
└── bookedCount

For example:

Slot ID: SLOT_01
Start: 10:00
End: 12:00
Capacity: 5
Booked Count: 3

The fundamental availability rule is:

bookedCount < capacity

Therefore:

3 < 5 → Available

But:

5 < 5 → False

So the slot is fully booked.

2. The Booking Request

A customer might send:

{
  "customerId": "C001",
  "orderId": "O001",
  "preferredSlotId": "SLOT_01"
}

The backend needs to:

Validate the request.
Find the requested slot.
Check availability.
Reserve capacity.
Create the reservation.
Return a confirmation.

The basic flow is:

Client
   |
   v
Validate Request
   |
   v
Find Slot
   |
   v
Check Availability
   |
   v
Reserve Capacity
   |
   v
Create Reservation
   |
   v
Return Confirmation

3. Why a Simple Availability Check Is Not Enough

A naive implementation might look like this:

const slot = await Slot.findById(slotId);

if (slot.bookedCount >= slot.capacity) {
    throw new Error("Slot is full");
}

slot.bookedCount += 1;

await slot.save();

At first glance, this looks correct.

But there is a serious concurrency problem.

4. The Race Condition Problem

Suppose we have:

Capacity = 5
Booked = 4

There is only one available position.

Now two requests arrive almost simultaneously:

Customer A
Customer B

The operations could happen like this:

Customer A → READ → bookedCount = 4
Customer B → READ → bookedCount = 4

Customer A → available
Customer B → available

Customer A → bookedCount = 5
Customer B → bookedCount = 6

Now we have:

Capacity = 5
Booked = 6

This is overbooking.

The problem isn't the availability condition itself.

The problem is that:

CHECK

and

UPDATE

are separate operations.

Between the check and the update, another request can modify the data.

This is called a:

Race Condition

5. What Is a Race Condition?

A race condition occurs when the result of an operation depends on the timing or ordering of concurrent operations.

In our case:

Request A
   |
   | Check availability
   |
   |--------+
            |
Request B   |
   |        |
   | Check  |
   |        |
   | Update |
   |        |
   |--------+
   |
   | Update

Both requests saw the same state.

That's why simply checking:

if (bookedCount < capacity)

is not enough.

We need to make the critical operation atomic.

6. Atomic Operations

An atomic operation is an operation that happens as one indivisible unit.

For our problem, we want the database to perform:

Check:

bookedCount < capacity

AND

Increment:

bookedCount = bookedCount + 1

as one operation.

Conceptually:

UPDATE delivery_slots
SET booked_count = booked_count + 1
WHERE id = ?
AND booked_count < capacity;

The important part is:

WHERE booked_count < capacity

The database itself decides whether capacity is still available.

7. Why Atomic Updates Solve the Problem

Consider:

Capacity = 5
Booked = 4

Two customers attempt to reserve the last position.

Request A executes:

UPDATE delivery_slots
SET booked_count = booked_count + 1
WHERE id = 'SLOT_01'
AND booked_count < capacity;

The condition is true.

The database updates:

Booked = 5

Now Request B executes the same operation.

The condition becomes:

5 < 5

which is false.

Therefore:

Rows affected = 0

Request B knows that the slot is no longer available.

The final state remains:

Capacity = 5
Booked = 5

No overbooking occurs.

8. A Generic Reservation Algorithm

The core algorithm can be represented as:

FUNCTION reserveSlot(slotId):

    UPDATE slot
    WHERE id = slotId
    AND bookedCount < capacity

    SET bookedCount = bookedCount + 1

    IF no row was updated:
        RETURN "Slot unavailable"

    RETURN "Slot reserved"

The database becomes responsible for enforcing the capacity condition.

9. Implementing It With Node.js

Let's assume we are using Node.js with a SQL database.

A repository method could look like:

async function reserveSlot(slotId) {
    const result = await db.query(
        `
        UPDATE delivery_slots
        SET booked_count = booked_count + 1
        WHERE id = ?
        AND booked_count < capacity
        `,
        [slotId]
    );

    return result.affectedRows === 1;
}

Now:

const reserved = await reserveSlot(slotId);

if (!reserved) {
    return {
        success: false,
        message: "Slot is no longer available"
    };
}

This is much safer than:

SELECT → check → UPDATE

10. The Complete Booking Service

A service layer can coordinate the entire process.

async function bookDeliverySlot({
    customerId,
    orderId,
    preferredSlotId
}) {

    if (!customerId) {
        throw new Error("Customer ID is required");
    }

    if (!orderId) {
        throw new Error("Order ID is required");
    }

    if (!preferredSlotId) {
        throw new Error("Preferred slot ID is required");
    }

    const slot = await findSlotById(preferredSlotId);

    if (!slot) {
        throw new Error("Delivery slot not found");
    }

    const reserved = await reserveSlot(preferredSlotId);

    if (!reserved) {

        const alternatives =
            await findAvailableAlternativeSlots(
                preferredSlotId
            );

        return {
            success: false,
            message: "The selected delivery slot is unavailable",
            alternatives
        };
    }

    const reservation = await createReservation({
        customerId,
        orderId,
        slotId: preferredSlotId
    });

    return {
        success: true,
        message: "Delivery slot booked successfully",
        reservation
    };
}

However, there is another important problem.

11. What Happens If Reservation Creation Fails?

Imagine this sequence:

1. Increment bookedCount
2. Create reservation

The database state becomes:

bookedCount = 5

But then:

createReservation()

fails.

Now the system says:

Booked = 5

even though the customer doesn't actually have a reservation.

We have consumed capacity without creating the booking.

This creates an inconsistent state.

12. Transactions

This is where a database transaction becomes useful.

We want:

Reserve slot
      +
Create reservation

to behave as one logical operation.

Either:

Both succeed

or:

Both fail

Conceptually:

BEGIN TRANSACTION

    Reserve slot

    Create reservation

COMMIT

If something fails:

BEGIN TRANSACTION

    Reserve slot

    Create reservation ❌

ROLLBACK

The rollback restores the previous state.

13. Transaction-Based Implementation

A simplified SQL-style implementation:

async function bookDeliverySlot({
    customerId,
    orderId,
    preferredSlotId
}) {

    const transaction = await db.beginTransaction();

    try {

        const slot = await findSlotById(
            preferredSlotId,
            transaction
        );

        if (!slot) {
            throw new Error("Delivery slot not found");
        }

        const result = await transaction.query(
            `
            UPDATE delivery_slots
            SET booked_count = booked_count + 1
            WHERE id = ?
            AND booked_count < capacity
            `,
            [preferredSlotId]
        );

        if (result.affectedRows === 0) {

            await transaction.rollback();

            const alternatives =
                await findAvailableAlternativeSlots(
                    preferredSlotId
                );

            return {
                success: false,
                message: "The selected delivery slot is unavailable",
                alternatives
            };
        }

        const reservation =
            await createReservation(
                {
                    customerId,
                    orderId,
                    slotId: preferredSlotId
                },
                transaction
            );

        await transaction.commit();

        return {
            success: true,
            message: "Delivery slot booked successfully",
            reservation
        };

    } catch (error) {

        await transaction.rollback();

        throw error;
    }
}

The exact transaction API depends on the database driver or ORM.

14. Finding Alternative Slots

A good booking system shouldn't simply tell the customer:

Slot unavailable.

It can improve the user experience by suggesting alternatives.

For example:

Requested:
12:00 - 14:00

Alternatives:

10:00 - 12:00
14:00 - 16:00
16:00 - 18:00

The query could be conceptually:

SELECT *
FROM delivery_slots
WHERE id != ?
AND booked_count < capacity
AND start_time > CURRENT_TIMESTAMP
ORDER BY start_time;

15. Ranking Alternative Slots

Not every available slot is equally useful.

We could rank alternatives according to:

Option 1 — Closest time

Requested: 12:00

10:00
14:00
16:00
18:00

Option 2 — Earliest available

Option 3 — Business priority

For example:

Same day
↓
Nearest time
↓
Lowest delivery cost

The business rules determine the sorting strategy.

16. Alternative Slot Function

A simple implementation:

async function findAvailableAlternativeSlots(
    preferredSlotId
) {

    const preferredSlot =
        await findSlotById(preferredSlotId);

    if (!preferredSlot) {
        return [];
    }

    return await Slot.find({
        _id: {
            $ne: preferredSlotId
        },
        bookedCount: {
            $lt: "$capacity"
        },
        startTime: {
            $gt: new Date()
        }
    }).sort({
        startTime: 1
    });
}

The exact syntax depends on the database.

For SQL databases, the equivalent condition would typically be:

booked_count < capacity

17. MongoDB Version

If the backend uses MongoDB, the same principle can be implemented with a conditional atomic update.

For example:

const slot = await DeliverySlot.findOneAndUpdate(
    {
        _id: slotId,
        $expr: {
            $lt: ["$bookedCount", "$capacity"]
        }
    },
    {
        $inc: {
            bookedCount: 1
        }
    },
    {
        new: true
    }
);

The important part is:

$expr: {
    $lt: ["$bookedCount", "$capacity"]
}

combined with:

$inc: {
    bookedCount: 1
}

The operation is performed atomically for the document.

If the result is:

null

the slot could not be reserved.

18. Handling Concurrent Requests With MongoDB

Suppose:

Capacity = 5
Booked = 4

Two requests execute:

findOneAndUpdate(...)

Request A succeeds:

Booked = 5

Request B evaluates:

5 < 5

which is false.

Therefore:

slot === null

Request B can then search for alternatives.

This protects the shared resource from overbooking.

19. The Complete Flow

The complete system can be represented as:

                    Customer
                       |
                       v
                Booking Request
                       |
                       v
                Validate Input
                       |
             +---------+---------+
             |                   |
          Invalid              Valid
             |                   |
             v                   v
        Return Error       Find Requested Slot
                                 |
                         +-------+-------+
                         |               |
                      Not Found        Found
                         |               |
                         v               v
                   Return Error    Attempt Atomic
                                    Reservation
                                         |
                              +----------+----------+
                              |                     |
                           Success                Failed
                              |                     |
                              v                     v
                       Create Booking       Find Alternatives
                              |                     |
                              v              +------+------+
                           Commit            |             |
                              |           Found          None
                              v             |             |
                          Success           v             v
                                     Return Options   Return Error

20. API Design

A REST API might expose:

POST /api/delivery-slots/book

Request:

{
  "customerId": "C001",
  "orderId": "O001",
  "preferredSlotId": "SLOT_01"
}

Successful response:

{
  "success": true,
  "message": "Delivery slot booked successfully",
  "reservation": {
    "id": "RES_001",
    "slotId": "SLOT_01",
    "customerId": "C001",
    "orderId": "O001"
  }
}

If the slot becomes unavailable:

{
  "success": false,
  "message": "The selected delivery slot is unavailable",
  "alternatives": [
    {
      "id": "SLOT_02",
      "startTime": "14:00",
      "endTime": "16:00"
    },
    {
      "id": "SLOT_03",
      "startTime": "16:00",
      "endTime": "18:00"
    }
  ]
}

21. HTTP Status Codes

The API can also use appropriate HTTP status codes.

For successful booking:

201 Created

Invalid request:

400 Bad Request

Unknown slot:

404 Not Found

Slot unavailable:

409 Conflict

Server/database failure:

500 Internal Server Error

Using:

409 Conflict

for an unavailable shared resource is particularly useful because the request itself can be valid while the resource state has changed.

22. Idempotency

There is another important issue.

Imagine the customer clicks:

Book

and the request succeeds.

But the network is slow.

The frontend doesn't receive the response.

The customer clicks again.

Now the backend receives:

Request 1
Request 2

Both may attempt to reserve capacity.

This can create duplicate reservations.

A common solution is an idempotency key.

For example:

Idempotency-Key: 8d7f9c21

The backend stores the result associated with that key.

If the same request arrives again:

Same Idempotency Key
        |
        v
Existing result?
        |
       Yes
        |
        v
Return previous result

Instead of creating another reservation.

23. Database Constraints

Application logic should not be the only protection.

The database should also enforce important invariants where possible.

For example, we want:

bookedCount <= capacity

The exact constraint strategy depends on the database.

This leads to an important backend principle:

Business-critical invariants should be protected as close to the data as practical.

The application controls the workflow, while the database protects data integrity.

24. Why "Read Then Write" Is Dangerous

This pattern is common:

const slot = await getSlot();

if (slot.bookedCount < slot.capacity) {

    slot.bookedCount++;

    await updateSlot(slot);
}

It looks reasonable, but under concurrency it becomes:

READ
  ↓
CHECK
  ↓
WAIT
  ↓
WRITE

Another request can modify the resource during that window.

A safer pattern is:

CONDITIONAL UPDATE

For example:

UPDATE delivery_slots
SET booked_count = booked_count + 1
WHERE id = ?
AND booked_count < capacity;

This moves the critical decision into the database operation itself.

25. Edge Cases

A production-ready implementation should consider more than the happy path.

Missing customer

Customer ID is required

Missing order

Order ID is required

Missing slot

Preferred slot ID is required

Unknown slot

Delivery slot not found

Full slot

Find alternatives

No alternatives

No available delivery slots

Concurrent booking

Use atomic reservation

Reservation creation failure

Rollback transaction

Duplicate booking

Use idempotency / unique constraints

Slot in the past

The system should reject expired slots:

startTime <= currentTime

Cancelled reservation

If a customer cancels:

bookedCount = bookedCount - 1

This operation should also be performed safely.

26. Cancellation

Booking isn't the only operation that affects capacity.

Suppose:

Capacity = 5
Booked = 5

A customer cancels.

We need:

Booked = 4

A safe operation could be:

UPDATE delivery_slots
SET booked_count = booked_count - 1
WHERE id = ?
AND booked_count > 0;

Again, the condition protects the invariant:

bookedCount >= 0

27. Testing Concurrent Booking

Concurrency should not only be discussed theoretically.

It should also be tested.

Suppose:

Capacity = 100
Booked = 99

Send:

10 concurrent requests

Expected result:

1 successful reservation
9 rejected requests

The final state must be:

Capacity = 100
Booked = 100

Never:

Booked = 101

A conceptual test:

const requests = Array.from(
    { length: 10 },
    (_, index) =>
        bookDeliverySlot({
            customerId: `C${index}`,
            orderId: `O${index}`,
            preferredSlotId: "SLOT_01"
        })
);

const results = await Promise.allSettled(requests);

const successfulBookings =
    results.filter(
        result =>
            result.status === "fulfilled" &&
            result.value.success
    );

console.log(
    successfulBookings.length
);

For a slot with one remaining position, the expected successful booking count is:

28. Important Architecture Principle

This problem demonstrates an important backend concept:

A delivery slot is not just a database record. It is a shared, limited resource.

Whenever multiple requests can consume the same limited resource, we need to think about:

Concurrency
+
Consistency
+
Atomicity
+
Data Integrity

The same concepts appear in:

Inventory systems
Seat booking
Hotel rooms
Appointment scheduling
Warehouse capacity
Payment processing
Ticket booking
Restaurant reservations
Rate-limit counters

The resource changes, but the concurrency problem remains similar.

29. A Better Production Architecture

A production system might separate responsibilities into layers:

Controller
    |
    v
Booking Service
    |
    v
Slot Repository
    |
    v
Database

Controller

Responsible for:

HTTP request
HTTP response
Input extraction

Service

Responsible for:

Business rules
Booking workflow
Alternative selection
Transactions

Repository

Responsible for:

Database queries
Atomic updates
Persistence

This separation makes the system easier to test and maintain.

30. Example Service Architecture

class DeliverySlotService {

    async book({
        customerId,
        orderId,
        preferredSlotId
    }) {

        this.validateRequest({
            customerId,
            orderId,
            preferredSlotId
        });

        const slot =
            await this.slotRepository.findById(
                preferredSlotId
            );

        if (!slot) {
            throw new Error(
                "Delivery slot not found"
            );
        }

        const reservation =
            await this.slotRepository.reserve(
                preferredSlotId,
                customerId,
                orderId
            );

        if (!reservation) {

            const alternatives =
                await this.slotRepository
                    .findAlternatives(
                        preferredSlotId
                    );

            return {
                success: false,
                alternatives
            };
        }

        return {
            success: true,
            reservation
        };
    }
}

The service doesn't need to know the details of SQL or MongoDB.

That's the responsibility of the repository.

31. Key Lessons

The most important lessons from delivery-slot allocation are:

1. Checking availability isn't enough

This:

if (bookedCount < capacity)

doesn't guarantee safe booking under concurrency.

2. Protect the critical section

Use an atomic operation:

UPDATE ...
WHERE booked_count < capacity

3. Use transactions when multiple changes must succeed together

For example:

Reserve capacity
+
Create reservation

4. Handle concurrency explicitly

Assume that multiple users can request the same resource simultaneously.

Don't design the system as if requests are processed one at a time.

5. Provide alternatives

A failed booking doesn't have to mean a bad user experience.

Return useful alternatives.

6. Protect against duplicate requests

Idempotency is important for booking and payment-like operations.

7. Test the race condition

Concurrency bugs often don't appear during normal testing.

Stress the critical operation with simultaneous requests.

32. Final Implementation Strategy

The complete strategy can be summarized as:

Receive Request
       ↓
Validate Input
       ↓
Find Slot
       ↓
Is Slot Valid?
   ↓           ↓
 No           Yes
 ↓             ↓
Error     Atomic Reservation
               ↓
       Reservation Successful?
          ↓             ↓
         No            Yes
         ↓              ↓
 Find Alternatives   Create Reservation
         ↓              ↓
    Return Result    Commit Transaction
                         ↓
                    Booking Success

The core invariant is:

bookedCount <= capacity

And the critical rule is:

Do not separate the availability check
from the capacity update when concurrency matters.

Instead of:

READ
 ↓
CHECK
 ↓
UPDATE

prefer:

CONDITIONAL ATOMIC UPDATE

For example:

UPDATE delivery_slots
SET booked_count = booked_count + 1
WHERE id = ?
AND booked_count < capacity;

Then combine the reservation creation with a transaction when both operations must remain consistent.

Conclusion

Delivery slot allocation may initially look like a simple CRUD operation:

Find slot
→ Check capacity
→ Increment booked count

But once multiple customers can access the same slot concurrently, the problem becomes a concurrency and data-consistency problem.

A robust implementation therefore needs:

Validation
+
Atomic operations
+
Transactions
+
Concurrency control
+
Alternative slots
+
Idempotency
+
Database integrity

The most important principle is simple:

When multiple requests compete for a limited shared resource, the operation that consumes that resource must be concurrency-safe.

This principle goes far beyond delivery slots. It is one of the fundamental ideas behind reliable backend systems.

JavaScript Closures — Part 3 (Engine Internals, Memory Management & Professional Patterns)

Abanoub Kerols — Wed, 26 Aug 2026 06:46:51 +0000

At this point, you already know what closures are and how they work.

Now it's time to understand how the JavaScript engine actually implements closures internally.

This is the level of understanding expected from Senior JavaScript Engineers.

How JavaScript Stores Variables

Whenever JavaScript executes your program, it creates something called an Execution Context.

Each execution context contains several internal components.

Conceptually, it looks like this:

Execution Context

├── Variable Environment
│     ├── count
│     ├── user
│     └── total
│
├── Lexical Environment
│
├── Scope Chain
│
└── this

The important parts for closures are:

Variable Environment
Lexical Environment

What is the Lexical Environment?

A Lexical Environment is an internal data structure used by the JavaScript engine.

Think of it as a dictionary that stores variables.

Example:

function outer() {

    let name = "John";

    let age = 30;

}

Internally, JavaScript stores something conceptually like this:

Lexical Environment

name → "John"

age → 30

Every function gets its own Lexical Environment.

Environment Records

The Lexical Environment itself contains another structure called the Environment Record.

Conceptually:

Lexical Environment

↓

Environment Record

↓

Variables

Example:

function user() {

    let firstName = "John";

    let lastName = "Doe";

}

Environment Record

firstName → John

lastName → Doe

Every variable declared with:

let
const
var
function
class

is stored here.

The Outer Environment Reference

Closures exist because every Lexical Environment keeps a reference to its parent.

Imagine this code.

let country = "Egypt";

function outer() {

    let city = "Cairo";

    function inner() {

        console.log(country);

        console.log(city);

    }

}

Internally

Global Environment

↓

country

↓

Outer Environment

↓

city

↓

Inner Environment

The inner function knows where its parent environment lives.

This relationship forms the Scope Chain.

The Hidden [[Environment]] Property

Every JavaScript function has an internal hidden property.

It isn't accessible from your code.

Conceptually:

Function

↓

[[Environment]]

↓

Lexical Environment

Example

function outer() {

    let score = 50;

    return function () {

        console.log(score);

    };

}

When the inner function is created...

JavaScript stores something like:

Inner Function

↓

[[Environment]]

↓

Outer Lexical Environment

That hidden reference is what makes closures possible.

Step-by-Step Closure Creation

Consider:

function createCounter() {

    let count = 0;

    return function () {

        count++;

        return count;

    };

}

Step 1

createCounter() executes

JavaScript creates:

Execution Context

↓

count = 0

Step 2

The inner function is created.

It secretly stores

[[Environment]]

↓

count

Step 3

The outer function finishes.

Normally:

Variables

↓

Destroyed

But...

JavaScript detects that another function still references them.

Instead of deleting them...

It preserves them.

Step 4

Whenever we call

counter();

The function accesses

count

through its closure.

Why Variables Don't Disappear

Normally:

function test() {

    let x = 10;

}

After execution

x

↓

Garbage Collection

Now compare

function test() {

    let x = 10;

    return function () {

        console.log(x);

    };

}

Now

Returned Function

↓

References x

↓

Garbage Collector

↓

Cannot delete x

Because it is still being used.

Closures and the Garbage Collector

JavaScript uses automatic memory management.

Objects are removed only when nothing references them.

Example

function createUser() {

    let name = "Alice";

    return function () {

        console.log(name);

    };

}

As long as the returned function exists...

The variable

name

cannot be removed.

Once the returned function becomes unreachable...

Everything becomes eligible for garbage collection.

Visualizing Memory

Before

const user = createUser();

Memory

Global

↓

user

↓

Closure

↓

name = Alice

Later

user = null;

Now

Nothing references Closure

Garbage Collector removes everything.

Memory Leaks

Closures themselves are not memory leaks.

The leak happens when we unintentionally keep references alive.

Bad Example

function createHugeArray() {

    const data = new Array(1000000).fill("JavaScript");

    return function () {

        console.log(data.length);

    };

}

Even if we only need the array length...

The entire array remains in memory.

Better

function createHugeArray() {

    const length = new Array(1000000).fill("JS").length;

    return function () {

        return length;

    };

}

Only a number is preserved.

Memory usage becomes much smaller.

Closures and Async Code

Closures become even more important with asynchronous JavaScript.

function fetchUser() {

    let username = "John";

    Promise.resolve().then(function () {

        console.log(username);

    });

}

fetchUser();

Output

John

The Promise callback remembers username.

Closures with async/await

async function loadUser() {

    let id = 10;

    await Promise.resolve();

    console.log(id);

}

loadUser();

Even after the function pauses...

The variables remain available.

The execution context is suspended—not destroyed.

Closures and Higher-Order Functions

A Higher-Order Function either:

accepts another function
returns another function

Closures make this possible.

Example

function multiply(multiplier) {

    return function (number) {

        return multiplier * number;

    };

}

Usage

const double = multiply(2);

const triple = multiply(3);

console.log(double(8));

console.log(triple(8));

Output

16

24

Each returned function owns its own closure.

Currying with Closures

Currying transforms

f(a, b)

into

f(a)(b)

Example

function add(a) {

    return function (b) {

        return a + b;

    };

}

Usage

const addFive = add(5);

console.log(addFive(10));

Output

The value

is preserved by the closure.

Partial Application

Partial Application is closely related.

function calculateTax(rate) {

    return function (price) {

        return price * rate;

    };

}

Usage

const egyptTax = calculateTax(0.14);

console.log(egyptTax(1000));

Output

Very common in Functional Programming.

Dependency Injection Using Closures

Instead of relying on global variables:

const logger = console.log;

Inject dependencies.

function createService(logger) {

    return {

        save(data) {

            logger(data);

        }

    };

}

The logger becomes private.

Testing becomes much easier.

Common Interview Question

What will this print?

function outer() {

    let x = 5;

    return function () {

        console.log(x);

    };

}

const fn = outer();

fn();

Answer

Why?

Because the returned function closes over x.

Another Interview Question

function outer() {

    let x = 10;

    return {

        increment() {

            x++;

        },

        get() {

            return x;

        }

    };

}

const obj = outer();

obj.increment();

obj.increment();

console.log(obj.get());

Output

Both methods share the same closure.

There is only one variable x.

Professional Uses of Closures

Closures power countless production-grade patterns, including:

React Hooks (useState, useMemo, useCallback)
Express Middleware
Redux Middleware
Authentication Wrappers
Logging Utilities
Rate Limiters
Debounce & Throttle Functions
Memoization
Dependency Injection
Function Factories
Plugin Systems
State Management Libraries
Encapsulation and Data Privacy

Understanding closures deeply helps you understand why these tools work the way they do.

Best Practices

✅ Use closures for encapsulation

Keep internal state private and expose only the operations you need.

✅ Prefer `let` and `const`

Modern JavaScript avoids many closure-related bugs that were common with var.

✅ Avoid capturing unnecessary objects

A closure keeps everything it references alive.

Capture only the data you actually need.

✅ Be mindful of memory

Closures are lightweight, but retaining large objects unnecessarily can increase memory usage.

✅ Use closures intentionally

Closures are a powerful abstraction—not just a language feature. They allow you to build cleaner APIs, isolate state, and create reusable behavior without relying on global variables.

Final Thoughts

Closures are one of the defining features of JavaScript.

They are not a trick, nor are they limited to interview questions.

They are a fundamental mechanism that enables many modern JavaScript patterns—from simple callbacks to advanced frameworks like React and backend frameworks like Express.

Once you understand how closures interact with lexical environments, execution contexts, and the garbage collector, you'll be able to reason about JavaScript code more confidently, write safer abstractions, and recognize the patterns used throughout professional codebases.

In many ways, mastering closures is the point where JavaScript starts to feel less like a scripting language and more like a language designed for building sophisticated software systems.

DEV Community: Abanoub Kerols

Server-Side Rendering (SSR) and Hydration: How Modern Web Applications Become Fast and Interactive

1. The Traditional Client-Side Rendering Model

2. What Happens During CSR?

The browser has to do a lot of work before the user sees meaningful content.

3. The Idea Behind Server-Side Rendering

4. SSR Is Not the Same as Hydration

5. A Simple Analogy

CSR

SSR

6. What Exactly Is Hydration?

7. SSR + Hydration Lifecycle

8. Why SSR Improves Perceived Performance

9. SSR vs CSR

10. The Most Important Concept: The Same UI Must Exist on Both Sides

Hydration Mismatch

11. Hydration Mismatches

12. Browser-Only APIs Can Also Cause Problems

13. Data Fetching Is Another SSR Challenge

14. Server-to-Client Data Transfer

15. Angular SSR

16. A Complete Angular SSR Example

17. Create the Application

18. Create a Product Service

19. Create the Component

20. What Happens During Hydration?

21. Hydration Does Not Mean "Render Everything Again"

22. Hydration and Event Handlers

Time to Interactive

Hydration Gap

23. The Hydration Gap

Partial Hydration

24. Partial Hydration

25. Angular Hydration Concepts

26. SSR Architecture in Production

27. SSR With a Backend API

28. SSR Is Not Free

29. SSR and Caching

30. SSR + CDN

31. SSR and SEO

32. SSR vs SSG

Static Site Generation

33. SSR vs SSG vs CSR

Admin Dashboard

Blog

E-commerce Product Page

34. SSR + Hydration + API Data

35. A More Realistic Product Example

36. Common SSR Mistakes

Mistake #1: Using window Everywhere

Mistake #2: Using localStorage During SSR

Mistake #3: Random Values

Mistake #4: Current Time

Mistake #5: Different Data

37. How to Think About SSR Code

38. The Universal JavaScript Model

Isomorphic / Universal Applications

39. Hydration Mismatch Debugging Strategy

1. Random values

2. Dates

3. Browser APIs

4. Conditional rendering

5. Different API results

6. Invalid HTML

40. SSR Security Considerations

41. Performance Optimization Strategy

42. The Deeper Architecture

43. A Complete Mental Model

44. The Key Difference in One Diagram

CSR

SSR

45. When Should You Use SSR?

46. When CSR May Be Better

47. SSR Is an Architectural Decision

48. Final Architecture

49. Final Takeaways

1. CSR

2. SSR

3. Hydration

4. SSR does not eliminate JavaScript

Mistake #1: Using `window` Everywhere

Mistake #2: Using `localStorage` During SSR