DEV Community: Ugochukwu Nebolisa

HTTP Caching Headers: The Performance Optimization You're Probably Missing

Ugochukwu Nebolisa — Tue, 17 Mar 2026 22:59:36 +0000

Intro

Your backend is fast. Your database queries are optimized. You've minimized your JavaScript bundles and compressed your images.
But your users are still downloading the same CSS file every single time they visit your site. They are re-fetching API responses that haven't changed in hours. Every page load makes unnecessary network requests that could have been avoided.

The problem? You're not leveraging HTTP caching headers.
HTTP caching is one of the most powerful performance optimizations available to web developers, yet it's surprisingly misunderstood. When configured correctly, it can dramatically reduce server load, decrease bandwidth costs, and make your application feel instantaneous to users.

And the best part? It requires no changes to your frontend code. It's all about telling the browser: "You already have this. Don't ask me again."

This guide covers the essential caching headers you need to know, how to implement them in Node.js/Express.

Let's go!!.

What is Caching?

Before we dive into HTTP-specific caching, let us establish what caching actually means.

Caching is the practice of storing copies of data in a temporary storage location so that future requests for that data can be served faster.

An analogy? Instead of walking to the library every time you need to reference a book, you photocopy the pages you need and keep them at your desk. The next time you need that information, you just look at your copy instead of making another trip.

In web development, caching happens at multiple levels:

Browser Cache (Client-Side): The user's browser stores copies of files (CSS, JavaScript, images, API responses) locally on their device. When they revisit your site, the browser can serve these files from disk instead of downloading them again.
CDN Cache (Edge): Content Delivery Networks store copies of your static assets on servers distributed around the world. When a user in Tokyo requests your site hosted in New York, the CDN serves files from a server closer to Tokyo.
Server Cache (Backend): Your server might cache database query results, rendered HTML, or computed values in memory (Redis, Memcached) to avoid expensive recalculations.
Database Cache: Databases cache frequently accessed data in memory to avoid slow disk reads.

For this article, let's focus on the first level: browser caching controlled by HTTP headers.

Why HTTP Caching Matters

Consider a typical website visit:

Without caching:
User visits your site, browser downloads: HTML (50KB), CSS (100KB), JavaScript (300KB), images (2MB) making it a total of 2.45MB downloaded. If the user clicks to another page, browser downloads everything again: 2.45MB. If the user refreshes the page, browser downloads everything again: 2.45MB.

With proper caching:
User visits your site, browser downloads: 2.45MB on first visit, user clicks to another page, browser uses cached files: 0KB downloaded (just new HTML). If the user refreshes the page, browser uses cached files: 0KB downloaded.

The impact:

Faster page loads (files served from local disk, not network).
Reduced server load (fewer requests hitting your backend).
Lower bandwidth costs (less data transferred).
Better user experience (pages feel instant).

The Two Types of HTTP Caching

HTTP caching works in two ways:

Freshness-based caching (Expiration):
Here, the server tells a browser that the file is fresh for a particular point of time. The browser stores the file and serves it directly from cache without making any network request until the expiration time. The headers involved are Cache-Control, Expires.
Validation-based caching (Conditional Requests)
The server tells the browser: "Here's the file and a fingerprint (ETag). Next time you need this file, send me the fingerprint. If it hasn't changed, I will tell you to use your cached version."
The browser still makes a request, but if nothing changed, the server responds with "304 Not Modified" and no file data, saving bandwidth. The headers involved are ETag, If-None-Match, Last-Modified, If-Modified-Since.

You can (and often should) use both types together.

Here's a simple example:

The first visit

Browser -> Server: GET /style.css
Server -> Browser: 200 OK
                   Cache-Control: max-age=86400
                   ETag: "abc123"
                   [CSS file content]

Second Visit (within 24hours)

Browser -> Server: (no request made, serves from cache)

Third Visit (after 24hours)

Browser -> Server: GET /style.css
                   If-None-Match: "abc123"
Server -> Browser: 304 Not Modified
                   (no file content sent)

The browser knows the file is still valid and uses its cached copy.

How HTTP Caching Works: The Request/Response Cycle

Let's trace through exactly what happens during HTTP requests and how caching headers control browser behavior.

The Basic Flow Without Caching

When you visit a website without any caching headers:

1. Browser: "I need /app.js"
   -> Makes network request to server

2. Server: "Here's app.js"
   -> Sends 200 OK with file content (500KB)

3. Browser: "I need /app.js again" (user refreshes page)
   -> Makes network request to server

4. Server: "Here's app.js again"
   -> Sends 200 OK with file content (500KB)

Every request downloads the full file. Wasteful.

The Flow With Freshness-Based Caching

When the server sends Cache-Control: max-age=3600:

1. Browser: "I need /app.js"
   -> Makes network request to server

2. Server: "Here's app.js, and it's fresh for 1 hour"
   -> Sends 200 OK
   -> Cache-Control: max-age=3600
   -> File content (500KB)

3. Browser stores:
   -> The file content
   -> The cache time (1 hour from now)

4. Browser: "I need /app.js again" (5 minutes later)
   -> Checks cache
   -> Sees file is still fresh (55 minutes remaining)
   -> NO NETWORK REQUEST MADE
   -> Serves from disk cache (0KB transferred)

5. Browser: "I need /app.js again" (65 minutes later)
   -> Checks cache
   -> Sees file is stale (expired)
   -> Makes network request to server

The Flow With Validation-Based Caching

When the server sends an ETag:

1. Browser: "I need /app.js"
   -> Makes network request to server

2. Server: "Here's app.js with fingerprint 'abc123'"
   -> Sends 200 OK
   -> ETag: "abc123"
   -> File content (500KB)

3. Browser stores:
   -> The file content
   -> The ETag "abc123"

4. Browser: "I need /app.js again"
   -> Makes network request to server
   -> Sends: If-None-Match: "abc123"

5a. Server checks: "Has app.js changed since 'abc123'?"
    -> No, it hasn't changed
    -> Sends 304 Not Modified
    -> NO FILE CONTENT sent (only headers, ~200 bytes)

5b. Browser:
    -> Receives 304
    -> Uses cached file (0KB file transfer)

OR

5a. Server checks: "Has app.js changed since 'abc123'?"
    -> Yes, it has changed (new ETag: "xyz789")
    -> Sends 200 OK
    → ETag: "xyz789"
    -> New file content (500KB)

5b. Browser:
    -> Receives 200 with new content
    -> Updates cache with new file and new ETag

The browser makes a request, but often gets a tiny 304 response instead of re-downloading the full file.

Combining Both
The best strategy uses both freshness and validation:

Cache-Control: max-age=3600
ETag: "abc123"

Why is this powerful?

1. First request:
   Browser -> Server: GET /app.js
   Server -> Browser: 200 OK
                      Cache-Control: max-age=3600
                      ETag: "abc123"
                      [500KB content]

2. Request within 1 hour:
   Browser -> (no request, serves from cache)
   Bandwidth used: 0KB
   Server load: 0 requests

3. Request after 1 hour (file unchanged):
   Browser -> Server: GET /app.js
                      If-None-Match: "abc123"
   Server -> Browser: 304 Not Modified
   Bandwidth used: ~200 bytes
   Server load: 1 request (but no file read/send)

4. Request after 1 hour (file changed):
   Browser -> Server: GET /app.js
                      If-None-Match: "abc123"
   Server -> Browser: 200 OK
                      ETag: "xyz789"
                      [500KB new content]
   Bandwidth used: 500KB
   Server load: 1 request

