DEV Community: Harsh Mangalam

Your Go API Is Running—But Is It Healthy?

Harsh Mangalam — Mon, 20 Jul 2026 07:08:11 +0000

A Go server can start successfully and still be unable to handle real requests.

The process may be running while PostgreSQL is down. The API is alive, but it cannot do its main job.

That led me to a simple question:

If the server is running, is the application truly healthy?

Here is what I learned while building a useful health endpoint in Go.

What is a health endpoint?

A health endpoint is a small HTTP endpoint, usually something like:

GET /health

It is mainly used by Docker, Kubernetes, load balancers, and monitoring tools. These systems call the endpoint and decide whether the application should receive traffic.

Health checks are commonly split into three types:

Liveness: Is the application process running?
Readiness: Can the application handle traffic right now?
Startup: Has the application finished starting?

A liveness check should be simple. Restarting the application will not fix a database outage.

The endpoint in this post is closer to a readiness check because it checks PostgreSQL. If the database is unavailable, the application keeps running but reports that it is not ready for traffic.

Decide what the response should look like

I wanted the response to answer three questions:

Is the whole application healthy?
Which dependency failed?
How long did each check take?

That gave me these two structs:

type Response struct {
    Status    string                 `json:"status"`
    Checks    map[string]CheckResult `json:"checks"`
    Timestamp time.Time              `json:"timestamp"`
}

type CheckResult struct {
    Status     string `json:"status"`
    Error      string `json:"error,omitempty"`
    DurationMS int64  `json:"duration_ms"`
}

func (r Response) Healthy() bool {
    return r.Status == "healthy"
}

The JSON tags control the field names in the response. omitempty hides the error field when there is no error. The small Healthy method keeps the handler easy to read.

When PostgreSQL is available, /health returns 200 OK:

{
  "status": "healthy",
  "checks": {
    "postgres": {
      "status": "up",
      "duration_ms": 2
    }
  },
  "timestamp": "2026-07-20T10:30:00Z"
}

When PostgreSQL is unavailable, it returns 503 Service Unavailable:

{
  "status": "unhealthy",
  "checks": {
    "postgres": {
      "status": "down",
      "error": "ping postgres: connection refused",
      "duration_ms": 8
    }
  },
  "timestamp": "2026-07-20T10:31:00Z"
}

The HTTP status is important. A tool should not need to read the JSON just to learn whether the application is ready.

Give every dependency the same shape

PostgreSQL may not be the only dependency forever. An API might later need Redis, Kafka, or another internal service.

A small interface gives every health check the same shape:

type Checker interface {
    Name() string
    Check(ctx context.Context) error
}

Each checker provides a name for the response and returns an error when its dependency is unavailable.

The PostgreSQL checker is small:

type PostgresChecker struct {
    pool *pgxpool.Pool
}

func NewPostgresChecker(pool *pgxpool.Pool) *PostgresChecker {
    return &PostgresChecker{pool: pool}
}

func (c *PostgresChecker) Name() string {
    return "postgres"
}

func (c *PostgresChecker) Check(ctx context.Context) error {
    if err := c.pool.Ping(ctx); err != nil {
        return fmt.Errorf("ping postgres: %w", err)
    }

    return nil
}

Ping asks the connection pool to contact PostgreSQL. We do not need a large SQL query. A health check should be fast, cheap, and safe to run often.

Wrapping the error with ping postgres adds useful context when something fails.

Run the checks safely

The service has one job: run every checker and combine the results.

type Service struct {
    checkers []Checker
}

func NewService(checkers ...Checker) *Service {
    return &Service{
        checkers: append([]Checker(nil), checkers...),
    }
}

The constructor accepts any number of checkers and stores a copy of the list. The service begins each request with a healthy response and an empty map for the individual results:

response := Response{
    Status:    "healthy",
    Checks:    make(map[string]CheckResult, len(s.checkers)),
    Timestamp: time.Now().UTC(),
}

For each checker, it:

Creates a two-second timeout.
Records the start time.
Runs the check.
Saves its status, error, and duration.
Marks the whole response unhealthy if any check fails.

The important part looks like this:

checkCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()

started := time.Now()
err := checker.Check(checkCtx)

result := CheckResult{
    Status:     "up",
    DurationMS: time.Since(started).Milliseconds(),
}

if err != nil {
    result.Status = "down"
    result.Error = err.Error()
}

Without a timeout, one stuck dependency could make /health wait forever.

The timeout is based on the incoming request context. If the caller disconnects, Go can cancel the remaining work instead of continuing a request nobody is waiting for.

Why run checks concurrently?

Imagine three dependencies:

PostgreSQL: 100 ms
Redis:      200 ms
Kafka:      300 ms

Running them one after another takes about 600 ms. Running them together takes about 300 ms, which is close to the slowest check.

The service starts one goroutine for each checker and uses a sync.WaitGroup to wait for all of them:

for _, checker := range s.checkers {
    wg.Add(1)

    go func(checker Checker) {
        defer wg.Done()
        // Run the check and build its result.
    }(checker)
}

wg.Wait()

The goroutines write to the same response map, so a sync.Mutex protects those writes:

mu.Lock()
response.Checks[checker.Name()] = result
if err != nil {
    response.Status = "unhealthy"
}
mu.Unlock()

With only one dependency, concurrency does not make the endpoint faster. Its value appears when more checks are registered.

Turn the result into HTTP

The handler runs the service, selects the status code, and writes JSON:

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    response := h.service.Check(r.Context())
    statusCode := http.StatusOK

    if !response.Healthy() {
        statusCode = http.StatusServiceUnavailable
    }

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(statusCode)
    _ = json.NewEncoder(w).Encode(response)
}

Finally, the checker, service, and handler are connected in main.go:

postgresChecker := health.NewPostgresChecker(pool)
healthService := health.NewService(postgresChecker)

mux.Handle("GET /health", health.NewHandler(healthService))

One request now follows a clear path:

GET /health
    -> handler
    -> health service
    -> dependency checkers
    -> JSON response

A few practical rules

Health checks should stay lightweight. Avoid large queries, writes, or slow calls to external services.

Health is also not the same as monitoring. A health endpoint answers, "Can this instance receive traffic?" Metrics, logs, and traces explain how the application performs and why failures happen.

Be careful with error messages too. Detailed errors are helpful during development, but a public endpoint should not reveal passwords, connection strings, or other private information.

For a small codebase, all of this can live in one health.go file. Split it later when the file becomes harder to navigate, not simply because it might grow one day.

What I learned

A useful health endpoint is more than a hard-coded {"status":"ok"} response.

It needs clear output, correct HTTP status codes, fast dependency checks, timeouts, and safe handling of multiple checks. It should also know its limit: health tells us whether the application is ready, while monitoring tells us what is happening over time.

It is a small feature, but it makes an API much easier to operate and trust.

From http.ServeMux to Dependency Injection in Go: A Beginner-Friendly Guide

Harsh Mangalam — Fri, 17 Jul 2026 07:29:15 +0000

When I first saw code like this, it felt as if too many things were happening in one line:

mux.Handle("GET /health", health.NewHandler(healthService))

What is a mux? Why are we giving it a handler? How does the handler get the service? Who calls ServeHTTP?

This article answers those questions by starting with the smallest possible Go HTTP server and building toward a clean handler-and-service design one step at a time.

The big idea

An HTTP request moves through the application like this:

GET /health
     │
     ▼
HTTP server
     │
     ▼
ServeMux
     │
     ▼
Health handler
     │
     ▼
Health service
     │
     ▼
Dependency checker

Each part has one job:

The HTTP server receives requests.
The mux decides which handler should receive each request.
The handler translates between HTTP and our application.
The service performs the application logic.
A checker knows how to inspect one dependency, such as PostgreSQL.

Let us build this structure gradually.

Step 1: The smallest useful mux and handler

Go provides an HTTP router called http.ServeMux. A router matches an incoming request with the code that should handle it.

The method-and-path pattern used below, such as "GET /health", requires Go 1.22 or newer.

package main

import (
    "fmt"
    "log"
    "net/http"
)

func main() {
    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "healthy")
    })

    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

There are three important lines here.

First, we create a mux:

mux := http.NewServeMux()

Second, we register a function for GET /health:

mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "healthy")
})

This tells the mux:

When a GET /health request arrives, run this function.

Finally, we start the server and give it the mux:

http.ListenAndServe(":8080", mux)

The server receives requests, but the mux decides where they go.

If we run the program and send this request:

curl http://localhost:8080/health

we receive:

healthy

Step 2: Give the handler function a name

An anonymous function is convenient, but it becomes harder to read as it grows. We can move it into a named function:

func healthHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "healthy")
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /health", healthHandler)

    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

Notice that we pass the function itself:

mux.HandleFunc("GET /health", healthHandler)

We do not call it:

// Wrong: this tries to call the function immediately.
mux.HandleFunc("GET /health", healthHandler())

