10 Javascript Interview Questions — part 1

While AI is great, and we use it a lot while coding, we still have to know JavaScript to clear JS interviews. We need to know the fundamentals and advanced concepts. In this article series, we’ll go through interesting JS questions that will test your knowledge of the language. Let’s get started.

1 What happens when you call setTimeout with a delay of 0, and why might the actual execution time vary?

When you call setTimeout(callback, 0), the callback function is not executed immediately. Instead, it's placed at the back of the message queue. The JavaScript engine will only execute this callback once the current call stack is empty. This is why the actual execution time may vary—it depends on the length of time it takes to process all the code currently in the call stack before the event loop can pull the callback from the message queue.

Here’s a simple example to illustrate this behavior:

console.log('Start');

setTimeout(() => {
  console.log('Callback executed');
}, 0);

console.log('End');

// The expected output will be:
// Start
// End
// Callback executed

Why the Actual Execution Time Varies

The delay isn’t a guaranteed execution time, but a minimum delay. Several factors can influence the actual time of execution:

• Call Stack: If the current code in the call stack is computationally expensive or takes a long time to run, the setTimeout callback will have to wait for it to finish. The callback only gets its turn when the stack is clear.
• Event Loop: The event loop is what checks the call stack and the message queue. It continuously pushes new tasks from the message queue to the call stack when the stack is empty.
• Browser/Node.js Environment: The JavaScript engine’s internal workings, including other tasks in the message queue (like user interactions or network requests), can affect the order and timing of execution.

This mechanism ensures that JavaScript, being a single-threaded language, doesn’t block the main thread. It allows for asynchronous operations without freezing the user interface.

2 Explain the difference between Object.create(null) and {}, and when you would use each.

The primary difference between Object.create(null) and {} lies in their prototype chain.

• {} is a shorthand for new Object(). It creates a plain object that inherits from Object.prototype. This means it has access to common methods and properties like toString(), hasOwnProperty(), and isPrototypeOf().
• Object.create(null) creates an object with no prototype at all. It's a truly empty object, often referred to as a "dictionary" or "hash map," with no inherited properties or methods from Object.prototype.

This distinction can be seen in the following example:

const obj1 = {};
const obj2 = Object.create(null);

console.log(obj1.toString); // function toString() { ... }
console.log(obj2.toString); // undefined

console.log(obj1.hasOwnProperty('a')); // false
// console.log(obj2.hasOwnProperty('a')); // TypeError: obj2.hasOwnProperty is not a function

console.log(Object.getPrototypeOf(obj1)); // [Object: null prototype] {}
console.log(Object.getPrototypeOf(obj2)); // null

When to Use Each

Use {} when:

You need a standard object for general-purpose use. This is the most common use case for objects in JavaScript. Since it inherits from Object.prototype, you can use built-in methods like toString(), hasOwnProperty(), and others without any special checks.

Use Object.create(null) when:

• You need a pure data map: Use this when you want to create an object that will only serve as a hash map or dictionary. It’s safe from prototype pollution, which is a common security vulnerability.
• You’re using the object to store user-provided keys: A malicious user could provide a key like "toString", which would overwrite the inherited method in a regular object ({}) but won't affect an object created with Object.create(null).
• Performance is critical: An object with no prototype chain can be slightly faster for property lookups and access, as the JavaScript engine doesn’t have to traverse the prototype chain.
• You’re building an API or a library: When building an API or a library that exposes objects, using Object.create(null) ensures that the consumers of your API don't accidentally rely on inherited methods that you haven't explicitly documented or intended to be part of the object's public API.

3 What are the potential issues with this code, and how would you fix them?

for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100);
}

The code will print 3 three times instead of 0, 1, and 2 as one might expect. This happens because of a classic JavaScript problem involving var and closures within a loop.

The Issue

The core issue is that var has function scope, not block scope. The variable i is declared once and is hoisted to the top of the function or global scope. The setTimeout callback function, which executes asynchronously after the loop has finished, forms a closure over the variable i. By the time the callbacks are executed, the loop has already completed, and the value of i has been incremented to 3. All three callbacks reference the same i variable in the outer scope, which holds the final value of 3.

Solutions

There are three common ways to fix this issue, each utilizing a different approach to create a new, distinct scope for each iteration.

1. Using let

The most modern and idiomatic solution is to use the let keyword, which has block scope. A new i is created for each iteration of the loop, so each setTimeout callback captures the correct value.

for (let i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100);
}
// Expected Output: 0, 1, 2

2. Using an Immediately Invoked Function Expression (IIFE)

Before let was widely adopted, a common solution was to wrap the setTimeout call in an IIFE. The IIFE creates a new function scope for each iteration, and by passing i as an argument, you can capture its value. This is a functional programming approach to creating a closure.

for (var i = 0; i < 3; i++) {
  ((j) => {
    setTimeout(() => console.log(j), 100);
  })(i);
}
// Expected Output: 0, 1, 2

3. Using bind()

Another less common but valid solution is to use bind(). The first argument to bind() is the value for this, which is not relevant here, so we pass null. The second argument allows you to pass a value to be used as an argument to the function when it's executed, effectively creating a new scope for each call.

for (var i = 0; i < 3; i++) {
  setTimeout(console.log.bind(null, i), 100);
}
// Expected Output: 0, 1, 2

4 How does JavaScript’s garbage collection work, and what can cause memory leaks in modern applications?

JavaScript’s garbage collection is primarily handled by an algorithm called mark-and-sweep. The garbage collector’s job is to reclaim memory that’s no longer in use by the program.

The Mark-and-Sweep Algorithm

1. Marking Phase: The garbage collector starts from the root objects, which are variables in the global scope (like window or global), and objects on the current call stack. It then "marks" all objects that are reachable from these roots. This includes following references from the root objects to other objects, and then from those objects to others, and so on. Any object that can be reached from the root is considered "in use."
2. Sweeping Phase: The garbage collector then “sweeps” through all memory. Any objects that were not marked as reachable are considered “garbage” and are removed, and their memory is freed.

Common Causes of Memory Leaks

Although JavaScript’s automatic garbage collection prevents many memory leaks, some common patterns in modern applications can still cause them. These leaks occur when objects that are no longer needed are still being referenced, preventing the garbage collector from freeing their memory.

1. Global Variables: Declaring variables without a keyword (var, let, or const) inside a function will make them global. They will then be referenced by the global object and will not be garbage collected until the application is closed.

function createLeak() {
  // 'leaky' becomes a global variable (e.g., window.leaky in a browser)
  leaky = 'I am leaking!';
}

2. Forgotten Timers and Event Listeners: If you set a setTimeout, setInterval, or an event listener without clearing it, the callback function will hold a reference to the objects within its scope. This prevents those objects from being garbage collected, even if the element or component they are associated with is removed from the DOM.

const element = document.getElementById('my-button');
element.addEventListener('click', () => {
  // This listener will not be garbage collected until the page unloads,
  // even if `element` is removed from the DOM.
});

// To prevent the leak, you must remove the listener
// element.removeEventListener('click', ...);

3. Detached DOM Elements: If you remove a DOM element from the document but a JavaScript variable still holds a reference to it, the entire element and its data will remain in memory. The garbage collector sees this as a valid reference and won’t free the memory.

let myElement = document.getElementById('some-id');
document.body.removeChild(myElement); // The element is removed from the DOM.
// However, `myElement` variable still holds a reference, causing a leak.
myElement = null; // Setting the reference to null prevents the leak.

4. Improper Closures: While closures are a powerful feature, they can cause memory leaks if not used carefully. A closure that references a large object or an element from an outer scope will keep that object in memory as long as the closure exists. If that closure is never released, the referenced object can never be collected.

5 Explain the differences between call, apply, and bind, then implement your own version of bind.

call, apply, and bind are all methods used to explicitly set the this context for a function. The main difference lies in how they handle function execution and arguments.

call

• Executes the function immediately.
• The first argument is the this value.
• The subsequent arguments are passed to the function individually, one by one.

Syntax: function.call(thisArg, arg1, arg2, ...)

const person = { name: 'Alice' };
function greet(city, country) {
  console.log(`Hello, my name is ${this.name} and I live in ${city}, ${country}.`);
}

greet.call(person, 'New York', 'USA');
// Output: Hello, my name is Alice and I live in New York, USA.

apply

• Executes the function immediately.
• The first argument is the this value.
• The arguments are passed to the function as a single array or an array-like object.

Syntax: function.apply(thisArg, [argsArray])

const person = { name: 'Bob' };
function greet(city, country) {
  console.log(`Hello, my name is ${this.name} and I live in ${city}, ${country}.`);
}

greet.apply(person, ['London', 'UK']);
// Output: Hello, my name is Bob and I live in London, UK.

bind

• Returns a new function with the this context permanently bound.
• Does not execute the function immediately.
• Arguments can be passed to the returned function at a later time.

Syntax: const newFunction = function.bind(thisArg, arg1, arg2, ...)

const person = { name: 'Charlie' };
function greet() {
  console.log(`Hello, my name is ${this.name}.`);
}

const boundGreet = greet.bind(person);
boundGreet();
// Output: Hello, my name is Charlie.

The main takeaway is: call and apply are for immediate execution, while bind is for creating a new, reusable function. The only difference between call and apply is how they accept arguments.

Implementing Your Own bind

To create a custom bind implementation, we need a function that returns another function. This returned function should be able to accept its own arguments and combine them with any arguments passed to the original bind call. We'll use a Symbol for the method name to avoid potential conflicts with existing properties on Function.prototype.

Function.prototype.myBind = function(thisArg, ...args) {
  const func = this; // 'this' refers to the function on which myBind is called.
  return function(...restArgs) {
    // Combine arguments from myBind and the returned function.
    const allArgs = [...args, ...restArgs];
    // Use apply to call the original function with the correct context and arguments.
    return func.apply(thisArg, allArgs);
  };
};

// Example usage with our custom myBind
const person = { name: 'Dave' };
function greet(city, country) {
  console.log(`Hello, my name is ${this.name} and I live in ${city}, ${country}.`);
}

const boundGreet = greet.myBind(person, 'Tokyo');
boundGreet('Japan');
// Output: Hello, my name is Dave and I live in Tokyo, Japan.

6 What is the temporal dead zone, and how does it affect let, const, and var declarations?

The Temporal Dead Zone (TDZ) is a behavioral characteristic of let and const declarations. It's the period between the beginning of a block scope and the point where a variable is declared and initialized with a value. During this time, the variable exists but cannot be accessed. Any attempt to access it will result in a ReferenceError.

How It Affects Declarations

let and const

Both let and const declarations are hoisted, but they are not initialized. This creates the TDZ. The variable name is "hoisted" to the top of its block scope, but it remains in a state where it cannot be accessed until the code execution reaches its actual declaration line.

Example:

{
  // TDZ for `x` starts here
  console.log(x); // ReferenceError: Cannot access 'x' before initialization
  let x = 'hello'; // TDZ for `x` ends here
}

This behavior is a key feature that helps catch common programming errors and promotes better code practices by making variable declaration explicit.

var

The var keyword does not have a temporal dead zone. Variables declared with var are fully hoisted—both their declaration and an initialization to undefined are moved to the top of their function or global scope. This means you can access a var variable before its declaration line without getting a ReferenceError.

{
  console.log(y); // undefined
  var y = 'world';
  console.log(y); // world
}

While this might seem flexible, it can lead to unexpected behavior and subtle bugs, which is one of the main reasons let and const were introduced to the language. The TDZ for let and const provides more predictable and safer variable scoping.

7 How would you implement deep equality comparison for two JavaScript objects, handling edge cases like circular references?

Deep equality comparison for two JavaScript objects is the process of checking if their properties and values are strictly equal, recursively. This goes beyond a simple === check, which only compares object references. A robust implementation needs to handle various data types and, importantly, circular references to prevent infinite loops.

Implementation without Circular Reference Handling

A basic recursive function can handle most cases. It would check for:

• Simple data types: Use strict equality (===) for primitives.
• Object and array types: Recursively call the function on their properties and elements.
• Null and other edge cases: Handle null and non-object types appropriately.

Here’s a simple example that works for non-circular objects:

function isEqual(obj1, obj2) {
  // 1. Check for strict equality (handles primitives and same object reference)
  if (obj1 === obj2) {
    return true;
  }

  // 2. Check for null or non-object types
  if (obj1 === null || typeof obj1 !== 'object' || obj2 === null || typeof obj2 !== 'object') {
    return false;
  }

  // 3. Get keys and check if they have the same number of properties
  const keys1 = Object.keys(obj1);
  const keys2 = Object.keys(obj2);

  if (keys1.length !== keys2.length) {
    return false;
  }

  // 4. Recursively check properties
  for (const key of keys1) {
    if (!keys2.includes(key) || !isEqual(obj1[key], obj2[key])) {
      return false;
    }
  }

  return true;
}

This implementation works well, but it will cause a stack overflow error if it encounters a circular reference.

Implementing Deep Equality with Circular Reference Handling

To handle circular references, we need to keep track of the objects we have already visited during the recursion. A good way to do this is with a WeakMap or two arrays to store the objects from each comparison pair. When comparing two objects, we first check if they have already been seen together in the current comparison chain.

Here is a more robust implementation using a WeakMap to store object pairs that have been visited.

