When people first learn backend systems, one server feels like enough.

And at first, it often is.

A client sends a request.
The server handles it.
The server reads or writes data in the database.
Then it sends a response back.

That simple model is a great place to start.

But it does not stay enough forever.

This lesson explains the basic ideas behind scaling in a very practical way:

• why one server eventually becomes a problem
• the difference between vertical and horizontal scaling
• what a load balancer does
• why stateless servers matter
• whether bottlenecks appear
• how a small to-do app can grow from one server to multiple servers

Why one server is not enough forever

A single server is simple.

That is its biggest strength.

There are fewer moving parts, fewer things to manage, and fewer places for bugs to hide. For a small product, this is often the right starting point.

But one server has two big limits.

1. It has limited capacity

A server can only handle so much work.

It has limited:

• CPU
• memory
• disk
• network capacity

As more users arrive, more requests hit that server. Eventually it gets overloaded.

When that happens, the app may:

• become slow
• start timing out
• fail requests
• crash

So the first problem is simple: one machine cannot handle unlimited traffic.

2. It is a single point of failure

If your whole app depends on one server, that one server becomes critical.

If it crashes, the whole app is down.

That means even if performance is fine today, reliability is still fragile.

A simple analogy is a store with one cashier.

When there are only a few customers, one cashier is fine.
When the store gets busy, the line grows.
If the cashier leaves, nobody gets served.

That is the core scaling problem.

Vertical scaling vs horizontal scaling

Once one server is not enough, there are two basic ways to grow.

Vertical scaling

Vertical scaling means making one server stronger.

You keep one machine, but upgrade it:

• more CPU
• more memory
• faster hardware

You are scaling “up”.

This is often the easiest first step because the architecture does not change much.

You do not need more app servers.
You do not need request routing between servers.
You do not need as much operational complexity.

but vertical scaling has limits.

You can only make one machine so big.
And even after upgrading it, it is still one machine.
So you still have a single point of failure.

Horizontal scaling

Horizontal scaling means adding more servers.

Instead of one machine doing all the work, several machines share it.

You are scaling “out”.

For example, instead of:

• 1 app server

you move to:

• 2 app servers
• 3 app servers
• 10 app servers

This helps with both traffic and reliability.

More traffic can be spread across multiple machines.
If one server dies, others may still keep the app running.

But horizontal scaling introduces new problems:

• how requests get distributed
• how servers stay consistent
• where shared state lives
• how bottlenecks move elsewhere

So horizontal scaling is more powerful, but also more complex.

The key difference

Vertical scaling: one stronger server
Horizontal scaling: more servers

That is the heart of it.

What a load balancer is

Once you have multiple app servers, a new question appears:

Which server should handle each request?

That is the job of the load balancer.

A load balancer sits in front of your app servers.

The client sends a request to the load balancer.
The load balancer decides which app server should receive it.
Then that server handles the request.

So the load balancer acts like a traffic director.

Why it matters

Without a load balancer, clients would need some other way to choose a server. That gets messy quickly.

A load balancer gives the system one front door.

It helps by:

• distributing traffic across servers
• preventing one server from taking all requests
• avoiding unhealthy or dead servers

The important idea is not “perfectly even traffic”.
The important idea is request routing.

A useful analogy is a restaurant host.

Customers arrive at the entrance.
The host decides where they go.
The host is not cooking the food.
The host is directing traffic.

That is what a load balancer does for servers.

Why stateless servers matter when scaling

When beginners hear “stateless”, it often sounds abstract.

It is actually a practical idea.

What is a state?

State is information that must be remembered.

Examples:

• whether a user is logged in
• shopping cart contents
• to-do items
• user preferences
• profile data

Some state is temporary while processing one request.
That is normal.

The real problem is important state that must still exist for later requests.

What is a stateless server?

A stateless server does not depend on its own memory to remember important data across requests.

That does not mean the server never uses memory.

it does.

It means the server does not keep important long-lived state only inside itself and assume the next request will come back to the same machine.

Instead, important shared state usually lives in a place all app servers can access, such as:

• a database
• a cache
• a session store

Why this matter with multiple servers

In a scaled system, a user’s first request might go to Server A.
Their next request might go to Server B.

If Server A kept important user state only in its own memory, Server B may not know it.

Then the system behaves strangely.

For example:

• user logs in through Server A
• login state lives only in Server A’s memory
• next request goes to Server B
• Server B does not know that user is logged in

Now the user appears logged out or gets inconsistent behavior.

That is why stateless app servers are so helpful when scaling horizontally.

They make it safe for any request to go to any server.

A good rule is:

Important long-lived state should not live only in one app server’s memory.

Common bottlenecks in a simple system

A bottleneck is the part of the system that limits the whole system.

Even if everything else is fast, the overloaded part slows everything down.

Think of a narrow part of a road.
Cars can move quickly before and after it, but traffic still gets stuck there.

In a simple system, these are common bottlenecks.

1. The app server

If one app server gets too many requests, it may run out of CPU or memory.

That can cause:

• slow responses
• crashes
• timeouts

This is often the first bottleneck in a small app.

2. The database

The database is one of the most common bottlenecks.

Why?

Because many requests need it.
Reads and writes often depend on it.
As traffic grows, the database can become overloaded.

That leads to:

• slow queries
• delayed responses
• a slow app overall

3. The network

Sometimes the issue is not CPU or the database.

Sometimes data just moves too slowly across the network.

This can matter more when:

• there is lots of traffic
• large files are being transferred
• services call each other often

4. Disk or storage

Reading and writing from storage can also become slow, especially with heavy writes or large amounts of data.

5. A shared dependency

This is an important scaling lesson:

Adding more app servers does not automatically fix the whole system.

Why not?

Because those app servers may all depend on one shared thing:

• one database
• one cache
• one file store

That shared dependency may become the next bottleneck.

So scaling is not just about adding machines.
It is about finding the actual limiting part.

A very useful rule is:

Your system is only as strong as its most overloaded important part.

A small example: scaling a to-do app

Let’s walk through a very small example.

Stage 1: one server

At the beginning, a to-do app might look like this:

This is enough for basic features:

• create a to-do
• list to-dos
• mark a to-do complete
• delete a to-do

This is a good MVP design.

It is simple.
It is easier to build.
It is easier to debug.
It is the right place to start for many apps.

What goes wrong as usage grows

Over time, more users start using the app.

Now the single app server must handle more requests:

• more people logging in
• more reads for to-do lists
• more writes for creating and updating tasks

Eventually that one server becomes overloaded.

So we need to scale.

Stage 2: add multiple app servers

Now the design becomes:

You now have:

• 1 load balancer
• 2 app servers
• 1 shared database

The load balancer receives requests and sends them to one of the app servers.

This helps spread the work.

Why statelessness matters here

Suppose a user sends two requests:

1. create a to-do
2. list all to-dos

The first request might go to Server A.
The second might got to Server B.

That is fine if important state is shared.

Both servers can read the same data from the database.

That is why the app servers should be stateless.

If one server stored important request state only in its own memory, the next server might not know it.

What improved?

The app can now handle more application traffic because the request-processing work is shared across multiple servers.

What did not automatically improve?

The database is still shared.

And now both app servers send work to that same database.

So after scaling the app layer, the database may become the next bottleneck.

This is a very common pattern:

1. one app server becomes overloaded
2. add more app servers
3. the database becomes the new limit

So the system is better than before, but it is not infinitely scalable.

The big lesson behind scaling basics

Scaling is not magic.

It is not just “add servers”.

Real scaling means asking:

• what is the current bottleneck?
• what problem are we solving?
• what new problems will this change introduce?

A beginner mistake is thinking that more servers always fix the system.

They do not.

They only help if the current bottleneck is the app server layer.

If the real bottleneck is the database, network, or disk, then adding app servers may do very little.

That is why good system design starts with simple architecture, then scales carefully based on an actual limits.

Building a Tiny To-Do App to Understand Client, Server, API, and Database Basics

When people hear system design, they often imagine giant distributed systems, millions of users, and complicated diagrams.

This is not where I would start.

I would start with a much simpler question:

What actually happens when a user does something in an app?

If you understand that clearly, you already have the foundation of system design.

Start with a simple example

Imagine a user opens a to-do app and clicks:

Add task

They type:

Buy milk

What happens next?

At a basic level:

1. The app sends a request
2. The server receives it
3. The server may store the task in a database
4. The server sends a response back
5. The app updates the screen

That simple flow is the core of many software systems.

Client and server

The first two ideas to understand are client and server.

Client
The client is the part the user interacts with.

Examples:

• a browser
• a mobile app
• a desktop app

The client collects input and shows results.

Server
The server is the part that does the work.

It usually:

• receives requests
• validates data
• applies rules
• reads or writes data
• sends response back

A useful beginner way to think about it is:

• client = where the user interacts
• server = where the system logic lives

That distinction matters.

A client is not just “the thing that sends first.”
A server is not just “the thing that replies.”

The real difference is their role in the system.

Request and response

When the client wants something, it sends a request.

Examples:

• log me in
• get my tasks
• create a task

The server process that request and sends back a response.

Examples:

• success
• failure
• data
• error message

This pattern is everywhere:

if you open an app and load your tasks, that is a request.
If the app shows your tasks after that, that came from a response.

This is one of the most important basic patterns in backend systems.

Why a database exists

A beginner might think:

“The server receives requests, so why not just keep everything there?”

Because server memory is temporary.

If the server crashes or restarts, data stored only in memory can disappear.

That is why important data is usually stored in a database.

A database gives the system durable storage.

That means important data can survive restarts.

Examples of data that should not disappear:

• users
• tasks
• orders
• messages
• account settings

So the basic flow becomes:

The server handles the request, but the database stores important data durably.

Example: creating a task

Let’s walk through a basic flow.

A user types:

Buy milk

Then:

1. The client collects the task text
2. The client sends a request to the server
3. The server receives the request
4. The server validates the request
5. The server tells the database to store the task
6. The database saves it
7. The server sends a response back
8. The client updates the UI

That is a complete beginner-friendly system flow.

It is simple, but it contains the core of system design thinking.

The server does more than forward data

Another common beginner misunderstanding is this:

The server is just middleman.

Not really.

The server often contains the application’s rules.

For example, during user signup, the server might:

• validate the email format
• check whether the password is strong enough
• check whether the email is already registered
• hash the password before storage
• save the user only if the input is valid

So the server is not just passing data around.

It is deciding:

• what is valid
• what is allowed
• what gets stored
• what gets rejected

This is a huge idea.

The server is where much of the system’s logic lives.

What an API is

Now we can name the way the client talks to the server.

That is usually an API.

A simple definition:

An API is the way a client talks to a server.

It defines:

• what requests can be made
• what data should be sent
• what responses come back

You can think of it like a menu.

A menu tells you what you can order.
An API tells the client what it can ask the server to do.

For a to-do app, an API might allow:

• creating a task
• listing tasks
• deleting a task

So an API is not magic.

It is just the contract between client and server.

Why the client is untrusted

This is one of the most important beginner ideas in backend design.

The client is untrusted.

Why?

Because the user controls it.

A user can:

• modify requests
• fake inputs
• bypass UI restrictions
• use scripts or bots
• send data the frontend never intended to allow

That means the server must not blindly trust the client.

For example:

• the client should not decide whether a login is valid
• the client should not decide whether a user is an admin
• the client should not decide the real price of a product

The server must validate important things itself.

A simple rule:

Never trust the client for important logic.

This rule shows up again and again in system design.

Reads and writes

Another useful basic distinction is read vs write.

Read

A read fetches existing data.

Examples:

• get all my tasks
• load my profile
• fetch messages

Write

A write changes data.

Examples:

• create a task
• update profile
• send a message
• delete a comment

This matters because systems often behave differently depending on whether they are read-heavy or write-heavy.

For now, the important thing is just understanding the distinction.

If the system is fetching data, that is a read.
If it is changing the data, that is a write.

Why important state should not live in one server’s memory

As systems grow, they often use more than one server.

That creates a new problem.

Suppose important user data lives only in one server’s memory.

What happens if:

• the next request goes to a different server?
• that original server crashes?
• the server restarts?

The data may be missing.

That is why important state usually should not live only inside one server’s local memory.

This is one reason people talk about stateless servers.

A stateless server does not depend on its own local memory to remember important things between requests.

That makes it easier to:

• add more servers
• replace failed servers
• distribute traffic safely

At beginner level, the main takeaway is simple:

Important long-term data should not depend on one server’s memory.

A clean mental model

By the end of this lesson, the basic model looks like this:

And each part has a role:

• Client: collects user input and displays results
• Server: validates requests, applies logic, and decides what happens
• Database: stores important data durably
• API: the contract the client uses to talk to the server

This the heart of many backend systems.

After learning these ideas, you should be able to explain:

• what a client is
• what a server is
• what request/response means
• why a database is needed
• what an API is
• why the client is untrusted
• the difference between reads and writes
• why important data should not live only in one server’s memory

That is not “advanced distributed systems.”

But it is real system design foundation.

And without it, more advanced topics will just feel like random buzzwords.

Final takeaway