The mux saves the function and calls it later when a matching request arrives.

Step 3: Introduce a service

Returning a fixed string does not require application logic. A real health endpoint may need to inspect PostgreSQL, Redis, or other dependencies.

We can put that logic in a service:

type HealthService struct{}

func (s *HealthService) Status() string {
    return "healthy"
}

For now, this service still returns a fixed value. That is okay—we are focusing on how the pieces connect.

One easy way to let the handler use the service is with a closure:

func main() {
    service := &HealthService{}
    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        status := service.Status()
        fmt.Fprintln(w, status)
    })

    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

The handler can use service because the function was created in the same surrounding scope.

The request now follows this path:

GET /health → mux → handler function → service.Status()

This is a good solution for a small program.

Step 4: Let a handler struct remember the service

As an application grows, a handler may need several methods or dependencies. A struct gives us a clear place to store them:

type HealthHandler struct {
    service *HealthService
}

The service field means every HealthHandler value remembers which health service it should use.

We create the handler with a constructor:

func NewHealthHandler(service *HealthService) *HealthHandler {
    return &HealthHandler{
        service: service,
    }
}

Passing a dependency into an object from the outside is called dependency injection. Despite the intimidating name, the idea is simple:

Create a value, then give it the things it needs.

The handler does not create its own service. main creates the service and passes it in.

Step 5: Understand the `http.Handler` interface

The standard library defines an interface that is approximately this:

type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

Any type with a matching ServeHTTP method can act as an HTTP handler.

We can make our HealthHandler satisfy that interface:

func (h *HealthHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    status := h.service.Status()
    fmt.Fprintln(w, status)
}

We do not need to write implements http.Handler. Go recognizes automatically that *HealthHandler has the required method.

Now we can register it with mux.Handle:

func main() {
    service := &HealthService{}
    handler := NewHealthHandler(service)

    mux := http.NewServeMux()
    mux.Handle("GET /health", handler)

    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

When a matching request arrives, the mux effectively calls:

handler.ServeHTTP(w, r)

We do not call ServeHTTP ourselves. The standard library does it for us.

`HandleFunc` versus `Handle`

These two methods are similar, so they are easy to confuse.

Use HandleFunc when you have a function:

mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "healthy")
})

Use Handle when you have a value that implements http.Handler:

handler := NewHealthHandler(service)
mux.Handle("GET /health", handler)

A useful shortcut is:

function                         → HandleFunc
value with a ServeHTTP method    → Handle

Applying this to a real health-check package

Now let us return to the original line:

mux.Handle("GET /health", health.NewHandler(healthService))

It becomes easier to understand if we expand it:

healthHandler := health.NewHandler(healthService)

mux := http.NewServeMux()
mux.Handle("GET /health", healthHandler)

The constructor stores the service inside the handler:

type Handler struct {
    service *Service
}

func NewHandler(service *Service) *Handler {
    return &Handler{
        service: service,
    }
}

The handler uses that stored service when a request arrives:

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    response := h.service.Check(r.Context())

    statusCode := http.StatusOK
    if !response.Healthy() {
        statusCode = http.StatusServiceUnavailable
    }

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(statusCode)
    _ = json.NewEncoder(w).Encode(response)
}

The handler has a narrow responsibility:

Ask the service for the current health result.
Choose the correct HTTP status code.
Encode the result as JSON.

It does not know how PostgreSQL is checked. That responsibility belongs elsewhere.

Wiring the complete application

The clearest way to read the application wiring is one layer at a time:

pool, err := db.NewPostgres(ctx)
if err != nil {
    return fmt.Errorf("initialize postgres: %w", err)
}
defer pool.Close()

postgresChecker := health.NewPostgresChecker(pool)
healthService := health.NewService(postgresChecker)
healthHandler := health.NewHandler(healthService)

mux := http.NewServeMux()
mux.Handle("GET /health", healthHandler)

Each line gives one object to the next:

PostgreSQL pool
      │
      ▼
PostgreSQL checker
      │
      ▼
Health service
      │
      ▼
Health handler
      │
      ▼
ServeMux

The shorter version is equivalent:

mux.Handle("GET /health", health.NewHandler(healthService))

The expanded version is often easier to learn and debug. The shorter version is only a convenience; it is not a different design.

Follow one request from beginning to end

Suppose we run:

curl http://localhost:8080/health

Here is what happens:

The HTTP server receives GET /health.
The server passes the request to the mux.
The mux finds the handler registered for GET /health.
The mux calls healthHandler.ServeHTTP(w, r).
The handler calls healthService.Check(r.Context()).
The service runs its registered dependency checkers.
The PostgreSQL checker calls pool.Ping(ctx).
The result returns through the service and handler.
The handler sends JSON and either 200 OK or 503 Service Unavailable.

The dependencies are created from bottom to top during startup:

pool → checker → service → handler → mux

The request travels from top to bottom at runtime:

mux → handler → service → checker → pool

Seeing those as two separate moments—application startup and request handling—usually removes much of the confusion.

Why keep the service and handler separate?

We could put everything inside one handler function. That might be fine for a tiny experiment, but separating them gives us useful boundaries:

The handler deals with HTTP concepts such as request contexts, JSON, and status codes.
The service coordinates health checks and decides whether the application is healthy.
Each checker understands one external dependency.
main creates and connects the components.

This also makes future changes local. Adding Redis does not require changing the handler:

healthService := health.NewService(
    postgresChecker,
    redisChecker,
)

The handler still asks the same service the same question.

Common beginner misunderstandings

“Does the mux execute the handler during startup?”

No. Registering a handler only saves it for later:

mux.Handle("GET /health", healthHandler)

It executes after a matching request arrives.

“Why do we not call `ServeHTTP`?”

The HTTP server and mux call it. Our responsibility is to provide a value with the correct method.

“Is `NewHandler` special Go syntax?”

No. It is an ordinary function following a common naming convention for constructors:

func NewHandler(service *Service) *Handler

“Does the mux know about the service?”

No. The mux knows only about the handler. The handler knows about the service because the service was injected into it.

“Why use a pointer such as `*Handler`?”

The pointer lets the handler methods work with the same handler value and its stored dependencies without copying the struct. This is the usual pattern for stateful handlers.

Final mental model

If you remember only five ideas, remember these:

http.Server receives HTTP requests.
http.ServeMux chooses a handler based on the request path and method.
A type becomes an http.Handler by defining ServeHTTP.
A handler can store a service in a struct field.
main creates the dependencies and connects them together.

The line that once looked complicated:

mux.Handle("GET /health", health.NewHandler(healthService))

now reads naturally:

Create a health handler that uses this health service, then register it for GET /health.

That is the core of mux, handlers, and dependency injection in Go.

How Next.js Image Optimization Works Under the Hood

Harsh Mangalam — Thu, 16 Jul 2026 06:39:54 +0000

When I first started using Next.js, I replaced every <img> with <Image /> because the documentation said it was "optimized."

It worked.

But I had one question:

What is it actually doing behind the scenes?

After digging into it, I realized the idea is much simpler than I expected.

Let's walk through it together.

The problem with a normal `<img>`

Imagine you have a beautiful travel photo.

taj-mahal.png
4000 × 3000
6 MB

You display it on your website like this:

<img src="/taj-mahal.png" />

When someone opens your page, the browser asks the server for that image.

Browser
   │
   ▼
GET /taj-mahal.png
   │
   ▼
Server sends 6 MB image

The browser downloads the entire file.

Now imagine your image is only shown inside a small card that's 300 pixels wide.

The browser still downloads the full 4000-pixel image.

That means you're downloading way more data than you actually need.

What would be the smarter approach?

Instead of sending the same image to everyone, what if we could do this?

For phones:

300 px image

For tablets:

600 px image

For desktops:

1000 px image

Everyone sees the same picture, but only downloads the size they actually need.

That is the main idea behind image optimization.

Enter Next.js `<Image />`

Instead of writing

<img src="/taj-mahal.png" />

we write

<Image
  src="/taj-mahal.png"
  width={500}
  height={300}
/>

Looks almost the same.
But behind the scenes, something very different happens.

The first surprise

You might think the browser requests this:

GET /taj-mahal.png

It doesn't.

Instead, it requests something like this:

GET /_next/image?url=/taj-mahal.png&w=640&q=75

At first, this looked strange to me.

Why isn't it requesting the actual image?

Meet the Image Optimizer

That /_next/image URL is a special endpoint created by Next.js.

Instead of sending the original image directly, the request goes through the optimizer first.

Browser
    │
    ▼
Next.js Image Optimizer
    │
    ▼
Original Image

You can think of it as a smart middleman.

Before giving the browser the image, it asks:

What size do you need?
What quality should I use?
Which image format does your browser support?

Then it prepares the best version.

What happens when the request arrives?

Suppose the browser sends:

GET /_next/image?url=/taj-mahal.png&w=640&q=75

Next.js now knows:

Original image location
Required width (640px)
Image quality (75)

Now the real work begins.

Step 1 — Load the original image

Next.js finds the original image.

It might come from:

your public folder
an external URL
cloud storage like S3

The optimizer first loads the original image into memory.

Step 2 — Resize it

Suppose the original image is

4000 px wide

But the browser only needs

640 px

There is no reason to send all 4000 pixels.

Next.js resizes the image to the requested width.

4000 px

↓

640 px

This alone saves a lot of bandwidth.

Step 3 — Compress it

Even after resizing, the image can often be made much smaller.

If the quality is set to 75, Next.js compresses it while trying to keep it looking almost identical.

For example:

400 KB

↓

90 KB

The user usually can't notice the difference, but their internet connection definitely can.

Step 4 — Choose a better format

Modern browsers support formats like:

WebP
AVIF

These formats are usually much smaller than PNG or JPEG.

When your browser makes a request, it also sends an Accept header that tells the server which image formats it understands.

For example:

Accept: image/avif,image/webp,image/*,*/*

If the browser supports WebP or AVIF, Next.js may convert the original PNG or JPEG into one of those formats before sending it back.

Original

PNG

↓

Optimized

WebP

The picture looks almost identical but downloads much faster.

Step 5 — Cache the result

Image optimization isn't free.

Resizing and compressing images takes CPU time.

So Next.js stores the optimized version.

The first request looks like this:

Browser

↓

Next.js

↓

Resize

↓

Compress

↓

Cache

↓

Send image

The second request becomes much simpler.

Browser

↓

Next.js

↓

Cache

↓

Send image

No resizing.

No compression.

Just return the cached image.

How does the browser know which size to download?

This part surprised me the most.

Next.js doesn't generate just one image.

It generates multiple versions.

Something like:

320 px

640 px

750 px

1080 px

1920 px

It then generates an HTML srcset attribute.

Something similar to this:

<img
  src="/_next/image?url=/taj-mahal.png&w=640&q=75"
  srcset="
    /_next/image?url=/taj-mahal.png&w=320&q=75 320w,
    /_next/image?url=/taj-mahal.png&w=640&q=75 640w,
    /_next/image?url=/taj-mahal.png&w=1080&q=75 1080w
  "
  sizes="100vw"
/>

Now here's the interesting part.

Next.js doesn't decide which image gets downloaded.

The browser does.

If you're on a phone, it might download the 640px version.

If you're on a desktop with a Retina display, it might choose the 1080px version.

The browser looks at:

Viewport size
Device pixel ratio (Retina, 2x, 3x, etc.)
The sizes attribute

Then it picks the most appropriate image.

Why do we provide `width` and `height`?

One more nice feature.

When you write

<Image
  width={800}
  height={600}
/>

the browser already knows how much space the image will take.

Even before the image finishes downloading.

That means your page doesn't suddenly jump around while loading.

Without dimensions:

Header

Text

(Image loads)

Everything moves down

With dimensions:

Header

[Reserved Image Space]

Text

Everything stays stable.

This improves a Core Web Vitals metric called Cumulative Layout Shift (CLS).

Putting everything together

<Image />

      │
      ▼

Browser requests

/_next/image

      │
      ▼

Next.js loads the original image

      │
      ▼

Resize

      │
      ▼

Compress

      │
      ▼

Convert to WebP/AVIF (if supported)

      │
      ▼

Store in cache

      │
      ▼

Send optimized image to the browser

Final thoughts

Before learning this, I thought <Image /> was just another React component.

It turns out it's much more than that.

It's an image optimization pipeline built into Next.js.

Instead of sending every visitor the same large image, it creates a version that's appropriate for their device, browser, and screen size.

As developers, we only write one component.

Behind the scenes, Next.js handles resizing, compression, modern image formats, caching, and responsive images for us.

That's a lot of work hidden behind a single line of code.

If you enjoyed this article, the next logical step is understanding how srcset and sizes actually work. That's where the browser starts making intelligent decisions about which image to download, and it's one of the coolest parts of responsive images.

Stop Using react-error-boundary in Next.js? Meet next/error

Harsh Mangalam — Fri, 03 Jul 2026 06:30:57 +0000

For a long time, whenever I needed an Error Boundary in React, I reached for react-error-boundary.

It has been the go-to solution because React itself only provides the low-level Error Boundary API.

But if you're using Next.js App Router, there's now a much cleaner option.

Starting with Next.js 16, you can use the built-in next/error package.

Let's see why it matters.

The Old Way

Most React applications use react-error-boundary.

import { ErrorBoundary } from "react-error-boundary";

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div>
      <p>Something went wrong.</p>
      <button onClick={resetErrorBoundary}>
        Try Again
      </button>
    </div>
  );
}

export default function App() {
  return (
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <Dashboard />
    </ErrorBoundary>
  );
}

It works well, but it means:

Installing another dependency
Learning another API
Slightly different patterns from what Next.js already provides

If you're already using Next.js, that's no longer necessary in many cases.

Enter `next/error`

Next.js now ships with a helper called catchError.

Instead of wrapping your component with <ErrorBoundary />, you simply wrap your fallback component.

'use client';

import { catchError, type ErrorInfo } from 'next/error';

function ErrorFallback(props, { retry }: ErrorInfo) {
  return (
    <div>
      <p>Something went wrong.</p>

      <button onClick={() => retry()}>
        Try Again
      </button>
    </div>
  );
}

export default catchError(ErrorFallback);

That's it.

No extra package.

No separate Error Boundary component.

A Real Example

Here's an example with a nicer UI.

'use client';

import { AlertTriangle } from 'lucide-react';
import { catchError, type ErrorInfo } from 'next/error';
import { Button } from '@/components/ui/button';

function ErrorFallback(
  props: { title?: string; compact?: boolean },
  { retry }: ErrorInfo
) {
  if (props.compact) {
    return (
      <div className="flex flex-col items-center gap-2 px-4 py-4 text-center">
        <AlertTriangle className="text-danger h-4 w-4" />
        <p className="text-gray text-xs">
          {props.title ?? 'Something went wrong'}
        </p>

        <Button
          size="sm"
          variant="secondary"
          onClick={() => retry()}
        >
          Try again
        </Button>
      </div>
    );
  }

  return (
    <div className="flex flex-col items-center gap-3 px-5 py-10 text-center">
      <AlertTriangle className="text-danger h-6 w-6" />

      <p className="text-sm font-medium">
        {props.title ?? 'Something went wrong'}
      </p>

      <Button
        size="sm"
        variant="secondary"
        onClick={() => retry()}
      >
        Try again
      </Button>
    </div>
  );
}

export default catchError(ErrorFallback);

Notice that your fallback component receives two things:

props → Any custom props you pass.
ErrorInfo → Helpful methods like retry().

Calling retry() tells Next.js to attempt rendering the component again.

Why This Feels Better

The API is surprisingly simple.

Instead of this:

<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Dashboard />
</ErrorBoundary>

You create an error boundary by exporting:

export default catchError(ErrorFallback);

Your fallback stays focused on displaying the UI.

Next.js handles the rest.

When Should You Use It?

If you're building a Next.js App Router application and only need client-side Error Boundaries, next/error is a great default.

It gives you:

✅ No additional dependency
✅ Smaller bundle
✅ Built into Next.js
✅ Retry support out of the box
✅ API that feels consistent with the framework

Should You Remove `react-error-boundary`?

If you're starting a new Next.js project, I'd probably reach for next/error first.

If you already have react-error-boundary everywhere, there's no urgent reason to rewrite everything overnight.

But for new components, using the built-in solution keeps your dependency list a little smaller and your code a little more aligned with Next.js.

Final Thoughts

One thing I like about recent Next.js releases is that they're gradually replacing common third-party utilities with built-in APIs.

next/error is another example of that.

It's a small addition, but it removes a dependency, simplifies your code, and gives you an Error Boundary API that feels like it belongs in the framework.

If you're using the App Router, it's definitely worth trying.

Resources

Next.js catchError documentation: https://nextjs.org/docs/app/api-reference/functions/catchError
Next.js 16 release notes: https://nextjs.org/blog

TypeScript is quietly killing baseUrl (and most people haven’t noticed yet)

Harsh Mangalam — Wed, 08 Apr 2026 05:13:34 +0000

If you’re seeing this warning:

Option 'baseUrl' is deprecated and will stop functioning in TypeScript 7.0

Yeah… it’s real.

For years, we’ve been doing this 👇