function isEqualCircular(obj1, obj2, map = new WeakMap()) {
  // 1. Strict equality check for primitives and same object reference
  if (obj1 === obj2) {
    return true;
  }

  // 2. Handle null or non-object types
  if (obj1 === null || typeof obj1 !== 'object' || obj2 === null || typeof obj2 !== 'object') {
    return false;
  }

  // 3. Check for circular references
  // If we've already compared these two objects, return true to prevent an infinite loop.
  // We use a WeakMap to avoid memory leaks.
  if (map.get(obj1) === obj2) {
    return true;
  }
  map.set(obj1, obj2); // Store the current pair of objects

  // 4. Handle array and object types
  if (Array.isArray(obj1) !== Array.isArray(obj2)) {
    return false;
  }

  const keys1 = Object.keys(obj1);
  const keys2 = Object.keys(obj2);

  if (keys1.length !== keys2.length) {
    return false;
  }

  // 5. Recursively check properties
  for (const key of keys1) {
    // We need to check if key exists in obj2 to avoid potential errors
    if (!Object.prototype.hasOwnProperty.call(obj2, key) || !isEqualCircular(obj1[key], obj2[key], map)) {
      return false;
    }
  }

  return true;
}

// Example with a circular reference
const a = { b: null };
const b = { a: a };
a.b = b;

const c = { d: null };
const d = { c: c };
c.d = d;

console.log(isEqualCircular(a, c)); // true

8 What are the performance implications of different iteration methods (for, forEach, map, for…of) and when would you choose each?

Different iteration methods in JavaScript have varying performance characteristics, with for loops generally being the fastest and most flexible, while array-specific methods like forEach and map provide better readability and functional benefits at a small performance cost.

Performance Implications

• for loop: This is the fastest iteration method. It's a low-level construct with minimal overhead. It has direct control over the loop index, making it memory-efficient and ideal for large datasets or performance-critical tasks.
• for...of loop: This loop is designed to iterate over iterable objects, such as arrays, strings, and maps. It is generally faster than forEach and map because it doesn't involve a function call for each iteration. It provides a clean syntax and avoids common off-by-one errors associated with for loops.
• forEach: This is an array method that calls a callback function for each element. The performance overhead comes from the function call in each iteration. While this overhead is negligible for small arrays, it can accumulate for large datasets. It also cannot be stopped or broken using break or return, which can be a limitation.
• map: Similar to forEach, map also involves a function call for each element, incurring a similar performance cost. However, its main distinction is that it returns a new array with the results of the callback function. This can be less performant than for loops if you don't need to create a new array.

When to Choose Each

• for loop: Choose a for loop when performance is the top priority, especially with large datasets, or when you need fine-grained control over the iteration, such as skipping elements, breaking out of the loop, or iterating in reverse.
• for...of loop: Use for...of when you want a simple and readable way to iterate over the values of an array or iterable object and do not need the index. It's a great balance of performance and readability.
• forEach: This is the go-to method for iterating over an array when readability is more important than absolute performance, and you need to perform a side effect for each element (e.g., logging to the console, pushing to another array).
• map: Choose map specifically when you need to transform each element of an array into a new value and create a new array containing the results. It's a core concept of functional programming and makes your code declarative and concise.

9 Explain how JavaScript’s this binding works in arrow functions vs regular functions, especially in the context of event handlers and method calls.

In JavaScript, the behavior of this is a crucial difference between regular functions and arrow functions. The key is that a regular function's this is dynamic and determined by how the function is called, while an arrow function's this is lexically scoped, meaning it's determined by the surrounding code where it was defined.

Regular Functions

The this value in a regular function is determined at runtime by its invocation context. It can change depending on how the function is called.

• Method Call: When a function is called as a method of an object (e.g., obj.myMethod()), this refers to the object itself.
• Simple Function Call: In a standard function call (e.g., myFunction()), this refers to the global object in non-strict mode (like window in browsers) and is undefined in strict mode.
• Constructor Call: When a function is called with new (e.g., new MyObject()), this refers to the newly created instance.
• Event Handlers: In the context of a DOM event listener, this typically refers to the element that the event listener was attached to.

Example:

const person = {
  name: 'Alice',
  greet: function() {
    console.log(this.name); // 'this' refers to the 'person' object
  }
};
person.greet(); // Output: Alice

const greetFunc = person.greet;
greetFunc(); // Output: '' (or 'undefined' in strict mode)

In the second call, the function is detached from the person object, and its this context defaults to the global object.

Arrow Functions

Arrow functions handle this differently. They do not have their own this binding. Instead, they lexically inherit the this value from the enclosing scope at the time they are defined. This behavior is fixed and cannot be changed by call, apply, or bind.

• In a Global Scope: this is the global object.
• Inside a Regular Function: this inherits the this of the regular function.
• Inside a Method: this inherits the this of the enclosing object, which is the object the method is defined on.

This makes them predictable and very useful for callbacks, especially in event handlers, where a regular function’s this might not be what you expect.

Example:

const person = {
  name: 'Bob',
  greet: function() {
    const innerArrowFunc = () => {
      console.log(this.name); // 'this' inherits from the outer 'greet' function
    };
    innerArrowFunc();
  },
  arrowGreet: () => {
    console.log(this.name); // 'this' inherits from the global scope (e.g., 'window')
  }
};

person.greet();       // Output: Bob
person.arrowGreet();  // Output: '' (or 'undefined')

Event Handlers

This distinction is especially important in event handling.

• Regular function handler: this will refer to the DOM element that triggered the event. This is useful if you need to manipulate the element directly.
• Arrow function handler: this will refer to the context where the handler was defined, which is often the component instance in frameworks like React or Vue, making it a common pattern.

const button = document.querySelector('#myButton');

// Regular function
button.addEventListener('click', function() {
  console.log(this); // 'this' is the button element
});

// Arrow function
button.addEventListener('click', (event) => {
  // In a component class, 'this' would refer to the class instance
  // Here, it would be the global object (window)
  console.log(this);
});

10 What happens during the execution of this code, and what are the potential race conditions?

Promise.resolve().then(() => console.log('A'));
setTimeout(() => console.log('B'), 0);
console.log('C');

During the execution of this code, the output will be C, A, B. This is a classic example that demonstrates the difference between the microtask queue (used by promises) and the macrotask queue (used by setTimeout).

Execution Breakdown

1. Synchronous Code: The JavaScript engine first executes all synchronous code. console.log('C') is called immediately.
2. Promise Microtask: Promise.resolve().then(...) places its callback (() => console.log('A')) into the microtask queue. The microtask queue has higher priority than the macrotask queue and is processed as soon as the current call stack is empty.
3. setTimeout Macrotask: setTimeout(() => console.log('B'), 0) places its callback (() => console.log('B')) into the macrotask queue. Macrotasks are processed by the event loop only after the microtask queue is empty.
4. Event Loop: Once the synchronous code is finished, the event loop checks the microtask queue. It finds the callback for console.log('A'), moves it to the call stack, and executes it.
5. Final Execution: After the microtask queue is empty, the event loop then checks the macrotask queue. It finds the callback for console.log('B'), moves it to the call stack, and executes it.

This priority system ensures that all promises are resolved before the next event loop cycle begins.

Potential Race Conditions

Race conditions can occur when multiple asynchronous tasks are initiated, and their execution order is not guaranteed, leading to unpredictable outcomes. In this specific code, the setTimeout callback has a defined minimum delay of 0, but its actual execution time depends on several factors:

• Task Queue Congestion: If there are other tasks (e.g., from other setTimeout calls, user events, or network requests) already in the macrotask queue, console.log('B') will have to wait for them to finish.
• Microtask Overload: If the microtask queue has many Promise or queueMicrotask callbacks, the setTimeout callback will be delayed until all microtasks are processed, making its execution time highly variable.

These race conditions highlight that setTimeout(..., 0) is not a zero-delay operation but rather a scheduling mechanism that yields control back to the event loop, with the exact timing depending on the engine's current workload.

Thanks for reading!

10 Javascript Interview Questions — part 1 was originally published in Tech Tonic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Object-Relational Mapping (ORM) libraries have become a foundational component in modern Node.js application development. Frameworks such as Sequelize, Prisma, and TypeORM offer abstractions that facilitate rapid development by modeling relational data as high-level JavaScript or TypeScript objects. These abstractions enable developers to interact with databases using familiar object-oriented paradigms, thereby reducing the need to write raw SQL and lowering the barrier to entry for full-stack developers.

Despite these productivity benefits, ORMs often fail to expose the full expressive power of Structured Query Language (SQL), particularly in the context of advanced database features. These include but are not limited to window functions, recursive common table expressions (CTEs), materialized views, and expression-based indexing. Such features are essential in domains requiring complex data transformations, hierarchical processing, or performance-critical analytics.

This article examines the limitations of popular Node.js ORMs in supporting advanced SQL features.

Let’s get started.

Common Limitations in SQL Feature Coverage

While ORM frameworks in Node.js abstract away much of the complexity involved in database access, they frequently lack support for a range of advanced SQL features. These limitations constrain the expressiveness, performance optimization, and structural modeling capabilities that relational databases inherently provide. This section outlines several such SQL constructs and the degree to which they are unsupported or inefficiently modeled by ORMs.

A. Window Functions

Window functions allow for complex analytics operations over rows related to the current row, using clauses such as OVER, PARTITION BY, and ORDER BY. They are commonly used for ranking, running totals, and lag/lead computations.

Raw SQL Example:

SELECT 
    user_id, 
    created_at,
    RANK() OVER (PARTITION BY user_id ORDER BY created_at) AS rank
FROM logins;

ORM Limitation:
Prisma and Sequelize do not support window functions through their query builders. Developers must resort to raw SQL, which bypasses the ORM’s type safety and abstraction benefits.

Workaround Example (Sequelize):

await sequelize.query(`
  SELECT user_id, created_at,
  RANK() OVER (PARTITION BY user_id ORDER BY created_at) AS rank
  FROM logins;
`);

B. Recursive Common Table Expressions (CTEs)

Recursive CTEs are essential for querying hierarchical or graph-structured data, such as organizational charts or category trees.

Raw SQL Example:

WITH RECURSIVE category_path(id, name, parent_id) AS (
  SELECT id, name, parent_id FROM categories WHERE parent_id IS NULL
  UNION ALL
  SELECT c.id, c.name, c.parent_id
  FROM categories c
  INNER JOIN category_path cp ON cp.id = c.parent_id
)
SELECT * FROM category_path;

ORM Limitation:
None of the major ORMs in Node.js support recursive CTEs natively. Developers are again forced to write raw SQL, undermining the abstraction layer and increasing maintenance complexity.

C. Materialized Views and View Binding

Materialized views are precomputed query results stored physically for improved read performance. Similarly, standard views abstract complex queries into logical tables.

ORM Limitation:
ORMs do not support view creation or materialized view refreshing. Moreover, interacting with existing views (e.g., read-only bindings) is inconsistently supported and often undocumented.

Example Issue:
Prisma currently does not support introspection or migration for materialized views. Sequelize requires defining a model manually, without schema validation.

D. Partial and Expression Indexes

Partial indexes restrict indexing to rows that meet a condition, while expression indexes index derived values. These features are vital for performance optimization in large datasets.

Raw SQL Example:

CREATE INDEX idx_active_users ON users (email) WHERE is_active = true;

ORM Limitation:
There is no declarative support for partial indexes or functional expressions in most Node.js ORMs. Even where custom indexing is allowed (e.g., Sequelize’s indexes property), the syntax does not cover expressions or conditions.

E. Native JSON and JSONB Operations

PostgreSQL’s JSONB support enables deep querying and indexing of semi-structured data using operators such as @>, #>>, and jsonb_path_query.

Raw SQL Example:

SELECT * FROM events WHERE payload @> '{"type": "click"}';

ORM Limitation:
Prisma and Sequelize allow storage of JSON but lack full support for these advanced operators in query builders. As a result, developers must revert to raw SQL or use database-specific extensions.

F. Table Inheritance and Advanced Constraints

Features like table inheritance (PostgreSQL) and domain-specific constraints enhance schema design and reuse.

ORM Limitation:
Most Node.js ORMs do not support inheritance hierarchies at the database level. Instead, developers must simulate these relationships using manual table joins or polymorphic associations, which are more error-prone and less performant.

Practical Implications of Feature Limitations

The absence of advanced SQL feature support in Node.js ORMs has direct consequences for the development, performance, and scalability of data-intensive applications. This section outlines the tangible effects that such limitations impose on real-world systems.

A. Increased Complexity Due to Raw SQL Injection

In scenarios where ORMs do not support necessary SQL features, developers are forced to bypass ORM abstractions and write raw SQL queries. This undermines the benefits of abstraction, introduces risks such as SQL injection (when parameterization is mishandled), and complicates code maintainability.

Example:

A recursive CTE implemented via raw query:

await prisma.$queryRaw`
  WITH RECURSIVE cte AS (
    SELECT id, parent_id FROM categories WHERE parent_id IS NULL
    UNION ALL
    SELECT c.id, c.parent_id FROM categories c
    JOIN cte ON c.parent_id = cte.id
  ) SELECT * FROM cte;
`;

This approach lacks type safety, autocompletion, and the composability typically provided by ORM layers.

B. Degraded Query Performance

Inability to define partial indexes, expression indexes, or leverage materialized views through ORMs restricts the ability to optimize query execution. Applications with large datasets may suffer from poor response times and high resource consumption.

For example, a system that filters millions of rows by is_active = true cannot benefit from partial indexing if the ORM does not support it, resulting in full table scans.

C. Reduced Portability and Migration Difficulty

When advanced SQL features are used via raw queries, portability across database systems is reduced. Developers must account for dialect-specific syntax and execution semantics, defeating ORM-level database abstraction.

Additionally, migration tools bundled with ORMs (e.g., Prisma Migrate, Sequelize CLI) do not handle views, CTEs, or expression indexes, leading to fragmented schema definitions across code and migration files.

D. Inconsistent Data Modeling

The lack of support for inheritance, views, and constraints forces developers to design workarounds at the application layer. For example, emulating polymorphic associations or enforcing constraints through validation logic increases the burden on application code and can lead to data integrity issues.

E. Tooling Limitations

ORM-based code editors, linters, and type systems cannot infer structure from raw SQL, reducing developer productivity and increasing the potential for runtime errors. Automated tests may also miss edge cases if not designed with raw query paths in mind.