We must remind ourselves that the system design does not being with:

• microservices
• sharding
• global scale
• event streaming

It begins with understanding the basic flow of an application.

When a user does something:

• who receives the request?
• who validates it?
• where is the data stored?
• who sends the result back?
• what should be trusted?
• what can fail?

If you can answer those questions clearly, you are on the right track.

But that is not where you start.

You start with the most basic question:

What actually happens when a user does something in an app?

That is what this lesson is about.

To make the ideas practical, we are building a tiny to-do app with three parts:

• a client
• a server
• a database

The app is intentionally small. A user can:

• create a task
• view all tasks

That is enough to understand the core flow of a backend system.

What this lesson teaches

By the end of this project, you should understand:

• what the client does
• what the server does
• what an API is
• why we use a database
• how request/response works
• the difference between a read and a write
• why the server must validate input

The mental model for this lesson is:

The stack

To keep this simple, we will use:

• Frontend: HTML, CSS, JavaScript
• Backend: Node.js + Express
• Database: SQLite

Why this stack?

Because it is small, local, and easy to understand. The goal is to learn the flow, not fight the tooling.

Step 1: Create the project structure

Create a project like this:

system-design-journey/
  client/
  server/
  README.md

Why this structure?

Because the lesson is about different parts of a system having different jobs.

• client/ is where user interaction happens
• server/ is where requests are handled
• README.md explains what the lesson teaches

Even the folder structure should reflect the architecture.

Step 2: Define the app scope

Before writing code, decide what the app actually does.

For Lesson 1, keep it small:

• create a task
• list all tasks

That’s it.

Why so small?

Because this already gives us:

• one write operation: create task
• one read operation: get tasks

That is enough to teach the basic backend flow without adding noise.

Step 3: Set up the server

Inside the server/ folder, initialize the backend:

npm init -y
npm install express sqlite3 cors

What these packages do:

• express helps us create the server and define routes
• sqlite3 gives us a simple local database
• cors allows the frontend to call the backend in local development

Now create server/app.js:

const express = require("express");
const cors = require("cors");
const db = require("./db");

const app = express();
const PORT = 3001;

app.use(cors());
app.use(express.json());

app.get("/", (req, res) => {
  res.json({ message: "Server is running" });
});

app.listen(PORT, () => {
  console.log(`Server listening on http://localhost:${PORT}`);
});

What this does:

• creates a server
• allows JSON request bodies
• enables local frontend/backend communication
• exposes a simple test route
• starts listening for requests

At this point, the server exists, but it does not do anything useful yet.

That is okay. Build in small steps.

Run it with:

node app.js

If you open http://localhost:3001, you should see:

{"message":"Server is running"}

That confirms the backend is alive.

Step 4: Add the database

Now we add durable storage.

Why?

Because server memory is temporary. If the server restarts, anything stored only in memory is lost.

A database keeps important data around.

Create server/db.js:

const sqlite3 = require("sqlite3").verbose();
const path = require("path");

const dbPath = path.join(__dirname, "todo.db");

const db = new sqlite3.Database(dbPath, (err) => {
  if (err) {
    console.error("Failed to connect to SQLite database:", err.message);
  } else {
    console.log("Connected to SQLite database.");
  }
});

db.serialize(() => {
  db.run(`
    CREATE TABLE IF NOT EXISTS tasks (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      title TEXT NOT NULL,
      created_at TEXT NOT NULL
    )
  `);
});

module.exports = db;

What this does:

• creates or opens a SQLite database file
• creates a tasks table if it does not exist
• stores tasks on disk instead of only in memory

Our table is simple:

• id identifies the task
• title stores the text
• created_at stores when it was created

That is enough for Lesson 1.

Step 5: Add the read endpoint

Now let’s build our first real API route:

GET /tasks

This is a read operation because it fetches existing data.

Add this to server/app.js:

app.get("/tasks", (req, res) => {
  db.all("SELECT * FROM tasks ORDER BY id DESC", [], (err, rows) => {
    if (err) {
      return res.status(500).json({ error: "Failed to fetch tasks" });
    }

    res.json(rows);
  });
});

What this does:

• receives a request for all tasks
• asks the database for the task rows
• returns them as JSON

This teaches an important idea:

The client does not talk directly to the database.
The server talks to the database and returns the result.

Step 6: Add the write endpoint

Now let’s build:

POST /tasks

This is a write operation because it changes the system state.

Add this to server/app.js:

app.post("/tasks", (req, res) => {
  const { title } = req.body;

  if (!title || !title.trim()) {
    return res.status(400).json({ error: "Title is required" });
  }

  const trimmedTitle = title.trim();
  const createdAt = new Date().toISOString();

  const query = `
    INSERT INTO tasks (title, created_at)
    VALUES (?, ?)
  `;

  db.run(query, [trimmedTitle, createdAt], function (err) {
    if (err) {
      return res.status(500).json({ error: "Failed to create task" });
    }

    res.status(201).json({
      id: this.lastID,
      title: trimmedTitle,
      created_at: createdAt,
    });
  });
});

What this teaches:

• the client sends data in the request body
• the server validates the input
• the server writes to the database
• the server returns a response

The validation part matters a lot.

Even if the frontend checks for empty input, the server must still validate it.

Why?

Because the client is untrusted. A user can bypass the UI and send bad requests directly.

That is why important validation belongs on the server.

Step 7: Test the API first

Before building the UI, test the backend by itself.

This is a good habit. It is easier to debug one layer at a time.

To test GET /tasks, open:

http://localhost:3001/tasks

At first, you should get:

[]

To test POST /tasks, use curl:

curl -X POST http://localhost:3001/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"Buy milk"}'

You should get a created task back.

Then visit GET /tasks again and confirm the task is there.

At this point, you already have:

• a server
• a database
• a read endpoint
• a write endpoint
• server-side validation
• persistence

That is already the core of Lesson 1.

Step 8: Build the client

Now we create the part the user interacts with.

Create client/index.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Lesson 1 - Tiny To-Do App</title>
  <link rel="stylesheet" href="./style.css" />
</head>
<body>
  <main class="container">
    <h1>Tiny To-Do App</h1>
    <p>Lesson 1: Client, Server, API, and Database Basics</p>

    <section class="task-form">
      <input
        type="text"
        id="taskInput"
        placeholder="Enter a task"
      />
      <button id="addTaskBtn">Add Task</button>
    </section>

    <section>
      <h2>Tasks</h2>
      <ul id="taskList"></ul>
    </section>
  </main>

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

This gives us:

• an input field
• a button
• a place to render tasks

That is all the client needs for this lesson.

Step 9: Add simple styling

Create client/style.css:

body {
  font-family: Arial, sans-serif;
  background: #f7f7f8;
  margin: 0;
  padding: 0;
}

.container {
  max-width: 600px;
  margin: 40px auto;
  background: white;
  padding: 24px;
  border-radius: 12px;
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08);
}

h1, h2 {
  margin-top: 0;
}

.task-form {
  display: flex;
  gap: 12px;
  margin: 20px 0;
}

input {
  flex: 1;
  padding: 10px;
  font-size: 16px;
}

button {
  padding: 10px 16px;
  font-size: 16px;
  cursor: pointer;
}

ul {
  padding-left: 20px;
}

li {
  margin-bottom: 8px;
}

This is not about design. It just makes the app readable.

Step 10: Fetch and render tasks

Now the client needs to call the API and show the results.

Create client/script.js:

const API_BASE_URL = "http://localhost:3001";

const taskInput = document.getElementById("taskInput");
const addTaskBtn = document.getElementById("addTaskBtn");
const taskList = document.getElementById("taskList");

async function fetchTasks() {
  try {
    const response = await fetch(`${API_BASE_URL}/tasks`);
    const tasks = await response.json();
    renderTasks(tasks);
  } catch (error) {
    console.error("Failed to fetch tasks:", error);
  }
}

function renderTasks(tasks) {
  taskList.innerHTML = "";

  for (const task of tasks) {
    const li = document.createElement("li");
    li.textContent = `${task.title} (${task.created_at})`;
    taskList.appendChild(li);
  }
}

fetchTasks();

What this does:

• sends a request to GET /tasks
• receives the task data from the server
• renders it in the browser

This is the read flow in action:

Step 11: Create tasks from the client

Now let the user submit tasks from the UI.

Add this to client/script.js:

async function createTask() {
  const title = taskInput.value.trim();

  if (!title) {
    alert("Please enter a task title.");
    return;
  }

  try {
    const response = await fetch(`${API_BASE_URL}/tasks`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ title }),
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(errorData.error || "Failed to create task");
    }

    taskInput.value = "";
    await fetchTasks();
  } catch (error) {
    console.error("Failed to create task:", error);
    alert(error.message);
  }
}

addTaskBtn.addEventListener("click", createTask);

taskInput.addEventListener("keydown", (event) => {
  if (event.key === "Enter") {
    createTask();
  }
});

What this teaches:

• the client reads user input
• the client sends a write request to the server
• the server decides whether the request is valid
• the server stores the task in the database
• the client refreshes the list after success

Notice something important here:

The client also checks for empty input, but that is only for better user experience.

The real protection is still on the server.

Step 12: Run the full app

Now test the full flow.

Start the server:

cd server
node app.js

Then open the client in your browser.

Now try this:

1. open the page
2. type a task
3. click Add Task
4. see it appear in the list
5. refresh the page
6. confirm the task is still there

That final refresh is important.

It shows that the task is not living only in browser state or server memory. It is stored in the database.

That is one of the biggest lessons here.

What this tiny app proves

Even though the app is small, it demonstrates the most important Lesson 1 ideas.

Client

The client collects input and displays output.

Server

The server receives requests, validates input, applies logic, and sends responses.

API

The client talks to the server through defined endpoints.

Database

The database stores important data durably.

Request/response

The entire app works through request/response cycles.

Read vs write

• GET /tasks is a read
• POST /tasks is a write

Server-side validation

The server does not trust the client and validates the title before storing it.

The request flow for creating a task

Here is the full flow when a user adds a task:

User types a task
  ↓
Client sends POST /tasks
  ↓
Server validates the title
  ↓
Server stores the task in SQLite
  ↓
Server returns the created task
  ↓
Client refreshes and renders the task list

And when the app loads tasks:

User opens the app
  ↓
Client sends GET /tasks
  ↓
Server reads tasks from SQLite
  ↓
Server returns JSON
  ↓
Client renders the task list

That is the foundation of many real systems.

Why this project is intentionally small

It would be easy to add more features:

• login
• delete task
• mark complete
• user accounts
• authentication

But that would make the lesson worse.

The goal of Lesson 1 is not to build a full product.

The goal is to clearly understand the basic architecture of an app:

• where input comes from
• where logic lives
• where data is stored
• how the parts talk to each other

A small project teaches that better than a bigger messy one.

Final takeaway

System design does not begin with scaling, sharding, or microservices.

It begins with understanding a simple flow:

A user does something. The client sends a request. The server handles it. The database stores or retrieves data. The server responds. The client updates.

That is what this tiny to-do app shows.

If you understand this clearly, you already have a real foundation for learning system design.

When I started learning frontend, I could often get things working.

I knew some patterns. I knew some syntax. I knew what to type to update an array, attach a click handler, or use a Promise.

But there was a gap I did not fully respect:

I often knew what to use, but not always why to use it.

That gap matters more than it seems.

Because in frontend, a lot of bugs do not come from not knowing a feature exists. They come from using the right-looking code with the wrong mental model.

Over the past phase of learning, I realized that a lot of my JavaScript understanding was like that. I could recognize patterns, but I could not always explain the mechanics precisely. And that is where things break down.

Knowing what to use is not the same as knowing why it works

It is easy to memorize things like:

• use spread syntax
• use map instead of mutating arrays
• promises run before timeouts
• avoid arrow functions for object methods
• use stopPropagation() for nested clicks

But memorizing those rules is not the same as understanding them.

For example, I used to think copying an object with spread syntax meant I had made a safe copy. But that is only true at one level.

const next = { ...state };

This creates a new outer object. It does not automatically create new nested objects and arrays inside it.

That means this kind of code is still dangerous:

const next = { ...state };
next.user.address.city = "Chiang Mai";

It looks like I made a copy. But I only copied the outer container. If address was never copied, I am still mutating shared data.

That was one of the biggest lessons for me: sometimes I was writing “modern JavaScript” without actually reasoning about what was still shared.

The real skill is being able to track identity

A lot of JavaScript became clearer once I started asking a better question:

What exactly is new here, and what is still shared?

That question helped across multiple topics.

With objects and arrays:

• Did I create a new object?
• Did I create a new array?
• Did I also create new nested objects inside it?
• Or did I just copy the container and keep the inner values shared?

With functions and closures:

• Is this function reading the current value?
• Or is it closing over a value that was derived earlier?

With this:

• Am I assuming this belongs to the object?
• Or am I checking how the function is actually being called?

With the event loop:

• Am I assuming setTimeout(..., 0) means “now”?
• Or do I understand that it still runs later?

That shift from syntax to mechanics changed a lot for me.

JavaScript looks simple until mutation gets involved