You get the best of both worlds: no requests during the fresh period, and efficient validation after expiration.

Understanding Cache Storage

Where does the browser store cached files?

Memory Cache (RAM):

Extremely fast.
Cleared when you close the tab/browser.
Used for resources needed during the current session.

Disk Cache (Hard Drive/SSD):

Persistent across browser sessions.
Survives browser restarts.
Larger storage capacity.

The browser decides which cache to use based on various factors (file size, available memory, cache headers). You don't control this directly.

Cache-Control: The Primary Caching Header

Cache-Control is the most important caching header. It controls whether resources are cached, who can cache them, and for how long.

The Essential Directives:
max-age=
How long the browser can use the cached version without checking with the server.

Cache-Control: max-age=86400

This file is fresh for 86400 seconds (24 hours). The browser won't make any request during this time.

It is used for:

Static assets that rarely change (CSS, JS with versioned filenames).
Images, fonts, videos.

Example values:

max-age=31536000: 1 year (maximum recommended for static assets).
max-age=3600: 1 hour (good for semi-dynamic content).
max-age=60: 1 minute (frequently changing data).

no-cache
Forces the browser to validate with the server before using the cached version, even if it's fresh.

Cache-Control: no-cache

Note: Despite the name, this does NOT prevent caching. The file is still cached, but the browser must check with the server (via ETag) before using it.

Use for:

Content that changes frequently but you still want validation.
HTML pages.

no-store
Prevents caching entirely. The browser must download fresh every time.

Cache-Control: no-store

Nothing is saved to cache. Every request downloads the full file.

Use for:

Sensitive data (banking info, private user data).
Content that should never be stored locally. Don't use for:
Static assets (terrible for performance).
Public content.

public:
Allows any cache (browser, CDN, proxy) to store the response.

Cache-Control: public, max-age=31536000

Use for:

Static assets served to all users.
Public images, CSS, JavaScript

private
Only the user's browser can cache this, not CDNs or shared caches.

Cache-Control: private, max-age=3600

Use for:

User-specific data (API responses with personal info).
Authenticated content.
Personalized HTML.

must-revalidate
Once the cached version expires, the browser must check with the server before using it. Cannot serve stale content.

Cache-Control: max-age=3600, must-revalidate

Use for:

Content where serving stale data would be problematic.
Financial data, inventory counts.

The immutable Directive
A special directive supported by modern browsers:

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

immutable tells the browser that the file won't change and doesn't need revalidation. This prevents unnecessary revalidation requests when users hit refresh.
Only use this for files with hashed/versioned filenames like app.a1b2c3.js. If the file changes, the filename changes, forcing a fresh download.

Combining Directives
You can combine multiple directives:

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

This means: anyone can cache this, it's fresh for 1 year, and it will never change (immutable).

ETag & Validation: Efficient Change Detection

ETags (Entity Tags) are fingerprints for resources. They let the browser ask "has this file changed?" without downloading it again.
How ETags Work
First request:

GET /api/users

Response:
200 OK
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Cache-Control: no-cache
[response data]

The server sends the file and its ETag (usually an MD5 hash of the content).

Subsequent request:

GET /api/users
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Response (if unchanged):
304 Not Modified
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
[no response data]

The browser sends the ETag. If the content hasn't changed, the server responds with 304 Not Modified and no data. The browser uses its cached version.
If the file changed:

Response:
200 OK
ETag: "7f5c8e9a2b3d4c1f6e8a9b0c1d2e3f4a5b6c7d8e"
[new response data]

The server sends the full file with a new ETag.

Strong vs Weak ETags

Strong ETag:

ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Indicates byte-for-byte identical content. Even a single character change produces a different ETag.

Weak ETag:

ETag: W/"33a64df551425fcc55e4d42a148795d9f25f89d4"

Prefixed with W/. Indicates semantically equivalent content, but bytes might differ (e.g., whitespace changes, gzip compression levels).

Use strong ETags for most cases. Weak ETags are for edge cases like dynamic compression.

Last-Modified Header (The Alternative)

Before ETags, there was Last-Modified:

Last-Modified: Wed, 21 Oct 2024 07:28:00 GMT

The browser sends this back as:

If-Modified-Since: Wed, 21 Oct 2024 07:28:00 GMT

If the file hasn't been modified since that timestamp, the server responds with 304 Not Modified.
ETags vs Last-Modified:

Feature	ETag	Last-Modified
Precision	Exact (content-based)	1-second granularity
Use case	Dynamic content, APIs	Static files
Performance	Requires hash calculation	Just timestamp check
Reliability	More accurate	Can fail with clock skew

Use ETags for APIs and dynamic content. Use Last-Modified (or both) for static files.

When to use ETags?

Content changes unpredictably.
You can't set long max-age times.
Users need reasonably fresh data.
The cost of serving stale content is high.

Examples:

HTML pages (need to check for updates, but don't want full re-downloads).
API endpoints that change occasionally.
User-generated content.

Don't use ETags when:

You have long max-age times (no validation needed during fresh period).
Every request needs fresh data anyway (just use no-store).
Computing the ETag is expensive (defeats the performance benefit).

Code Examples in Node.js/Express

Let's look at code snippets on how to implement caching.

Set up Express

const express = require('express');
const app = express();

Caching Static Assets
For static files (CSS, JS, images), use aggressive caching:

app.use('/static', express.static('public', {
  maxAge: '1y',
  immutable: true
}));

This automatically adds Cache-Control: public, max-age=31536000, immutable
Note: Only use this for versioned filenames like app.a1b2c3.js.

API Response - Public Data
Cache public API data for 5 minutes:

app.get('/api/products', (req, res) => {
  res.set('Cache-Control', 'public, max-age=300');
    const products = [
    { id: 1, name: 'Product A', price: 29.99 },
    { id: 2, name: 'Product B', price: 49.99 }
  ];

  res.json(products);
});

API Response - User-Specific Data
Cache user data privately for 10 minutes:

app.get('/api/user/profile', (req, res) => {
  res.set('Cache-Control', 'private, max-age=600');

  const profile = {
    id: 123,
    name: 'John Doe',
    email: 'john@example.com'
  };

  res.json(profile);
});

HTML Pages - Always Validate

app.get('/', (req, res) => {
  res.set('Cache-Control', 'no-cache');
  res.sendFile(path.join(__dirname, 'public', 'index.html'));
});

Express automatically generates ETags. The browser will validate on each request.

Implementing ETags Manually
For more control over validation:

const crypto = require('crypto');

app.get('/api/data', (req, res) => {
  const data = {
    timestamp: Date.now(),
    message: 'Hello World'
  };

  const etag = crypto
    .createHash('md5')
    .update(JSON.stringify(data))
    .digest('hex');

  if (req.headers['if-none-match'] === etag) {
    return res.status(304).end();
  }

  res.set('ETag', etag);
  res.set('Cache-Control', 'no-cache');
  res.json(data);
});

Preventing Cache for Sensitive Data

app.get('/api/banking/account', (req, res) => {
  res.set('Cache-Control', 'no-store, private');

  const account = {
    balance: 15234.56,
    accountNumber: '****1234'
  };

  res.json(account);
});

Reusable Cache Middleware
You can create a middleware to simplify setting Cache-Control.

const cache = (duration, options = {}) => {
  return (req, res, next) => {
    const type = options.private ? 'private' : 'public';
    const directives = [type, `max-age=${duration}`];

    if (options.immutable) directives.push('immutable');
    if (options.mustRevalidate) directives.push('must-revalidate');

    res.set('Cache-Control', directives.join(', '));
    next();
  };
};

app.get('/api/posts', cache(300), (req, res) => {
  const posts = [
    { id: 1, title: 'First Post' },
    { id: 2, title: 'Second Post' }
  ];
  res.json(posts);
});

app.get('/api/user/settings', cache(600, { private: true }), (req, res) => {
  const settings = { theme: 'dark', notifications: true };
  res.json(settings);
});

Quick Reference Table

Below is a quick reference of resource types and which type of cache directives to use.

Resource Type	Cache-Control	Duration	Notes
Versioned CSS/JS	public, max-age=31536000, immutable	1 year	Filename changes on update
Unversioned images	public, max-age=86400	1 day	Use shorter for frequently updated
HTML pages	no-cache	Validate each time	Allow caching with ETag
Public API (slow changes)	public, max-age=3600	1 hour	Adjust based on update frequency
Public API (frequent changes)	public, max-age=300	5 minutes	Good default
User data	private, max-age=600	10 minutes	Private ensures no CDN caching
Real-time data	public, max-age=5	5 seconds	Or use no-store
Sensitive data	no-store, private	Never	Banking, health records

Final Thoughts

Every unnecessary network request is a missed opportunity. Every repeated download of the same CSS file wastes time and bandwidth. HTTP caching headers solve this. They tell browsers to reuse resources that haven't changed, eliminating redundant requests and making your site feel instant.

useOptimistic: Build Snappier React UIs with Optimistic Updates

Ugochukwu Nebolisa — Tue, 03 Mar 2026 15:00:51 +0000

Intro

Have you ever clicked a like button on a social media post and watched it... do nothing for a second? Maybe it shows a loading spinner. Maybe the button just sits there, unresponsive, while your click travels to the server and back.

Now compare that to Instagram or Twitter. You tap the heart icon, and it instantly turns red. No waiting. No spinners. The UI responds immediately, making the app feel lightning-fast even if your network connection isn't.

That is an optimistic update. The UI assumes your action will succeed and updates immediately, while the actual server request happens in the background. If something goes wrong, it quietly rolls back.

React 19 introduced the useOptimistic hook to make this pattern easy to implement. Before this hook, you had to manually manage optimistic state, handle rollbacks, and coordinate between local UI state and server state. It was doable, but messy. With useOptimistic, you get instant UI feedback with just a few lines of code.

In this article, we will build a real example from scratch, compare it side-by-side with the traditional useState approach and learn when you should (and shouldn't) use optimistic updates.

Why useOptimistic?

Before we write build an example, let's understand where optimistic updates shine. These are scenarios where the user action is highly likely to succeed and waiting for server confirmation creates unnecessary friction.

Social Interactions (Likes and Comments):
When a user likes a post, they expect the heart to turn red instantly. If there is a 500ms round-trip delay to the database, the app feels "heavy." Since a "Like" rarely fails due to business logic, it's the perfect candidate for an optimistic update.
Task Management (To-Do Lists or Kanban):
Checking off a task or moving a card between columns should feel tactile. Using useOptimistic, the task moves immediately. If the server eventually returns an error (e.g., a lost connection), the hook automatically rolls the UI back to its previous state.
Real-time Messaging:
Modern chat apps don't show a "sending..." spinner for every single message. They append the message to the chat window immediately with a slightly faded style. Once the server confirms, the style updates to "sent."

The use cases are not limited to the three above. But you will quickly notice that useOptimistic works best when:

The operation is likely to succeed.
The rollback is simple and safe.
The operation is not critical.
Instant feedback will greatly improve UX.

Setting up a project

Now for the fun part, Let's create a fresh React app with TypeScript using Vite. We will keep it minimal, no unnecessary dependencies.

# Create a new Vite project with React and TypeScript
npm create vite@latest useoptimistic-demo -- --template react-ts

# Navigate into the project
cd useoptimistic-demo

# Install dependencies
npm install

# Start the dev server
npm run dev

Your app should now be running at http://localhost:5173.

Open up the project folder in your favorite code editor, then delete the boilerplate files/folders: src/assets, src/App.css, src/index.css(we will use inline style for this). Also delete where they were imported from the remaining files.

Let's build the bare UI. Replace what you have in your src/App.tsx with this:

import { useState } from "react";

const mockPost = {
  id: "post-1",
  author: "Jane Doe",
  content: "Just learned about useOptimistic in React 19!",
  likes: 42,
  isLiked: false,
};

function App() {
  const [post, setPost] = useState(mockPost);

  const handleLike = () => {
    // Logic goes here
  };

  return (
    <div
      style={{
        minHeight: "100vh",
        background: "#f5f5f5",
        padding: "2rem",
      }}
    >
      <div
        style={{
          maxWidth: "600px",
          margin: "0 auto",
        }}
      >
        <h1
          style={{
            marginBottom: "2rem",
            color: "#333",
            fontSize: "2rem",
          }}
        >
          useOptimistic
        </h1>

        <div
          style={{
            background: "white",
            borderRadius: "12px",
            padding: "1.5rem",
          }}
        >
          <div
            style={{
              marginBottom: "1rem",
            }}
          >
            <h3
              style={{
                fontSize: "1rem",
                fontWeight: "600",
                color: "#333",
                margin: 0,
              }}
            >
              {post.author}
            </h3>
          </div>

          <p
            style={{
              color: "#555",
              lineHeight: "1.6",
              marginBottom: "1.5rem",
              fontSize: "0.95rem",
            }}
          >
            {post.content}
          </p>

          <div
            style={{
              display: "flex",
              alignItems: "center",
              gap: "0.5rem",
            }}
          >
            <button
              onClick={handleLike}
              style={{
                background: "transparent",
                border: "none",
                cursor: "pointer",
                fontSize: "1.5rem",
                padding: "0.5rem",
                display: "flex",
                alignItems: "center",
                justifyContent: "center",
                transition: "transform 0.2s",
              }}
            >
              {post.isLiked ? "❤️" : "🤍"}
            </button>
            <span
              style={{
                color: "#666",
                fontSize: "0.9rem",
                fontWeight: "500",
              }}
            >
              {post.likes} likes
            </span>
          </div>
        </div>
      </div>
    </div>
  );
}

export default App;

What we have is just UI, nothing happens just yet. Feel free to make changes to the design if you'd like.

Using useState Hook

Before we jump right in to useOptimistic, I want us to have a feeling about how useState alone will handle it. Replace your handleLike function with this.

  const handleLike = async () => {
    // We are simulating a network delay.
    await new Promise((resolve) => setTimeout(resolve, 2000));

    setPost((prev) => ({
      ...prev,
      likes: prev.likes + (prev.isLiked ? -1 : 1),
      isLiked: !prev.isLiked,
    }));
  };

What did you notice? We see that we had to wait for about 2 seconds before the "Like" heart turned red.

With useOptimistic Hook

Now let's adapt our component to use the useOptimistic hook. Replace your App.tsx with the code below:

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

const mockPost = {
  id: "post-1",
  author: "Jane Doe",
  content: "Just learned about useOptimistic in React 19!",
  likes: 42,
  isLiked: false,
};

function App() {
  const [post, setPost] = useState(mockPost);
  const [optimisticPost, setOptimisticPost] = useOptimistic(
    post,
    (currentPost, newLikeState: { isLiked: boolean; likes: number }) => ({
      ...currentPost,
      ...newLikeState,
    }),
  );

  const handleLikeAction = async () => {
    const newIsLiked = !optimisticPost.isLiked;
    const newLikes = optimisticPost.likes + (newIsLiked ? 1 : -1);

    startTransition(async () => {
      setOptimisticPost({ isLiked: newIsLiked, likes: newLikes });

      // We are simulating a network delay.
      await new Promise((resolve) => setTimeout(resolve, 2000));

      setPost((prev) => ({
        ...prev,
        likes: prev.likes + (prev.isLiked ? -1 : 1),
        isLiked: !prev.isLiked,
      }));
    });
  };

  return (
    <div
      style={{
        minHeight: "100vh",
        background: "#f5f5f5",
        padding: "2rem",
      }}
    >
      <div
        style={{
          maxWidth: "600px",
          margin: "0 auto",
        }}
      >
        <h1
          style={{
            marginBottom: "2rem",
            color: "#333",
            fontSize: "2rem",
          }}
        >
          useOptimistic
        </h1>

        <div
          style={{
            background: "white",
            borderRadius: "12px",
            padding: "1.5rem",
          }}
        >
          <div
            style={{
              marginBottom: "1rem",
            }}
          >
            <h3
              style={{
                fontSize: "1rem",
                fontWeight: "600",
                color: "#333",
                margin: 0,
              }}
            >
              {post.author}
            </h3>
          </div>

          <p
            style={{
              color: "#555",
              lineHeight: "1.6",
              marginBottom: "1.5rem",
              fontSize: "0.95rem",
            }}
          >
            {post.content}
          </p>

          <div
            style={{
              display: "flex",
              alignItems: "center",
              gap: "0.5rem",
            }}
          >
            <button
              onClick={handleLikeAction}
              style={{
                background: "transparent",
                border: "none",
                cursor: "pointer",
                fontSize: "1.5rem",
                padding: "0.5rem",
                display: "flex",
                alignItems: "center",
                justifyContent: "center",
                transition: "transform 0.2s",
              }}
            >
              {optimisticPost.isLiked ? "❤️" : "🤍"}
            </button>
            <span
              style={{
                color: "#666",
                fontSize: "0.9rem",
                fontWeight: "500",
              }}
            >
              {optimisticPost.likes} likes
            </span>
          </div>
        </div>
      </div>
    </div>
  );
}

export default App;

Did you notice the change? Now the like state changes instantly as the user clicks. But let's understand what is happening. Let's analyze the useOptimistic code block.

  const [optimisticPost, setOptimisticPost] = useOptimistic(
    post, // current state
    (currentPost, newLikeState: { isLiked: boolean; likes: number }) => ({ // reducer function
      ...currentPost,
      ...newLikeState,
    }),
  );

The hook receives two values:

The current value/ state (passthrough):
This is the "source of truth." It is the value that will be returned whenever no optimistic update is in progress.This usually comes from your server data or a useState hook.
An optional reducer function (which takes in two arguments):

currentState: The current optimistic state (or the passthrough value if this is the first update).
optimisticValue: The "action" or payload you passed to the trigger function. It doesn't have to be a boolean; it can be an object (just like we did), a string, or whatever piece of data you need to calculate the next state.

Then the hook returns two values:

optimisticState (The Result):
This is the value you use in your JSX. If an update is pending (inside a transition), this is the value calculated by your reducer. If no update is pending, this automatically reverts to the passthrough (the real state).
addOptimistic (The Trigger):
This is a function you call to kick off the update. It takes one argument: the optimisticValue (the payload) that you want to send to your reducer.

If you notice, you will see that we used a transition (startTransition). Optimistic updates must happen inside a transition or a Server Action, this tells react when to start or stop the optimistic state (basically helps it to track the optimistic state).

Now, one may ask, what happens when a network request fails? Let's find out. Change your handleLikeAction function to this:

 const handleLikeAction = async () => {
    const newIsLiked = !optimisticPost.isLiked;
    const newLikes = optimisticPost.likes + (newIsLiked ? 1 : -1);

    startTransition(async () => {
      setOptimisticPost({ isLiked: newIsLiked, likes: newLikes });

      try {
        // We are simulating a network delay.
        await new Promise((_, reject) => setTimeout(reject, 2000));

        setPost((prev) => ({
          ...prev,
          likes: prev.likes + (prev.isLiked ? -1 : 1),
          isLiked: !prev.isLiked,
        }));
      } catch (error) {
        console.error("Failed to update like status:", error);
      }
    });
  };

You see the magic? When we clicked on like, the heart turns red instantly. But then our promise is rejected (simulating network failure) and immediately the state is reverted to unlike. This then tells you that react always compares the real state of our post object with that of the optimistic state. If the transition finishes and the two states are not the same (because our setPost never ran due to an error), React realizes the "lie" was wrong and snaps the UI back to match the real state. You don't have to manually rollback.

What you can do is to handle your error in the catch block either by showing an error toast or just logging on the console if there's no need to give a visual feedback of that error.

When NOT to Use useOptimistic

While useOptimistic is powerful, it is not appropriate for every situation. Using it incorrectly can lead to poor user experience, data inconsistencies, or even dangerous bugs.

Let's explore scenarios where you should avoid optimistic updates

Financial Transactions (Payments, Transfers, Refunds):
Imagine clicking "Send 500 (in your local currency)" and the UI immediately shows "Payment sent", but the server rejects it due to insufficient funds. By the time the error appears and the UI rolls back, the user might have already closed the app, thinking the payment went through. Rather, show a clear loading state. Wait for server confirmation before updating the UI.
Destructive Actions (Delete, Archive, Permanent Changes):
Deleting something optimistically means it disappears from the UI immediately. If the deletion fails, the item reappears confusing users who might think it is a bug or duplicate. User's might even lose trust in your app's reliability.
Complex Business Logic:
If the success of an action depends on server-side calculations that the client can't predict, skip it. For example, a Promo Code input. You can't optimistically assume a code is valid and apply a discount before the server validates it.

So always check if failure is critical, destructive, or has external side effects. If that's the case, avoid useOptimistic.

Use `useOptimistic` when	Avoid `useOptimistic` when
Action is highly likely to succeed.	Action has a high chance of rejection.
The operation is non-critical (likes, reactions, follows)	The operation is critical (payments, deletions, account changes)
The goal is perceived speed.	The goal is absolute accuracy.
Server validation is simple.	Server validation is complex.

Final Thought

Phew... If you made to the end, congratulations cause it has been a long one. useOptimistic is a small hook with a big impact. It transforms user interactions from slow and waiting to instant and delightful. The best part? It's not even about making your backend faster. It's about being smarter with how you present state changes to users. Start small. Add it to one feature. Feel the difference. Then expand from there. You can get the react's official documentation here useOptimistic react docs. Happy Coding :).

Git HEAD

Ugochukwu Nebolisa — Tue, 17 Feb 2026 14:00:10 +0000

Git HEAD: It’s Not as Scary as It Sounds

Ugochukwu Nebolisa ・ Feb 17

#git #beginners

Git HEAD: It’s Not as Scary as It Sounds

Ugochukwu Nebolisa — Tue, 17 Feb 2026 13:49:14 +0000

Intro

Ever run a command and seen the message You are in 'detached HEAD' state? If you’re like me, your first instinct was probably to close the terminal and hope your computer didn't explode. But don't panic. HEAD is actually your best friend in Git.

What is Git HEAD

Simply put, HEAD is a pointer to your current location in your Git repository. Think of it as a "You Are Here" sticker on your project’s map.

More technically, HEAD is a reference that points to the current branch reference, which in turn points to the latest commit on that branch. When you make a new commit, Git updates your current branch to point to this new commit, and HEAD follows along.

You can see where HEAD is pointing at any time by running:

git log --oneline -1

Or you can get the full details by running

cat .git/HEAD

In most cases, you will see something like ref: refs/heads/main, which means HEAD is pointing to the main branch (mine points to master). This is called a "symbolic reference" which means that HEAD points to a branch name, not directly to a commit.

How HEAD Moves When You Work

Understanding how HEAD moves is key to understanding Git itself. Let's look at the most common scenarios:

When You Make a Commit

When you create a new commit:

Git creates a new commit object with your changes
Git updates your current branch to point to this new commit
HEAD (which points to your branch) automatically follows along

Remember our first commit?

We see that the HEAD was pointing to that very first commit. What if we add another one then run the same command git log --oneline -1

# Make a change and commit
git add .
git commit -m "new feature"

# We will see that HEAD has moved to that commit
git log --oneline -1

We now see that HEAD points to the latest commit in our current branch.

What happens when we switch branches?

# Let's create and checkout a branch
git checkout -b feature-branch

# Verify which branch we are on
git branch

We see that we are at our newly created branch. Let's now run cat .git/HEAD and see where our HEAD points to.

Nice, we see that our head points to the current checkout branch.

HEAD, Working Directory, and Staging Area: What's the Difference?

HEAD represents your last committed state, the snapshot of your project as it was when you last committed (We've understood this one already).

The Working Directory is what you actually see in your file system right now. The files you are actively editing. Changes here are untracked by Git until you explicitly tell it about them.

The Staging Area (Index) is a middle ground. A "preparation zone" where you place changes that you intend to include in your next commit. When you run git add, you are moving changes from your working directory into the staging area.

Detached HEAD State

Have you seen this message before?
You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by switching back to a branch.

It's not as scary as it looks. Remember how we said HEAD normally points to a branch, which then points to a commit? In detached HEAD state, that middle step is skipped. HEAD points directly to a commit instead of a branch. So instead of HEAD to point to the branch the commit belongs to, it points directly to that commit instead of the branch.

How do you end up in a detached HEAD?
Simple, run the command

git checkout <commit ID/Hash>

What happens when we run this command cat .git/HEAD again?

We see that it return a commit hash instead of a branch name, meaning that our HEAD now points to the commit.

What can you do in a detached HEAD?

You can simply make experimental changes and if you don't really need those changes, you can checkout to any available branches. Git will eventually garbage collect those commits and they will be lost. This is the only genuine risk of detached HEAD state.
If you have made those experimental changes and you feel you would love to retain them, you can simply checkout a new branch from your current state git checkout -b <new-branch>.This "attaches" your detached HEAD commits to a real branch, so they won't be lost.
What if you checkout to an available branch mistakenly? Does it mean that the changes you made in a detached HEAD is gone? Don't worry yet, Git keeps a log of everywhere HEAD has been. Run git reflog and we will get something like this:

Find the commit hash of your lost work then run git checkout -b recovery-branch <commit-hash>

Wrapping Up

You now have a solid understanding of one of Git's most fundamental concepts. Before we finish, let's connect HEAD to a command you have probably seen or used before and now you will understand exactly why it works.

You may have seen this command suggested as a way to undo your last commit:

git reset HEAD~1

Now that you understand HEAD, you know why this command works:

HEAD: your current commit (the one you just made)
~1: "one commit before"
git reset HEAD~1: "move HEAD back one commit"

Git simply moves your branch pointer and HEAD along with it, back to the previous commit, effectively undoing your last commit while keeping your changes in the working directory.
The same logic applies to HEAD~2 (two commits back), HEAD~3, and so on. Once you see HEAD as a pointer you can do arithmetic on, a whole family of Git commands suddenly start to make sense.

Final Thoughts

Git HEAD is one of those concepts that quietly underpins almost everything you do in Git. Once you internalize that it is just a pointer,one that you can move, inspect, and reason about, commands that once felt daunting to understand suddenly becomes easy.

The next time you see a detached HEAD warning or reach for git reset, you will know exactly what's happening under the hood.

git commit -m "Happy commiting :)"

I Broke My Portfolio: The Debugger Protocol

Ugochukwu Nebolisa — Sat, 31 Jan 2026 11:04:38 +0000

This is a submission for the New Year, New You Portfolio Challenge Presented by Google AI

About Me

Hi, I'm a Software Engineer who builds web applications from database to deployment. With a strong foundation in React and Node.js, I create seamless user experiences backed by robust APIs and efficient data systems. I enjoy solving real problems through code. I built a puzzle portfolio because I wanted to express that engineering is about solving problems, not just writing code.

Portfolio

Live Demo: https://the-debugger-portfolio-899943784474.us-west1.run.app

How I Built It

The concept was simple: The portfolio loads in a "Critical Failure" state. The user (the recruiter) acts as the Lead Engineer and must drag-and-drop the correct technology chips to "patch" the bugs and reveal my projects.

The Tech Stcak

Frontend: Next.js (App Router) for the framework.
Styling: Tailwind CSS. I leaned heavily into a "Cyberpunk/Terminal" aesthetic to sell the "System Failure" vibe.
State Management: Zustand. I needed a robust state machine to handle the sequential leveling system (Intro -> Level 1 -> Level 2 -> Level 3 -> Victory).
Interactivity: react-dnd for the drag-and-drop mechanics.

Powered by Google AI

Gemini API (The AI Assistant): I integrated the Gemini API to act as a "System AI." If a user struggles to fix a bug (e.g., they try to use MongoDB to fix a Real-Time WebSocket error), Gemini analyzes the game state and provides a context-aware hint. It explains why that tech was the wrong choice, effectively teaching the user about my stack while they play.
Google AI Studio: I used Gemini 3 Pro (Preview) in AI Studio to help architect the "Game State" logic. It helped me map out the complex relationships between the error messages and the valid solutions for my specific projects.

Deployment

The entire application is containerized using Docker and deployed to Google Cloud Run. This ensures that the animation-heavy UI runs smoothly and scales automatically.

What I'm Most Proud Of

First and foremost, I am really proud and amazed of how far AI has come. With just a simple prompt, one can achieve a lot of things (the limitation is just your mind).

I'm also proud of the "Narrative Logic" of the game. I didn't just throw random bugs at the user. Each level corresponds to the actual architecture of my projects:

Level 1 (Save-It): You have to fix the Real-Time layer using Ably/Firebase.
Level 2 (Brij): You have to fix the Fullstack Routing using Next.js.
Level 3 (Graso): You have to fix the Asset Tokenization using Sui Move.

It forces the user to understand the architecture of my projects to win. By the time they unlock the final screen, they don't just know what I built—they understand how I built it.

Building a Message-to-SQL AI Agent with Mastra and Telex.im

Ugochukwu Nebolisa — Sun, 02 Nov 2025 20:19:24 +0000

Introduction

As developers, we spend a significant amount of time writing SQL queries. Whether it's a simple SELECT statement or a complex JOIN with multiple aggregations, remembering the exact syntax can be tedious. What if you could just describe what you want in plain English and get production-ready SQL?

That's exactly what I built for the HNG Stage 3 Backend Task - a Message-to-SQL AI Agent that translates natural language into SQL queries using Mastra AI and integrated with Telex.im.

The Problem

Every developer faces these challenges:

Syntax Complexity: SQL has different dialects (PostgreSQL, MySQL, SQLite, etc.) with subtle differences
Best Practices: It's easy to write working SQL that performs poorly or has security issues
Context Switching: Moving between thinking about business logic and remembering SQL syntax breaks flow
Security: SQL injection vulnerabilities are still one of the most common security issues

The Solution

I built an AI agent that:

Converts natural language to SQL queries
Validates syntax and suggests best practices
Explains complex queries in plain English
Optimizes queries for better performance
Works with multiple SQL dialects
Integrates seamlessly with Telex.im for team collaboration

Technical Architecture

Tech Stack

Framework: Mastra AI - A powerful TypeScript framework for building AI agents
LLM: Grok llama-3.1-8b-instant for natural language understanding
Integration Platform: Telex.im - An AI agent platform like Make.com, but specifically designed for communities, bootcamps, and educational environments. Think of it as a Slack alternative where AI agents work alongside humans.
Language: TypeScript with Node.js
Storage: LibSQL for agent memory and observability

Try It Live!

Try the SQL Agent on Telex

This agent translates your natural language questions into production-ready SQL queries. Just ask it something like "Get all users who registered in the last 30 days" and it will generate optimized SQL with security checks, formatting, and explanations

Why Mastra?

Mastra made this project straightforward because it provides:

Built-in Agent Framework: No need to build from scratch
Tool System: Easy to create specialized tools for SQL operations
Workflow Management: Clean way to orchestrate multi-step processes
Memory & Context: Built-in conversation memory
Observability: Out-of-the-box tracing and monitoring
Scoring System: Quality evaluation for agent outputs

Specific Mastra Features Used

Here are the key Mastra features I leveraged in this project:

1. Agent Framework (`@mastra/core/agent`)

import { Agent } from '@mastra/core/agent';

export const sqlAgent = new Agent({
  name: 'SQL Generator Agent',
  instructions: '...',  // Detailed system prompt
  model: 'groq/llama-3.1-8b-instant',  // LLM configuration
  tools: { ... },  // Custom tools
  scorers: { ... },  // Quality evaluation
  memory: new Memory({ ... })  // Conversation context
});

This gave me a production-ready agent with just a few lines of configuration.

2. Tool System (`@mastra/core/tools`)

import { createTool } from '@mastra/core/tools';

export const sqlValidatorTool = createTool({
  id: 'sql-validator',
  description: "'Validates and formats SQL queries',"
  inputSchema: z.object({ ... }),  // Zod validation
  outputSchema: z.object({ ... }),
  execute: async ({ context }) => { ... }
});

The tool system made it easy to extend the agent with specialized SQL capabilities.

3. Workflow Orchestration (`@mastra/core/workflows`)

import { createStep, createWorkflow } from '@mastra/core/workflows';

const sqlWorkflow = createWorkflow({
  id: 'sql-workflow',
  inputSchema: z.object({ ... }),
  outputSchema: z.object({ ... })
}).then(generateSQLStep);

Workflows allowed me to chain multiple steps and handle complex logic flows.

4. Quality Scoring (`@mastra/core/scores`)

import { createScorer } from '@mastra/core/scores';

export const sqlCorrectnessScorer = createScorer({
  name: 'SQL Correctness',
  type: 'agent',  // LLM-as-judge
  judge: {
    model: 'groq/llama-3.1-8b-instant',
    instructions: '...'
  }
})
  .preprocess(({ run }) => { ... })
  .analyze({ ... })
  .generateScore(({ results }) => { ... })
  .generateReason(({ results, score }) => { ... });

The scoring system uses LLM-as-judge to evaluate output quality automatically.

5. Memory & Context (`@mastra/memory`)

import { Memory } from '@mastra/memory';
import { LibSQLStore } from '@mastra/libsql';

memory: new Memory({
  storage: new LibSQLStore({
    url: 'file:../mastra.db'
  })
})

Built-in memory storage maintains conversation context across interactions.

Building the Agent

Step 1: Project Setup

First, I initialized the project with Mastra:

npm create mastra@latest -y

The project structure:

src/mastra/
├── agents/
│   └── sql-agent.ts       # Main agent definition
├── tools/
│   └── sql-tool.ts        # SQL tools
├── scorers/
│   └── sql-scorer.ts      # Quality evaluation
├── workflows/
│   └── sql-workflow.ts    # Workflow orchestration
└── index.ts               # Mastra configuration

Step 2: Creating SQL Tools

I built four specialized tools to enhance the agent's capabilities:

1. SQL Validator Tool

export const sqlValidatorTool = createTool({
  id: "sql-validator",
  description: "Validates and formats SQL queries",
  inputSchema: z.object({
    sql: z.string(),
    dialect: z
      .enum(["postgresql", "mysql", "sqlite", "mssql", "oracle"])
      .optional(),
  }),
  outputSchema: z.object({
    isValid: z.boolean(),
    formatted: z.string(),
    warnings: z.array(z.string()),
    suggestions: z.array(z.string()),
  }),
  execute: async ({ context }) => {
    return validateSQL(context.sql, context.dialect || "postgresql");
  },
});

This tool checks for:

SQL syntax correctness
Dangerous patterns (missing WHERE in UPDATE/DELETE)
Best practice violations (SELECT *)
Security vulnerabilities

2. Schema Info Tool

Provides common database patterns and examples:

export const schemaInfoTool = createTool({
  id: "schema-info",
  description: "Provides common database schema patterns",
  inputSchema: z.object({
    tableType: z.string(),
  }),
  outputSchema: z.object({
    commonColumns: z.array(z.string()),
    relationships: z.array(z.string()),
    examples: z.array(z.string()),
  }),
  execute: async ({ context }) => {
    return getSchemaInfo(context.tableType);
  },
});

3. SQL Explainer Tool

Breaks down complex queries into understandable components:

export const sqlExplainerTool = createTool({
  id: "sql-explainer",
  description: "Explains what a SQL query does in plain English",
  inputSchema: z.object({
    sql: z.string(),
  }),
  outputSchema: z.object({
    explanation: z.string(),
    components: z.array(
      z.object({
        part: z.string(),
        description: z.string(),
      })
    ),
  }),
  execute: async ({ context }) => {
    return explainSQL(context.sql);
  },
});

4. SQL Optimizer Tool

Suggests performance improvements:

export const sqlOptimizerTool = createTool({
  id: "sql-optimizer",
  description: "Suggests optimizations for SQL queries",
  // ... implementation
});

Step 3: Defining the Agent

The agent ties everything together with clear instructions:

export const sqlAgent = new Agent({
  name: "SQL Generator Agent",
  instructions: `
You are an expert SQL assistant that helps developers translate 
natural language queries into SQL statements.

Guidelines:
- Ask for clarification on table/column names if not specified
- Default to PostgreSQL syntax unless specified
- Use explicit JOIN syntax
- Avoid SELECT * in production queries
- Include security warnings for dangerous patterns
- Format with proper indentation
  `,
  model: "groq/llama-3.1-8b-instant",
  tools: {
    sqlValidatorTool,
    schemaInfoTool,
    sqlExplainerTool,
    sqlOptimizerTool,
  },
  scorers: {
    sqlCorrectness: {
      /* ... */
    },
    intentMatch: {
      /* ... */
    },
    readability: {
      /* ... */
    },
  },
  memory: new Memory({
    storage: new LibSQLStore({ url: "file:../mastra.db" }),
  }),
});

Step 4: Quality Scoring

I implemented three scorers to ensure high-quality outputs:

SQL Correctness Scorer

Uses groq/llama-3.1-8b-instant as a judge to evaluate:

Syntax correctness
Best practices adherence
Security issues

export const sqlCorrectnessScorer = createScorer({
  name: "SQL Correctness",
  type: "agent",
  judge: {
    model: "groq/llama-3.1-8b-instant",
    instructions: "Evaluate SQL for syntax, best practices, and security...",
  },
})
  .preprocess(({ run }) => {
    /* Extract SQL */
  })
  .analyze({
    /* Analyze quality */
  })
  .generateScore(({ results }) => {
    /* Calculate score */
  })
  .generateReason(({ results, score }) => {
    /* Explain score */
  });

Intent Match Scorer

Ensures the generated SQL matches what the user actually wanted:

export const intentMatchScorer = createScorer({
  name: "Intent Match",
  // Checks if SELECT query was generated for retrieval intent, etc.
});

Readability Scorer

Evaluates formatting and documentation:

export const readabilityScorer = createScorer({
  name: "SQL Readability",
  // Checks formatting, indentation, comments
});

Step 5: Creating the Workflow

The workflow orchestrates the entire process:

const generateSQLStep = createStep({
  id: "generate-sql",
  description: "Generates SQL query from natural language",
  execute: async ({ inputData, mastra }) => {
    const agent = mastra?.getAgent("sqlAgent");

    const response = await agent.stream([
      { role: "user", content: inputData.message },
    ]);

    let responseText = "";
    for await (const chunk of response.textStream) {
      responseText += chunk;
    }

    return { sql: extractSQL(responseText), explanation: responseText };
  },
});

const sqlWorkflow = createWorkflow({
  id: "sql-workflow",
  inputSchema: z.object({
    message: z.string(),
    dialect: z
      .enum(["postgresql", "mysql", "sqlite", "mssql", "oracle"])
      .optional(),
  }),
}).then(generateSQLStep);

Integrating with Telex.im

Setting Up the Integration

Create an AI Co-Worker in Telex
In your Telex dashboard, navigate to the AI Co-Workers section and create a new co-worker.
Deploy the Agent
I deployed to Render for easy hosting
Create Workflow JSON

  {
  "active": true,
  "category": "productivity",
  "description": "A project manager bot that tracks and summarizes tasks for Telex users.",
  "id": "unique_id_generated",
  "long_description": "You help users manage tasks and summarize chat history. Recognize project deadlines, remind users, and provide friendly nudges. Use clear, concise language and ask for missing details.",
  "name": "project_helper_agent",
  "nodes": [
    {
      "id": "task_agent_node",
      "name": "Project helper bot",
      "parameters": {},
      "position": [100, 100],
      "type": "a2a/mastra-a2a-node",
      "typeVersion": 1,
      "url": "https://your-domain.com/a2a/agent/sqlAgent"
    }
  ],
  "pinData": {},
  "settings": {
    "executionOrder": "v1"
  },
  "short_description": "Task/project manager for Telex"
}

Import to Telex
- Upload workflow JSON to Telex
- Activate the workflow

Testing the Integration

The agent works beautifully in Telex! Here's a real conversation:

Me: "Get all users who registered in the last 30 days"

Agent:

SELECT id, username, email, created_at
FROM users
WHERE created_at >= CURRENT_DATE - INTERVAL '30 days'
ORDER BY created_at DESC;

Explanation: This query retrieves user information for accounts created in the last 30 days, sorted by most recent first. It uses explicit column selection (avoiding SELECT *) and includes proper date arithmetic.

Security Note: Use parameterized queries to prevent SQL injection when implementing this.

Conclusion

Building this SQL agent taught me:

AI agents are powerful when combined with specialized tools
Mastra makes building production-ready agents surprisingly straightforward
Quality scoring is essential for reliable outputs
Integration platforms like Telex make agents accessible to teams

Try It Yourself

The project is open source! Check it out:

GitHub: hng-stage-3
Telex Integration: instructions-link

Resources

Acknowledgments

Thanks to:

@mastra for the excellent AI framework
@teleximapp for the integration platform
@hnginternship for this challenging task

What would you build with AI agents? Let me know in the comments!

If you found this helpful, please share it with other developers building AI agents.

Building a Dynamic Profile API with Express.js and TypeScript — HNG Backend Stage Zero

Ugochukwu Nebolisa — Thu, 16 Oct 2025 10:32:52 +0000

Introduction

As part of the HNG Backend Stage 0 challenge, I built a RESTful API using Express.js and TypeScript that returns my profile information together with a random cat fact fetched dynamically from the Cat Facts API.

This project helped me refine key backend concepts like API consumption, structured JSON responses, and handling asynchronous requests gracefully.

Project Overview

The main goal was to create a GET /me endpoint that outputs the following structure:

{
  "status": "success",
  "user": {
    "email": "your.email@example.com",
    "name": "Your Full Name",
    "stack": "Node.js/Express"
  },
  "timestamp": "2025-10-16T12:34:56.789Z",
  "fact": "A random cat fact from Cat Facts API"
}

This JSON response includes my details, a dynamically generated timestamp (in UTC ISO 8601 format), and a random cat fact fetched from an external API.

Tech Stack

Here’s what I used to implement the project:

Runtime: Node.js
Language: TypeScript
Framework: Express.js
HTTP Client: Axios
Additional Libraries: CORS, Dotenv

Implementation

Here’s the simplified version of the /me endpoint:

import express, { Request, Response } from 'express';
import axios from 'axios';
import dotenv from 'dotenv';

dotenv.config();
const app = express();
const PORT = process.env.PORT || 3000;

app.use((req, res, next) => {
console.log([${new Date().toISOString()}] ${req.method} ${req.url});
next();
});

app.get('/me', async (req: Request, res: Response) => {
const timestamp = new Date().toISOString();

let catFact = '';
try {
const { data } = await axios.get('https://catfact.ninja/fact', { timeout: 5000 });
catFact = data.fact;
} catch {
catFact = 'Could not fetch a cat fact at this moment.';
}

res.status(200).json({
status: 'success',
user: {
email: process.env.USER_EMAIL!,
name: process.env.USER_NAME!,
stack: process.env.USER_STACK!,
},
timestamp,
fact: catFact,
});
});

app.listen(PORT, () => {
console.log(Server running on port ${PORT});
});

Testing the API

You can run and test the API locally by executing:

npm run dev

Then, use curl or Postman:

curl http://localhost:3000/me

Expected output:

Deployment

I deployed using PXXL App, a free hosting platform. You can check out the live link here Api Url

What I Learned

This task helped me strengthen:

Error handling: ensuring graceful fallbacks on API failure
Dynamic data generation: timestamps and per-request responses
Environmental configurations: protecting sensitive data
Code readability: through TypeScript interfaces and module separation

Conclusion

The Stage 0 backend task was a straightforward yet meaningful challenge. It blends creativity with structured engineering principles.

I’m excited for the next HNG stage and the opportunity to work with even more complex integrations.

Connect with Me

GitHub: benedictfred
LinkedIn: Ugochukwu Nebolisa
Twitter/X: Nebolisa

That's it brethren.Thanks for reading! If you’re also working on HNG tasks or even any project drop your comment below, let’s connect and grow together

Why I Want to Be a Front-End Developer and How HNG Will Help Me Achieve My Goals

Ugochukwu Nebolisa — Thu, 30 Jan 2025 00:39:12 +0000

My Motivation for Becoming a Front-End Developer

The world of technology has always fascinated me, but my journey into front-end development was driven by my passion for creating visually appealing and interactive web experiences. I always admired the idea of bringing designs to life, ensuring that users have seamless and engaging interactions with web applications. Seeing a well-structured interface respond dynamically to user input excites me, and I am committed to mastering this field to build functional, beautiful, and intuitive digital solutions.
Then, I feel that frontend is a good way to get into tech not because it's really easy but because it's not boring since you see everything you are doing on the web.

How HNG Will Help Me Grow in Front-End Development

The HNG Internship is an incredible opportunity to refine my skills and gain hands-on experience in front-end development. This intensive program offers mentorship from industry experts, real-world projects, and collaboration with talented developers. HNG's structured approach will help me:

Enhance my technical skills: I will sharpen my skills on modern frontend technologies.
Work on real world projects: HNG internship emphasizes on building real world projects, ensuring I learn the structure and format of a real world project.
Collaborate with community: The world of tech is all about collaboration with people with similar minds. Of course this internship will create the platform where I collaborate with other great minds.
Get Mentorship and Feedback: HNG Internship provides experienced mentors that will provide a guidance on how to navigate learning in order to prevent common learning pitfalls.

For companies looking for skilled professionals, you can Hire React.js Developers to bring top-tier front-end solutions to your projects.

My Goals for the HNG Internship & How I Plan to Achieve Them

What is an internship without goals? To make the most of the HNG Internship, I have set clear goals:

Master Advanced Front-End Concepts: I aim to deepen my understanding of frameworks like Next.js and improve my ability to build optimized and fast applications.
Build a strong portfolio: By working on diverse projects, I tend to improve my portfolio that showcases my skills and creativity.
Improve by problem solving skills: By working on different projects, I will meet different problems and also learn different ways to solve them.
Expand My Professional Network: "Your network is your net worth". Connecting with industry professionals and fellow interns will open doors for future collaborations and job opportunities.

Additionally, for businesses in need of skilled professionals, you can Hire Web Developers to elevate your digital presence with cutting-edge web solutions.

Bottom Line

Achieving success in any field is easier when you have the right platform. The HNG Internship provides an ideal environment for me to learn, grow, and ultimately become a top-tier front-end developer.

Bootstrap vs Tailwind

Ugochukwu Nebolisa — Fri, 28 Jun 2024 20:56:11 +0000

Bootstrap

Bootstrap was developed by Mark Otto and Jacob Thornton at Twitter and was released in 2011. It is a free and open-source CSS framework which is aimed at a responsive and easy design of websites. Bootstrap comes with a set of pre-made components which enables one to design a website fast and with ease.

Tailwind

Tailwind is a utility-first CSS framework. It is a highly customizable and low-level CSS framework that gives you all of the building blocks you need to build designs. This framework has no ready made components rather allows you to build your own custom designs with the utility class.

Comparisons

Philosophy:

Bootstrap is a component-based framework which comes with a ready made set of components for quick designing.

Tailwind on the other hand is a utility-first framework which provides low-level utility classes that you can use to build custom designs without pre-defined components.

Performance:

Bootstrap requires some big files to be incorporated in the project for development which occupies a larger space.

Tailwind needs only style sheets to get the work done which takes lesser space.

Customization:

Bootstrap is customizable but it involves overriding existing styles or using provided theme variables to change the look of components.

Tailwind is fully customizable allowing developers to create components using the utility classes enabling granular control over over styles.

Learning Curve:

Bootstrap is easier to learn because of the provided component-based styles making it to be considered as more beginner-friendly CSS framework.

Tailwind due to it's utility-first approach have a steeper learning curve because developers need an understanding of utility-first principles and building designs from scratch.

Community:

Bootstrap has a well-established community with a well-defined documentations, plugins and themes providing good support to developers.

Tailwind has a rapidly growing ecosystem with an active community support. Though newer than Bootstrap, it’s gaining popularity quickly.

Which one to choose

Personally, I would say that

Bootstrap is best for:

Quick prototyping and development with a consistent look and feel.
Developers who prefer a predefined set of components.
Beginners who are new to making websites.

Tailwind is best for:

Developers who want complete control over their design and are comfortable building components from scratch.
Projects requiring a unique design with a high degree of customization.
Teams looking to optimize CSS file size with utility-first approaches and modern build tools.

Expectations in HNG

I just got enrolled in HNG internship program. HNG Internship is a remote internship program designed to help young developers and designers improve their skills through practical, hands-on experience. I look forward to being an improved person after this internship and you can be too.
For more enquiries, visit the HNG internship website and find out how you can hire enthusiastic interns

DEV Community: Ugochukwu Nebolisa

HTTP Caching Headers: The Performance Optimization You're Probably Missing

Intro

What is Caching?

Why HTTP Caching Matters

The Two Types of HTTP Caching

How HTTP Caching Works: The Request/Response Cycle

Understanding Cache Storage

Cache-Control: The Primary Caching Header

ETag & Validation: Efficient Change Detection

Strong vs Weak ETags

Last-Modified Header (The Alternative)

Code Examples in Node.js/Express

Quick Reference Table

Final Thoughts

useOptimistic: Build Snappier React UIs with Optimistic Updates

Intro

Why useOptimistic?

Setting up a project

Using useState Hook

With useOptimistic Hook

When NOT to Use useOptimistic

Final Thought

Git HEAD

Git HEAD: It’s Not as Scary as It Sounds

Ugochukwu Nebolisa ・ Feb 17

Git HEAD: It’s Not as Scary as It Sounds

Intro

What is Git HEAD

How HEAD Moves When You Work

When You Make a Commit

What happens when we switch branches?

HEAD, Working Directory, and Staging Area: What's the Difference?

Detached HEAD State

What can you do in a detached HEAD?

Wrapping Up

Final Thoughts

I Broke My Portfolio: The Debugger Protocol

About Me

Portfolio

How I Built It

The Tech Stcak

Powered by Google AI

Deployment

What I'm Most Proud Of

Building a Message-to-SQL AI Agent with Mastra and Telex.im

Introduction

The Problem

The Solution

Technical Architecture

Tech Stack

Try It Live!

Why Mastra?

Specific Mastra Features Used

1. Agent Framework (@mastra/core/agent)

2. Tool System (@mastra/core/tools)

3. Workflow Orchestration (@mastra/core/workflows)

4. Quality Scoring (@mastra/core/scores)

5. Memory & Context (@mastra/memory)

Building the Agent

Step 1: Project Setup

Step 2: Creating SQL Tools

1. SQL Validator Tool

2. Schema Info Tool

3. SQL Explainer Tool

4. SQL Optimizer Tool

Step 3: Defining the Agent

Step 4: Quality Scoring

SQL Correctness Scorer

Intent Match Scorer

Readability Scorer

Step 5: Creating the Workflow

Integrating with Telex.im

Setting Up the Integration

Testing the Integration

Conclusion

Try It Yourself

Resources

Acknowledgments

Building a Dynamic Profile API with Express.js and TypeScript — HNG Backend Stage Zero

1. Agent Framework (`@mastra/core/agent`)

2. Tool System (`@mastra/core/tools`)

3. Workflow Orchestration (`@mastra/core/workflows`)

4. Quality Scoring (`@mastra/core/scores`)

5. Memory & Context (`@mastra/memory`)