{
  "extends": "@workspace/typescript-config/bun.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

But TypeScript is moving away from module resolution hacks.

💡 The shift
TypeScript no longer wants to resolve your imports.

👉 Your runtime / bundler should do that (Bun, Vite, Next, etc.)
👉 TypeScript should just type-check

✅ The simple fix
Just remove baseUrl.

{
  "extends": "@workspace/typescript-config/bun.json",
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

⚡ Why this matters

Future-proof (TS 7 won’t break you)
Cleaner separation of concerns
Matches modern tooling direction

🧩 Why Dialog Doesn’t Work When Wrapped with Tooltip in Radix / ShadCN UI (And How to Fix It)

Harsh Mangalam — Thu, 07 Aug 2025 17:37:45 +0000

When working with Radix UI (used under the hood in shadcn/ui), things are usually smooth — composable, accessible, and beautifully engineered.

But one day, I wrapped a DialogTrigger with a Tooltip and…

Nothing happened.

No errors. No warnings. Just a button that didn’t open the dialog. 🤯

Turns out, there's a common but sneaky mistake that trips up many devs — and it’s all about the order in which you nest your components.

❌ The Broken Version

This is what I initially wrote — trying to wrap my dialog trigger in a tooltip:

<Dialog open={open} onOpenChange={setOpen}>
  <DialogTrigger asChild>
    <Tooltip>
      <TooltipTrigger asChild>
        <Button size="icon" variant="outline">
          <EditIcon />
        </Button>
      </TooltipTrigger>
      <TooltipContent>Edit podcast</TooltipContent>
    </Tooltip>
  </DialogTrigger>
  <DialogContent className="max-w-4xl max-h-[80vh] overflow-y-auto">
    {/* Form goes here */}
  </DialogContent>
</Dialog>

At first glance, this looks totally fine.

But the dialog wouldn’t open when clicking the button.
The tooltip shows, but the dialog never appears.

🤔 What’s Going Wrong?
Let’s break this down.

Both DialogTrigger and TooltipTrigger from Radix use the asChild prop, which means:

They don’t render any DOM element themselves.

Instead, they pass event handlers like onClick to their child — which must be a real DOM element, like a .

In the broken example, DialogTrigger wraps Tooltip, which is not a DOM element — it's just a React component.
So the click event never reaches a usable target for Dialog.

✅ The Working Version
Here’s the corrected nesting:

<Dialog open={open} onOpenChange={setOpen}>
  <Tooltip>
    <TooltipTrigger asChild>
      <DialogTrigger asChild>
        <Button size="icon" variant="outline">
          <EditIcon />
        </Button>
      </DialogTrigger>
    </TooltipTrigger>
    <TooltipContent>Edit podcast</TooltipContent>
  </Tooltip>
  <DialogContent className="max-w-4xl max-h-[80vh] overflow-y-auto">
    {/* Form goes here */}
  </DialogContent>
</Dialog>

Why does this work?

TooltipTrigger passes props down to DialogTrigger
DialogTrigger passes props down to the final Button
The Button becomes the single, shared DOM element that receives both behaviors

🧠 Rule of Thumb

Always place the outermost wrapper (like Tooltip) outside, and the final DOM element (like Button) inside both DialogTrigger and TooltipTrigger, using asChild.

Understanding Legacy Promise Throwing Behavior in React

Harsh Mangalam — Mon, 06 Jan 2025 06:39:14 +0000

React is a powerful and versatile JavaScript library used for building user interfaces. One of its modern features, Suspense, allows components to handle asynchronous data gracefully. However, the concept of "Legacy Promise Throwing Behavior" in React often causes confusion among developers. This blog post aims to break down what this behavior entails, how it fits into React’s rendering process, and why it’s important to understand when working with concurrent features.

What Is Legacy Promise Throwing Behavior?

Legacy Promise Throwing Behavior refers to the mechanism where React components "throw" a promise during rendering. This tells React that the component is waiting for some asynchronous data to be resolved before it can be fully rendered.

When a promise is thrown, React pauses rendering of that part of the component tree and instead renders a fallback UI, if defined, using Suspense. Once the promise resolves, React re-renders the component with the resolved data.

Key Features of Legacy Promise Throwing:

Throwing Promises During Rendering: Components can indicate they’re awaiting data by throwing a promise.
Integration with Suspense: This behavior works seamlessly with Suspense to show fallback content.
Asynchronous Data Handling: It provides a declarative way to handle async data fetching within React’s rendering lifecycle.

How Does It Work?

Let’s take a step-by-step look at how this behavior functions:

Component Throws a Promise: During rendering, a component encounters a promise and throws it.
Rendering Paused: React halts rendering for that branch of the component tree.
Fallback UI: If a Suspense boundary is present, React renders the fallback UI.
Promise Resolves: Once the promise resolves, React resumes rendering and integrates the resolved data.

Example of Legacy Promise Throwing

import React, { Suspense } from 'react';

// Simulated fetch function
function fetchData() {
  return new Promise((resolve) => {
    setTimeout(() => resolve("Data loaded!"), 2000);
  });
}

// Component that throws a promise
function AsyncComponent() {
  const data = useData(); // Custom hook
  return <div>{data}</div>;
}

function useData() {
  const promise = fetchData();
  if (!promise._result) {
    throw promise;
  }
  return promise._result;
}

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <AsyncComponent />
    </Suspense>
  );
}

export default App;

Explanation:

Fetching Data: The useData hook fetches data asynchronously using the fetchData function.
Throwing a Promise: If the data is not yet available, the promise is thrown.
Suspense Fallback: The Suspense component displays "Loading..." until the promise resolves.
Resolved Data: Once the promise resolves, the AsyncComponent renders the loaded data.

Modern React and Concurrent Features

React 18 introduced concurrent rendering, which refines how promise throwing works. Key improvements include:

Time-Slicing: React’s concurrent rendering splits work into smaller chunks, keeping the UI responsive even while waiting for async data.
Controlled Suspense Boundaries: Suspense boundaries handle promise throwing more gracefully.
Improved Error Handling: Better error boundaries for components that fail to fetch data.

Best Practices

While Legacy Promise Throwing is foundational to Suspense, developers should use modern libraries and patterns for a better experience:

Use React Query or SWR

Libraries like React Query and SWR provide robust solutions for data fetching, caching, and synchronization, eliminating the need to manually throw promises.

Leverage use Hook (React 18+)

React 18 introduced the use hook (experimental) for handling promises in a cleaner, declarative way.

function AsyncComponent() {
  const data = use(fetchData());
  return <div>{data}</div>;
}

Avoid Throwing Promises Directly

Throwing promises manually can lead to unexpected issues, especially in non-concurrent environments. Instead, rely on libraries or utilities that abstract these complexities.

Wrap Suspense for Reusability

Encapsulate Suspense logic in reusable components for cleaner code:

function WithSuspense({ children }) {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      {children}
    </Suspense>
  );
}

Conclusion

Legacy Promise Throwing Behavior is a cornerstone of React’s Suspense feature, enabling seamless handling of asynchronous data during rendering. However, as React evolves, so do the tools and patterns for managing async operations. By understanding this behavior and leveraging modern practices, developers can create efficient, responsive, and maintainable applications.

Mastering Literal Types in TypeScript: true as const vs true

Harsh Mangalam — Wed, 18 Dec 2024 12:03:12 +0000

In TypeScript, there is a significant difference between the two statements:

clientLoader.hydrate = true as const;
clientLoader.hydrate = true;

FYI I have picked these example from React router v7.

Let’s break down the difference with detailed explanations and examples

clientLoader.hydrate = true as const;

The as const assertion in TypeScript is a way of telling the TypeScript compiler to treat a value as its literal type, rather than the general type.
In this case, true as const means that the type of hydrate will be the literal true and not boolean. It essentially locks the value of hydrate to true specifically.

Example:

interface ClientLoader {
  hydrate: true;  // The type of hydrate is set to the literal value `true`
}

const clientLoader: ClientLoader = {
  hydrate: true as const,
};

clientLoader.hydrate = true; // This is valid

// clientLoader.hydrate = false; // Error: Type 'false' is not assignable to type 'true'

In the above example, clientLoader.hydrate is specifically typed as true. You cannot assign any value other than true to hydrate because of the as const assertion.
This type of assignment is useful when you want to enforce immutability for certain properties.

clientLoader.hydrate = true;

Without the as const assertion, TypeScript will infer the type of hydrate as boolean. This means that hydrate can be assigned any boolean value (true or false).

Example:

interface ClientLoader {
  hydrate: boolean;  // The type of hydrate is set to `boolean`
}

const clientLoader: ClientLoader = {
  hydrate: true,
};

clientLoader.hydrate = true;  // This is valid
clientLoader.hydrate = false; // This is also valid

In this case, since hydrate is typed as boolean, you can assign true or false to it.
It provides flexibility to switch between both true and false.

Feature	`clientLoader.hydrate = true as const;`	`clientLoader.hydrate = true;`
Type of hydrate	`true` (literal type)	`boolean` (general type)
Flexibility	Can only be `true`	Can be `true` or `false`
Use Case	When you want the property to be strictly `true` and not allow changes	When the property can hold any boolean value
Type Inference	The type of `hydrate` is narrowed to `true`	The type of `hydrate` is inferred as `boolean`