One of the clearest examples was array methods.

At a surface level, I already knew methods like map, filter, push, sort, slice, and splice.

But knowing their names is not enough.

The real question is: which ones mutate, and which ones produce new values?

That difference is huge in frontend.

For example:

const arr = [3, 1, 2];
const result = arr.sort();

If I only know “sort sorts arrays,” I might miss the important part: sort() mutates the original array and returns the same array.

So now:

• arr was changed
• result is the same array
• any code depending on immutability can break in confusing ways

The safer version is:

const sorted = [...arr].sort();

That tiny difference reflects a much better mental model:
make a new array first, then mutate the new one instead of the original.

That pattern came up again and again. reverse() behaves similarly. push() mutates and returns a length, not a new array. splice() mutates, while slice() copies.

These are not trivia questions. These are bug sources.

“I copied it” is often not enough

One of the hardest but most valuable lessons was learning that copying one level is not the same as performing a safe immutable update.

Consider this:

const next = {
  ...state,
  items: [...state.items]
};

This creates:

• a new outer object
• a new items array

But if items contains objects, those inner objects are still shared.

So this is still a mutation bug:

next.items[0].name = "Z";

That line changes the same object that still exists inside the original state.

This was a turning point for me, because it forced me to stop thinking in broad labels like “copied” or “not copied.”

Instead, I had to think in paths:

What exact path am I updating, and did I copy every level along that path?

That is a much more useful engineering habit.

Closures are simple until they become stale

Closures were another case where I knew the concept loosely, but not sharply enough.

I understood the general idea: an inner function can access variables from the outer scope.

But the more important lesson was this:

A closure does not magically give you “the latest value” in every form.

Sometimes you are closing over a variable.
Sometimes you are closing over a value that was derived too early.

That difference matters.

This version goes stale:

function createLogger() {
  let count = 0;
  const label = `Count is ${count}`;

  return {
    increment() {
      count++;
    },
    log() {
      console.log(label);
    }
  };
}

Even after incrementing, log() still prints the old label.

Why? Because label was created once, early, when count was still 0.

But this version works differently:

function createLogger() {
  let count = 0;

  return {
    increment() {
      count++;
    },
    log() {
      console.log(`Count is ${count}`);
    }
  };
}

Now the string is built when log() runs, so it uses the current count.

This was a useful lesson beyond closures themselves. It taught me to ask:

Am I reading current state at execution time, or am I using a value that was captured too early?

That question matters a lot in real frontend code.

this is one of those things that punishes vague thinking

Before, I had a fuzzy mental model that this somehow referred to the object.

That works just enough to fool you.

What I had to learn was:

this is usually determined by how the function is called, not where it was written.

That explains why this works:

const user = {
  name: "Sam",
  sayName() {
    console.log(this.name);
  }
};

user.sayName();

But this changes behavior:

const fn = user.sayName;
fn();

Same function. Different call-site.

And arrow functions made the distinction even clearer: they do not get this from the call-site the same way regular functions do.

This was another pattern where I had seen the rule before, but understanding the “why” made it stick.

The event loop is not hard, but it does require precision

I had seen examples with promises and setTimeout, but I had not fully internalized the ordering.

Now the rule is much clearer in my head:

• synchronous code runs first
• then microtasks
• then macrotasks

So:

console.log("start");
setTimeout(() => console.log("timeout"), 0);
Promise.resolve().then(() => console.log("promise"));
console.log("end");

prints:

start
end
promise
timeout

The useful part was not memorizing the output. It was understanding why.

That helped me reason about nested cases too, like promises created inside timeouts, or timeouts scheduled inside promise callbacks.

Again, the theme was the same:
not just recognizing the pattern, but being able to explain the mechanics.

Event bubbling made frontend feel more physical

Event propagation also became clearer once I stopped treating it like magic.

A click is not just “a click handler ran.”
It moves through phases.

That helped me understand bugs like:

• clicking a button inside a clickable card
• a modal backdrop and modal content interfering with each other
• parent handlers running unexpectedly

stopPropagation() also became more precise in my head. It does not cancel the click itself. It stops the event from continuing through the propagation path.

That sounds small, but these small wording differences matter because they shape how I debug.

The biggest shift: from code recognition to code reasoning

If I had to summarize what changed, it is this:

I am trying to move from recognizing code patterns to reasoning about behavior.

Before, I might look at code and think:

• that looks right
• I have seen that syntax before
• that is probably the React/JavaScript way to do it

Now I am trying to ask:

• what is actually being mutated?
• what is newly created?
• what is still shared?
• when is this value being read?
• what queue is this callback entering?
• what determines this here?
• what phase is this event in?

That feels closer to real engineering.

Because real bugs usually do not ask whether I have seen the syntax before.
They ask whether my mental model is accurate enough to predict behavior.

What I learned from this phase

The biggest lesson was not one specific JavaScript feature.

It was that shallow knowledge is enough to write code that looks correct, but not enough to debug confidently.

Knowing what to use helps you start.

Knowing why to use it helps you:

• avoid subtle bugs
• debug with less guessing
• reason about state changes
• make safer updates
• explain your code clearly
• trust your own decisions more

And I think that is the real progression I am after.

Not just writing code that works once.

Writing code that I actually understand.

If you’ve ever built a system that needs to work with PDFs, generating them, merging them, or converting HTML, you’ve probably experienced the moment every developer hits eventually.

It’s just a PDF. Why is this so complicated?

I’ve seen that moment from multiple angles: as a support engineer helping developers under tight deadlines, as a web application engineer building the PDF viewer and demo apps, and as someone who has tested countless PDFs that don’t behave the way anyone expects.

Working at Iron Software has given me a front-row seat to how developers actually interact with PDFs. I’ve seen the assumptions they make, the shortcuts they take, and the surprises they encounter, especially when dealing with complex or inconsistent documents.

This article is not just about IronPDF as a product. It’s an honest look at the real challenges developers face and the patterns I’ve seen repeatedly while supporting hundreds of users. If you work with PDFs, these insights will feel familiar and hopefully useful.

Creating PDFs feels simple — until you need to do it programmatically

On the surface, creating a PDF feels easy. Using tools like Adobe Acrobat, Google Docs, Microsoft Word, or even your browser’s “Print to PDF”, the process is instant and predictable. Everything seems effortless.

This leads many developers to assume:

If Adobe or Google Docs can generate perfect PDFs with one click, how hard can it be to do this through code?

But the moment you try to:

• convert dynamic HTML into a PDF
• generate PDFs inside an API
• ensure consistent output across environments

you quickly discover how much complexity is hidden behind that one-click export.