In summary, the absence of advanced SQL support in ORMs translates to increased complexity, performance trade-offs, and fragmented application logic. These consequences highlight the need to critically evaluate the use of ORMs in systems with complex data processing requirements.

Thanks for reading!

Advanced SQL Features Not Fully Supported by Node.js ORMs was originally published in Tech Tonic on Medium, where people are continuing the conversation by highlighting and responding to this story.

ORM frameworks have gained widespread adoption in the Node.js ecosystem due to their ability to simplify database interactions and improve developer productivity. By abstracting the underlying relational database operations into high-level, object-oriented interfaces, ORMs reduce the complexity of managing persistent data and enforce consistency across application layers. The benefits of ORM usage, including maintainability, security, and cross-database compatibility, are well documented.

However, despite these advantages, ORMs are not universally optimal for all scenarios. Certain applications require high-performance data processing, complex query capabilities, or fine-grained control over transactional behavior that exceed the abstraction capabilities of typical ORM tools. Additionally, ORM usage may introduce operational challenges such as schema migration difficulties and increased runtime overhead, particularly in serverless or microservice architectures.

This article critically examines circumstances in which direct database access or alternative approaches may be preferable to ORM frameworks within Node.js applications. Let’s get started.

1. Performance Overhead in High-Volume Transactions

ORM frameworks introduce an additional abstraction layer between application logic and the database engine, which inherently incurs some performance overhead. This overhead comes primarily in the form of metadata processing, object instantiation, and query construction within the ORM’s internal mechanisms. While these operations are often negligible in small to medium workloads, they can significantly impact performance in scenarios involving high-volume transactions or bulk data processing.

In high-throughput applications requiring rapid insertion, updating, or retrieval of large datasets, the extra CPU cycles and memory consumption associated with ORM abstractions can lead to increased latency and reduced throughput. Moreover, ORM-generated queries, while syntactically correct, are not always optimized for performance; they may contain superfluous joins, nested selects, or unneeded data retrieval that degrade execution efficiency.

Some public benchmarks have demonstrated that raw SQL queries executed via native drivers consistently outperform ORM-generated queries in bulk operations. For example, bulk insertions implemented with direct parameterized SQL statements exhibit lower latency and higher throughput compared to ORM batch operations that internally map each record to an object instance before insertion.

The following code shows the difference:

Raw SQL Bulk Insert Using pg Library:

async function bulkInsertUsers(users) {
  // Construct bulk insert query using parameterized values
  const values = users.map((user, i) => `($${i * 2 + 1}, $${i * 2 + 2})`).join(', ');
  const query = `INSERT INTO users (name, email) VALUES ${values}`;
  const params = users.flatMap(user => [user.name, user.email]);
  await pool.query(query, params);
}

ORM Bulk Insert Using Sequelize:

async function bulkInsertUsers(users) {
  await User.bulkCreate(users); // Each user mapped to model instance internally
}

2. Limited SQL Expression and Complex Querying

In the raw SQL version, the query is constructed explicitly and executed directly, minimizing overhead. In contrast, the ORM version requires Sequelize to instantiate model objects for each record, validate fields, and generate individual insert queries or batch statements, which introduces computational overhead and memory usage.

While ORM frameworks simplify the implementation of common database operations, they impose limitations when expressing complex or highly optimized SQL queries. ORMs typically provide abstractions that cover standard CRUD operations and basic filtering or sorting logic. However, expressing advanced SQL constructs — such as Common Table Expressions (CTEs), window functions, recursive queries, or database-specific optimization hints — may either be unsupported or result in verbose, unreadable syntax.

This limitation becomes more visible in applications requiring analytical queries, multi-level aggregations, or fine-grained control over execution plans. In such cases, the ORM’s high-level interface may obscure critical database semantics or fail to expose advanced query capabilities available in the underlying relational engine.

Developers may attempt to work around these constraints using ORM-specific query builders or raw query escape hatches, but these solutions often reduce the benefits of using an ORM in the first place. Furthermore, reliance on undocumented or inconsistent query-generation behavior may lead to fragile implementations that break across versions or database dialects.

The following example illustrates the difference:

Raw SQL Using pg:

async function getTopUsersByPostCount() {
  const query = `
    SELECT id, name, post_count FROM (
      SELECT users.id, users.name, COUNT(posts.id) AS post_count,
             RANK() OVER (ORDER BY COUNT(posts.id) DESC) AS rank
      FROM users
      LEFT JOIN posts ON users.id = posts.user_id
      GROUP BY users.id
    ) ranked_users
    WHERE rank <= 3
  `;
  const result = await pool.query(query);
  return result.rows;
}

ORM Attempt Using Sequelize:

// Sequelize does not natively support window functions in a composable way.
// A raw query is required for such operations.
async function getTopUsersByPostCount() {
  const [results] = await sequelize.query(`
    SELECT id, name, post_count FROM (
      SELECT users.id, users.name, COUNT(posts.id) AS post_count,
             RANK() OVER (ORDER BY COUNT(posts.id) DESC) AS rank
      FROM users
      LEFT JOIN posts ON users.id = posts.user_id
      GROUP BY users.id
    ) ranked_users
    WHERE rank <= 3
  `);
  return results;
}

In this case, the use of raw SQL is mandatory even when using an ORM, as the abstraction layer does not expose mechanisms to define window functions or derived tables in a structured, type-safe manner. The need to bypass the ORM undermines its core advantages and introduces inconsistencies in code structure.

3. Lack of Fine-Grained Transaction and Locking Control

Transactions are a foundational mechanism in relational databases for ensuring atomicity, consistency, isolation, and durability (ACID). In advanced application scenarios — particularly those involving concurrent updates, conditional writes, or resource locking — fine-grained control over transaction semantics is essential. While ORM frameworks provide basic support for transactional operations, they often abstract away or limit access to critical features such as isolation levels, advisory locks, savepoints, and conflict resolution mechanisms.

ORMs typically expose transactions through high-level wrappers or callback-based execution contexts, which are sufficient for simple commit/rollback workflows. However, this abstraction becomes restrictive in use cases requiring precise control over the transaction lifecycle, such as retryable writes, multi-phase commit protocols, or deadlock avoidance strategies. Furthermore, integration with database-specific locking primitives (e.g., SELECT ... FOR UPDATE, LOCK TABLE, or advisory locking functions) is frequently incomplete or unsupported.

The following example illustrates the difference:

Raw SQL with Advisory Locking and Isolation Level:

async function updateBalanceWithLock(userId, amount) {
  const client = await pool.connect();
  try {
    await client.query('BEGIN ISOLATION LEVEL SERIALIZABLE');

    // Acquire advisory lock
    await client.query('SELECT pg_advisory_xact_lock($1)', [userId]);

    const result = await client.query(
      'SELECT balance FROM accounts WHERE user_id = $1 FOR UPDATE',
      [userId]
    );
    const currentBalance = result.rows[0].balance;
    const newBalance = currentBalance + amount;

    await client.query(
      'UPDATE accounts SET balance = $1 WHERE user_id = $2',
      [newBalance, userId]
    );

    await client.query('COMMIT');
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }
}

ORM (Sequelize) Equivalent — Limited Capability:

async function updateBalance(userId, amount) {
  const t = await sequelize.transaction({ isolationLevel: 'SERIALIZABLE' });
  try {
    const account = await Account.findOne({ where: { userId }, transaction: t, lock: t.LOCK.UPDATE });
    account.balance += amount;
    await account.save({ transaction: t });
    await t.commit();
  } catch (err) {
    await t.rollback();
    throw err;
  }
}

While the ORM version supports transaction boundaries and row-level locking, it does not support advisory locking or custom transaction logic without falling back to raw SQL. Moreover, handling database-specific exceptions or implementing retry logic in the context of ORM-managed transactions is non-trivial due to the lack of low-level control over the execution flow.

4. Schema Management and Migration Friction

In relational databases, schema evolution is a critical aspect of long-term application maintenance. It consists of the creation, alteration, and deprecation of tables, columns, constraints, indexes, and relationships. While ORM frameworks often integrate schema migration tooling, their abstractions introduce friction in maintaining alignment between application models and actual database schemas, especially in large-scale or heterogeneous environments.

ORM-based migration tools typically generate schema change scripts based on differences detected in model definitions. However, this process is inherently fragile and may yield inaccurate or non-deterministic results in complex schema scenarios, such as composite keys, partial indexes, or conditional constraints. Furthermore, automated diffing mechanisms can lead to silent regressions when coupled with implicit conventions or misconfigured data types.

Direct database access combined with manually curated migration scripts offers greater reliability and auditability. Hand-written migrations allow teams to explicitly define and review all schema changes, enforce consistent naming conventions, and integrate database-specific features. They also improve compatibility across environments where schema versions may diverge due to race conditions, partial deployments, or tooling inconsistencies.

The following example demonstrates a schema migration using direct SQL with the node-pg-migrate tool:

Manual Migration Script (PostgreSQL, using node-pg-migrate):

exports.up = (pgm) => {
  pgm.createTable('users', {
    id: { type: 'serial', primaryKey: true },
    email: { type: 'varchar(255)', notNull: true, unique: true },
    created_at: { type: 'timestamp', notNull: true, default: pgm.func('now()') },
  });

  pgm.addIndex('users', 'email', { unique: true });
};

exports.down = (pgm) => {
  pgm.dropTable('users');
};

ORM Schema Definition and Migration (Sequelize):

// Model definition
const User = sequelize.define('User', {
  email: {
    type: DataTypes.STRING,
    allowNull: false,
    unique: true,
  },
  createdAt: {
    type: DataTypes.DATE,
    allowNull: false,
    defaultValue: Sequelize.NOW,
  },
});

// Migration generated via CLI (simplified)
module.exports = {
  up: async (queryInterface, Sequelize) => {
    await queryInterface.createTable('Users', {
      id: { type: Sequelize.INTEGER, autoIncrement: true, primaryKey: true },
      email: { type: Sequelize.STRING, allowNull: false, unique: true },
      createdAt: { type: Sequelize.DATE, allowNull: false, defaultValue: Sequelize.NOW },
    });
  },
  down: async (queryInterface) => {
    await queryInterface.dropTable('Users');
  },
};

Although ORM migrations provide convenience, they tightly couple schema changes to the ORM’s internal representations, leading to versioning issues and incompatibilities in projects that demand precision. Additionally, ORM-generated migrations often lack support for full-text indexing, geospatial columns, or database triggers — requiring supplemental raw SQL injections and breaking consistency.

5. Debugging, Logging, and Error Transparency

Effective debugging and monitoring are critical requirements in production-grade applications. When interacting with relational databases, clear visibility into executed queries, associated parameters, execution plans, and error propagation paths is essential for diagnosing faults, identifying performance bottlenecks, and ensuring query correctness. ORM frameworks, by virtue of abstraction, often obfuscate this visibility, hindering fine-grained introspection.

ORMs typically encapsulate query generation and execution, which results in loss of direct access to the actual SQL statements executed against the database. While some frameworks provide limited query logging, the logs may omit parameter values, normalize whitespace, or truncate large queries, thereby impeding root cause analysis. Additionally, ORM-level exceptions are frequently generalized or wrapped in custom error classes, which obscure the original database error codes and messages necessary for accurate remediation.

In contrast, applications using raw SQL via native drivers offer complete transparency and granular logging. Developers retain full control over query formatting, parameter binding, and error handling, thereby enabling precise instrumentation and integration with observability tooling.

Example: Raw SQL with Detailed Logging Using pg Library

async function getUserByEmail(email) {
  const query = 'SELECT * FROM users WHERE email = $1';
  console.log('Executing Query:', query, 'Parameters:', [email]);

  try {
    const res = await pool.query(query, [email]);
    return res.rows[0];
  } catch (err) {
    console.error('Database Error:', err.code, err.message);
    throw err;
  }
}

ORM Equivalent (Sequelize) with Limited Logging:

const user = await User.findOne({ where: { email } });
// Underlying query is not directly visible unless logging is enabled

Enabling Sequelize Logging (with Limitations):

const sequelize = new Sequelize(DB_URI, {
  logging: (msg) => console.log('ORM Query:', msg),
});

Even with explicit logging enabled, the Sequelize ORM logs only the final SQL string, typically without bound parameter values or context-specific metadata. This limits traceability in multi-user or multi-tenant applications, where precise parameter matching is necessary for security and audit purposes.

Furthermore, the error-handling model in most ORMs abstracts vendor-specific error codes (e.g., PostgreSQL’s 23505 for unique constraint violations) into high-level error types. This generalization complicates the implementation of fine-grained retry policies or conditional logic based on error semantics.

Thanks for reading!

When Not to Use ORM: Performance and Flexibility Considerations in Node.js Applications was originally published in Tech Tonic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Node.js has become a prominent runtime environment for developing scalable and efficient server-side applications, particularly due to its event-driven, non-blocking I/O model. A critical component of most Node.js applications is database interaction, which can be implemented either through direct database access using raw SQL queries or by using Object-Relational Mapping (ORM) tools. Direct database access provides fine-grained control over queries and operations, but it often leads to verbose code, higher complexity, and increased risk of errors.

Object-Relational Mapping (ORM) is a programming technique that facilitates the conversion of data between incompatible systems using object-oriented paradigms. In the world of Node.js, ORM tools such as Sequelize, TypeORM, and Prisma provide abstractions over relational databases, enabling developers to interact with data using objects and class definitions rather than writing raw SQL queries. This abstraction simplifies many aspects of database management and aligns with modern software engineering practices.

This article presents five critical advantages of using ORM over direct database access in Node.js applications. Let’s get started.

1. Code Abstraction and Maintainability

One of the principal advantages of using an ORM in Node.js applications is the abstraction it provides over raw SQL queries. In traditional database access patterns, developers are required to manually construct SQL statements and handle query execution. This leads to repetition, increased verbosity, and tightly coupled logic, all of which negatively affect maintainability.