Why Use as const?

Enforcing Immutability: as const locks down the value so that it can’t be changed to something else. This is particularly useful when you want to ensure that a specific value is always the same throughout the program.
Literal Types for Discriminated Unions: When working with discriminated unions, as const allows you to create specific cases based on literal types, as shown below:

type Status = 'pending' | 'completed' | 'failed';

const status: Status = 'pending'; // 'pending' is a valid value

// status = 'in-progress'; // Error: Type '"in-progress"' is not assignable to type 'Status'

// With 'as const'
const taskStatus = 'pending' as const;
// Now taskStatus is narrowed down to the literal type 'pending'

Conclusion

Use as const when you want to assign a specific literal value to a property and enforce that the value remains fixed.
Use regular assignment (true, false, etc.) when you want to allow a property to accept different boolean values or when the exact value doesn’t need to be restricted.

This makes as const a useful tool for more precise typing and enforcing stricter value constraints in your TypeScript code.

Celebrating 100th Open Source Contributions: A Journey of Growth and Collaboration.

Harsh Mangalam — Tue, 27 Aug 2024 18:25:24 +0000

I'm thrilled to announce that I've reached a personal milestone: completing my 100th open-source contribution! This journey has been nothing short of incredible, and I'm honored to have contributed to a vibrant and diverse range of projects that have not only sharpened my skills but also allowed me to give back to the community that has given me so much.

My 100th contribution was made to the modular-forms library, an open source form library with performance, type safety and bundle size in mind.

If you're passionate about building cool stuff, check out my GitHub profile: https://github.com/harshmangalam – I'm always working on new and exciting projects!

A Look Back: My Open Source Journey

Over the years, I have had the privilege of contributing to a wide variety of open-source projects, each one teaching me something new and providing me with invaluable experiences. Here are some of the projects that I've been a part of:

Expo
Expo is a framework and platform for building cross-platform mobile applications using React Native. It simplifies the development process by providing a set of tools and libraries that handle common tasks like navigation, camera access, and push notifications. Expo's managed workflow allows developers to build, test, and deploy apps with minimal configuration and hassle.

Deno
Deno is a modern runtime for JavaScript and TypeScript built on V8 and Rust. It aims to improve security, simplicity, and performance by offering built-in TypeScript support, a secure sandboxed execution environment, and a single executable with no need for a package manager. Deno emphasizes a standard library and modularity, providing an alternative to Node.js with enhanced features for contemporary development.

Fresh.js
Fresh.js is a web framework for building high-performance applications with a focus on simplicity and speed. It is built on Deno and leverages its features to offer server-side rendering (SSR) and static site generation (SSG) out of the box. Fresh.js emphasizes minimal client-side JavaScript, optimizing performance by delivering fast initial loads and efficient updates. It uses a component-based architecture, similar to other modern frameworks, to facilitate building dynamic, reactive user interfaces.

Qwik
Qwik is a modern front-end framework designed for building high-performance, instantly loading web applications. It was developed by the team at Builder.io to address the performance limitations of traditional frameworks when it comes to building complex web applications

Qwik UI
Qwik UI is a component library designed to work seamlessly with the Qwik framework. It provides a set of pre-built, reusable UI components that can be used to quickly build user interfaces while taking full advantage of Qwik's unique performance characteristics. By leveraging Qwik's principles of resumability and instant loading, Qwik UI aims to deliver highly optimized and responsive user experiences.

Solid.js
SolidJS is a declarative, efficient, and flexible JavaScript library for building user interfaces. It emphasizes fine-grained reactivity, enabling high performance by updating only the parts of the DOM that change. Unlike other frameworks, SolidJS compiles components down to optimized, low-level JavaScript code, making it exceptionally fast. It offers a syntax similar to React, making it easy for React developers to transition. SolidJS also prioritizes simplicity and predictability, allowing developers to build complex applications with a straightforward and intuitive approach.

SolidStart
SolidStart is a full-stack framework built on top of SolidJS, designed for creating highly performant web applications. It provides features like server-side rendering (SSR), routing, and data fetching, making it easier to build scalable and efficient applications. SolidStart leverages SolidJS's fine-grained reactivity to deliver fast and seamless user experiences from the server to the client.

GraphQL Yoga
GraphQL Yoga is a fully-featured GraphQL server that is simple to set up and easy to use. It provides a flexible, plug-and-play architecture that supports various frameworks and environments, including Express, Fastify, and serverless functions. GraphQL Yoga includes features like subscriptions, real-time data, and file uploads out-of-the-box. It's designed to work seamlessly with TypeScript, offering type safety and developer-friendly tools. GraphQL Yoga aims to be lightweight yet powerful, making it suitable for both small projects and large-scale applications.

Shotstack
Shotstack is a cloud-based video editing API that enables developers to programmatically create, edit, and render videos. It offers a range of features like transitions, effects, text overlays, and audio integration, making it possible to automate video production tasks. Shotstack supports a wide array of media formats and can handle both 2D and 3D rendering

Remix.run:
Remix.run is a modern web framework focused on optimizing user experience and performance by leveraging server-side rendering (SSR) and client-side navigation. It emphasizes data fetching and caching strategies that improve speed and responsiveness. Remix enables developers to build robust and scalable applications with a strong emphasis on traditional web fundamentals like progressive enhancement and full-page reloads. It integrates well with various backends and APIs, allowing for flexible and efficient data management. Remix's architecture aims to provide a seamless user experience and a streamlined development process.

Deno SaaSKit
Deno SaaSKit is a SaaS boilerplate built on Deno, designed to accelerate the development of software-as-a-service applications. It provides essential features like authentication, billing, and multi-tenancy out-of-the-box. Deno SaaSKit leverages Deno's modern runtime and TypeScript support to deliver a secure, scalable, and maintainable foundation for SaaS projects.

Revoltchat
Revoltchat is an open-source alternative to Discord, designed for creating and managing online communities and chat environments. It offers features such as text and voice channels, user roles, and real-time messaging. Revoltchat emphasizes privacy and control, allowing users to host their own servers and manage data independently. The platform is built with a focus on flexibility and customizability, catering to various community needs and preferences.

Prisma
Prisma is a modern ORM (Object-Relational Mapping) tool for Node.js and TypeScript applications that simplifies database interactions. It provides a type-safe database client and a powerful schema management tool, allowing developers to define their data models using a declarative schema language. Prisma supports various databases, including PostgreSQL, MySQL, and SQLite, and offers features like automatic migrations and query optimization. It aims to streamline database workflows, improve developer productivity, and enhance the overall developer experience.

Drizzle ORM
Drizzle ORM is a lightweight, type-safe ORM (Object-Relational Mapping) library for TypeScript and JavaScript. It focuses on simplicity and performance, providing a straightforward API for querying and managing database records. Drizzle ORM supports various databases, including PostgreSQL, MySQL, and SQLite. It emphasizes type safety and minimal configuration, making it easier for developers to work with databases while ensuring reliable and maintainable code.

Open source is more than just code. It's about community, collaboration, and continuous learning. Every contribution I've made has been an opportunity to learn from others, share my knowledge, and solve real-world problems. Open source has given me the platform to experiment, innovate, and most importantly, connect with like-minded individuals who share the same passion for technology.

Looking Forward
As I celebrate this milestone, I am more motivated than ever to continue my journey in the open-source world. There are countless more projects to explore, more challenges to tackle, and more communities to engage with. I am excited about the future and the endless possibilities that lie ahead.

To everyone who has been part of this journey—thank you! Here's to the next 100 contributions and beyond!

Thanks.

Managing Static Assets in Public Directory vs Imports

Harsh Mangalam — Fri, 19 Jul 2024 09:21:33 +0000

When building modern web applications, handling static assets such as images, fonts, and stylesheets is a crucial aspect of ensuring a smooth user experience. Developers often face the dilemma of whether to place these assets in a public directory or to import them directly into their modules with the help of bundler like vite. Each approach has its pros and cons, and the best choice often depends on the specific needs of the project. In this blog post, we will explore both methods and help you decide which strategy might be best for your application.

The Public Directory Approach

The public directory is a common place to store static assets. This directory is usually located at the root of your project and serves files directly to the client.

For example if you have created your project using vite you can see something like this

Pros:

Simplicity: Placing assets in the public directory is straightforward. You simply add your files to the public folder, and they are served from url.
Direct Access: Assets in the public directory are accessible via a URL path, making it easy to reference them in your HTML files or stylesheets.
No Build Dependency: Since these assets are not part of the build process, they don't need to be processed by your build tool (e.g., Webpack, Vite), which can reduce build times.

Cons:

Lack of Versioning: Since files in the public directory are not processed by the build tool, they lack automatic cache-busting mechanisms. This can lead to issues with outdated files being served to users.
No Module Context: Public assets are not part of the module system, so they can't be easily imported or manipulated within your JavaScript code.
Potential Security Risks: Exposing a public directory can sometimes lead to security risks if sensitive files are inadvertently included.

Example

export default function App() {
  return (
    <div>
      <a href="https://vitejs.dev" target="_blank">
        <img src={"/vite.svg"} className="logo" alt="Vite logo" />
      </a>
    </div>
  );
}

Importing Assets

Alternatively, you can import assets directly into your JavaScript or CSS modules. This method involves using a build tool like vite to bundle and process these assets.

Pros:

Versioning and Cache Busting: Build tools can automatically hash filenames, ensuring that users always get the most up-to-date version of your assets.
Module Context: Imported assets are part of the module system, allowing you to leverage tree-shaking and other optimizations.
Conditional Loading: You can conditionally load assets based on the current environment or user actions, which can improve performance.
Easier Refactoring: As your project grows, imported assets make it easier to refactor and move files around without breaking references.

Cons:

Build Complexity: Incorporating assets into the build process can add complexity and increase build times, especially for large projects.
Tooling Requirements: This approach requires a build tool like Webpack, Rollup, or Vite, which adds a layer of dependency and configuration.
Learning Curve: Developers need to understand how to configure their build tools to handle different types of assets, which can be challenging for beginners.

Example

import reactLogo from "./assets/react.svg";

export default function App() {
  return (
    <div>
      <a href="https://react.dev" target="_blank">
        <img src={reactLogo} className="logo react" alt="React logo" />
      </a>
    </div>
  );
}

Which Approach Should You Choose?

Choosing between the public directory and imports depends on your project's requirements and constraints.

Use the Public Directory if:

You need a simple and quick setup.
Your assets are relatively static and infrequently changed.
You prefer direct URL access without involving build tools.

Use Imports if:

You need better asset versioning and cache-busting.
Your project benefits from module-based asset management.
You want to leverage build-time optimizations and conditional loading.

In many cases, a hybrid approach might be the best solution. For example, you can place large, infrequently changed files in the public directory while importing smaller, more dynamic assets directly into your modules.

Optimize DX with Typesafe Environment Variables and code Autocomplete

Harsh Mangalam — Mon, 08 Jul 2024 09:10:39 +0000

Hello! In this article, we'll guide you through configuring your codebase to achieve autocomplete for environment variables and ensure that missing variables trigger build-time errors.

Typesafe environment variables offer several benefits:

Reduced Errors: They help catch missing or incorrectly typed environment variables at compile time, reducing runtime errors.
Improved Developer Experience: Autocomplete support in IDEs speeds up development by providing hints and suggestions for environment variables.
Enhanced Code Readability: TypeScript's type annotations make it clear what type each environment variable should be, improving code clarity and maintainability.
Better Documentation: Type annotations serve as documentation, making it easier for developers to understand how to use environment variables correctly in different parts of the codebase.

In environment variables, we store sensitive data that should not be exposed in the codebase, such as JWT secrets, Database URLs, Stripe API keys, and other confidential information. This practice enhances security by preventing sensitive data from being hardcoded into the source code, thereby reducing the risk of exposure in case of unauthorized access or leaks.

By default, developers do not receive autocomplete support for process.env in Node.js, Bun.env in Bun runtime, or Deno.env.get() in Deno runtime. This lack of autocomplete can lead to manual errors and inefficiencies during development. Implementing typesafe handling of environment variables ensures that developers benefit from IDE autocomplete features, improving efficiency, reducing errors, and enhancing the overall development experience. This practice also promotes code clarity and maintainability by enforcing strict typing and documentation of environment variable usage throughout the codebase.

Let's set up a new server using the Hono framework.

bun create hono@latest typesafe-env

Here I am using Bun because it doesn't require any third-party libraries to parse .env files. Bun has built-in features for parsing .env files, which makes configuration straightforward. Similarly, Deno also provides native capabilities for handling environment variables without additional dependencies.

If you are using Node.js, you will need third-party libraries like dotenv to parse .env files for environment variable configuration.

Bun can reads the following files automatically.

.env
.env.production, .env.development, .env.test (depending on value of NODE_ENV)
.env.local

Create new .env file and add all the env variables.


DATABASE_URL="postgresql://harshmangalam:123456@localahost:5432/typesafe-env?schema=default"
JWT_SECRET="itssecret!!"
PORT=4000
MAINTENANCE_MODE=false
DOMAINS=["http://localhost:3000","http://localhost:4000","https://openeventblend.com"]

Install zod

bun add zod

Zod is a TypeScript-first schema validation library that allows you to define and validate data schemas easily. It provides a way to create robust, composable, and typed schemas for your application's data, ensuring type safety and validation at runtime.

/src/config/env.ts


import * as z from "zod";

// Create zod schema for env variables
const envSchema = z.object({
  DATABASE_URL: z.string(),
  JWT_SECRET: z.string(),
  PORT: z.coerce.number().min(1000).max(65535),
  MAINTENANCE_MODE: z.coerce.boolean(),
});

export async function parseENV() {
  try {
    envSchema.parse(Bun.env);
  } catch (err) {
    console.error("Invalid Env variables Configuration::::", err);
    process.exit(1);
  }
}

declare module "bun" {
  interface Env extends z.TypeOf<typeof envSchema> {}
}

This code snippet is a TypeScript declaration that extends the Env interface within the "bun" module or namespace. Here's a breakdown of what each part means:

declare module "bun": This declares a module or namespace named "bun" in TypeScript. Modules or namespaces in TypeScript are used to organize code and encapsulate its components.
interface Env extends z.TypeOf<typeof envSchema>: Within the "bun" module, this declares an interface named Env. It extends (extends) the type derived from a Zod schema (z.TypeOf).
z.TypeOf<typeof envSchema>: This is a TypeScript type operator provided by the Zod library. It retrieves the TypeScript type that corresponds to the Zod schema envSchema. Essentially, it defines the structure and types of environment variables as validated by the Zod schema.

This declaration allows TypeScript to enforce type checking and provide IntelliSense support for environment variables accessed through bun.Env, ensuring that they adhere to the structure defined by envSchema.

src/index.ts

import { Hono } from "hono";
import { parseENV } from "./config/env";

parseENV();

const app = new Hono();

app.get("/", (c) => {
  return c.text("Hello Hono!");
});

export default {
  fetch: app.fetch,
  port: Bun.env.PORT,
};

Import parseENV into the root file, and you'll immediately benefit from autocomplete for Bun.env across all your project files.

Repo link

Implement JWT Refresh Token Authentication with Elysia JS and Prisma: A Step-by-Step Guide

Harsh Mangalam — Thu, 13 Jun 2024 16:39:03 +0000

In this comprehensive guide, we'll walk you through the process of integrating JWT refresh token authentication into your application using Elysia JS and Prisma.

Authentication vs Authorization

Authentication is the process of verifying the identity of a user or system attempting to access a resource or service.

Authorization is the process of determining what actions or resources a user is permitted to access within a system or application after they have been successfully authenticated.

JWT

JSON Web Token (JWT) authentication is a stateless, token-based authentication mechanism used to securely transmit information between parties as a JSON object

Header: Contains metadata about the token, such as the type of token (JWT) and the signing algorithm (e.g., HMAC SHA256 or RSA).
Payload: Contains the claims, which are statements about an entity (typically, the user) and additional data. Claims can be of three types: registered, public, and private.
Signature: Ensures that the token hasn't been altered. It's created by taking the encoded header, the encoded payload, a secret, the algorithm specified in the header, and signing them.

Tech Stack

Bun - Bun is a javascript runtime just like Nodejs and Deno but with better performance and developer experience.

Elysia - Elysia is a web framework built on top of Bun just like Express is a web framework built on top of Nodejs.

Prisma - Prisma is an ORM and Database Toolkit provide smoother way to connect SQL and NoSQL database. Prisma provide easy to use API to interact with db.

PostgreSQL - PostgreSQL is the World's Most Advanced Open Source Relational Database.

Typescript - A javascript with type safety features.

Setup new elysia project

Step 1
Make sure Bun is already installed in your system. You can install bun using curl

curl https://bun.sh/install | bash

Step 2
Create new elysia project using bun. elysia-prisma-jwt-auth is name of our project

bun create elysia elysia-prisma-jwt-auth

Step 3
Go to the project directory

cd elysia-prisma-jwt-auth

Step 4
Now you can open the project in vscode

code .

Step 5
Start the elysia server

bun dev

You can also follow Elsysia Quick start guide to setup project or if you want custom setup
https://elysiajs.com/quick-start.html

In the next process we will define our required routes

POST /api/auth/sign-up - Create new account
POST /api/auth/sign-in - Sign in to existing account
GET /api/auth/me - Fetch current user
POST /api/auth/logout - Logout current user
POST /api/auth/refresh - Create new pair of access & refresh token from existing refresh token