Desktop tools hide their entire rendering pipeline behind a simple UI. When you build your own workflow, you are suddenly responsible for:

• rendering engines
• layout engines
• font and asset loading
• timing
• viewport control
• print vs. screen CSS

That gap between perceived simplicity and actual complexity is at the core of almost every HTML-to-PDF problem developers run into, and it’s exactly why tools like IronPDF exist.

Why HTML-to-PDF is harder than people think

HTML was never designed to become a paged, fixed-layout document format. Browsers do their best to interpret layout on the fly, but when converting HTML to PDF, everything becomes stricter.

1. HTML relies heavily on dynamic behavior

Modern web pages include:

• async JavaScript
• API-driven content
• hydration steps for frameworks
• lazy loading
• animations and transitions

A PDF engine needs to decide:

When is the page “ready” to capture?
There is no universal answer.

2. CSS behaves differently in print mode

Developers often forget that:

• print CSS overrides screen CSS
• overflow rules behave differently
• absolute/fixed elements shift in print contexts
• margins and bleed areas change the layout

Tiny differences in CSS can significantly change the resulting PDF.

3. Fonts and assets must be fully loaded

A browser can fallback gracefully in real time.
A PDF renderer cannot.

If fonts or images haven’t loaded when rendering begins, the output will differ from what you saw in your browser.

4. Frameworks add another layer of complexity

React, Vue, Angular, Svelte, and Blazor all hydrate the DOM asynchronously.

If the PDF engine captures the DOM too early, it will literally snap the loading state.

This is where IronPDF’s architecture matters

IronPDF uses a Chromium-based rendering engine, which is the same underlying technology used by modern browsers.

This means IronPDF:

• understands modern CSS
• supports web fonts
• renders JavaScript
• accurately calculates the layout
• behaves like a real browser

Learn more here: https://ironpdf.com/tutorials/html-to-pdf/

But IronPDF goes one step further:
It gives developers control over when and how the page should be rendered for PDF output.

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.WaitFor.RenderDelay(1000);
renderer.RenderingOptions.WaitFor.JavaScript();
renderer.RenderingOptions.WaitFor.NetworkIdle0();

var pdf = renderer.RenderUrlAsPdf(url);
pdf.SaveAs("output.pdf");

You can control

• render delays
• JavaScript execution
• viewport dimensions
• additional CSS injection
• print settings
• marging and header/footer behavior

This is essential for real-world web apps, where timing, layout, and loading order are unpredictable.

renderer.RenderingOptions.CssMediaType = IronPdf.Rendering.PdfCssMediaType.Screen;
renderer.RenderingOptions.CustomCssUrl = "screen.css";

The most common HTML-to-PDF issues developers encounter

1. The PDF doesn’t match the webpage

Even with a Chromium engine, differences arise due to:

• print vs. screen styling
• font loading delays
• hydration timing
• lazy-loaded elements
• responsive components are resizing differently

Expected:

Reality:

When I build demos, I rely on IronPDF’s configuration options to overcome these issues:

• JavaScript execution hooks
• render-on-event
• custom CSS injection
• controlled viewport settings

These ensure that the PDF output matches developer expectations.

2. Working with form fields and signatures

Even though this isn’t as common as HTML-to-PDF, it still surprises developers that:

• form fields are separate from page content
• signatures have both visual and cryptographic layers

IronPDF handles these details consistently, but for most developers today, HTML-to-PDF remains the core challenge.

Why IronPDF works so well for developers

Across hundreds of developers, one pattern is clear:

They don’t want to learn PDF internals. They just want a PDF that looks like the webpage.

IronPDF is built around that expectation: usability.

The benefits developers appreciate most:

1. Browser-accurate HTML-to-PDF

The Chromium engine gives developers:

• predictable rendering
• modern CSS support
• accurate framework behavior
• realistic layout calculations
• consistency across environments

It’s as close to “what you see in a browser is what you get in the PDF” as developers can get, while giving them more control than a regular browser.

2. An intuitive C# API

Whether you’re:

• rendering HTML strings
• converting live URLs
• applying print styling
• configuring headers and footers

IronPDF’s API remains consistent, approachable, and easy to integrate. When I build demo apps, the API's usability is always the standout feature.

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlString);
pdf.SaveAs("output.pdf");

3. Designed for real developer workflows

IronPDF simplifies the entire HTML-to-PDF pipeline by:

• handling Chromium internally
• abstracting timing and loading concerns
• giving developers override controls
• supporting advanced styling scenarios

This combination of accuracy + usability is exactly what developers want.

Final Thoughts

If you’re building anything involving PDFs, especially HTML-to-PDF conversion, you’ll eventually run into these challenges. It’s not your fault; it’s simply how HTML, CSS, and browsers behave when turned into a fixed-layout format.

That’s exactly why IronPDF exists.

With a Chromium engine and a developer-focused API, IronPDF makes HTML-to-PDF conversion predictable and manageable, so developers can focus on building features instead of wrestling with rendering quirks.

From support to engineering, I’ve seen firsthand how much time and frustration IronPDF saves developers and how much smoother projects run when HTML-to-PDF “just works”.

Try IronPDF

If you’re looking for a reliable way to generate or manipulate PDFs in .NET, explore the product here:

https://ironpdf.com

Introduction

When most people think of data structures, they imagine dry textbook examples with numbers and nodes. But learning them doesn’t have to be boring. I decided to teach myself singly linked lists by building something fun and relatable: a music playlist manager in JavaScript.

This small project let me practice creating nodes, linking them together, traversing them, and manipulating the list — all key skills when learning linked lists.

Why Linked Lists?

Arrays are great, but they have limitations when it comes to insertions and deletions in the middle of the list. Linked lists solve this by letting each element (or “node”) point to the next one, making reordering fast and memory-efficient.

Here’s the mental model:

Head -> Song 1 -> Song 2 -> Song 3 -> null

When you remove Song 2, you simply adjust Song 1’s next pointer to skip over it and link to Song 3.

The Building Blocks

I broke the project into two classes:

1. Song — represents each song.
2. Playlist — manages the linked list (adding, removing, displaying, playing).

Here’s what a single node looks like:

class Song {
  constructor(title, genre, author, singer, duration, next = null) {
    this.title = title;
    this.genre = genre;
    this.author = author;
    this.singer = singer;
    this.duration = duration;
    this.next = next;
  }
}

Adding Songs to the Playlist

The addSong() method appends a new node to the end of the list. If the list is empty, the new song becomes the head.

addSong({ title, genre, author, singer, duration, next }) {
  const newSong = new Song(title, genre, author, singer, duration, next);

  if (!this.head) {
    this.head = newSong;
    this.current = this.head;
  } else {
    let last = this.head;
    while(last.next) last = last.next;
    last.next = newSong;
  }
}