ORMs encapsulate query logic within object-oriented interfaces and reusable models. These abstractions allow developers to define data schemas using high-level constructs, which enhances readability and reduces the cognitive load associated with interpreting raw queries. As applications scale, this abstraction becomes increasingly beneficial for maintaining large codebases and enforcing consistency across database operations.

The following example illustrates the distinction:

Raw SQL (Using pg library):

// db.js
const { Pool } = require('pg');
const pool = new Pool();

async function getUserByEmail(email) {
  const query = 'SELECT id, name, email FROM users WHERE email = $1';
  const values = [email];
  const result = await pool.query(query, values);
  return result.rows[0];
}

Using ORM (Sequelize):

// models/User.js
const { Sequelize, DataTypes } = require('sequelize');
const sequelize = new Sequelize(/* config */);

const User = sequelize.define('User', {
  name: DataTypes.STRING,
  email: DataTypes.STRING
});

// elsewhere in application logic
async function getUserByEmail(email) {
  return await User.findOne({ where: { email } });
}

In the ORM version, the model definition and retrieval logic are separated, promoting modularity and reuse. The SQL query is abstracted away, and the intent is clearly expressed through high-level syntax.

2. Improved Productivity and Developer Experience

ORM frameworks significantly enhance developer productivity by reducing the amount of boilerplate code required to perform routine database operations. ORM tools offer high-level APIs, built-in schema synchronization, and automatic query generation, which collectively streamline development workflows. This improvement in efficiency is particularly relevant in agile environments where rapid iteration and frequent schema changes are common.

Furthermore, modern ORMs integrate with popular IDEs to provide features such as auto-completion, type checking, and inline documentation. These capabilities reduce context-switching and minimize syntactic or logical errors during development. By abstracting repetitive tasks, ORMs allow developers to focus on business logic rather than database syntax, thereby improving overall velocity and code quality.

The difference in productivity can be seen in the following example:

Raw SQL (Using pg library):

async function createUser(name, email) {
  const query = 'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id';
  const values = [name, email];
  const result = await pool.query(query, values);
  return result.rows[0].id;
}

Using ORM (Sequelize):

async function createUser(name, email) {
  const newUser = await User.create({ name, email });
  return newUser.id;
}

In the ORM version, the insertion logic is expressed in a single, declarative line without the need to construct query strings or manually handle value interpolation. Additionally, the ORM internally handles data type mapping, escaping, and schema validations, which would otherwise require explicit implementation in raw SQL.

3. Cross-Database Compatibility

ORM frameworks are designed to provide a unified interface for interacting with various relational database management systems (RDBMS). This abstraction enables applications to remain largely agnostic to the underlying database engine, thus simplifying database migrations and reducing vendor lock-in. In contrast, applications that rely on raw SQL are tightly coupled to the specific syntax, functions, and capabilities of the chosen RDBMS, leading to increased maintenance overhead when switching database systems.

ORMs achieve cross-database compatibility by internally translating high-level operations into dialect-specific SQL queries. Most modern ORMs support multiple dialects (e.g., PostgreSQL, MySQL, SQLite, and Microsoft SQL Server) through configurable adapters or dialect modules. This capability allows teams to develop and test applications against one database engine and deploy them to another with minimal changes to application logic.

The following example demonstrates this critical advantage:

Using ORM (Sequelize):

// config/sequelize.js
const { Sequelize } = require('sequelize');

const sequelize = new Sequelize('database_name', 'username', 'password', {
  host: 'localhost',
  dialect: 'postgres' // Can be changed to 'mysql', 'sqlite', etc.
});

module.exports = sequelize;

Model and Query (Dialect-Independent):

// models/User.js
const { DataTypes } = require('sequelize');
const sequelize = require('../config/sequelize');

const User = sequelize.define('User', {
  name: DataTypes.STRING,
  email: DataTypes.STRING
});

// data access
async function getAllUsers() {
  return await User.findAll();
}

In this example, the application logic remains unchanged regardless of whether the underlying database is PostgreSQL, MySQL, or SQLite. Only the dialect parameter in the configuration needs to be updated. This level of decoupling is not feasible when using raw SQL, where even basic syntax differences (e.g., LIMIT vs. TOP) require conditional logic or entirely separate query definitions.

4. Built-in Security Features

Security is a fundamental requirement in application development, particularly when dealing with persistent data storage. One of the inherent advantages of ORM frameworks is the inclusion of built-in security mechanisms that mitigate common vulnerabilities associated with direct SQL access. The most notable among these is protection against SQL injection, a critical threat in applications that construct raw queries using dynamic user input.

ORMs address this issue by using parameterized queries and escaping mechanisms automatically during query construction. These protections are enforced consistently across all query methods, eliminating the need for manual sanitization or query validation logic. In contrast, direct database access requires developers to manually ensure that all input is properly escaped and parameterized, increasing the risk of oversight and human error.

The following example illustrates the difference in handling user input.

Raw SQL (Unsafe Example Using pg):

async function findUserUnsafe(email) {
  const query = `SELECT * FROM users WHERE email = '${email}'`; // vulnerable to SQL injection
  const result = await pool.query(query);
  return result.rows[0];
}

Raw SQL (Safe Parameterized Version):

async function findUserSafe(email) {
  const query = 'SELECT * FROM users WHERE email = $1';
  const result = await pool.query(query, [email]);
  return result.rows[0];
}

ORM Version (Sequelize):

async function findUser(email) {
  return await User.findOne({ where: { email } }); // parameterization handled internally
}

In the ORM example, parameterization is implicit. The framework constructs the appropriate SQL query using dialect-specific escaping and binding methods, thereby ensuring that user-provided values are never directly embedded into raw query strings. This eliminates the possibility of injection attacks under standard usage patterns.

In addition to query-level protections, many ORM tools also support features such as model-level validation, input sanitization, and role-based access control when integrated with application-level authorization mechanisms.

5. Easier Data Relationships and Modeling

Relational databases are fundamentally designed around the concept of data normalization, where complex entities are distributed across multiple related tables. Managing these relationships — such as one-to-one, one-to-many, and many-to-many — requires careful construction of SQL queries, joins, and foreign key constraints. When using direct database access, such operations often involve verbose, error-prone SQL that must be manually maintained.

ORM frameworks simplify relationship modeling by enabling developers to define associations directly in the application layer using declarative syntax. These associations are represented as object references, allowing seamless navigation and querying across related entities without explicitly writing JOIN clauses. This abstraction enhances both the expressiveness and clarity of data access logic.

The following example demonstrates how a one-to-many relationship between User and Post entities is modeled and queried.

Raw SQL (Using pg, One-to-Many Query):

async function getPostsByUser(userId) {
  const query = `
    SELECT posts.id, posts.title
    FROM posts
    INNER JOIN users ON users.id = posts.user_id
    WHERE users.id = $1
  `;
  const result = await pool.query(query, [userId]);
  return result.rows;
}

ORM Version (Sequelize, with Relationship Mapping):

// models/User.js
const User = sequelize.define('User', {
  name: DataTypes.STRING,
});

// models/Post.js
const Post = sequelize.define('Post', {
  title: DataTypes.STRING,
});

// Define relationship
User.hasMany(Post, { foreignKey: 'user_id' });
Post.belongsTo(User, { foreignKey: 'user_id' });

// Query with ORM
async function getPostsByUser(userId) {
  const user = await User.findByPk(userId, {
    include: [{ model: Post }]
  });
  return user.Posts;
}

In the ORM example, relationships are modeled once using high-level method calls such as hasMany and belongsTo. The resulting association can then be leveraged across the application to execute related queries without explicitly specifying join conditions. This not only reduces the amount of code but also minimizes the likelihood of errors arising from incorrectly written joins or mismatched foreign keys.

Thanks for reading!

5 Key Advantages of Using ORM over Direct Database Access in Node.js Applications was originally published in Tech Tonic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Node.js: The fastest web framework in 2025 — Static file server case

Introduction

This article serves as the 2025 update to one of my most widely read pieces over the past three years. At the start of 2024, I published a comparative analysis of the most popular web frameworks in the Node.js ecosystem. That article & the series continues to attract significant traffic and remains the top result on Google for its topic.

In the previous & first article of this series, we’ve already seen how the frameworks compare to each other for the simplest hello world case. The results (RPS only) are summarized below:

Node.js: The fastest web framework in 2025

From this article, we’ll start looking at more practical use cases. In this article, the second in the series, we’ll take a comparative look at the case of static file servers.

NOTE: The winner from ‘hello world case’, hyper express, is dropped out of this comparison. HyperExpress uses LiveDirectory to load all the files in memory, which makes it impractical. I have 100K files in my test environment, and loading them into memory is totally impractical.

If you happen to see this article first, you can see others in this series here:

• Fastest web framework in 2025 — Hello world case

Test setup

All tests are executed on MacBook Pro M2 with 16G RAM. There are 8+4 CPU cores. The Node.js version is v23.11.1 (latest at the time of writing).

The load tester is a modified version of Bombardier (written in Go) that can send a different static URL for each request.

There are 100K files in the static directory. Each file size is exactly 10K (102400 bytes).

The code for each application is as follows:

Express

import express from "express";

const app = express();

app.use(
  "/static",
  express.static("/Users/mayankc/Work/source/perfComparisons/static"),
);

app.listen(3000);

Fastify

const fastify = require("fastify");
const app = fastify();

app.register(require("@fastify/static"), {
  root: "/Users/mayankc/Work/source/perfComparisons/static",
  prefix: "/static/",
  prefixAvoidTrailingSlash: true,
});

app.listen({ port: 3000 });

Hapi

const Hapi = require("@hapi/hapi");

const start = async () => {
  const server = Hapi.server({
    routes: {
      files: {
        relativeTo: "/Users/mayankc/Work/source/perfComparisons/static",
      },
    },
    port: 3000,
    host: "127.0.0.1",
  });

  await server.register(require("@hapi/inert"));

  server.route({
    method: "GET",
    path: "/static/{filename}",
    handler: {
      file: function (request) {
        return request.params.filename;
      },
    },
  });

  await server.start();
};

start();

Koa

import Koa from "koa";
import serve from "koa-static";
import mount from "koa-mount";

const app = new Koa();
app.use(
  mount("/static", serve("/Users/mayankc/Work/source/perfComparisons/static")),
);

app.listen(3000);

Restify

import restify from "restify";

var server = restify.createServer();
server.get(
  "/static/*",
  restify.plugins.serveStaticFiles(
    "/Users/mayankc/Work/source/perfComparisons/static",
  ),
);
server.listen(3000);

Ultimate Express

import express from "ultimate-express";

const app = express();

app.use(
  "/static",
  express.static("/Users/mayankc/Work/source/perfComparisons/static"),
);

app.listen(3000);

NestJS

main.ts

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}

bootstrap();

app.module.ts

import { Module } from "@nestjs/common";
import { ServeStaticModule } from "@nestjs/serve-static";
import { AppController } from "./app.controller";

@Module({
  imports: [
    ServeStaticModule.forRoot({
      rootPath: "/Users/mayankc/Work/source/perfComparisons/static",
      serveRoot: "/static",
    }),
  ],
  controllers: [AppController],
  providers: [],
})
export class AppModule {}

app.controller.ts

import { Controller, Get } from "@nestjs/common";

@Controller()
export class AppController {
  constructor() {}

  @Get()
  getHello(): string {
    return "Hello, world!";
  }
}

NestJS Fastify

main.ts

import { NestFactory } from "@nestjs/core";
import {
  FastifyAdapter,
  NestFastifyApplication,
} from "@nestjs/platform-fastify";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter(),
  );
  app.useStaticAssets({
    root: "/Users/mayankc/Work/source/perfComparisons/static",
    prefix: '/static/',
  });
  await app.listen(3000);
}
bootstrap();

app.module.ts

import { Module } from "@nestjs/common";
import { AppController } from "./app.controller";

@Module({
  imports: [],
  controllers: [AppController],
  providers: [],
})
export class AppModule {}

app.controller.ts

import { Controller, Get } from "@nestjs/common";

@Controller()
export class AppController {
  constructor() {}

  @Get()
  getHello(): string {
    return "Hello, world!";
  }
}

Results

A total of 200K requests are executed for 100 concurrent connections. Along with latencies, I’ve also collected CPU and memory usage. This gives a complete picture. Just having high RPS is not enough. We also need to know the cost of the RPS.

The results in chart form are as follows:

Verdict

To begin with, the results for a practical scenario like serving static files differ significantly from the theoretical “Hello, world” benchmark. In this test, the requests per second (RPS) for most frameworks fall within a relatively narrow range of 8,000 to 9,500, indicating minimal performance variance across the board.

Notably, Express, which ranked lowest in the previous benchmark, climbs to second place in this round. This improvement may reflect the benefits of its long-standing maturity and ongoing optimizations over the years.

The top performer in this category is Restify, which delivers the highest throughput while maintaining relatively low resource consumption — making it a strong candidate for static content delivery.

Interestingly, Ultimate-Express, which led the previous round, ranks at the bottom this time, highlighting how performance can vary significantly depending on the nature of the workload.

Winner: Restify

If you happen to see this article first, you can see others in this series here:

• Fastest web framework in 2025 — Hello world case

Node.js: The fastest web framework in 2025 — Static file server case was originally published in Tech Tonic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

This article serves as the 2025 update to one of my most widely read pieces over the past three years. At the start of 2024, I published a comparative analysis of the most popular web frameworks in the Node.js ecosystem. That article continues to attract significant traffic and remains the top result on Google for its topic.

Node.js: The fastest web framework in 2024

However, given the rapid pace of change in the web development landscape, that piece, now over 18 months old, no longer reflects the current state of the ecosystem. As we approach mid-2025, it’s time for a comprehensive refresh.

Coincidentally, TechEmpower has also released Round 23 of their widely respected benchmarking series:

TechEmpower Web Framework Performance Comparison
Performance comparison of a wide spectrum of web application frameworks and platforms using community-contributed tests.
www.techempower.com

This new series of articles builds upon TechEmpower’s findings, with a specific focus on resource usage and latency in addition to raw requests per second (RPS).

The series will progress through multiple layers of real-world web application complexity — from the classic “Hello, world” example to handling JSON data, serving static files, performing database reads, and ultimately implementing practical use cases such as a URL shortener, a QR code generator, and JWT-based MySQL record access.

In this first installment, we begin with the foundational “Hello, world” example. While not practical on its own, it serves as a consistent and neutral baseline for all subsequent benchmarks.

Let’s dive in.

Before you read further, the other articles in this series are:

• Fastest web framework in 2025 — Static file server case

Testing Environment

All tests are executed on a MacBook Pro M2 with 16G RAM. There are 8+4 CPU cores. The load tester is Bombardier (written in Go). The Node.js version is v23.11.1 (latest stable release at the time of writing).

I’m including Node’s native server too. This gives a good baseline for all the other frameworks. It is well known that Node’s native server is pretty much a bare-bones server.

The code for each application is as follows:

Native

import http from "node:http";

const reqHandler = (req, resp) => {
  try {
    if (req.method !== "GET") {
      return resp.writeHead(405).end();
    }
    if (req.url !== "/") {
      return resp.writeHead(404).end();
    }
    resp.writeHead(200, {
      "content-type": "text/plain",
    });
    resp.end("Hello world");
  } catch (e) {
    resp.writeHead(500).end();
  }
};

http.createServer(reqHandler).listen(3000);

Note: Native code is longer so that it is close to the other frameworks where we usually don’t see this code.

Express

(Etag is disabled because other frameworks doesn’t send it by default)

import express from "express";

const app = express();

const reqHandler = (req, res) => {
  res.send("Hello World!");
};

app.disable("etag");
app.get("/", reqHandler);

app.listen(3000, () => console.log("Listening on 3000"));

Fastify

import Fastify from "fastify";

const fastify = Fastify({
  logger: false,
});

const reqHandler = (request, reply) => {
  reply.send("Hello World!");
};

fastify.get("/", reqHandler);

fastify.listen({ port: 3000 });

Koa

import Koa from "koa";
import Router from "@koa/router";

const app = new Koa();
const router = new Router();

const reqHandler = (ctx, next) => {
  ctx.body = "Hello World!";
};

router.get("/", reqHandler);

app
  .use(router.routes())
  .use(router.allowedMethods());

app.listen(3000);

Hapi

import Hapi from "@hapi/hapi";
const server = Hapi.server({
  port: 3000,
  host: "127.0.0.1",
});

const reqHandler = (request, h) => {
  return "Hello World!";
};

server.route({
  method: "GET",
  path: "/",
  handler: reqHandler,
});

server.start();

Restify

import restify from "restify";

const reqHandler = (req, res, next) => {
  res.contentType = "text/plain";
  res.send("Hello World!");
  next();
};

var server = restify.createServer();
server.get("/", reqHandler);
server.listen(3000);

Hyper-Express

import HyperExpress from "hyper-express";
const webserver = new HyperExpress.Server();

const reqHandler = (request, response) => {
  response.send("Hello World!");
};

webserver.get("/", reqHandler);
webserver.listen(3000);

Ultimate-Express

New entrant this time.

import express from "ultimate-express";

const app = express();

const reqHandler = (req, res) => {
  res.send("Hello World!");
};

app.get("/", reqHandler);

app.listen(3000, () => console.log("Listening on 3000"));

NestJS

(The NestJS app code is generated through their CLI. Only few relevant files are shown here)

main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.getHttpAdapter().getInstance().set('etag', false);
  await app.listen(3000);
}
bootstrap();

app.module.ts

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

app.controller.ts

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }
}

app.service.ts

import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

NestJS (Fastify)

By default, NestJS uses express adapter. Therefore, the performance is slightly worse than Express (which itself is the slowest in this lot). Fortunately, NestJS allows configuring fastify adapter instead of express.

main.ts

import { NestFactory } from "@nestjs/core";
import {
  FastifyAdapter,
  NestFastifyApplication,
} from "@nestjs/platform-fastify";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter(),
  );

  await app.listen(3000);
}
bootstrap();

All other files are same as NestJS (express).

Results

A total of 1M requests are executed for 100 concurrent connections. Along with latencies, I’ve also collected CPU and memory usage. This gives a complete picture. Just having high RPS is not enough. We also need to know the cost of the RPS.

The results in chart form are as follows:

Verdict

Before diving into the analysis, it’s important to acknowledge that this comparison includes a diverse mix of frameworks — ranging from lightweight libraries to feature-rich, opinionated platforms. Among them, NestJS (available with both Express and Fastify underpinnings) stands out as a full-fledged application framework, offering significantly more built-in functionality than most others in this list. As such, comparing NestJS directly with minimalist frameworks like Koa may not be entirely equitable.

In terms of raw performance, Express emerges as the slowest, handling approximately 20,000 requests per second. However, it’s worth emphasizing that Express has stood the test of time. It remains the most mature, reliable, and widely adopted web framework in the Node.js ecosystem. Despite lagging in raw throughput, Express continues to be a dominant force and is unlikely to lose its relevance any time soon.

At the other end of the spectrum, Hyper-Express retains its position as the fastest option, consistent with the findings from the 2024 analysis. Close behind is Ultimate-Express, which also demonstrates excellent performance. Both leverage uWebSockets under the hood, enabling similar high-throughput characteristics.

As for my personal recommendation, I lean toward Fastify (or Nest-Fastify) as a balanced choice. It consistently delivers solid performance — approximately 87,000 requests per second — while maintaining the reliability and robustness expected from a production-ready framework.

Winner: HyperExpress

This was only about the do-nothing ‘hello world’ server. The winning margins might not be as wide for more complex cases. I’ll get to them very soon.

Once again, the other articles in this series are:

• Fastest web framework in 2025 — Static file server case

Node.js: The fastest web framework in 2025 was originally published in Tech Tonic on Medium, where people are continuing the conversation by highlighting and responding to this story.

With React 19, the development experience becomes more fluid and user-centric, thanks in part to new hooks like useOptimistic. This hook addresses a long-standing challenge in frontend development—how to make interfaces feel fast and responsive when dealing with asynchronous updates, especially in form submissions, list modifications, or API-driven state transitions.

What Is useOptimistic?

The useOptimistic hook allows you to optimistically update the UI by predicting the final state of an asynchronous operation before it actually completes. Instead of waiting for a server response to reflect a change, your interface can immediately show the intended result, giving users instant feedback and a smoother experience.

Internally, useOptimistic works by layering a temporary optimistic state over the current actual state. When the async task finishes, the real state replaces or reconciles with the optimistic one. This helps bridge the perceptual gap between user actions and server acknowledgment.

Why is this needed?

Before useOptimistic, implementing such a feature often required writing complex custom logic—duplicating state management, manually rolling back changes on failure, and syncing server data. This led to bloated components and fragile UI behavior. The useOptimistic hook simplifies this pattern and makes it declarative.

Syntax overview

const [optimisticState, addOptimistic] = useOptimistic(
  baseState,
  (previousState, optimisticUpdate) => {
    // return a new optimistic state
  }
);

Parameters:

1. baseState: The current, committed state from the server or authoritative data source. This should be a value you trust to be accurate, such as the result of a useState, useReducer, or fetched response.
2. reducerFn(previousState, optimisticUpdate): A pure function that defines how each new optimistic update transforms the current optimistic state. It’s similar in spirit to a reducer in useReducer, but it's applied to maintain an ephemeral state layer over baseState.

Returns:

• optimisticState – This is what should be rendered in the UI. It's a blend of the base state and any applied optimistic updates.
• addOptimistic(updatePayload) – A function you call when you want to simulate a change instantly. It accepts a payload that reducerFn will use to compute the next optimistic state.

Internal flow

Here’s how useOptimistic behaves in practice:

1. The UI renders using optimisticState.
2. When a user triggers an action (e.g., form submission), you:

• Call addOptimistic(payload) to show the optimistic change.
• Fire off an async task to persist the change to a backend.
• Once the task resolves, you update baseState to the server-confirmed state via setState, setTodos, or similar.

3. The optimistic layer is then reconciled or discarded.

This pattern ensures your interface stays fast and responsive even while waiting for real-world delays like API roundtrips.

Code sample 1: Basic counter

This example demonstrates a simple use case of incrementing a counter optimistically.

'use client'; // needed for client components

import { useOptimistic, useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);
  const [optimisticCount, addOptimistic] = useOptimistic(count, (prev, next) => prev + next);

  const increment = async () => {
    addOptimistic(1); // show immediately
    await fakeAPICall(); // simulate server sync
    setCount((c) => c + 1); // commit real state
  };

  return (
    <div>
      <p>Count: {optimisticCount}</p>
      <button onClick={increment}>+1</button>
    </div>
  );
}

async function fakeAPICall() {
  return new Promise((res) => setTimeout(res, 1000));
}

• The UI shows the new count instantly.
• The real state count is updated once the fake API call completes.
• This structure mimics how real-time apps (like chat or notification systems) behave.

Code sample 2: Optimistic to-do list

Imagine a to-do list where new tasks are shown immediately after submission, even though the server response may take a second or two.

'use client';

import { useOptimistic, useState } from 'react';

export default function TodoList() {
  const [todos, setTodos] = useState([{ id: 1, title: 'Learn React 19' }]);

  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    (prev, next) => [...prev, next]
  );

  const handleAdd = async (title) => {
    const newTodo = { id: Date.now(), title };
    addOptimisticTodo(newTodo); // temporary optimistic view

    const serverTodo = await saveToServer(newTodo);
    setTodos((t) => [...t, serverTodo]); // update real state
  };

  return (
    <div>
      <ul>
        {optimisticTodos.map((todo) => (
          <li key={todo.id}>{todo.title}</li>
        ))}
      </ul>
      <button onClick={() => handleAdd('Write docs')}>Add Task</button>
    </div>
  );
}

async function saveToServer(todo) {
  return new Promise((res) =>
    setTimeout(() => res({ ...todo, id: Math.random() * 10000 }), 1500)
  );
}

• Optimistic updates prevent flickers or perceived lags in dynamic UIs.
• The server may return a different id, so reconciling it back into the real state is crucial.
• This pattern improves UX while retaining data integrity.

Code sample 3: Error handling & rollback

Optimistic updates should also handle failures gracefully. In this example, we simulate a rollback if the server call fails.

'use client';

import { useOptimistic, useState } from 'react';

export default function FriendRequest() {
  const [status, setStatus] = useState('Not Sent');
  const [optimisticStatus, addOptimisticStatus] = useOptimistic(status, (_, next) => next);

  const sendRequest = async () => {
    addOptimisticStatus('Sending...');
    try {
      await sendToServer(); // may fail
      setStatus('Sent');
    } catch {
      setStatus('Not Sent'); // rollback on error
    }
  };

  return (
    <div>
      <p>Status: {optimisticStatus}</p>
      <button onClick={sendRequest}>Send Friend Request</button>
    </div>
  );
}

async function sendToServer() {
  const shouldFail = Math.random() < 0.3;
  return new Promise((res, rej) =>
    setTimeout(() => (shouldFail ? rej() : res()), 1000)
  );
}

• Reflects the transient “Sending…” state immediately.
• If the server fails, we rollback to the prior state.
• Demonstrates how useOptimistic integrates with error boundaries and recovery flows.

Code Sample 4: Optimistic product rating

In this example, we optimistically update the average rating of a product as soon as the user submits a new rating.

'use client';

import { useOptimistic, useState } from 'react';

export default function ProductRating() {
  const [ratingData, setRatingData] = useState({ total: 100, count: 25 });

  const [optimisticRating, addOptimisticRating] = useOptimistic(
    ratingData,
    (prev, newRating) => {
      const updatedTotal = prev.total + newRating;
      const updatedCount = prev.count + 1;
      return { total: updatedTotal, count: updatedCount };
    }
  );

  const handleRate = async (value) => {
    addOptimisticRating(value); // optimistic feedback
    try {
      await submitRatingToServer(value);
      setRatingData((prev) => ({
        total: prev.total + value,
        count: prev.count + 1,
      }));
    } catch {
      // Handle rollback or notify user
    }
  };

  const average = (optimisticRating.total / optimisticRating.count).toFixed(1);

  return (
    <div>
      <p>Average Rating: {average}</p>
      <button onClick={() => handleRate(5)}>Rate 5 Stars</button>
    </div>
  );
}

async function submitRatingToServer(value) {
  return new Promise((res) => setTimeout(() => res(true), 1000));
}

• This simulates instant feedback on a rating action.
• The user sees the updated average immediately.
• If the server fails, error handling or a silent rollback can be added to revert the UI.

Code sample 5: Optimistic shopping cart update

In a real-time e-commerce scenario, users expect immediate updates when adding items to a cart. This example shows how to use useOptimistic to manage that.

'use client';

import { useOptimistic, useState } from 'react';

export default function ShoppingCart() {
  const [cart, setCart] = useState([{ id: '123', name: 'T-Shirt', qty: 1 }]);

  const [optimisticCart, addOptimisticItem] = useOptimistic(
    cart,
    (prevCart, newItem) => {
      const existing = prevCart.find((item) => item.id === newItem.id);
      if (existing) {
        return prevCart.map((item) =>
          item.id === newItem.id ? { ...item, qty: item.qty + newItem.qty } : item
        );
      }
      return [...prevCart, newItem];
    }
  );

  const handleAddToCart = async () => {
    const newItem = { id: '456', name: 'Cap', qty: 1 };
    addOptimisticItem(newItem);

    try {
      await fakeCartAPI(newItem);
      setCart((prev) => {
        const existing = prev.find((item) => item.id === newItem.id);
        if (existing) {
          return prev.map((item) =>
            item.id === newItem.id ? { ...item, qty: item.qty + 1 } : item
          );
        }
        return [...prev, newItem];
      });
    } catch {
      // optional rollback logic
    }
  };

  return (
    <div>
      <h3>Shopping Cart</h3>
      <ul>
        {optimisticCart.map((item) => (
          <li key={item.id}>
            {item.name} - Qty: {item.qty}
          </li>
        ))}
      </ul>
      <button onClick={handleAddToCart}>Add Cap</button>
    </div>
  );
}