Create new file route.ts to keep all routes related code here
src/route.ts

import { Elysia } from "elysia";

export const authRoutes = new Elysia({ prefix: "/auth" })
  .post(
    "/sign-in",
    async (c) => {
      return {
        message: "Sig-in successfully",
      };
    },

  )
  .post(
    "/sign-up",
    async (c) => {
      return {
        message: "Account created successfully",
      };
    },
  )
  .post(
    "/refresh",
    async (c) => {
      return {
        message: "Access token generated successfully",
      };
    }
  )
  .post("/logout", async (c) => {
    return {
      message: "Logout successfully",
    };
  })
  .get("/me", (c) => {
    return {
      message: "Fetch current user",
    };
  });

Elysia is using method chaining to synchronize type safety for later use. Without method chaining, Elysia can't ensure your type integrity.

src/index.ts

import { Elysia } from "elysia";
import { authRoutes } from "./route";

const app = new Elysia({ prefix: "/api" }).use(authRoutes).listen(3000);

console.log(
  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
);

Now import the auth routes and pass in use() method. We have added the prefix /api so that all the routes will start with /api like sign-in will be now /api/auth/sign-in.

Setup Prisma

Step 1
Install prisma cli as dev dependencies. dev dependencies are only required in local development it does not included in production build and runtime

bun add -d prisma

Step 2
Initialize prisma project

bunx prisma init

Step 3
Add prisma schema that will map to database table. Here we are going to add User schema to store user information.

enum UserRole {
  User
  Admin
}

model User {
  id           String    @id @default(uuid())
  name         String    @db.VarChar(60)
  email        String    @unique
  password     String
  location     Json?
  isAdult      Boolean   @default(false)
  isOnline     Boolean?  @default(false)
  role         UserRole? @default(User)
  refreshToken String?
  createdAt    DateTime  @default(now())
  updatedAt    DateTime  @updatedAt
}

createdAt field will be added when new user will be added. updatedAt field will be initially same as createdAt but will change once you will be update any field of this table. For id here we are using uuid this will generate unique id as a string.

We have also created an enum for user role their value can be User or Admin and will help to implement Authorization and role based authentication.

Step 4
Update .env file created by prisma init command and add DATABASE_URL value. We are using PostgrSQL hence the URI will be in the form of postgresql://username:password@host:port/db?schema=public

DATABASE_URL="postgresql://harshmangalam:123456@localhost:5432/meetup?schema=public"

You can omit ?schema=public by default in postgres it is public schema.

Step 5
Sync up the prisma schema with the postgresql database

bunx prisma db push

This command should not be used in production in production always run migration command instead of push command.

For better developer expericence you can put this command in package.json scripts

"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "bun run --watch src/index.ts",
    "prisma:push": "bunx prisma db push"
  },

So that later you can use this short command instead of long prisma command.

bun prisma:push

Step 6
Install @prisma/client to make interaction with prisma server. usually this step is not required because during Step 5 its automatically get installed

bun i @prisma/client

Step 7
generate prisma schema types for autocomplete. This step is also not required usually because during Step 5 it automatically get generated and added types to node_modules

Step 8
Create new instance of prisma client so that we can reuse that instance to make interact with db.

lib/prisma.ts

import { PrismaClient } from "@prisma/client";
export const prisma = new PrismaClient();

Now our db setup is completed and ready to use the prisma instance in our route handlers.

Implement Sign-up

src/route.ts

import { loginBodySchema, signupBodySchema } from "./schema";
import { prisma } from "./lib/prisma";
import { reverseGeocodingAPI } from "./lib/geoapify";
import { jwt } from "@elysiajs/jwt";
import {
  ACCESS_TOKEN_EXP,
  JWT_NAME,
  REFRESH_TOKEN_EXP,
} from "./config/constant";
import { getExpTimestamp } from "./lib/util";

.post(
    "/sign-up",
    async ({ body }) => {
      // hash password
      const password = await Bun.password.hash(body.password, {
        algorithm: "bcrypt",
        cost: 10,
      });

      // fetch user location from lat & lon
      let location: any;
      if (body.location) {
        const [lat, lon] = body.location;
        location = await reverseGeocodingAPI(lat, lon);
      }
      const user = await prisma.user.create({
        data: {
          ...body,

          password,
          location,
        },
      });
      return {
        message: "Account created successfully",
        data: {
          user,
        },
      };
    },
    {
      body: signupBodySchema,
      error({ code, set, body }) {
        // handle duplicate email error throw by prisma
        // P2002 duplicate field erro code
        if ((code as unknown) === "P2002") {
          set.status = "Conflict";
          return {
            name: "Error",
            message: `The email address provided ${body.email} already exists`,
          };
        }
      },
    }
  )

Client will make an api call to /api/auth/sign-up with the json body

{
    "name":"Harsh Mangalam",
    "email":"harshdev8218@gmail.com",
    "password":"12345678",
    "isAdult":true,
    "location":[25.5940947,85.1375645] // [lat,lon]
}

Bun has built in methods to hash passowrd you do not need to install any third party libs like bcryptjs or argon.
You can read more about this here Hash a password with Bun

I have create a function reverseGeocodingAPI() that will accept lat and lon to return the location from geoapify services.

We can configure geoapify using following steps:-

Step 1
Collect API key from https://www.geoapify.com/

Step 2
Create a new file lib/geoapify.ts that will handle making api call to geoapify service and collect location response from there

async function reverseGeocodingAPI(lat: number, lon: number) {
  const resp = await fetch(
    `https://api.geoapify.com/v1/geocode/reverse?lat=${lat}&lon=${lon}&apiKey=${Bun.env.GEOAPIFY_API_KEY}`
  );
  const jsonResp = await resp.json();
  const data = jsonResp?.features[0]?.properties;
  return data;
}

export { reverseGeocodingAPI };

Again we do not need to install any third party libs for making api request like node-fetch, axios etc... because Bun support web standared and fetch is generally available to make api request built into the platform.

Next we will create schema for the body by default elysia use Typebox to provide type safety of request params, body, etc...

src/schema.ts

import { t } from "elysia";

const signupBodySchema = t.Object({
  name: t.String({ maxLength: 60, minLength: 1 }),
  email: t.String({ format: "email" }),
  password: t.String({ minLength: 8 }),
  location: t.Optional(t.Tuple([t.Number(), t.Number()])),
  isAdult: t.Boolean(),
});

export { signupBodySchema };

Also we are handling errors for duplicate email because prisma throw error for duplicate fields with code P2002 in that case we can return Conflict status code with 409.

Implement Log-in

src/route.ts

.post(
    "/sign-in",
    async ({ body, jwt, cookie: { accessToken, refreshToken }, set }) => {
      // match user email
      const user = await prisma.user.findUnique({
        where: { email: body.email },
        select: {
          id: true,
          email: true,
          password: true,
        },
      });

      if (!user) {
        set.status = "Bad Request";
        throw new Error(
          "The email address or password you entered is incorrect"
        );
      }

      // match password
      const matchPassword = await Bun.password.verify(
        body.password,
        user.password,
        "bcrypt"
      );
      if (!matchPassword) {
        set.status = "Bad Request";
        throw new Error(
          "The email address or password you entered is incorrect"
        );
      }

      // create access token
      const accessJWTToken = await jwt.sign({
        sub: user.id,
        exp: getExpTimestamp(ACCESS_TOKEN_EXP),
      });
      accessToken.set({
        value: accessJWTToken,
        httpOnly: true,
        maxAge: ACCESS_TOKEN_EXP,
        path: "/",
      });

      // create refresh token
      const refreshJWTToken = await jwt.sign({
        sub: user.id,
        exp: getExpTimestamp(REFRESH_TOKEN_EXP),
      });
      refreshToken.set({
        value: refreshJWTToken,
        httpOnly: true,
        maxAge: REFRESH_TOKEN_EXP,
        path: "/",
      });

      // set user profile as online
      const updatedUser = await prisma.user.update({
        where: {
          id: user.id,
        },
        data: {
          isOnline: true,
          refreshToken: refreshJWTToken,
        },
      });

      return {
        message: "Sig-in successfully",
        data: {
          user: updatedUser,
          accessToekn: accessJWTToken,
          refreshToken: refreshJWTToken,
        },
      };
    },
    {
      body: loginBodySchema,
    }
  )

Client will make an api call to /api/auth/log-in and will send json body

{
    "email":"user5@gmail.com",
    "password":"12345678"
}

We will verify the email and password from db. Next we will generate two tokens one for Access token and another for Refresh token.
We will send both tokens in response cookies so that the further api call to protected route will have those tokens and will store refresh token in db for further use to generate access token.

Again we do not need to add any third party libs for cookies handling Elysia provides all methods to handle cookies.

We will need to add jwt plugin to handle jwt token generation and verification