Removing Songs

Deleting a song meant finding the previous node and pointing its next to skip over the deleted node — a perfect exercise for linked list traversal.

removeSong(titleToDelete) {
  if (!this.head) return;

  if (this.head.title === titleToDelete) {
    this.head = this.head.next;
    return;
  }

  let prev = this.head;
  let curr = this.head.next;

  while (curr) {
    if (curr.title === titleToDelete) {
      prev.next = curr.next;
      return;
    }

    prev = curr;
    curr = curr.next;
  }
}

Traversing and Playing Songs

Finally, I created playNextSong() to traverse the list and loop back to the start when reaching the end — just like a real music player.

playNextSong() {
  if (!this.current) {
    console.log("No songs in the playlist."); 
    return;
  }

  console.log(`Now playin: ${this.current.title}`);
  this.current = this.current.next || this.head;
}

There you have it: a clean, simple Linked List project you can build today.

One place where hidden inefficiency can creep in is event handling.

The Problem

In many interactive UIs, elements are created dynamically:

• New chat messages
• Infinite-scroll product listings
• To-do list tasks

If you attach event listeners to each element as it’s created, you may:

• Increase memory usage (every listener takes space)
• Increase CPU overhead (more functions for the browser to manage)
• Risk leaking memory if you forget to clean up listeners on removed nodes

The kicker? On a modern computer, you might not feel these costs until they’re huge, but they’re still there.

A Concrete Example: Dynamic To-Do List

Imagine a simple to-do list:

• Add tasks dynamically
• Click a task to toggle “done”
• Delete tasks

Naive Approach

function addTask(text) {
  const li = document.createElement("li");
  li.textContent = text;
  
  // Attach a click listener
  li.addEventListener("click", () => {
    li.classList.toggle("done");
  });

  document.querySelector("#taskList").appendChild(li);
}

Every new <li> gets its own function in memory. Add 1,000 tasks and you now have 1,000 listeners.

Event Delegation Approach

// Attach a click listener
document.querySelector("#taskList").addEventListener("click", (e) => {
  const targeted = e.target.closest("li");

  if (targeted) {
    targeted.classList.toggle("done");
  }
});

Here we attach one listener to the parent <ul> and let events “bubble up”. No matter how many <li> we add, the listener count stays constant.

You can check out the code here.

Takeaways

• Event delegation reduces memory usage, avoids unnecessary function bindings, and simplifies clean-up.
• It is a cleaner approach.

In this article, I’ll walk you through a generalized version of that solution, discuss why it worked, and outline the pros and cons of this approach.

The Problem
Blazor uses IJSRuntime to call JavaScript functions. Typically, we import a module like this:

var module = await jsRuntime.InvokeAsync<IJSObjectReference>(
  "import", "./_content/ProjectName/Components/MyComponents.razor.js"
);

When you have multiple interop classes like FirstJsInterop, SecondJsInterop, etc, each one ends up with:

• The same constructor logic
• The same disposal logic
• Just a different JS file path

This violates the DRY principle and makes the code harder to maintain and scale.

The Factory-Based Solution

Instead of repeating that logic everywhere, I created two reusable layers:

1. A Factory Class to Load JS Modules

public class InteropFactor
{
    private readonly IJSRuntime _jsRuntime;
    private const string BasePath = "./_content/ProjectName/Components/{0}.razor.js";

    public InteropFactory(IJSRuntime jsRuntime) 
    {
        _jsRuntime = jsRuntime;
    }

    public Lazy<Task<IJSObjectReference>> LoadModule(string fileName)
    {
        string path = string.Format(BasePath, fileName);
        return new(() => _jsRuntime.InvokeAsync<IJSObjectReference>("import", path).AsTask());
    }
}

This abstracts away the import logic and returns a Lazy<Task<IObjectReference>> to ensure the module loads only once per instance.

2. A Base Class to Handle Boilerplate

public class Interop : IAsyncDisposable
{
    private readonly Lazy<Task<IJSObjectReference>> _moduleTask;

    public Interop(Lazy<Task<IJSObjectReference>> moduleTask) 
    {
        _moduleTask= moduleTask;
    }

    public Lazy<Task<IJSObjectReference>> LoadModule(string fileName)
    {
        string path = string.Format(BasePath, fileName);
        return new(() => _jsRuntime.InvokeAsync<IJSObjectReference>("import", path).AsTask());
    }

    protected async ValueTask<T> InvokeAsync<T>(string function, params object[] args)
    {
        var module = await _moduleTask.Value;
        return await module.InvokeAsync<T>(function, args);
    }

    protected async ValueTask InvokeVoidAsync(string function, params object[] args)
    {
        var module = await _moduleTask.Value;
        await module.InvokeVoidAsync(function, args);
    }

    public async ValueTask DisposeAsync()
    {
        if (_moduleTask.IsValueCreated)
        {
            var module = await _moduleTask.Value;
            await module.DisposeAsync();
        }
    }
}

Now, each interop class becomes lean and focused on just its JavaScript responsibilities.

Example Usage: MyComponentsJsInterop

public class MyComponentsJsInterop : Interop
{
    public MyComponentsJsInterop(InteropFactory factor)
        : base(factory.LoadModule("MyComponents")) {} 
    {

    }

    public ValueTask DoFirstTask() => InvokeVoidAsync("doFirstTask");
}

Summary

The Factory Pattern helped me create a clean and maintainable approach to managing JS interop in Blazor. If your app grows beyond one or two JS modules, this pattern can save you from boilerplate and complexity.

I kept hearing terms like pivot, low, high, and swapping, but when I tried tracing it myself using an array like [5, 4, 3, 2, 1], I got confused.

• “Does the pivot change during the sort?”
• “When do I stop?”

If you’ve ever felt the same, this guide is for you — a step-by-step walkthrough using the array [5, 4, 3, 2, 1].

What is QuickSort?

QuickSort is a divide and conquer algorithm that:

1. Picks a pivot.
2. Partitions the array so that values ≤ pivot go to one side and values ≥ pivot go to the other.
3. Recursively sorts both sides.

In this article of QuickSort, we:

• Pick a pivot (we’ll use the middle element)
• Use two pointers: i (from left) and j (from right).
• Move them toward each other and swap when needed.

Step 1: Choose a Pivot

We’ll pick the pivot from the middle of the array.

[5, 4, 3, 2, 1]

So the middle element is 3.
That’s our pivot. We’re going to sort everything around it.

Step 2: Initialize Pointers

• Let’s set i to the first index (value = 5)
• Let’s set j to the last index (value = 1)