async function fakeCartAPI(item) {
  return new Promise((res) => setTimeout(() => res(true), 1000));
}

• Demonstrates how to merge new items or update quantities optimistically.
• Avoids UI flicker by updating the cart list instantly.
• Allows for graceful degradation if the server response fails.

Best practices

• Keep optimistic updates minimal: Only reflect what’s necessary. Overextending optimistic assumptions can cause jarring rollbacks.
• Ensure reconciliation logic is robust: Sync real and optimistic states carefully, especially when the server modifies data (e.g., timestamps, IDs).
• Combine with suspense and error boundaries: For a seamless experience in server-heavy apps, pair useOptimistic with use() and suspense.

When not to use it

• Critical state updates: For banking, transactions, or sensitive operations, avoid assuming success.
• Highly unpredictable server behavior: If the outcome is frequently different from the input, optimistic updates may degrade UX rather than improve it.

Thanks for reading!

Use Optimistic hook in React 19 was originally published in Tech Tonic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

Managing AWS credentials in CI/CD pipelines can be risky and cumbersome. With OIDC federation, you can securely authenticate GitHub Actions and GitLab CI/CD pipelines to AWS without storing static credentials. In this post, we’ll walk through how to set up OIDC federation with AWS, enabling secure, short-lived access for your automation workflows — the modern way.

For Github, OIDC is supported on all plans, including Free tier and hosted runners, but for Gitlab, it’s available only if you are on Premium, Ultimate, or using GitLab-hosted runners that support OIDC

What is OIDC Federation?

Modern cloud security favors short-lived, identity-based credentials over long-lived static access keys. That’s where OIDC (OpenID Connect) Federation comes in.

OIDC is an authentication protocol based on OAuth 2.0 that allows external identity providers (like GitHub Actions or GitLab CI) to securely federate access to AWS — without creating or storing long-term credentials.

Why Use OIDC in CI/CD?

Traditionally, teams use IAM users or long-lived access keys in GitHub/GitLab to access AWS. This approach is:

• ❌ Hard to rotate securely
• ❌ Risky if leaked (especially in public repos)
• ❌ Shared across environments or pipelines

OIDC solves this by allowing GitHub or GitLab to assume a role in AWS securely at runtime using an identity token, with no secrets stored in your code or pipeline.

How It Works

1. In your cloud provider, create an OIDC trust between your cloud role and your GitHub workflow(s) that need access to the cloud.
2. Every time a workflow runs, GitHub’s OIDC provider auto-generates a signed OIDC token. This token contains claims like the repository, branch, workflow, and job context — establishing a secure and verifiable identity about the job.
3. The workflow presents this token to AWS using sts:AssumeRoleWithWebIdentity.
4. AWS validates the claims and issues temporary cloud credentials to the job — valid only for the duration of the run.

Creating an OIDC Trust in AWS (GitHub & GitLab)

Now that we understand the power of OIDC Federation, the next step is to create that trust between AWS and your CI/CD platform.

This trust is what allows GitHub or GitLab to assume an IAM role — using an OIDC token — without any AWS access keys.

Step 1: Create an OIDC Identity Provider in AWS

An Identity Provider (IdP) in AWS is what lets you register GitHub or GitLab as a trusted issuer of identity tokens. You only need to do this once per account per CI/CD provider.

GitHub OIDC Setup

1. Go to the AWS Console → IAM → Identity providers → Add provider
2. Choose:

• Provider type: OpenID Connect
• Provider URL: https://token.actions.githubusercontent.com
• Audience: sts.amazonaws.com

3. Click Add provider

This tells AWS to trust tokens issued by GitHub Actions, as long as the token’s audience is AWS STS (Security Token Service). In your GitHub workflow, make sure to explicitly request an OIDC token by setting:

permissions:
  id-token: write
  contents: read

GitLab OIDC Setup

If you’re using GitLab-hosted runners (with Premium or Ultimate tier), you can use their native OIDC integration.

1. Go to the AWS Console → IAM → Identity providers → Add provider
2. Choose:

• Provider type: OpenID Connect
• Provider URL: https://gitlab.com
• Audience: https://gitlab.com

3. Click Add provider

Now AWS will accept signed tokens from GitLab jobs. GitLab jobs must explicitly request a token using the id_tokens keyword in .gitlab-ci.yml:

id_tokens:
  default:
    aud: https://gitlab.com

Step 2: Create IAM Role(s) with Trust Policy and Permissions

With the identity provider in place, we now create one IAM role per environment (dev, stg, prod). Each role:

• Defines what the workflow is allowed to do (permissions)
• Defines who is allowed to assume it (trust policy)

Permission (GitHubRole_dev or GitLabRole_dev )

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["secretsmanager:GetSecretValue"],
      "Resource": "arn:aws:secretsmanager:YOUR_AWS_REGION:YOUR_AWS_ACCOUNT_ID:secret:dev/v1.0.0/*"
    },
    {
      "Effect": "Allow",
      "Action": ["ssm:SendCommand"],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "ec2:ResourceTag/Environment": "dev"
        }
      }
    }
  ]
}

This policy allows the role to:

• Read secrets under dev/v1.0.0/ from Secrets Manager
• Send SSM commands only to EC2 instances tagged as Environment=dev

IAM Trust Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:your-org/your-repo:*"
        }
      }
    },
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/gitlab.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "gitlab.com:aud": "https://gitlab.com"
        },
        "StringLike": {
          "gitlab.com:sub": "project_path:your-group/your-project:ref_type:branch:ref:*"
        }
      }
    }
  ]
}

This lets either GitHub or GitLab assume the same role — useful if you’re deploying from both platforms.

Prepare EC2 for Deployment

Once GitHub/GitLab has secure access to your AWS environment using OIDC, the next step is to prepare your EC2 instance for actual app deployment. This includes setting up reverse proxy, TLS certificates, and storing environment-specific secrets.

Setting Up TLS with Let’s Encrypt on a Custom-Built NGINX Server

To maximize flexibility and enable custom modules, we install NGINX from source. This approach is documented in the project’s README, which includes:

• Compiling NGINX with required modules
• Creating a systemd service
• Reverse proxy config for NestJS (port 3000)

After you finish setting up the Nginx from source, then let’s install TLS certificate to secure out requests.

Option 1 — DNS-01 Challenge (Manual, No Auto-Renew)

Use this if you prefer manual setup and are okay with reissuing the certificate manually every 90 days.

sudo certbot certonly --manual --preferred-challenges dns -d yourdomain.com

This method will prompt you to add a TXT record to your domain’s DNS. No HTTP server is needed. However, auto-renewal is not supported unless you use DNS automation via route53 or another provider plugin.

Option 2 — HTTP-01 Challenge (Supports Auto-Renew)

Before issuing the certificate, you must configure NGINX to serve .well-known/acme-challenge/ from a persistent path that won't be overridden during deployments.

Update your NGINX config (typically at /etc/nginx/nginx.conf or your custom path):

user www-data;
worker_processes auto;

events {
    worker_connections 65000;
    multi_accept on;
}

http {
    include mime.types;
    default_type application/octet-stream;

    client_body_buffer_size 10K;
    client_max_body_size 8m;
    client_header_buffer_size 1k;
    client_body_timeout 12;
    client_header_timeout 12;
    keepalive_timeout 15;
    send_timeout 10;

    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    types_hash_max_size 2048;

    gzip on;
    gzip_disable "msie6";
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    # HTTP-only server for certificate issuance
    server {
        listen 80;
        server_name yourdomain.com;

        # Serve ACME challenge from a safe location
        location ^~ /.well-known/acme-challenge/ {
            root /var/www/letsencrypt;
            allow all;
        }

        # Redirect everything else to HTTPS
        location / {
            return 301 https://$host$request_uri;
        }
    }
}

Then create the directory that will be used for challenges:

sudo mkdir -p /var/www/letsencrypt
sudo chown -R ec2-user /var/www/letsencrypt

Restart NGINX (use your custom path):

systemctl restart nginx

Now that NGINX is ready to serve challenges, issue your certificate:

sudo certbot certonly --webroot -w /var/www/letsencrypt -d yourdomain.com

If successful, Certbot will create:

/etc/letsencrypt/live/yourdomain.com/fullchain.pem
/etc/letsencrypt/live/yourdomain.com/privkey.pem

Now insert the listen 443 server block with SSL config:

server {
    listen 443 ssl http2;
    server_name yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDH+AESGCM:ECDH+AES256:ECDH+AES128:DH+3DES:!ADH:!AECDH:!MD5;
    ssl_prefer_server_ciphers on;

    ssl_session_cache shared:SSL:40m;
    ssl_session_timeout 4h;
    ssl_session_tickets on;
    ssl_dhparam /etc/nginx/ssl/dhparam.pem;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header Referrer-Policy strict-origin-when-cross-origin;
    add_header X-XSS-Protection "1; mode=block";

    root /home/ec2-user/sites;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~* \.(css|js|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot|otf|mp4|webm|ogg|ogv|webp|avif)$ {
        expires 1M;
        access_log off;
        log_not_found off;
        add_header Cache-Control "public, max-age=2592000, immutable";
        add_header Pragma public;
        add_header Vary Accept-Encoding;
    }

    location /apis {
        proxy_pass http://localhost:3000/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_buffering on;
        proxy_buffers 16 4k;
        proxy_buffer_size 8k;
        proxy_busy_buffers_size 16k;

        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;

        client_max_body_size 50M;
    }
}

Because NGINX was built from source and is not located at /usr/sbin/nginx, Certbot’s default reload hook won't work.

Add this cron job instead:

sudo crontab -e

0 2 * * * certbot renew --quiet --deploy-hook "/usr/bin/nginx -s reload"

Test it:

sudo certbot renew --dry-run

This ensures TLS certificates will renew automatically before they expire.

Make sure everytime CICD deploys to server, it does not overwrite /var/www/letsencrypt/ — or your auto-renewal will fail.

Create Cloud Credentials as Secrets for Each Environment

Your jobs will likely need credentials (e.g., ec2 host and key, AWS account id). You’ll store these securely based on environment (dev, stg, prod).

Github: Repo → Settings → Environments → dev | stg | prod → Add Secret.

Gitlab: Settings → CI/CD → Variables

Store Environment Variables in AWS Secrets Manager

Your app reads secrets like DB credentials from AWS Secrets Manager at runtime. Store them using a clear naming convention:

dev/v1.0.0/database
stg/v1.0.0/database
prod/v1.0.0/database

Each secret should contain a JSON payload like:

{
  "DB_HOST": "db.dev.example.com",
  "DB_USER": "postgres",
  "DB_PASSWORD": "secure_password",
  "DB_NAME": "myapp"
}

This way, in your GitHub Actions or GitLab pipeline, you can dynamically fetch:

aws secretsmanager get-secret-value --secret-id "${DEPLOY_ENV}/v1.0.0/database"

Use the output to generate .env on the EC2 machine during deployment.

GitHub Actions Workflow: Deploy NestJS to EC2

Trigger

on:
  push:
    branches:
      - dev
      - stg
      - main

This workflow is triggered whenever a push happens to dev, stg, or main. Each branch maps to a deployment environment.

Job 1: set-env — Determine Which Environment Is Being Deployed

jobs:
  set-env:
    name: Set Deployment Environment
    runs-on: ubuntu-latest
    outputs:
      deploy-env: ${{ steps.set-env.outputs.DEPLOY_ENV }}  # ✅ Pass evaluated DEPLOY_ENV
    steps:
      - name: Evaluate DEPLOY_ENV
        id: set-env
        run: echo "DEPLOY_ENV=${{ github.ref_name == 'main' && 'prod' || github.ref_name }}" >> $GITHUB_OUTPUT

What it does:

• Runs a tiny script that checks the branch being pushed
• Dynamically sets DEPLOY_ENV as dev, stg, or prod

run: echo "DEPLOY_ENV=${{ github.ref_name == 'main' && 'prod' || github.ref_name }}" >> $GITHUB_OUTPUT

• If main, it sets DEPLOY_ENV=prod
• If dev, it sets DEPLOY_ENV=dev
• If stg, it sets DEPLOY_ENV=stg

Job 2: ci — Compile, Lint, and Test the Code

uses: ./.github/workflows/ci.yaml

This imports another workflow (ci.yaml) as a reusable workflow. It receives:

with:
  deploy-env: ${{ needs.set-env.outputs.deploy-env }}

Inside ci.yaml, there are 4 sub-jobs:

🔹 setup

• Checks out the repo
• Sets up Node.js
• Generates a cache key based on package-lock.json + env
• Uses actions/cache to store apis/node_modules
• Installs dependencies with npm ci inside the apis/ folder

🔹 lint

• Depends on setup
• Restores node_modules from cache
• Runs npm run lint inside apis/ to enforce code quality

🔹 build

• Depends on setup and lint
• Runs npm run build to generate production-ready JS in apis/dist
• Uploads build output (apis/dist) as an artifact

🔹 test

• Depends on setup and build
• Downloads the compiled app (dist)
• Restores node_modules
• Runs npm run test (or ls -a if placeholder)

🟩 CI ends by producing:

• node_modules (cached)
• dist/ (artifact)

Job 3: deploy — Deploy Built App to EC2