bun add @elysiajs/jwt

You can read more about jwt plugins here https://elysiajs.com/plugins/jwt.html

Here also we have added login body schema we can add those schema in src/schema.ts file

...

const loginBodySchema = t.Object({
  email: t.String({ format: "email" }),
  password: t.String({ minLength: 8 }),
});

export { loginBodySchema, signupBodySchema };

Next we will create new auth plugin that will take care of velidate and verify jwt token when any request will received.

API Request ------->  Auth Plugin --------> API Handler

src/plugin.ts

import jwt from "@elysiajs/jwt";
import Elysia from "elysia";
import { JWT_NAME } from "./config/constant";
import { prisma } from "./lib/prisma";
import { User } from "@prisma/client";

const authPlugin = (app: Elysia) =>
  app
    .use(
      jwt({
        name: JWT_NAME,
        secret: Bun.env.JWT_SECRET!,
      })
    )
    .derive(async ({ jwt, cookie: { accessToken }, set }) => {
      if (!accessToken.value) {
        // handle error for access token is not available
        set.status = "Unauthorized";
        throw new Error("Access token is missing");
      }
      const jwtPayload = await jwt.verify(accessToken.value);
      if (!jwtPayload) {
        // handle error for access token is tempted or incorrect
        set.status = "Forbidden";
        throw new Error("Access token is invalid");
      }

      const userId = jwtPayload.sub;
      const user = await prisma.user.findUnique({
        where: {
          id: userId,
        },
      });

      if (!user) {
        // handle error for user not found from the provided access token
        set.status = "Forbidden";
        throw new Error("Access token is invalid");
      }

      return {
        user,
      };
    });

export { authPlugin };

Here we have utilized the jwt plugin to verify jwt token received from request cookies. During login we have added userId in jwt sub and here we have just got the userId and fetch user info from db and added to derive so that available in next request handler.

Here we have raised two error status code

401 Unauthorized that can be raise in case of access token is not available
403 Forbidden in case of access token is incorrect.

Lets utilize auth plugin in our protected route like /api/auth/logout/ and /api/auth/me.

Create new route to fetch current user
/src/route.ts

import { authPlugin } from "./plugin";

.use(authPlugin)
  .get("/me", ({ user }) => {
    return {
      message: "Fetch current user",
      data: {
        user,
      },
    };
  })

We are receiving user in context that are added from derive in auth plugin.

Lets add new route to logout user

/src/route.ts

  .use(authPlugin)
  .post("/logout", async ({ cookie: { accessToken, refreshToken }, user }) => {
    // remove refresh token and access token from cookies
    accessToken.remove();
    refreshToken.remove();

    // remove refresh token from db & set user online status to offline
    await prisma.user.update({
      where: {
        id: user.id,
      },
      data: {
        isOnline: false,
        refreshToken: null,
      },
    });
    return {
      message: "Logout successfully",
    };
  })

After logout we are just removing all the cookies and setting user status to offline.

Create access token from refresh token

/src/route.ts

  .post(
    "/refresh",
    async ({ cookie: { accessToken, refreshToken }, jwt, set }) => {
      if (!refreshToken.value) {
        // handle error for refresh token is not available
        set.status = "Unauthorized";
        throw new Error("Refresh token is missing");
      }
      // get refresh token from cookie
      const jwtPayload = await jwt.verify(refreshToken.value);
      if (!jwtPayload) {
        // handle error for refresh token is tempted or incorrect
        set.status = "Forbidden";
        throw new Error("Refresh token is invalid");
      }

      // get user from refresh token
      const userId = jwtPayload.sub;

      // verify user exists or not
      const user = await prisma.user.findUnique({
        where: {
          id: userId,
        },
      });

      if (!user) {
        // handle error for user not found from the provided refresh token
        set.status = "Forbidden";
        throw new Error("Refresh token is invalid");
      }
      // create new access token
      const accessJWTToken = await jwt.sign({
        sub: user.id,
        exp: getExpTimestamp(ACCESS_TOKEN_EXP),
      });
      accessToken.set({
        value: accessJWTToken,
        httpOnly: true,
        maxAge: ACCESS_TOKEN_EXP,
        path: "/",
      });

      // create new refresh token
      const refreshJWTToken = await jwt.sign({
        sub: user.id,
        exp: getExpTimestamp(REFRESH_TOKEN_EXP),
      });
      refreshToken.set({
        value: refreshJWTToken,
        httpOnly: true,
        maxAge: REFRESH_TOKEN_EXP,
        path: "/",
      });

      // set refresh token in db
      await prisma.user.update({
        where: {
          id: user.id,
        },
        data: {
          refreshToken: refreshJWTToken,
        },
      });

      return {
        message: "Access token generated successfully",
        data: {
          accessToken: accessJWTToken,
          refreshToken: refreshJWTToken,
        },
      };
    }
  )

Here we are re creating the access token and refresh token from existing refresh token and setting in cookies also we are updating available refresh token in db.

I have added all constants in src/config/constant.ts

const ACCESS_TOKEN_EXP = 5 * 60; // 5 minutes
const REFRESH_TOKEN_EXP = 7 * 86400; // 7 days
const JWT_NAME = "jwt";
export { ACCESS_TOKEN_EXP, REFRESH_TOKEN_EXP, JWT_NAME };

I have created one utility function related to date that will return timestamps from seconds.

src/lib/util.ts

function getExpTimestamp(seconds: number) {
  const currentTimeMillis = Date.now();
  const secondsIntoMillis = seconds * 1000;
  const expirationTimeMillis = currentTimeMillis + secondsIntoMillis;

  return Math.floor(expirationTimeMillis / 1000);
}

export { getExpTimestamp };

All the codebase is open source you can access and contribute to repo
https://github.com/harshmangalam/elysia-prisma-jwt-auth

DEV Community: Harsh Mangalam

Your Go API Is Running—But Is It Healthy?

What is a health endpoint?

Decide what the response should look like

Give every dependency the same shape

Run the checks safely

Why run checks concurrently?

Turn the result into HTTP

A few practical rules

What I learned

From http.ServeMux to Dependency Injection in Go: A Beginner-Friendly Guide

The big idea

Step 1: The smallest useful mux and handler

Step 2: Give the handler function a name

Step 3: Introduce a service

Step 4: Let a handler struct remember the service

Step 5: Understand the http.Handler interface

HandleFunc versus Handle

Applying this to a real health-check package

Wiring the complete application

Follow one request from beginning to end

Why keep the service and handler separate?

Common beginner misunderstandings

“Does the mux execute the handler during startup?”

“Why do we not call ServeHTTP?”

“Is NewHandler special Go syntax?”

“Does the mux know about the service?”

“Why use a pointer such as *Handler?”

Final mental model

How Next.js Image Optimization Works Under the Hood

The problem with a normal <img>

What would be the smarter approach?

Enter Next.js <Image />

The first surprise

Meet the Image Optimizer

What happens when the request arrives?

Step 1 — Load the original image

Step 2 — Resize it

Step 3 — Compress it

Step 4 — Choose a better format

Step 5 — Cache the result

How does the browser know which size to download?

Why do we provide width and height?

Putting everything together

Final thoughts

Stop Using react-error-boundary in Next.js? Meet next/error

The Old Way

Enter next/error

A Real Example

Why This Feels Better

When Should You Use It?

Should You Remove react-error-boundary?

Final Thoughts

Resources

TypeScript is quietly killing baseUrl (and most people haven’t noticed yet)

🧩 Why Dialog Doesn’t Work When Wrapped with Tooltip in Radix / ShadCN UI (And How to Fix It)

❌ The Broken Version

Understanding Legacy Promise Throwing Behavior in React

What Is Legacy Promise Throwing Behavior?

Key Features of Legacy Promise Throwing:

How Does It Work?

Example of Legacy Promise Throwing

Modern React and Concurrent Features

Best Practices

Use React Query or SWR

Leverage use Hook (React 18+)

Avoid Throwing Promises Directly

Wrap Suspense for Reusability

Conclusion

Mastering Literal Types in TypeScript: true as const vs true

Let’s break down the difference with detailed explanations and examples

Why Use as const?

Conclusion

Celebrating 100th Open Source Contributions: A Journey of Growth and Collaboration.

A Look Back: My Open Source Journey

Managing Static Assets in Public Directory vs Imports

The Public Directory Approach

Importing Assets

Which Approach Should You Choose?

Optimize DX with Typesafe Environment Variables and code Autocomplete

Step 5: Understand the `http.Handler` interface

`HandleFunc` versus `Handle`

“Why do we not call `ServeHTTP`?”

“Is `NewHandler` special Go syntax?”

“Why use a pointer such as `*Handler`?”

The problem with a normal `<img>`

Enter Next.js `<Image />`

Why do we provide `width` and `height`?

Enter `next/error`

Should You Remove `react-error-boundary`?