So:

i = 0 -> arr[i] = 5
j = 4 -> arr[j] = 1

Step 3: Compare & Swap

Now remember:

• Elements on the left of the pivot should be less than or equal to the pivot.
• Elements on the right of the pivot should be greater than or equal to the pivot.

So we check:

Is arr[i] (5) >= pivot (3)? -> Yes
Is arr[j] (1) <= pivot (3)? -> Yes

Since both are true, we swap them.

The array becomes:

[1, 4, 3, 2, 5]

Now we move the pointers:

• i = 1 now points to 4
• j = 3 now points to 2

Step 4: Compare & Swap Again

Now check:

Is arr[i] (4) >= pivot (3)? -> Yes
Is arr[i] (2) <= pivot (3)? -> Yes

Both are true again, so we swap:

[1, 2, 3, 4, 5]

Move the pointers again:

• i = 2, j = 2

Step 5: Check If We’re Done

At this point: i = 2, j = 2
When i ≥ j, we know:

• The pivot is now in the correct place.
• Everything to the left of it is ≤ pivot.
• Everything to the right is ≥ pivot.

So we return j = 2 to split the array into two subarrays:

• Left: [1, 2]
• Right: [4, 5]

QuickSort will then recursively sort these parts:

Even though the array is already sorted at this point, the algorithm doesn’t know that — so it keeps going until each section is just one element.

Once the recursive calls reach the point where low ≥ high, QuickSort knows it’s done.

And that’s how it works — one pivot, two pointers, a few swaps, and repeat. Easy as crawling.

class Solution {
    partition(arr, low, high) {
        let mid = Math.floor((low + high) / 2);
        let pivot = arr[mid];
        let i = low - 1;
        let j = high + 1;

        while (true) {
            do {
                i++;
            } while (arr[i] < pivot);

            do {
                j--;
            } while (arr[j] > pivot);

            if (i >= j) return j;

            [arr[i], arr[j]] = [arr[j], arr[i]];
        }
    }

    quickSort(arr, low, high) {
        if (low < high) {
            let p = this.partition(arr, low, high);
            this.quickSort(arr, low, p);
            this.quickSort(arr, p + 1, high);
        }
    }
}

// Usage
const sol = new Solution();
let arr = [5, 4, 3, 2, 1];
sol.quickSort(arr, 0, arr.length - 1);
console.log(arr); // [1, 2, 3, 4, 5]

In this post, I’ll show you how I bypassed that bottleneck by using plain JavaScript and an ASP.NET Core controller for a much faster, more reliable upload process.

Why the Problem Happens:

• In Blazor Server, InputFile sends file data via SignalR in small chunks, which can be slow or hit limits for larger files.
• You may want a direct HTTP approach (like a standard web form) that doesn’t rely on Blazor’s real-time pipeline.
• Using a controller with multipart/form-data is typically faster and more reliable for large files.

Step 1: Creating the Controller

Here’s a straightforward ASP.NET Core controller that accepts an upload file, writes it to disk, and returns a success message as JSON. This is the core piece for bypassing Blazor’s built-in InputFile approach:

[Route("api/[controller]")]
[ApiController]
public class UploadFileController : ControllerBase
{
    [HttpPost(nameof(Upload))]
    public async Task<IActionResult> Upload(IFormFile file)
    {
        // 1. Create a file stream on the server to store the uploaded file.
        using var fileStream = new FileStream(file.FileName, FileMode.Create);

        // 2. Open the uploaded file from the request as a read stream.
        using var stream = file.OpenReadStream();

        // 3. Asynchronously copy all file data into the newly created server file.
        await stream.CopyToAsync(fileStream);

        // 4. Return a JSON response indicating success (and the file path).
        return Ok(new 
        { 
            FilePath = file.FileName, 
            Message = "File uploaded successfully!" 
        });
    }
}

Step 2: Registering Controllers in Program.cs

To ensure your controller (from Step 1) is recognized by ASP.NET Core, you must register the controller services and map the controller routes in your Program.cs. For example:

// 1. Add controller services
builder.Services.AddControllers();

// 2. Map controller routes
app.MapControllers();

Step 3: JavaScript Function to Handle the File Upload

Below is a simple JavaScrpit function that listens for a file selection and then immediately uploads that file to our ASP.NET Core controller endpoint. You can place this code in a javascript file.

export function UploadFile() {
    const fileInput = document.getElementById("file-input");

    fileInput.addEventListener("change", async (event) => {
        console.time("timer");  // Just for performance measurement

        const file = event.target.files[0];
        if (!file) {
            console.warn("No file selected.");
            return;
        }

        // 1. Build a FormData object for the file
        const formData = new FormData();
        formData.append("file", file);

        // 2. Send the file via fetch to the controller
        const response = await fetch("/api/UploadFile/Upload", {
            method: "POST",
            body: formData
        });

        // 3. Handle the response
        if (!response.ok) {
            const text = await response.text();
        } else {
            const data = await response.json();
            console.log(data);
        }

        console.timeEnd("timer");  // End performance measurement
    });
}

Step 4: Creating a .NET Method That Calls the JavaScript Function

Finally, you can bridge your Blazor Server code and the JavaScript file using JavaScript Interop.

// This C# method calls the JS function "UploadFile" we defined earlier
public async ValueTask UploadFile()
{
    var module = await _ModuleTask.Value;
    await module.InvokeVoidAsync("UploadFile");
}

You must also add the following to the Program.cs for dependency injection:

builder.Services.AddScoped<AppJsInterop>();

Step 5: Using the Interop in a Blazor Component

Finally, here’s an example of how you can call your interop method UploadFile() inside a Blazor component. The component renders a plain input file tag and in OnAfterRenderAsync, it invokes the JavaScript function to setup the event listener and handle the upload:

@page "/using-direct-http"

@inject AppJsInterop AppJsInterop

<h3>UsingDirectHttp</h3>

<!-- Plain HTML input, no Blazor InputFile component -->
<input type="file" id="file-input" />

@code {
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            // Call the interop method that loads "app.js" 
            // and invokes the UploadFile function
            await AppJsInterop.UploadFile();
        }

        await base.OnAfterRenderAsync(firstRender);
    }
}

Performance Comparison

During testing, I measured how long it took to upload a 7 MB file using Blazor’s InputFile and a direct ASP.NET Core controller approach. Following are the screenshots comparing the two methods:

Blazor’s Input File

ASP.NET Core controller

I think the difference is largely due to SignalR chunking in Blazor’s InputFile approach, whereas direct HTTP POST bypasses that overhead. Your exact results may vary depending on file size, network conditions, and hosting environment.

Sample Project On GitHub