This job is responsible for securely deploying the production-ready NestJS application to an EC2 instance. It uses GitHub OIDC to authenticate into AWS, fetches secrets, installs dependencies, and starts the app using PM2.

Environment Setup

env:
  DEPLOY_ENV: ${{ needs.set-env.outputs.deploy-env }}
environment: ${{ needs.set-env.outputs.deploy-env }}
permissions:
  id-token: write
  contents: read

• Dynamically assigns the environment (dev, stg, prod) based on the branch.
• Grants the job permission to request a temporary OIDC token to access AWS.

Checkout the Repository

- name: Checkout Repository
  uses: actions/checkout@v4

Pulls the project source code so it can access project files and structure.

Setup Node.js Environment

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'

Ensures Node.js is available to run any scripts or installs if needed on the runner.

Download Build Artifact

- name: Download Build Artifact
  uses: actions/download-artifact@v4
  with:
    name: nestjs-build-${{ env.DEPLOY_ENV }}
    path: apis/dist/

Fetches the compiled app (apis/dist/) previously generated by the CI build job.

Deploy via Composite Action

- name: Deploy using Composite Action
  uses: ./.github/actions/deploy-to-ec2
  with:
    ec2_host: ${{ secrets.EC2_HOST }}
    ec2_user: ${{ secrets.EC2_USER }}
    ec2_ssh_key: ${{ secrets.EC2_SSH_KEY }}
    pm2_app_name: ${{ secrets.PM2_APP_NAME }}
    aws_region: "${{ secrets.AWS_REGION }}"
    secret_id: "/${{ env.DEPLOY_ENV }}/v1.0.0/database"
    role_arn: ${{ secrets.ROLE_ARN }}

This step performs the actual deployment using a reusable composite GitHub Action, which does the following:

Authenticate to AWS via OIDC

- uses: aws-actions/configure-aws-credentials@v4

Uses sts:AssumeRoleWithWebIdentity to get short-lived AWS credentials for deployment.

Fetch Secrets from AWS Secrets Manager

- name: Fetch Secrets via AWS CLI and write .env
      shell: bash
      run: |
        aws secretsmanager get-secret-value \
          --secret-id "${{ inputs.secret_id }}" \
          --query SecretString \
          --output text > secret.json

        jq -r 'to_entries[] | "\(.key)=\(.value)"' secret.json > .env
      env:
        AWS_DEFAULT_REGION: ${{ inputs.aws_region }}

Pulls a secret JSON object (e.g., DB credentials) and exports them as environment variables.

Upload App to EC2 via SSH

scp -i private_key.pem -r .env apis/dist apis/package.json apis/package-lock.json ...

Transfers only the necessary build output and config files. Also uploads the sites/ folder separately to the EC2 home directory.

Deploy on EC2

ssh -i private_key.pem ...
cd nestjs-app
npm ci
pm2 start or restart ...

Installs Node dependencies, then either starts or restarts the NestJS app with PM2.

The deployment flow for GitLab CI is fundamentally the same. Full implementations for both GitHub Actions and GitLab CI (including reusable jobs, cache setup, deployment logic, and secret management) are available in the source repo.

The OIDC-Driven Pipeline in Action

Once everything is configured correctly, here’s what a successful OIDC-powered deployment looks like:

🚀 1. GitHub Workflow Executes Successfully

With the OIDC role assumed, the GitHub Actions workflow automatically:

• Detects the correct deployment environment (dev, stg, or prod)
• Caches and installs dependencies
• Lints, builds, and tests the NestJS app
• Deploys the output to EC2

🔐 2. OIDC Role Assumption Log

Thanks to the permissions:

permissions:
  id-token: write
  contents: read

and this configuration:

- name: Configure AWS Credentials with OIDC
  uses: aws-actions/configure-aws-credentials@v4

You will see the workflow assume your IAM role with messages like:

This confirms that no long-lived credentials were used. The job was authenticated using a short-lived federated identity, the secure way.

3. PM2 Launches the App on EC2

Once files are transferred, the EC2 deploy step runs:

📦 Installing dependencies via npm ci...
🔐 Writing .env from secrets...
🚀 Restarting app via PM2...

And then you should see:

Your NestJS app is now:

• Running via PM2
• Served behind your custom-built, TLS-enabled NGINX
• Automatically provisioned through GitHub Actions + OIDC

Conclusion

By integrating OIDC federation with GitHub Actions and GitLab CI, you’ve built a modern, secure, and fully automated deployment pipeline for your NestJS application. This setup eliminates the need for static AWS credentials, simplifies role-based access, and promotes best practices in cloud security.

You’ve also:

• Compiled and configured NGINX from source for full control
• Secured your EC2 instance with Let’s Encrypt TLS certificates
• Structured your deployment process to be environment-aware (dev/stg/prod)
• Used AWS Secrets Manager to manage sensitive environment variables cleanly
• Leveraged PM2 to manage your app lifecycle in production

This architecture ensures that each deployment is predictable, secure, and scalable, while also being easy to maintain and extend across cloud environments or infrastructure teams.

Follow Me On Linkedin To Stay Connected

https://www.linkedin.com/in/ninh-kim-927571149/

AWS OIDC Federation: Secure Authentication with GitHub & GitLab was originally published in Tech Tonic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

In microservices, service-to-service communication must be secure, especially in distributed or cloud environments. While gRPC handles fast binary messaging, it doesn’t protect against untrusted sources by default.

That’s where mTLS (mutual TLS) comes in — a secure handshake where both services authenticate each other using certificates from a shared CA.

In this post, we’ll start by breaking down how TLS works, then dive into the algorithms behind it and how to issue your own certs. From there, we’ll walk through a step-by-step implementation using NestJS + gRPC + mTLS, and finish with a working setup, real results, and a wrap-up of best practices.

Understanding TLS

TLS is the backbone of secure communication on the internet. It protects your data from being read or tampered with by attackers. Let’s break down how TLS works and what those mysterious cipher suites actually mean.

The TLS Handshake: Securely Switching to Symmetric

1. Client Hello
   The client says:
   “Hi! I support these TLS versions and cipher suites. Let’s agree on how to talk securely.”
2. Server Hello
   The server replies with:
   - The chosen TLS version
   - The selected cipher suite
   - Its certificate (which includes the public key)
3. Certificate Verification
   The client:
   - Verifies the server’s certificate (e.g., using a CA it trusts). If this check fails, the handshake terminates immediately.
   - Extracts the public key from the certificate
4. Key Exchange (ECDHE)
   - The server sends Diffie-Hellman parameters (curve, ECDHE Pubkey, etc.)
   - These parameters are digitally signed using the server’s private key. Hence, the client can use the public key (from the verified certificate) to validate the signature and ensure the parameters weren’t tampered with (defending against MITM)
5. Shared Key Generation
   - After verifying everything, the client sends its own ECDHE Pubkey
   - Now both sides compute the same symmetric key using ECDHE. This key is never sent over the wire — it’s generated independently on both ends.
6. Secure Session Begins
   - All future communication is encrypted using the symmetric key (e.g., AES-256-GCM)
   - Integrity is ensured using hashing (e.g., SHA-384)

What’s Inside a Cipher Suite?

A cipher suite is a collection of algorithms TLS will use for:

• Key exchange (e.g., Diffie-Hellman, ECDHE, RSA)
• Authentication (e.g., RSA, ECDSA)
• Symmetric encryption (e.g., AES-GCM, ChaCha20)
• Message integrity (e.g., SHA256, SHA384)

Here’s an example:

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

• ECDHE: Elliptic Curve Diffie-Hellman Ephemeral (secure key exchange)
• ECDSA: Elliptic Curve Digital Signature Algorithm — used for authentication, meaning the server proves its identity using an ECDSA certificate (instead of RSA).
• AES_128_GCM: Advanced Encryption Standard with 128-bit key in Galois/Counter Mode — used for encrypting the actual data.
• SHA256: Used for message integrity, ensuring the encrypted message hasn’t been tampered with.

Before we dive deeper, let’s cover a few key concepts that will help you understand how TLS actually works.

Symmetric Encryption

• Uses one shared key for both encrypting and decrypting.
• Much faster and more efficient for large amounts of data.
• Used in: bulk data encryption during a session.

📦 Example: AES, ChaCha20

Hashing Algorithms: Ensuring Data Integrity

Encryption keeps your data confidential, but how do we make sure it wasn’t tampered with in transit?

That’s where hashing algorithms come in.

A hash is like a digital fingerprint of your data — a fixed-length string of characters that uniquely represents the original message. Even a tiny change in the input (like changing one letter) results in a completely different hash.

Example:

sha256("hello")  =>  2cf24dba5fb0a...
sha256("hello!") =>  b1946ac92492d...

In TLS, a hashing algorithm like SHA-256 or SHA-384 is used to generate a digest of the handshake data (e.g. key exchange parameters), then be signed by the server’s private key (e.g., RSA or ECDSA), we’ll see this in the next section with Asymmetric Encryption

If the hashes match, the data hasn’t been modified — this proves integrity and authenticity.

This is a core part of why TLS is secure — even if an attacker intercepts the traffic, they can’t modify anything without breaking the signature or causing a hash mismatch.

Asymmetric Encryption

• Uses two keys: a public key (shared with the world) and a private key (kept secret).
• Messages encrypted with the public key can only be decrypted by the private key.
• Used in: authentication, digital signatures, and secure key exchange.

📦 Example: RSA, ECDSA

In TLS, asymmetric encryption (public/private key crypto) is not used to encrypt all the communication — that would be too slow and computationally expensive, as well as requiring the public-private keys pair on both sides is considered complicated.

Instead, it’s only used for validating chain of trust of certificates (out of scope for this post) and be used during the key exchange phase, specifically to:

• Generate a digest of the handshake data (e.g. key exchange parameters)
• Sign this digest using the server’s private key (e.g., RSA or ECDSA)
• Send the signed hash along with the server’s certificate

Then the client:

• Uses the server’s public key (from the cert) to verify the signature
• Recomputes the hash of the same handshake data
• Compares it to the signed version

The encryption of data sent between client and server during communication is performed through Symmetric Encryption — a much faster and more efficient way. But how to create a shared one and securely transmit that in the public network is not that easy. That leads us to the concept of Diffie-Hellman algorithm.

With ephemeral key exchange (ECDHE), each session gets a new symmetric key, so even if it’s compromised later, past sessions stay safe → Perfect Forward Secrecy.

Alright, now that we’ve covered the essentials, let’s get back into how TLS actually works.

The Magic of Diffie-Hellman (Key Exchange)

Diffie-Hellman (especially ECDHE) is how both sides generate the same symmetric key — without ever sending it directly.

Each side generates a private key, computes a public version, exchanges that public data, and ends up with the same secret.

Here’s a snapshot captured using Wireshark, showing a packet exchanged during the TLS key exchange process.

When using Elliptic Curve Diffie-Hellman Ephemeral (ECDHE), the server sends the following:

• Curve Type: Tells the client the form of the elliptic curve equation. Typically, this is something like y² = x³ + ax + b. The curve type determines the values of a and b.
• Named Curve: Instead of sending full curve parameters, a predefined curve (like secp256r1) is used. This includes the starting generator point G.
• Public Key (Pubkey): This is the result of multiplying the server’s private key with the base point G. Think of it as:

PubKey = privKey × G

The client uses this information, performs a similar operation with its own private key, then send its PubKey back to the server. Eventually, and both end up with the same shared secret key.

Key = privKey × PubKey

Even though the PubKey are exchanged in the open, the private keys are never sent. Thanks to the hardness of the elliptic curve discrete logarithm problem, an attacker can’t reverse-engineer the private key from the PubKey. If someone compromises the TLS cert in the future, they still can’t decrypt past messages.

How mTLS Works: Algorithms and Certificate Issuance

Normally in TLS, the server has a TLS certificate and a public/private key pair, while the client does not.

In mTLS, however, both the client and server have a certificate, and both sides authenticate using their public/private key pair. Compared to regular TLS, there are additional steps in mTLS to verify both parties.

1. Client connects to server
2. Server presents its TLS certificate
3. Client verifies the server’s certificate
4. Client presents its TLS certificate
5. Server verifies the client’s certificate
6. Key Exchange (ECDHE), both sides perform Diffie-Hellman key exchange to derive the same shared secret
7. Client and server exchange information over encrypted TLS connection

The organization implementing mTLS acts as its own certificate authority. This contrasts with standard TLS, in which the certificate authority is an external organization that checks if the certificate owner legitimately owns the associated domain.

A “root” TLS certificate is necessary for mTLS; this enables an organization to be their own certificate authority. The certificates used by authorized clients and servers have to correspond to this root certificate. The root certificate is self-signed, meaning that the organization creates it themselves.

Step-by-Step Implementing mTLS in NestJS Microservices with gRPC

Init Both Services

nest new user-service
nest new order-service

Choose:

• Package manager: npm
• Skip testing if you want a clean base

then install Packages & Setup Auto Proto Generation

npm install @nestjs/microservices @grpc/grpc-js @grpc/proto-loader
npm install --save-dev @protobuf-ts/protoc @protobuf-ts/plugin

and adding this script in package.json

"scripts": {
  "proto:gen": "protoc \
    --plugin=protoc-gen-ts=$(pwd)/node_modules/.bin/protoc-gen-ts \
    --ts_out=src/generated \
    --proto_path=proto \
    proto/*.proto"
}

For user-service/main.ts, it supposes to serve both HTTP and gRPC request:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { MicroserviceOptions, Transport } from '@nestjs/microservices';
import { join } from 'path';
import * as fs from 'fs';
import * as grpc from '@grpc/grpc-js';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const ca = fs.readFileSync(join(__dirname, '../certs/ca.crt'));
  const cert = fs.readFileSync(join(__dirname, '../certs/user.crt'));
  const key = fs.readFileSync(join(__dirname, '../certs/user.key'));

  // gRPC server for user.proto
  app.connectMicroservice<MicroserviceOptions>({
    transport: Transport.GRPC,
    options: {
      url: '0.0.0.0:50051',
      package: 'user',
      protoPath: join(__dirname, '../proto/user.proto'),
      credentials: grpc.ServerCredentials.createSsl(
        ca, // root CA
        [
          {
            cert_chain: cert,
            private_key: key,
          },
        ],
        true, // require client certificate
      ),
    },
  });

  await app.startAllMicroservices(); // 👈 start gRPC
  await app.listen(3000); // 👈 start HTTP
  console.log(
    '🚀 user-service running on http://localhost:3000 and gRPC on :50051',
  );
}
bootstrap();

The same setting for order-service, except it does not listen for serving any HTTP API. Next, we register order client in user service app module:

import { Module } from '@nestjs/common';
import { ClientsModule, Transport } from '@nestjs/microservices';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import * as fs from 'fs';
import { join } from 'path';
import * as grpc from '@grpc/grpc-js';

@Module({
  imports: [
    ClientsModule.register([
      {
        name: 'ORDER_PACKAGE',
        transport: Transport.GRPC,
        options: {
          url: 'order-service:50051',
          package: 'order',
          protoPath: join(__dirname, '../proto/order.proto'),
          credentials: grpc.credentials.createSsl(
            fs.readFileSync(join(__dirname, '../certs/ca.crt')), // root CA
            fs.readFileSync(join(__dirname, '../certs/user.key')), // client key
            fs.readFileSync(join(__dirname, '../certs/user.crt')), // client cert
          ),
        },
      },
    ]),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

From now on, we can inject that client to any service that needs to communicate with the order service. That’s all we need to bring microservices to live. The rest of the implementation for controllers, services, or any app behaviours are up to you, or you can follow this Nest official document.

Setup mTLS with Certs

From project root:

mkdir -p certs && cd certs

# 1. Generate CA
openssl genrsa -out ca.key 4096
openssl req -x509 -new -key ca.key -sha256 -days 365 -out ca.crt -subj "/CN=ca.local"

# 2. order-service (with SAN = order-service)
openssl genrsa -out order.key 2048
openssl req -new -key order.key -out order.csr -subj "/CN=order-service"
openssl x509 -req -in order.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out order.crt -days 365 \
  -extfile <(printf "subjectAltName=DNS:order-service")

# 3. user-service (with SAN = user-service)
openssl genrsa -out user.key 2048
openssl req -new -key user.key -out user.csr -subj "/CN=user-service"
openssl x509 -req -in user.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out user.crt -days 365 \
  -extfile <(printf "subjectAltName=DNS:user-service")

Then copy certs into each service:

cp ca.crt user.crt user.key user-service/certs/
cp ca.crt order.crt order.key order-service/certs/

Private keys (*.key) and certificates (*.crt) must not be committed to Git. Doing so would expose your infrastructure to severe security risks, we’ll create environment secrets later on for storing them in Github and retrieving once the deployment happens.

Creating Dockerfile & Docker Compose

Same structure for both user and order services but only exposes port 50051 for the later. And, we will treat the user-service as a gateway of handling client requests passing from Nginx web server.

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm install

COPY . .
RUN npm run proto:gen && npm run build

EXPOSE 3000
EXPOSE 50051

CMD ["node", "dist/main"]

For local development, create docker-compose.yaml

version: "3.9"
services:
  user-service:
    build: ./user-service
    ports:
      - "3000:3000" # HTTP (for NGINX / REST clients)
      - "50052:50051" # gRPC (for internal microservice comms)
    depends_on:
      - order-service

  order-service:
    build: ./order-service
    ports:
      - "50051:50051"

  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - user-service

But for the production, we will replace images configured in docker-compose file with the latest one built in the CD step, then create another one for prod:

version: "3.9"

services:
  user-service:
    image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/user-service:latest # 🔁 Will be replaced by GitHub Actions (sed)
    ports:
      - "3000:3000" # HTTP (for NGINX / REST clients)
      - "50052:50051" # gRPC (for internal microservice comms)
    restart: always
    environment:
      - NODE_ENV=production
    depends_on:
      - order-service

  order-service:
    image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/order-service:latest # 🔁 Will be replaced by GitHub Actions (sed)
    ports:
      - "50051:50051"
    restart: always
    environment:
      - NODE_ENV=production

  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - user-service

NGINX Reverse Proxy

Simply passing all request to the user-service, from that, the user-service will internally talks to the order-service.

events {}

http {
  upstream user_api {
    server user-service:3000;
  }

  server {
    listen 80;

    location / {
      proxy_pass http://user_api;
    }
  }
}

GitHub Actions: CI/CD with ECR + EC2

In this configuration, we authenticate github with AWS by OIDC, then build images and push to ECR. Later on, login to EC2 with SSH and pull the newest images to EC2 instance and initialize docker container with docker-compose.prod.yaml file.

name: Deploy Services to EC2 via ECR

on:
  push:
    branches: [dev]

jobs:
  deploy:
    name: Deploy to EC2 (Dev)
    runs-on: ubuntu-latest
    environment: dev

    permissions:
      id-token: write
      contents: read

    env:
      IMAGE_TAG: ${{ github.sha }}
      APP_DIR: /home/ec2-user

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Configure AWS OIDC Credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          role-to-assume: ${{ secrets.ROLE_ARN }}
          aws-region: ${{ secrets.AWS_REGION }}

      - name: Log in to Amazon ECR
        run: |
          aws ecr get-login-password --region ${{ secrets.AWS_REGION }} | \
          docker login --username AWS --password-stdin \
          ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com

      - name: Inject mTLS Certs into user-service and order-service
        run: |
          mkdir -p user-service/certs order-service/certs

          echo "${{ secrets.USER_CRT }}" > user-service/certs/user.crt
          echo "${{ secrets.USER_KEY }}" > user-service/certs/user.key
          echo "${{ secrets.CA_CRT }}"   > user-service/certs/ca.crt

          echo "${{ secrets.ORDER_CRT }}" > order-service/certs/order.crt
          echo "${{ secrets.ORDER_KEY }}" > order-service/certs/order.key
          echo "${{ secrets.CA_CRT }}"    > order-service/certs/ca.crt

      - name: Build & Push Docker Images
        run: |
          # USER SERVICE
          docker build -t user-service:${{ env.IMAGE_TAG }} ./user-service
          docker tag user-service:${{ env.IMAGE_TAG }} \
            ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com/${{ secrets.ECR_USER_REPO }}:${{ env.IMAGE_TAG }}
          docker push ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com/${{ secrets.ECR_USER_REPO }}:${{ env.IMAGE_TAG }}

          # ORDER SERVICE
          docker build -t order-service:${{ env.IMAGE_TAG }} ./order-service
          docker tag order-service:${{ env.IMAGE_TAG }} \
            ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com/${{ secrets.ECR_ORDER_REPO }}:${{ env.IMAGE_TAG }}
          docker push ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com/${{ secrets.ECR_ORDER_REPO }}:${{ env.IMAGE_TAG }}

      - name: 📦 Copy docker-compose and nginx config to EC2
        uses: appleboy/scp-action@v0.1.4
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ec2-user
          key: ${{ secrets.EC2_SSH_KEY }}
          source: "docker-compose.prod.yaml,nginx/nginx.conf"
          target: ${{ env.APP_DIR }}
          debug: true
      
      - name: 🚀 SSH Deploy to EC2
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ec2-user
          key: ${{ secrets.EC2_SSH_KEY }}
          script: |
            cd $APP_DIR

            # Update docker-compose.prod.yaml with the latest image tags
            sed -i "s|image:.*user-service.*|image: ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com/${{ secrets.ECR_USER_REPO }}:${{ env.IMAGE_TAG }}|" docker-compose.prod.yaml
            sed -i "s|image:.*order-service.*|image: ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com/${{ secrets.ECR_ORDER_REPO }}:${{ env.IMAGE_TAG }}|" docker-compose.prod.yaml

            # 🚀 Log in to ECR using EC2 IAM role
            aws ecr get-login-password --region ${{ secrets.AWS_REGION }} | \
              docker login --username AWS --password-stdin \
              ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com

            docker-compose -f docker-compose.prod.yaml pull
            docker-compose -f docker-compose.prod.yaml down
            docker-compose -f docker-compose.prod.yaml up -d

Don’t forget to assign a role for your EC2 instance so that it can pull images from your ECR. Below is the recommended minimal ECR Pull Policy for EC2:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "*"
    }
  ]
}

Practical Demo: Running and Verifying Secure Communication

After completing the deployment process, we verified that secure mTLS communication between services was working correctly.

To test the system:

1. Deployed both user-service and order-service to the EC2 instance using GitHub Actions and Docker Compose.
2. Ensured mTLS certificates were injected properly into each service during the CI/CD pipeline.
3. Verified logs confirmed mutual authentication between services on startup.

Postman Test

We sent a request to the user-service endpoint using Postman:

GET http://<your-domain>/user/1

• The user-service made a secure gRPC call to order-service.
• The order-service responded with the user's order history.
• The response was returned to Postman successfully.

If you try with an invalid certificate, for example, re-sign the order certificate by changing subjectAltName=DNS:localhost. Rebuild and test it with Postman, you’ll encounter the following error:

🛡️ Verified Security

• All inter-service communication is encrypted and authenticated using mutual TLS.
• Unauthorized services without valid certificates are rejected during the handshake.

This confirms the setup is secure, resilient, and production-ready for handling internal service communication via gRPC and mTLS.

Conclusion

In this guide, we explored how to protect microservice communication using mutual TLS (mTLS) over gRPC. We covered:

• The need for trust in service-to-service communication
• How TLS and mTLS work under the hood
• Generating and managing certificates with OpenSSL
• Implementing a real-world setup using NestJS, Docker, and GitHub Actions

By enforcing mTLS, you’re not just encrypting traffic — you’re ensuring that only verified services can talk to each other. This protects against internal threats, spoofed services, and unauthorized access.

As your system grows, securing internal APIs with mTLS becomes just as important as securing public ones. It’s a small effort for a massive gain in trust and resilience.

Start small, secure early — and scale with confidence.

Follow Me On Linkedin To Stay Connected

https://www.linkedin.com/in/ninh-kim-927571149/

Strengthening Microservices: Implementing mTLS over gRPC for Trusted Communication was originally published in Tech Tonic on Medium, where people are continuing the conversation by highlighting and responding to this story.

After receiving the ground-breaking response for a similar article published in 2024, and catering to the requests for a follow-up, I’m writing a similar article in 2025. This is the exact same comparison, but executed on latest of everything (Go and frameworks).

In this article, we’ll run a hello world comparison using several popular go frameworks such as Gin, Fiber, Echo, HTTP router, chi, beego, and Iris. Yes, this one is a dummy case of hello world. If you’re looking for a more solid and real-world comparison, this article is not for you.

Let’s jump directly into to the article.

Test setup

All tests are executed on MacBook Pro M2 with 16G RAM. There are 8+4 CPU cores. The load tester is Bombardier (also written in Go). The Go version is v1.23.5 (latest at the time of writing).

The code for each application is as follows:

Gin

package main

import (
  "net/http"
  "github.com/gin-gonic/gin"
)

func main() {
  r := gin.New()

  r.GET("/", func(c *gin.Context) {
    c.String(http.StatusOK, "Hello world!")
  })

  r.Run(":3000")
}

Fiber

package main

import (
  "github.com/gofiber/fiber/v2"
)

func main() {
  app := fiber.New()
  port := ":3000"

  app.Get("/", func(c *fiber.Ctx) error {
    return c.SendString("Hello World!")
  })

  app.Listen(port)
}

Echo

package main

import (
  "net/http"
  "github.com/labstack/echo/v4"
)

func main() {
  e := echo.New()
  e.GET("/", func(c echo.Context) error {
    return c.String(http.StatusOK, "Hello World!")
  })
  e.Start(":3000")
}

Iris

package main

import "github.com/kataras/iris/v12"

func main() {
  app := iris.New()

  app.Get("/", func(ctx iris.Context) {
    ctx.Text("Hello World!")
  })

  app.Listen(":3000")
}

Chi

package main

import (
  "net/http"
  "github.com/go-chi/chi/v5"
)

func main() {
  r := chi.NewRouter()
  r.Get("/", func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Hello World!"))
  })
  http.ListenAndServe(":3000", r)
}

Http Router

package main

import (
  "fmt"
  "net/http"
  "log"
  "github.com/julienschmidt/httprouter"
)

func Hello(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
  fmt.Fprintf(w, "Hello World!")
}

func main() {
  router := httprouter.New()
  router.GET("/", Hello)

  log.Fatal(http.ListenAndServe(":3000", router))
}

Beego

package main

import web "github.com/beego/beego/v2/server/web"

type MainController struct {
  web.Controller
}

func (c *MainController) Get() {
  c.Ctx.WriteString("Hello world!")
}

func main() {
  web.Router("/", &MainController{})
  web.Run()
}

Results

A total of 10M requests are executed for 100 concurrent connections. Along with latency, I’ve also collected CPU and memory usage (as always the case). This gives a complete picture. Just having high RPS is not enough. We also need to know the cost of the RPS. A framework giving a high performance by hogging the CPU may not be useful for production applications.

The results in chart form are as follows:

Time taken

(Lesser is better)

Requests per second

(More is better)

Latencies

(Lesser are better)

Resources

(Lesser are better)

Conclusion

Numbers show that Echo is the best performer.

I also understand & heard (many times) that TechEmpower benchmarks show fiber demonstrating the highest performance. These are my results, and they show Fiber to be lacking in performance. I won’t be changing my results because TechEmpower demonstrated different results in 2023.

Thanks for reading!

If you see any missing framework, please let me know.

Go: The fastest web framework in 2025 was originally published in Tech Tonic on Medium, where people are continuing the conversation by highlighting and responding to this story.