DEV Community: Saiful Islam

useSearchNavigate: Type-Safe URL State Without the Drift

Saiful Islam — Wed, 28 Oct 2026 12:10:59 +0000

A small hook over TanStack Router's navigate that keeps tabs, dialogs, and pages in the URL with types intact, and why the write lands after the commit instead of during render.

The Problem

You are building a company page with three tabs and a button that opens a "New purchase" dialog. The page works on the first click.

import { useState } from "react";

function CompanyPage() {
  const [tab, setTab] = useState<"details" | "purchase" | "payment">("details");
  const [dialogOpen, setDialogOpen] = useState(false);

  return (
    <section>
      <button onClick={() => setTab("purchase")}>Purchases</button>
      {tab === "purchase" && (
        <button onClick={() => setDialogOpen(true)}>Add new</button>
      )}
      {dialogOpen && <div role="dialog">New purchase</div>}
    </section>
  );
}

Then the user refreshes the page. The tab is back on "details" and the dialog is closed. The same happens when they copy the link and send it to a colleague, or press the browser back button after switching tabs.

The first fix most people try is to seed useState from the URL:

const search = useSearch({ from: "/companies/$companyId" });
const [tab, setTab] = useState(search.tab); // frozen at mount

This survives a refresh, but it breaks on back and forward. The URL changes, search.tab changes, and tab keeps the value it had on mount. Now the URL and the screen disagree.

The second fix is to write the query string by hand with window.history.pushState. The URL now updates, but the router does not know about the change, so nothing re-renders from the new value. Reading the value back gives you a raw string that you have to trust, so "2" and 2 look the same to your code until something breaks.

The third fix is to use <Link search={{ tab: "purchase" }}> everywhere. This is closer, but the object you pass replaces the whole search object. Switching to the payments tab drops page and q from the URL, so the user loses their place every time they change tabs.

The tension: the component needs the value to be the source of truth for what it renders, and the URL needs to be the source of truth for what survives a reload, and no single naive tool gives you both without a copy that can drift.

The resolution is to declare the search schema on the route, read it with a typed hook, and write it through one setter:

const search = Route.useSearch();
const setSearch = useSearchNavigate(Route.fullPath);

<button onClick={() => setSearch({ tab: "purchase" })}>Purchases</button>;

The rest of this tutorial shows how the pieces fit.

The Mental Model

Think of the URL as a shared clipboard passed between two desk clerks. The clipboard holds the current form for the page. The first clerk, validateSearch, checks every entry on the clipboard when it arrives and fills in blanks with defaults. The second clerk, useSearchNavigate, is the only person allowed to write a new entry, and does it by handing the clipboard back to the router.

Identity: the clipboard belongs to one route. useSearchNavigate binds to that route's path once, so every write goes to the same clipboard.
Update timing: a write does not change state directly. It asks the router for a new clipboard. The new entry is checked and the page re-renders only after the router accepts it.
Read timing: components read the checked entry through useSearch. A read always returns the validated, typed value, never the raw string from the address bar.

Two consequences follow from this:

You never keep a second copy of a search value in useState. If you need it, read it from the clipboard.
Writes are navigations, so they are history entries by default. Treat each write as a page change, not a state tweak.

The clipboard is the state, and the clerks only ever touch it through the front desk.

How to Use It

Setup

Swap @/ for whatever path alias your project uses. The hook imports the route types generated by TanStack Router, so run the router generator (the Vite plugin or the TanStack Router CLI) at least once.

src/
├── hooks/
│   └── use-search-navigate.ts
└── routes/
    ├── companies/
    │   └── $companyId.tsx
    └── routeTree.gen.ts   (generated by TanStack Router)

The hook, in full:

import { useCallback } from "react";

import { useNavigate } from "@tanstack/react-router";

import type { FileRoutesByFullPath, FileRouteTypes } from "@/routeTree.gen";

/** All full route paths from the generated route tree (API routes excluded). */
export type RoutePath = Exclude<FileRouteTypes["fullPaths"], `/api/${string}`>;

/** Fully-resolved search schema (own + parent routes) for a given route path */
export type SearchOf<TPath extends RoutePath> =
  FileRoutesByFullPath[TPath]["types"]["fullSearchSchema"];

/**
 * Either a partial object (merged into the current search params)
 * or an updater function receiving the previous search params.
 */
export type SearchUpdate<TPath extends RoutePath> =
  Partial<SearchOf<TPath>> | ((prev: SearchOf<TPath>) => SearchOf<TPath>);

type SearchNavigateOptions = {
  /** Replace the current history entry instead of pushing a new one */
  replace?: boolean;
  /** Reset scroll position after navigating */
  resetScroll?: boolean;
  /** Hash to set on the URL */
  hash?: string;
};

/** null | undefined | '' | NaN */
function isEmptyValue(value: unknown): boolean {
  return (
    value === null ||
    value === undefined ||
    value === "" ||
    (typeof value === "number" && Number.isNaN(value))
  );
}

/**
 * Type-safe helper to navigate by changing only the search params of a route.
 * Keys whose value is null, undefined, '' or NaN are removed from the URL.
 */
export function useSearchNavigate<const TPath extends RoutePath>(path: TPath) {
  const navigate = useNavigate({ from: path });

  return useCallback(
    (update: SearchUpdate<TPath>, options: SearchNavigateOptions = {}) => {
      const searchValue = (prev: SearchOf<TPath>) => {
        const next =
          typeof update === "function"
            ? update(prev)
            : (Object.assign({}, prev, update) as SearchOf<TPath>);

        return Object.fromEntries(
          Object.entries(next as Record<string, unknown>).filter(
            ([, value]) => !isEmptyValue(value)
          )
        );
      };

      void (navigate as (opts: unknown) => Promise<void>)({
        to: ".",
        search: searchValue,
        ...options,
      });
    },
    [navigate]
  );
}

The route declares its search schema with validateSearch, then reads and writes it. The file, in full:

import { createFileRoute, useSearch } from "@tanstack/react-router";
import { z } from "zod";

import { useSearchNavigate } from "@/hooks/use-search-navigate";

const tabs = ["details", "purchase", "payment"] as const;

const searchSchema = z.object({
  tab: z.enum(tabs).catch("details"),
  page: z.number().int().min(1).catch(1),
  q: z.string().catch(""),
  createDialog: z.boolean().catch(false),
});

export const Route = createFileRoute("/companies/$companyId")({
  validateSearch: searchSchema,
  component: CompanyPage,
});

function CompanyPage() {
  const search = Route.useSearch();
  const setSearch = useSearchNavigate(Route.fullPath);

  return (
    <section>
      <nav>
        {tabs.map((tab) => (
          <button
            key={tab}
            aria-pressed={search.tab === tab}
            onClick={() => setSearch({ tab, page: 1 })}
          >
            {tab}
          </button>
        ))}
      </nav>
      {search.tab === "purchase" && <PurchasesPanel />}
    </section>
  );
}

function PurchasesPanel() {
  const search = useSearch({ from: "/companies/$companyId" });
  const setSearch = useSearchNavigate("/companies/$companyId");

  const handleOpenDialog = (value: boolean) => {
    setSearch((prev) => ({ ...prev, createDialog: value }));
  };

  return (
    <section>
      <button onClick={() => handleOpenDialog(true)}>Add new</button>
      {search.createDialog && (
        <div role="dialog">
          <p>New purchase</p>
          <button onClick={() => handleOpenDialog(false)}>Close</button>
        </div>
      )}
    </section>
  );
}

Why .catch() and not .default()? .default(x) only fills a missing key. A malformed value such as ?page=abc still fails validation and throws. .catch(x) fills both cases, so a hand-edited or stale link falls back to a safe value instead of breaking the page. Use .default() only when you want bad input to surface as an error.

The import line for the hook is import { useSearchNavigate } from "@/hooks/use-search-navigate";. Your route file must live where TanStack Router expects it, and the string passed to createFileRoute must match its full path.

Pattern 1: Read the value in any child

A component under the route reads typed values without props.

import { useSearch } from "@tanstack/react-router";

function TabHeading() {
  const { tab, page } = useSearch({ from: "/companies/$companyId" });

  return (
    <h2>
      {tab} (page {page})
    </h2>
  );
}

The payoff: tab is a union of three strings and page is a number. Your editor and the compiler both know it.

Pattern 2: Paginate with an updater

Use the function form when the next value depends on the previous one.

import { useSearch } from "@tanstack/react-router";

import { useSearchNavigate } from "@/hooks/use-search-navigate";

function Pager() {
  const { page } = useSearch({ from: "/companies/$companyId" });
  const setSearch = useSearchNavigate("/companies/$companyId");

  return (
    <div>
      <button
        disabled={page <= 1}
        onClick={() =>
          setSearch((prev) => ({ ...prev, page: prev.page - 1 }))
        }
      >
        Previous
      </button>
      <span>Page {page}</span>
      <button
        onClick={() =>
          setSearch((prev) => ({ ...prev, page: prev.page + 1 }))
        }
      >
        Next
      </button>
    </div>
  );
}

The payoff: prev is the validated search, so prev.page + 1 is a number. Refreshing keeps the page, and the back button walks through pages.

Pattern 3: Reset paging and skip history

When a change invalidates the current page, write both keys in one call. Use replace when the user is only adjusting the view and back should not step through it.

import { useSearchNavigate } from "@/hooks/use-search-navigate";

type Tab = "details" | "purchase" | "payment";

function TabSwitcher() {
  const setSearch = useSearchNavigate("/companies/$companyId");

  const switchTab = (tab: Tab) => {
    setSearch({ tab, page: 1 }, { replace: true });
  };

  return (
    <div>
      <button onClick={() => switchTab("details")}>Details</button>
      <button onClick={() => switchTab("payment")}>Payments</button>
    </div>
  );
}

The payoff: switching tabs always starts at page 1, and the history stack does not fill with one entry per click.

Pattern 4: Clearing a value removes it from the URL

Empty values are dropped from the address bar. The read side then falls back to the schema default.

import { useSearch } from "@tanstack/react-router";

import { useSearchNavigate } from "@/hooks/use-search-navigate";

function SearchBox() {
  const { q } = useSearch({ from: "/companies/$companyId" });
  const setSearch = useSearchNavigate("/companies/$companyId");

  return (
    <div>
      <input
        defaultValue={q}
        onBlur={(event) => setSearch({ q: event.target.value, page: 1 })}
      />
      <button onClick={() => setSearch({ q: "" })}>Clear</button>
    </div>
  );
}

The payoff: after "Clear", the URL has no q key and q reads as "" again. The URL stays short, and the schema stays the single definition of the default.

Anti-pattern

❌ Copying a search value into state. The copy freezes at mount, and the back button changes the URL but not the tab.

const search = useSearch({ from: "/companies/$companyId" });
const [tab, setTab] = useState(search.tab); // ❌ never updates from the URL

Read search.tab directly every render, and write through setSearch.

When to Use It

Reach for URL search state only when all three are true:

Someone should be able to bookmark, share, or refresh into this exact view.
The value can be expressed as a small serializable value such as a string, number, boolean, or short array.
You set it from event handlers or effects, never from render.

Do not reach for it for these situations:

Situation	Better tool
Text being typed into a form before save	`react-hook-form` or local `useState`
Open or closed state for a tooltip	Local `useState` in the component
Server lists and details	TanStack Query, keyed by the search values you read
User theme or language preference	Cookie, `localStorage`, or a context provider
Large nested objects or whole records	Store an ID in the URL and load the record
Tokens, secrets, or personal data	Never in the URL. Use a session cookie or server state.

The smell test: if a copied link to the page would be wrong without this state, the state belongs in search params. If the link would be noise, keep it in useState.

How It Works Under the Hood

The setter identity is stable. useNavigate({ from: path }) runs once per render, and useCallback(..., [navigate]) returns the same function while navigate stays the same. You can put the setter in an effect's dependency list without causing a loop.
Writes land after the commit, not during render. The setter calls navigate, which asks the router for a new location. The router matches the route, runs validateSearch on the new URL, and then re-renders subscribed components. Calling setSearch during render would start a navigation on every render, so keep it in handlers and effects.
The updater receives the validated value. prev is the output of validateSearch, not the raw query string. The merge Object.assign({}, prev, update) is shallow, so nested objects in the search schema are replaced, not merged.
Empty values are removed, and defaults fill them back. isEmptyValue drops null, undefined, "", and NaN before the URL is written. Booleans are not in that list, so createDialog=false stays in the URL. If page has a default of 1, then setSearch({ page: undefined }) removes the key and reading returns 1. One consequence: an effect that calls setSearch on mount with an unchanged value still creates a navigation, so compare against the current value first.
Every write costs an allocation and a history entry. Each call creates a copy of the search object, builds entries with Object.fromEntries, and pushes a history entry unless you pass replace: true. Use replace for high-frequency updates. The void in front of navigate discards the returned promise, so a rejected navigation becomes an unhandled rejection in the console.

Timeline for one click on "Payments" in the tab navigation, starting from ?tab=details:

Phase	`search.tab` the component sees	URL
Before click	`details`	`?tab=details`
Click handler calls `setSearch`	`details`	unchanged
Router runs `validateSearch` on the new location	`payment` is a candidate only	`?tab=payment`
Commit: subscribed components re-render	`payment`	`?tab=payment`
A concurrent render that React abandons	`details` (the committed value)	not visible

The abandoned render has no side effect, because the setter never runs during render. It only ever sees the committed value.

Server rendering. validateSearch runs on the server when the initial URL is matched, and the same schema runs again in the browser. As long as the schema is deterministic, the server HTML and the client's first render agree. Setters do not run during server rendering, because event handlers and effects do not run there.

Comparison with built-in options. TanStack Router's <Link search={(prev) => ({ ...prev, tab: "payment" })}> covers the same ground for links. It is the right choice when the control is a link. The hook is for imperative updates from handlers and effects, and it adds the empty-value cleanup and a fixed route path. It does not replace Link, and it does not remove the need for a route-level schema.

Conclusion

Search params trade a little ceremony for state that a refresh, a shared link, and the back button all respect. The core tradeoff is that the URL becomes a second store, so you pay for validation once in the schema and keep every write on one typed path.

Declare the state in validateSearch, and read it with useSearch or Route.useSearch().
Write through one setter, with the updater form when the next value depends on the previous one.
Never copy a search value into useState, because the copy will drift from the URL.

Put state in the URL when someone else should be able to land on the same view. When the boring answer is a local useState that nobody will ever share, use that and move on.

useDebouncedCallback: Debounce Without the Stale Closure

Saiful Islam — Mon, 26 Oct 2026 17:52:28 +0000

A small hook that stops a delayed callback from firing with yesterday's state — and keeps the timer's identity stable even when the callback changes on every render.

The Problem

Here is a search box that looks right at a glance. Every keystroke updates the input and schedules a request. The previous timer is cleared, so only the last keystroke should fetch.

function SearchBox() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState<string[]>([]);

  const scheduleSearch = useMemo(() => {
    let timer = 0;
    return () => {
      window.clearTimeout(timer);
      timer = window.setTimeout(() => {
        fetch(`/api/search?q=${query}`)
          .then((response) => response.json())
          .then(setResults);
      }, 300);
    };
  }, []);

  return (
    <input
      onChange={(event) => {
        setQuery(event.target.value);
        scheduleSearch();
      }}
    />
  );
}

The input is live. The data is frozen.

The URL is built from query captured when the memoized function was created. That was the first render, where query was "". Type react, wait 300 ms, and you get the results for an empty search. The component has a stale closure, and the empty dependency array is the cause.

The first fix is to add query to the dependency array:

// before
}, []);
// after
}, [query]);

Now every keystroke creates a new scheduler. The old timer is not cleared by the new one, because the timer variable lives inside the old closure. A fast typist gets one pending timer per keystroke, each with its own query. If scheduleSearch is passed to a child or used in an effect, the identity churn also causes re-subscriptions and defeats memoization.

The second fix is to keep the scheduler in a ref and read the latest query from another ref:

const queryRef = useRef(query);
queryRef.current = query;

const scheduleSearch = useCallback(() => {
  window.setTimeout(() => {
    void fetch(`/api/search?q=${queryRef.current}`);
  }, 300);
}, []);

This works in a simple app, but writing a ref during render is not render-pure. React can start a render, let a higher-priority update interrupt it, and throw the first render away. The ref now holds a value from a render that never committed. In concurrent React, that is a correctness bug, not a style nit.

The third fix is to put the callback in useCallback and accept the changing identity:

const scheduleSearch = useCallback(() => {
  const id = window.setTimeout(() => {
    void fetch(`/api/search?q=${query}`);
  }, 300);
  return () => window.clearTimeout(id);
}, [query]);

The timer is fresh, but the function is new on every keystroke. If an effect depends on it, the effect tears down and re-registers each time. If it is a prop to a memoized child, the child re-renders anyway. The debounce survives; the stable identity you needed does not.

You need one function to do two jobs: keep a stable identity for the timer and every effect that depends on it, yet read the newest state when the timer finally fires.

The hook below splits those jobs. The scheduler is stable. The callback is read through a ref at fire time.

const handleCallback = useCallbackRef(callback);
const debounceTimerRef = useRef(0);

useEffect(() => () => window.clearTimeout(debounceTimerRef.current), []);

const setValue = useCallback(
  (...args: Parameters<T>) => {
    window.clearTimeout(debounceTimerRef.current);
    debounceTimerRef.current = window.setTimeout(
      () => handleCallback(...args),
      delay
    );
  },
  [handleCallback, delay]
);

return setValue;

The Mental Model

Think of a mailbox with a fixed address and a replaceable letter.

The mailbox is the function you get back. Its address never changes, so the timer, effects, and children always know where to send work. The letter inside is the callback. After every committed render, a new letter replaces the old one. When the timer finally rings, the carrier opens the box and reads whatever letter is there.

Identity: the returned scheduler is the mailbox. It closes over a stable ref object, not over the callback value, so its identity survives callback changes.
Update timing: the letter is replaced in a passive effect after commit. A render that never commits never becomes the letter.
Read timing: the wrapper reads callbackRef.current when the timer fires, not when the timer is scheduled. That is the difference between fresh and stale.

Two consequences follow. An inline callback no longer resets the timer, because the scheduler's identity does not change. And a pending timer can call the newest callback with arguments from the call that scheduled it, so pass the exact value you want if that distinction matters.

The mailbox never moves; only the letter inside changes.

How to Use It

The hook has one helper. Put both files next to each other.

src/
└── hooks/
    ├── use-callback-ref.ts
    └── use-debounced-callback.ts

src/hooks/use-callback-ref.ts:

import { useEffect, useMemo, useRef } from "react";

function useCallbackRef<T extends (...args: never[]) => unknown>(
  callback: T | undefined
): T {
  const callbackRef = useRef(callback);

  useEffect(() => {
    callbackRef.current = callback;
  });

  return useMemo(() => ((...args) => callbackRef.current?.(...args)) as T, []);
}

export { useCallbackRef };

src/hooks/use-debounced-callback.ts:

import { useCallback, useEffect, useRef } from "react";

import { useCallbackRef } from "@/hooks/use-callback-ref";

export function useDebouncedCallback<T extends (...args: never[]) => unknown>(
  callback: T,
  delay: number
) {
  const handleCallback = useCallbackRef(callback);
  const debounceTimerRef = useRef(0);

  useEffect(() => () => window.clearTimeout(debounceTimerRef.current), []);

  const setValue = useCallback(
    (...args: Parameters<T>) => {
      window.clearTimeout(debounceTimerRef.current);
      debounceTimerRef.current = window.setTimeout(
        () => handleCallback(...args),
        delay
      );
    },
    [handleCallback, delay]
  );

  return setValue;
}

Import it with your project's alias. Swap @/ for whatever alias you use.

import { useDebouncedCallback } from "@/hooks/use-debounced-callback";

Search as the user types

import { useState } from "react";

import { useDebouncedCallback } from "@/hooks/use-debounced-callback";

export function SearchBox() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState<string[]>([]);

  const search = useDebouncedCallback(async (value: string) => {
    const response = await fetch(`/api/search?q=${encodeURIComponent(value)}`);
    setResults((await response.json()) as string[]);
  }, 300);

  return (
    <input
      value={query}
      onChange={(event) => {
        setQuery(event.target.value);
        search(event.target.value);
      }}
    />
  );
}

The callback can be async, and the input updates immediately while the request waits. The scheduler stays stable across renders, so a new function identity does not restart the timer. Debouncing the request does not cancel requests already in flight; add AbortController if out-of-order responses matter.

Save a draft after the user pauses

import { useState } from "react";

import { useDebouncedCallback } from "@/hooks/use-debounced-callback";

type Draft = { title: string; body: string };

export function DraftEditor() {
  const [draft, setDraft] = useState<Draft>({ title: "", body: "" });
  const save = useDebouncedCallback((nextDraft: Draft) => {
    void fetch("/api/draft", {
      method: "PUT",
      body: JSON.stringify(nextDraft),
    });
  }, 800);

  return (
    <textarea
      value={draft.body}
      onChange={(event) => {
        const next = { ...draft, body: event.target.value };
        setDraft(next);
        save(next);
      }}
    />
  );
}

Passing the next draft as an argument makes the delayed write carry the snapshot from the keystroke that scheduled it, while the callback itself can still see the latest render's state.

Keep a listener subscribed once

import { useEffect } from "react";

import { useDebouncedCallback } from "@/hooks/use-debounced-callback";

type Point = { x: number; y: number };

export function useScrollReport() {
  const report = useDebouncedCallback((point: Point) => {
    void fetch("/api/scroll", {
      method: "POST",
      body: JSON.stringify(point),
    });
  }, 250);

  useEffect(() => {
    const onScroll = () => report({ x: window.scrollX, y: window.scrollY });
    window.addEventListener("scroll", onScroll);
    return () => window.removeEventListener("scroll", onScroll);
  }, [report]);
}

The effect runs once because report does not change when the callback body changes. That is the payoff: a stable dependency that still calls the latest code.

Anti-pattern

❌ Do not call the debounced function during render.

import { useDebouncedCallback } from "@/hooks/use-debounced-callback";

function SearchBox({ query }: { query: string }) {
  const run = useDebouncedCallback((value: string) => {
    void fetch(`/api/search?q=${value}`);
  }, 300);

  run(query);
  return <p>Searching for {query}</p>;
}

This schedules a timer on every render, including renders caused by unrelated state, and it makes render impure. Call it from the event that actually happened.

When to Use It

Reach for this hook only when all three statements are true:

You need a delayed call from a rapid event, and only the final call's arguments should win.
The callback can change between renders because it closes over state or props, and it should use the newest committed version.
You need a stable function identity for a dependency array, a memoized child, or a long-lived subscription.

Situation	Better tool
You need to cancel or flush the pending call	A debounce utility with `cancel()` and `flush()`
Every call matters and must run in order	A queue or throttle
You are debouncing a value, not an event	`useDeferredValue`, or derive the value first
The callback must run during server rendering or in Node	A server-side scheduler with the correct timer type
You need to cancel in-flight network requests	`AbortController` in addition to debouncing
You need the pending call to run on unmount	Explicit cleanup or a library with `flush()`

Smell test: if you cannot name the event that starts the timer and the render value that must stay fresh, you probably want a plain setTimeout or a debounce library, not this hook.

How It Works Under the Hood

The wrapper is the address. useCallbackRef returns a function created with useMemo(..., []). That function closes over the ref object, not over callback. The inner call is callbackRef.current?.(...args), so the identity stays fixed while the value behind it changes. In current React the memoized wrapper is retained for the component's lifetime, though useMemo is documented as a performance optimization rather than a semantic guarantee. useDebouncedCallback then wraps the scheduler in useCallback with [handleCallback, delay]. Because handleCallback is stable, changing the callback does not change setValue. Changing delay does, which is why the delay should be a constant or a memoized value.
The ref is updated after commit, not during render. The helper uses useEffect(() => { callbackRef.current = callback; }); with no dependency array. It runs after every committed render. This is deliberate. A render can be discarded before it commits; writing the callback ref during render would let a discarded render leak its callback into the live tree. The effect only exposes callbacks from committed renders. The read is deferred until fire time, which is why the timer never closes over the old callback.
The timer is a single slot. debounceTimerRef starts at 0. Every call clears the previous timeout and stores the new id. The unmount effect returns a cleanup that clears whatever id is current. Only the last call before the delay wins; earlier arguments are dropped. The cost is one timeout and one retained argument list per pending call. The cleanup happens on unmount, but not when delay or callback changes. A pending timer keeps its original delay until it fires. There is no public cancel or flush.
Effect ordering creates a narrow edge. The callback ref is updated in a passive effect after commit. A timer that fires between commit and that effect would see the previous committed callback. For a normal debounce delay this window is effectively invisible, but it is not zero. In development, StrictMode runs effect setup, cleanup, and setup again on mount; the initial cleanup clears timer id 0, which is harmless unless you scheduled a timer from a layout effect in that gap.
The timer is browser code. window.setTimeout and window.clearTimeout are referenced only when the returned function is called or when cleanup runs. During server rendering, effects do not run and the returned function should not be called, so the component renders without touching window. If you need the hook in Node or React Native, replace window.setTimeout with the global timer and use ReturnType<typeof setTimeout> for the ref type; do not call the returned function during SSR.

Here is the value at each phase. S1 is the scheduler identity; it stays the same as long as delay does.

Phase	`callbackRef.current`	`setValue`	Timer
Initial render with callback A	A	S1	none
Commit and passive effect	A	S1	none
Discarded concurrent render with callback B	A	S1	none
New committed render with callback C	A	S1	none
Passive effect after that commit	C	S1	none
First `setValue("re")`	C	S1	T1
Next render with inline callback D	C	S1	T1
Passive effect after that commit	D	S1	T1
T1 fires	D	S1	fired

The table shows the split: the callback slot moves, the scheduler does not. A discarded render never reaches the slot. A timer scheduled before a render can fire with the callback from before or after that render, depending on whether the passive effect has run.

useEffectEvent, where your React version provides it, solves a related problem: an effect that needs the latest props or state without re-running. It is not a general-purpose debounce scheduler. Its function is meant to be called from effects, not passed to children or stored as an event handler, and it does not manage timer identity or cleanup. This hook solves a broader, older problem: a stable function you can hand to an event handler, a subscription, or a child, with the latest callback read when the timer fires.

Conclusion

The tradeoff is small and deliberate: one stable scheduler, one mutable callback slot, one timer. You give up cancel, flush, and automatic rescheduling when the delay changes. In return, you get a function that can sit in dependency arrays without restarting the timer, while still calling the newest committed callback.

Stable identity is not a frozen closure. The wrapper is stable; the callback is read at fire time.
Update the callback after commit, never during render. A discarded render must not leak into the live tree.
The pending timer is cleared on unmount, not on every change. Keep the delay stable and pass the exact arguments you want the delayed call to receive.

Use it when a debounced event handler must survive re-renders. Reach for a real debounce utility when you need cancel, flush, or a timer that reschedules when the delay itself changes.

useCallbackRef: A Stable Callback That Never Goes Stale

Saiful Islam — Sun, 25 Oct 2026 09:11:18 +0000

A five-line hook that gives you one function identity for the life of a component while always calling the newest version — and why the swap waits until after paint, not during render.

The Problem

You have an autosave. It is almost right.

import { useEffect, useState } from "react";

type Draft = { id: string; body: string };

function Editor({
  draftId,
  initialBody,
  onSave,
}: {
  draftId: string;
  initialBody: string;
  onSave: (draft: Draft) => Promise<void>;
}) {
  const [body, setBody] = useState(initialBody);

  useEffect(() => {
    const id = setInterval(() => {
      void onSave({ id: draftId, body }); // ⚠️ `body` from the mount render
    }, 5000);
    return () => clearInterval(id);
  }, [draftId]);

  return (
    <textarea value={body} onChange={(event) => setBody(event.target.value)} />
  );
}

You type for two minutes. The save spinner blinks every five seconds. The server receives the same draft every time: the body you passed as initialBody, usually an empty string. Nothing throws. The network tab is green. The bug is invisible until someone reopens the document and finds the work gone.

So you try the fixes, in order.

Fix attempt 1 — add the value to the dependency array.

-  }, [draftId]);
+  }, [draftId, body]);

The interval is now correct and useless. Every keystroke tears it down and builds a new one, so the timer restarts before it ever reaches five seconds. A fast typist never autosaves at all. If the parent passes an inline arrow for onSave — which it usually does — unrelated parent renders reset it too.

Fix attempt 2 — memoize the callback.

const handleSave = useCallback((draft: Draft) => onSave(draft), [onSave]);

To earn a stable identity, the callback has to stop closing over the thing that changes. Drop body from its dependencies and you have recreated the original bug one level up. Keep body and the identity changes on every keystroke, which is the interval reset again. You have moved the same decision into a second dependency array, not made it.

Fix attempt 3 — silence the linter.

-  }, [draftId]);
+  }, [draftId]); // eslint-disable-line react-hooks/exhaustive-deps

The warning is gone. The stale draft is not.

The real problem is not the dependency array. The timer needs one thing from the handler — a stable identity so it is never rebuilt — and the handler needs the other — current state at the moment it fires. A closure can only give you one of them, because the captured variables and the function are the same object.

A ref breaks that coupling: the ref never changes, its contents do. This hook wraps a ref in a function so the stable setInterval can call the fresh closure.

import { useEffect, useMemo, useRef } from "react";

function useCallbackRef<T extends (...args: never[]) => unknown>(
  callback: T | undefined
): T {
  const callbackRef = useRef(callback);

  useEffect(() => {
    callbackRef.current = callback;
  });

  return useMemo(() => ((...args) => callbackRef.current?.(...args)) as T, []);
}

The Mental Model

Think of the extension number for a hotel front desk.

The number never changes. useMemo(() => …, []) builds one wrapper on the first render and returns that same function until the component unmounts. Timers, sockets, and third-party widgets can store it and never invalidate it.
Whoever answers changes per shift. After every commit, callbackRef.current = callback replaces the body with the function from the latest render.
You only learn who is on duty when you dial. The wrapper forwards the call at invocation time. It does not copy the callback when it was created.
An empty desk just rings out. The optional call callbackRef.current?.(...) turns a undefined callback into a silent no-op instead of a crash.

Two consequences follow directly:

The wrapper is not a value you can inspect. Calling it is the only way to observe the current callback; reading it during render tells you nothing.
It is exactly right for code that stores a function — timers, listeners, widget constructors, memoized children — and wrong for code that has to decide whether to run based on the function identity.

A quick way to remember it: same number, whoever is on shift.

How to Use It

One file, no dependencies beyond React:

src/
└── hooks/
    └── use-callback-ref.ts

src/hooks/use-callback-ref.ts:

import { useEffect, useMemo, useRef } from "react";

/**
 * A custom hook that converts a callback to a ref to avoid triggering re-renders when passed as a
 * prop or avoid re-executing effects when passed as a dependency
 */
function useCallbackRef<T extends (...args: never[]) => unknown>(
  callback: T | undefined
): T {
  const callbackRef = useRef(callback);

  useEffect(() => {
    callbackRef.current = callback;
  });

  return useMemo(() => ((...args) => callbackRef.current?.(...args)) as T, []);
}

export { useCallbackRef };

Import it through whatever alias your project uses; the examples below assume @/:

import { useCallbackRef } from "@/hooks/use-callback-ref";

The one rule that makes every pattern below work: wrap the closure, not the values. The hook stabilizes a function. If a value is read outside that function, the hook cannot help you.

Pattern 1: A timer that must survive every render

type Draft = { id: string; body: string };

function useAutosave(save: () => void) {
  const saveRef = useCallbackRef(save);

  useEffect(() => {
    const id = setInterval(() => saveRef(), 5000);
    return () => clearInterval(id);
  }, [saveRef]);
}

function Editor({
  draftId,
  initialBody,
  onSave,
}: {
  draftId: string;
  initialBody: string;
  onSave: (draft: Draft) => Promise<void>;
}) {
  const [body, setBody] = useState(initialBody);

  useAutosave(() => {
    void onSave({ id: draftId, body });
  });

  return (
    <textarea value={body} onChange={(event) => setBody(event.target.value)} />
  );
}

The caller passes a brand-new closure on every render, which looks wasteful and is the point: the ref keeps the newest one, and the interval keeps its original identity. One timer for the life of the editor, writing whatever is in the textarea at the tick.

Pattern 2: A listener that outlives the render

function useFlushOnExit(flush: () => void) {
  const flushRef = useCallbackRef(flush);

  useEffect(() => {
    const handler = () => flushRef();
    window.addEventListener("pagehide", handler);
    return () => window.removeEventListener("pagehide", handler);
  }, [flushRef]);
}

function Editor({
  draftId,
  initialBody,
}: {
  draftId: string;
  initialBody: string;
}) {
  const [body, setBody] = useState(initialBody);

  useFlushOnExit(() => {
    navigator.sendBeacon(`/api/drafts/${draftId}`, JSON.stringify({ body }));
  });

  return (
    <textarea value={body} onChange={(event) => setBody(event.target.value)} />
  );
}

There is exactly one registration and no window where the page is unloading with no listener attached. The payload is assembled at unload time from the current state, not from the state at mount.

Pattern 3: A callback handed to a non-React instance

// Stand-in for a widget library that captures its callback at construction.
class Typeahead {
  constructor(
    private readonly input: HTMLInputElement,
    private onPick: ((value: string) => void) | undefined
  ) {}

  press() {
    this.onPick?.(this.input.value);
  }

  destroy() {
    this.onPick = undefined;
  }
}

function SearchField({ onPick }: { onPick: (value: string) => void }) {
  const inputRef = useRef<HTMLInputElement>(null);
  const pickRef = useCallbackRef((value: string) => onPick(value));

  useEffect(() => {
    const input = inputRef.current;
    if (!input) return;
    const widget = new Typeahead(input, (value) => pickRef(value));
    return () => widget.destroy();
  }, [pickRef]);

  return <input ref={inputRef} />;
}

The widget is constructed once and stores a function forever. Changing onPick — even on every parent render — never forces you to destroy and rebuild it, which for a real editor, map, or chart means the undo history and viewport survive too.

Pattern 4: A stable prop for a memoized child

type Row = { id: string; label: string };

const RowItem = memo(function RowItem({
  row,
  selected,
  onSelect,
}: {
  row: Row;
  selected: boolean;
  onSelect: (id: string) => void;
}) {
  return (
    <button aria-pressed={selected} onClick={() => onSelect(row.id)}>
      {row.label}
    </button>
  );
});

function RowList({
  rows,
  onOpen,
}: {
  rows: Row[];
  onOpen: (id: string) => void;
}) {
  const [selectedId, setSelectedId] = useState<string | null>(null);

  const select = useCallbackRef((id: string) => {
    if (selectedId === id) {
      setSelectedId(null);
      return;
    }
    setSelectedId(id);
    onOpen(id);
  });

  return (
    <div>
      {rows.map((row) => (
        <RowItem
          key={row.id}
          row={row}
          selected={row.id === selectedId}
          onSelect={select}
        />
      ))}
    </div>
  );
}

select reads selectedId, yet its identity never changes. A useCallback with [selectedId] would hand every row a new prop each time the selection moves and defeat the memo; here only the two rows whose selected flag changed re-render.

The one thing not to do

// ❌ the wrapper is stable; `page` is still frozen at 0
const load = useCallbackRef(onLoad);

useEffect(() => {
  void load(page);
}, []);

The hook stabilizes a function, not the variables around the call site. If the effect must react to page, put page in the dependency array. The wrapper only helps when the current page is read inside the function you hand it.

When to Use It

Reach for useCallbackRef when all three are true:

Something stores your function beyond the render that created it — a timer, a DOM listener, a widget instance, a memoized child.
When that thing fires, it needs the values from the latest render, not the ones from setup.
Re-subscribing to get those values would be expensive, disruptive, or visibly wrong: a reset interval, a reconnect, a lost editor history, a gap in events.

Don't reach for it when:

Situation	Better tool
Adding the dependency is cheap and harmless	Just add it to the array
The effect must re-run when a value changes	Put that value in the dependency array
You need a DOM node	`useRef<HTMLDivElement>(null)`
You only need a stable handler with stable deps	`useCallback`
You are inside an effect and want the latest props	`useEffectEvent` (React 19.2+)
You need the result during render	Call the prop or compute it directly

A useful smell test: if the consumer keeps working after you add the callback to a dependency array and let it re-subscribe, this hook is extra machinery.

How It Works Under the Hood

1. `useRef(callback)` seeds the desk before the first shift

const callbackRef = useRef(callback);

useRef ignores its argument after the first render and returns the same object for the component's lifetime. Seeding it with callback instead of null means the wrapper is callable immediately — during the first render, from a layout effect, from a child's effect — with the callback from that same render. A null seed would open a window where the first legitimate call is a no-op.

2. `useMemo(…, [])` makes the identity stable and allocates once

return useMemo(() => ((...args) => callbackRef.current?.(...args)) as T, []);

The factory runs on the first render and the result is cached. Every later render returns the same function object, so a consumer that stored it never needs to be told anything changed.

useRef(() => …) would be tempting, but the expression inside useRef(...) is evaluated on every render — you would allocate a throwaway closure per render just to discard it. useCallback(fn, []) is equivalent here; it compiles to useMemo(() => fn, []). React's docs describe useMemo as a performance optimization rather than a hard guarantee, but the identity is stable for the life of the mounted component, which is the contract this hook needs.

3. `useEffect` with no dependency array updates after paint

useEffect(() => {
  callbackRef.current = callback;
});

No dependency array means every commit, not every render. The distinction matters: if React starts a render and throws it away — an interrupted concurrent render, a suspended tree, a superseded update — the effect never runs, so the ref still holds the last callback that actually reached the screen. Assigning callbackRef.current = callback in the render body would leak values from renders the user never saw.

This is a passive effect, so it runs after the browser paints. On the client the sequence is:

React renders (a read of current here returns the previous callback).
React commits the DOM.
Layout effects run.
Browser paints.
Passive effects run and the ref receives the new callback.

A native listener or a setInterval tick can fire between steps 4 and 5, because passive effects are scheduled as a task rather than run synchronously at commit. That gap is the price of using useEffect instead of useLayoutEffect. It is short and, for the consumers this hook targets, harmless; if you need the update to land before paint, swap in useLayoutEffect (behind an SSR guard) and accept that it blocks paint.

4. The read is deferred to call time

callbackRef.current?.(...args);

The wrapper does not close over callback; it closes over the ref. Every invocation reads current fresh, which is the entire mechanism. The optional chaining handles the undefined case: a hook that accepts T | undefined can be handed a callback that disappears (a cleared prop, a disabled feature) and calls become silent no-ops rather than TypeErrors.

That flexibility has a typing cost. If you call useCallbackRef(undefined) with no contextual type, TypeScript falls back to the constraint, and the return type is (...args: never[]) => unknown — not your handler's signature. Pass a typed variable when you need the real type back.

5. The constraint and the assertion

<T extends (...args: never[]) => unknown>

never[] accepts any function signature. Parameter positions are checked contravariantly, and never is assignable to everything, so a (id: string, count: number) => void satisfies the constraint; unknown[] would reject it. Using any[] would also work but would leak any into inference.

as T is load-bearing. The wrapper's body cannot prove it implements an arbitrary T — TypeScript cannot spread a generic parameter tuple into a generic call — so the assertion restores the exact signature at the boundary. Two things it does not preserve: this binding (the callback is called as a plain function) and properties attached to the function object (they exist on the original, not on the wrapper).

The timeline

Assume the component receives a new onSave prop on each render:

Point in time	`callback` prop	`callbackRef.current`	Returned function
Render 1	`fn A`	`fn A` (seed)	`W1` (new)
Commit 1	`fn A`	`fn A`	`W1`
Passive effect 1	`fn A`	`fn A`	`W1`
Render 2	`fn B`	`fn A` — old value during render	`W1`
Paint 2	`fn B`	`fn A` — not updated yet	`W1`
Click between paint and effect	`fn B`	`fn A` — previous handler runs	`W1`
Passive effect 2	`fn B`	`fn B`	`W1`
Render 3 (discarded)	`fn C`	`fn B` — never updated, correctly	`W1`
Commit 3	`fn C`	`fn C`	`W1`
Unmount	—	released	released

Effect ordering

Passive effects run child-first. If a child's useEffect calls a wrapper owned by its parent in the same commit, the parent's effect has not run yet, so the child reaches the previous render's callback. Layout effects have the mirror-image issue. This rarely matters because the hook's consumers are timers, listeners, and event handlers, not effects in the same commit — but if you hit it, move the value into a prop for that one path.

Cost

One ref and one wrapper per component instance, both alive until unmount. One effect closure allocated per commit — the effect has no dependency array, so React cannot skip it — plus one property write. Zero extra renders, zero subscriptions, no per-call allocation. The ref retains the newest callback, and therefore anything that callback closes over, until it is replaced or the component unmounts; that is the one memory consideration worth naming.

A note on server rendering

useEffect never runs on the server, so the ref keeps its seed. That is fine: nothing calls the wrapper during SSR except your own render code, and if it does, it reaches the callback from that render rather than undefined. Functions are not serialized into HTML, so there is no hydration mismatch — only the usual rule that the client's first render must match the server's, which this hook does not affect. No isomorphic-layout-effect wrapper is needed here precisely because the hook uses the passive effect.

Compared to `useEffectEvent`

React 19.2 ships useEffectEvent, which returns a stable function that reads the latest props and state. It covers the narrow case this hook is often reached for: calling the newest callback from inside an effect. It deliberately refuses the rest — the linter stops you from passing that function to a socket constructor, a memoized child, or an event listener registered elsewhere, because those calls happen outside the effect system it is designed around. useCallbackRef is the general-purpose version: any function, handed to anything, callable anywhere except during render.

Conclusion

The tension is not really about dependency arrays. It is that a function carries its captured values with it, so a stable function is a stale function unless something outside the closure can refresh it. useCallbackRef puts that refresh in a ref that is updated after every commit, and exposes a wrapper whose identity never changes.

The wrapper is stable, so timers, listeners, widgets, and memoized children are set up once.
The ref is refreshed after every commit, so the call that eventually fires reaches the newest closure.
The update is deliberately late — after paint, never during render — which keeps discarded renders from leaking into the ref and keeps the hook out of the rendering path.

Wrap the closure, not the values, and it disappears into the background. Everywhere the consumer can simply take a dependency and re-subscribe, the boring answer is still correct.

useAsRef: The Latest Value Without the Re-Subscribe

Saiful Islam — Fri, 23 Oct 2026 09:57:22 +0000

A four-line hook that kills stale closures without making your effects run again — and why the update happens after commit, not during render.

The Problem

You have an effect that should run once. Inside it, you read something that changes on every render — a prop, a callback, a config object. React hands you two options, and both are wrong.

function ChatRoom({ roomId }: { roomId: string }) {
  const [messages, setMessages] = useState<Message[]>([]);

  useEffect(() => {
    const socket = new WebSocket(`/ws/${roomId}`);
    socket.onmessage = (event) => {
      const message = JSON.parse(event.data) as Message;
      setMessages((prev) => [...prev, message]); // ✅ setter is stable, updater sees latest
    };
    return () => socket.close();
  }, [roomId]);
}

The setter above is safe: setMessages never changes identity, and the functional updater receives the latest state instead of a captured copy. Now change one thing: the component needs to call a prop.

socket.onmessage = (event) => {
  onMessage(JSON.parse(event.data)); // ⚠️ which `onMessage`?
};

That closure captured the onMessage from the render that created the socket. Every message after the first render goes to the original handler — the one that saw the old room, the old user, the empty message list. Nothing throws. The UI just quietly drifts out of sync.

So you try the fixes, in order:

Fix attempt 1 — add the dependency.

-  }, [roomId]);
+  }, [roomId, onMessage]);

Now every parent render that passes an inline arrow tears down the socket and reconnects. You get a reconnect storm, dropped messages during the gap, and a server that marks the user offline and online over and over.

Fix attempt 2 — silence the linter.

-  }, [roomId, onMessage]);
+  }, [roomId]); // eslint-disable-line react-hooks/exhaustive-deps

The lint warning is gone. The bug is not. You've just moved it somewhere it's harder to find.

Fix attempt 3 — wrap everything in useCallback.

You memoize onMessage, then its parent memoizes its props, then someone passes items.filter(...) as a prop and the chain breaks. You now maintain a dependency graph by hand, and the socket still reconnects whenever a parent re-renders.

The real problem isn't the dependency array. It's that you need two different things from the same value: a stable identity so the subscription never restarts, and the current value when the callback eventually fires. A closure gives you the first and loses the second. A dependency array gives you the second and loses the first.

useAsRef gives you both, because a ref has a stable identity and mutable contents.

function useAsRef<T>(props: T) {
  const ref = React.useRef<T>(props);

  useIsomorphicLayoutEffect(() => {
    ref.current = props;
  });

  return ref;
}

The Mental Model

Think of a mailbox bolted to the component.

The mailbox never moves. ref is the same object on every render, forever. Effects, timers, and third-party listeners can keep a reference to it without being torn down.
The mail is replaced after every commit. The render function does not write to the mailbox. React finishes committing, then the hook drops in the freshest props.
Readers always get yesterday's mail until today's delivery lands. Anything that reads during render sees the previous commit's value. Anything that reads from an event handler, timer, subscription, or passive effect — i.e. after commit — sees the current one.

That last point is the whole design. useAsRef is not "a ref that is always up to date." It's "a ref that is up to date by the time any real-world event can read it."

Two consequences follow directly:

It is not a source of truth for rendering. If you need a value in JSX, use the prop.
It is exactly right for code that runs outside React's render cycle — sockets, intervals, ResizeObserver, editor instances, map callbacks, IntersectionObserver, imperative widgets.

A quick way to remember it: stable handle, fresh contents, never a re-render.

How to Use It

The hook is two small files that live in your app's hooks folder. This article assumes the common src/ layout — adapt the paths to yours:

src/
└── hooks/
    ├── use-as-ref.ts
    └── use-isomorphic-layout-effect.ts

src/hooks/use-isomorphic-layout-effect.ts — a five-line helper that picks the right effect on the server and the client:

import * as React from "react";

const useIsomorphicLayoutEffect =
  typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;

export { useIsomorphicLayoutEffect };

src/hooks/use-as-ref.ts — the hook itself:

import * as React from "react";

import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect";

function useAsRef<T>(props: T) {
  const ref = React.useRef<T>(props);

  useIsomorphicLayoutEffect(() => {
    ref.current = props;
  });

  return ref;
}

export { useAsRef };

Then import it like any other hook. The examples below use the @/ alias most React setups configure; swap in whatever your project uses:

import { useAsRef } from "@/hooks/use-as-ref";

If you already have an isomorphic layout effect helper (many SSR-ready apps do), keep yours and skip the first file.

Pattern 1: A long-lived effect that needs current props

function PresenceIndicator({
  roomId,
  userId,
  sendPing,
}: {
  roomId: string;
  userId: string;
  sendPing: (roomId: string, userId: string) => void;
}) {
  const latest = useAsRef({ roomId, userId, sendPing });

  useEffect(() => {
    const id = setInterval(() => {
      const props = latest.current;
      props.sendPing(props.roomId, props.userId);
    }, 15_000);

    return () => clearInterval(id);
  }, [latest]); // stable, so this runs exactly once

  return null;
}

The interval is created once. When the user switches rooms or the parent passes a new sendPing, the contents change but the timer doesn't. No teardown, no drift.

Grouping several values into one object (useAsRef({ roomId, userId, sendPing })) is the common case: one ref, one read, and the call site stays readable.

Pattern 2: Handing a callback to a non-React system

type ServerEvent = { type: string; payload: unknown };

function useRealtimeEvents(onEvent: (event: ServerEvent) => void) {
  const onEventRef = useAsRef(onEvent);

  useEffect(() => {
    const socket = new WebSocket("/ws");
    socket.onmessage = (message) => {
      onEventRef.current(JSON.parse(message.data) as ServerEvent);
    };
    return () => socket.close();
  }, []); // never reconnects, no matter how `onEvent` changes
}

This is the shape to reach for in any realtime provider. The socket owns its lifecycle; the ref owns the handler. Changing onEvent — even on every render — can no longer restart the connection.

Pattern 3: A stable event handler that reads current values

type StepperProps = {
  value: number;
  max: number;
  step: number;
  onChange: (value: number) => void;
};

function Stepper({ value, max, step, onChange }: StepperProps) {
  const propsRef = useAsRef({ value, max, step, onChange });

  const handleKeyDown = useCallback(
    (event: React.KeyboardEvent) => {
      const { value, max, step, onChange } = propsRef.current;
      if (event.key !== "ArrowUp") return;
      onChange(Math.min(value + step, max));
    },
    [propsRef]
  );

  return <div role="spinbutton" onKeyDown={handleKeyDown} />;
}

No dependency list to maintain, no stale value, and handleKeyDown is safe to pass into a memo child or an imperative library that captures it once.

Pattern 4: Read-then-write for back-to-back updates

Because the ref is writable, you can update it before scheduling a re-render. That matters when a hook has to support back-to-back functional updates in the same tick — the classic controlled/uncontrolled state hook. Keeping the current value in a ref lets the second call see what the first one just produced:

// Inside a useControllableState-style hook.
const valueRef = useAsRef(value);

const setValue = useCallback(
  (next: T | ((prev: T) => T)) => {
    const prev = valueRef.current;
    const newValue = typeof next === "function" ? next(prev) : next;
    if (Object.is(newValue, prev)) return;

    valueRef.current = newValue; // visible immediately to the next call
    setUncontrolledValue(newValue);
  },
  [valueRef]
);

useAsRef will overwrite ref.current with the committed value on the next commit, so the manual write is a short-lived optimistic value, not a fork of state.

The one thing not to do

// ❌ renders the previous commit's value
return <span>{countRef.current}</span>;

Reading during render is the single misuse that turns a useful hook into a confusing one. If it's in JSX, it's a prop.

When to Use It

Reach for useAsRef when all three are true:

Something outside React will call back later — a timer, socket, observer, event listener, or third-party instance.
That callback needs the newest value.
Re-subscribing to get the newest value would be expensive, disruptive, or visibly wrong (connection resets, scroll jumps, editor state loss, animation restarts).

Don't reach for it when:

Situation	Better tool
Adding the dependency is cheap and harmless	Just add it to the array
You need a DOM node	`useRef<HTMLDivElement>(null)`
You need a stable function identity to pass as a prop	`useCallback`, or a small wrapper that always calls the latest callback
You need to react to a value changing	`useEffect` with that value in the deps
You need the value during render	Use the prop itself
The value is a state setter	Functional updater: `setX(prev => …)`

A useful smell test: if removing useAsRef and adding the dependency produces no user-visible behavior change, the hook was unnecessary indirection.

How It Works Under the Hood

Four lines, and four details worth understanding.

1. `useRef<T>(props)` — stable identity, seeded with the first value

const ref = React.useRef<T>(props);

useRef returns the same object across every render of the component's lifetime. The initial argument is only used on the first render; after that it's ignored. Seeding it with props (rather than null) means the ref is already readable before any effect fires — on the very first commit, a child's layout effect (which runs before the parent's) reads the initial props instead of null. In React 19's types, the result is a RefObject<T> whose current is mutable.

2. `useIsomorphicLayoutEffect` — update after commit, before paint

useIsomorphicLayoutEffect(() => {
  ref.current = props;
});

There is no dependency array, so this runs after every commit. That's intentional: you don't want to enumerate dependencies for a value you're already holding, and the assignment is a single property write — cheaper than the bookkeeping needed to skip it.

On the client, useIsomorphicLayoutEffect is useLayoutEffect. That runs synchronously after React has mutated the DOM but before the browser paints. So the sequence is:

React renders your component (reading the ref gives the old value).
React commits DOM changes.
Layout effects run; ref.current becomes the new value.
Browser paints.
Passive useEffect callbacks run.

By the time a user can click, scroll, or receive a socket frame, the ref is current. Using a passive useEffect here would leave a window where a paint has happened but the ref still holds the previous value.

3. Why not just assign during render?

If all you wanted were the latest value, ref.current = props in the render body would be simpler. It's also unsafe.

React may render a component and throw the result away — an interrupted concurrent render, a Suspense fallback, or a state update that gets superseded. Render must be pure, and mutating a ref during render mutates shared state that survives the discarded render. You'd end up with a ref holding a value that never actually committed, and a callback reading props from a UI state the user never saw.

React 18+ and StrictMode double-invocation make this worse. Assigning in a layout effect ties the write to the commit, which is the only moment the value is real.

This is the same territory React's useEvent RFC explored — the ancestor of today's useEffectEvent. useEffectEvent solves the effect-only case, but it deliberately refuses to be handed to a socket, a timer, or a third-party widget. useAsRef is the general-purpose version of that idea: not just functions, any value, usable anywhere outside render.

4. Why the effect ordering matters

React runs layout effects child-first, then the parent. So if a child's layout effect calls a callback stored in the parent's useAsRef ref, it will still see the previous render's callback — the parent's layout effect hasn't run yet. Passive effects (useEffect) always see the updated ref, because all layout effects across the tree run before any passive effect.

In practice this almost never bites: consumers of useAsRef are timers, sockets, and event handlers, not layout effects. But if you hit it, the fix is to keep the value as a prop in that path rather than routing it through the ref.

The timeline

Assume useAsRef(count) and a parent that increments count each click:

Point in time	`count` (prop)	`countRef.current`
Render 1	`0`	`0` (seed from `useRef`)
Commit 1	`0`	`0`
Render 2	`1`	`0` — old value during render
Commit 2	`1`	`1`
Click handler after paint	`1`	`1`
Render 3 (discarded)	`2`	`1` — never updated, correctly
Commit 3	`2`	`2`

Cost

One ref object for the component's lifetime — it is never recreated. The hook itself does no allocation per render beyond the effect closure React already allocates; a fresh props object is created only if you pass an object literal. Then one property write per commit, zero extra renders, zero subscriptions. The ref holds the latest props between renders, so previous values are released as soon as they're replaced — no leak, though anything the latest props reach is kept alive for as long as the component is mounted.

A note on server rendering

On the server, useIsomorphicLayoutEffect resolves to useEffect, which never runs. The ref simply keeps its initial value. That's fine: no timers, sockets, or click handlers execute during SSR. The isomorphic wrapper exists to avoid React's "useLayoutEffect does nothing on the server" warning, not to make the ref work on the server.

Conclusion

Stale closures happen when a stable identity and a current value are forced to be the same thing. Dependency arrays buy freshness by throwing away the identity; refs buy identity by giving up freshness. useAsRef separates the two:

The ref object is stable, so subscriptions, timers, and third-party listeners are created once.
The ref contents are refreshed after every commit, before paint, so anything that reads outside render sees the current value.
The render phase deliberately sees the old value, which keeps the hook safe under concurrent rendering and prevents it from becoming a second source of truth.

Use it where React stops and the rest of the world begins: sockets, intervals, observers, editors, and any callback that outlives a render. Everywhere else, the boring answer — a prop or a dependency — is still the right one.

Setting Up PostgreSQL with Docker Compose for Development and Production

Saiful Islam — Sat, 29 Nov 2025 15:05:26 +0000

Working with PostgreSQL becomes much easier when you run it inside Docker. It gives you a clean environment, consistent versions, and a quick setup for both development and production. In this guide, we will walk step by step through a practical setup using Docker Compose.

This setup includes:

A custom PostgreSQL configuration
Automatic initialisation scripts
Separate Docker Compose files for development and production
A clear folder structure
Easy commands for starting and stopping the containers

Let us begin by reviewing the folder layout.

1. Folder Structure

Here is the structure used in this guide:

infra/
├─ docker/
│  ├─ docker-compose-dev.yml
│  └─ docker-compose.yml
├─ postgres/
│  ├─ init-scripts/
│  │  └─ init.sql
│  └─ postgres.conf
├─ package.json

Each file has its own purpose:

**postgres.conf* → Custom PostgreSQL configuration
init.sql → Creates roles, permissions, and databases
docker-compose-dev.yml → Development compose file
docker-compose.yml → Production compose file
package.json scripts → Simple commands for starting and stopping services

2. Custom PostgreSQL Configuration

The file postgres.conf defines PostgreSQL tuning parameters.
Some of the key settings include:

Connection limits
Memory tuning
WAL optimisation
Logging options
Security settings

An example:

# Connection settings
listen_addresses = '*'
port = 5432
max_connections = 200

# Memory settings
shared_buffers = 512MB
effective_cache_size = 1GB
work_mem = 4MB
maintenance_work_mem = 128MB

# WAL settings
wal_buffers = 16MB
checkpoint_completion_target = 0.9
wal_compression = on
min_wal_size = 512MB
max_wal_size = 2GB

# Logging
log_destination = 'stderr'
logging_collector = off
log_min_messages = warning
log_min_error_statement = error
log_min_duration_statement = 1000

# Security
ssl = off
password_encryption = scram-sha-256

# Performance
random_page_cost = 1.1
effective_io_concurrency = 200

Keeping this file external makes it easy to adjust performance for development and production without modifying container images.

3. Database Initialisation with init.sql

The init.sql script runs automatically the first time the container starts.
It performs tasks such as:

Creating roles (db_migrator, db_rw, db_ro)
Creating the test database
Setting permissions for each role
Configuring default privileges
Enforcing secure database access

An example:

-- ---------- 1. Create roles ----------
DO $$
BEGIN
    IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'db_migrator') THEN
        CREATE ROLE db_migrator LOGIN PASSWORD '12345678';
    END IF;

    IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'db_rw') THEN
        CREATE ROLE db_rw LOGIN PASSWORD '12345678';
    END IF;

    IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'db_ro') THEN
        CREATE ROLE db_ro LOGIN PASSWORD '12345678';
    END IF;
END
$$;

-- ---------- 2. Create databases ----------
CREATE DATABASE test;

-- ============================================================
-- Apply permissions for each database
-- ============================================================

------------------------------------------------------------
-- Setup for project_db
------------------------------------------------------------
\connect project_db

-- Remove unsafe default privileges
REVOKE ALL ON DATABASE project_db FROM PUBLIC;
REVOKE CREATE ON SCHEMA public FROM PUBLIC;

-- Prisma requires the db_migrator to own the schema
ALTER SCHEMA public OWNER TO db_migrator;

-- db_Migrator full control
GRANT USAGE, CREATE ON SCHEMA public TO db_migrator;

-- Read/Write application user
GRANT USAGE ON SCHEMA public TO db_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO db_rw;
GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA public TO db_rw;

-- Readonly user
GRANT USAGE ON SCHEMA public TO db_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO db_ro;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO db_ro;

-- Default privileges for FUTURE objects created by db_migrator
ALTER DEFAULT PRIVILEGES FOR ROLE db_migrator IN SCHEMA public
    GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO db_rw;

ALTER DEFAULT PRIVILEGES FOR ROLE db_migrator IN SCHEMA public
    GRANT SELECT ON TABLES TO db_ro;

ALTER DEFAULT PRIVILEGES FOR ROLE db_migrator IN SCHEMA public
    GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO db_rw;

ALTER DEFAULT PRIVILEGES FOR ROLE db_migrator IN SCHEMA public
    GRANT USAGE, SELECT ON SEQUENCES TO db_ro;

-- Allow connections
GRANT CONNECT ON DATABASE project_db TO db_migrator, db_rw, db_ro;

-------------------------------
-- Setup for test database
-------------------------------
\connect test

REVOKE ALL ON DATABASE test FROM PUBLIC;
REVOKE CREATE ON SCHEMA public FROM PUBLIC;

ALTER SCHEMA public OWNER TO db_migrator;
GRANT USAGE, CREATE ON SCHEMA public TO db_migrator;

GRANT USAGE ON SCHEMA public TO db_rw, db_ro;

GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO db_rw;
GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA public TO db_rw;

GRANT SELECT ON ALL TABLES IN SCHEMA public TO db_ro;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO db_ro;

ALTER DEFAULT PRIVILEGES FOR ROLE db_migrator IN SCHEMA public
    GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO db_rw;

ALTER DEFAULT PRIVILEGES FOR ROLE db_migrator IN SCHEMA public
    GRANT SELECT ON TABLES TO db_ro;

ALTER DEFAULT PRIVILEGES FOR ROLE db_migrator IN SCHEMA public
    GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO db_rw;

ALTER DEFAULT PRIVILEGES FOR ROLE db_migrator IN SCHEMA public
    GRANT USAGE, SELECT ON SEQUENCES TO db_ro;

GRANT CONNECT ON DATABASE test TO db_migrator, db_rw, db_ro;

This ensures a predictable PostgreSQL environment and follows best practices for separating permissions.

Docker automatically executes any .sql file placed inside:

/docker-entrypoint-initdb.d

This is why we mount that directory inside the container.

4. Development Compose File

The development file is simple and focuses on flexibility.
Key features include:

PGAdmin for database management
Exposed ports for local access
Mounted configuration and initialisation scripts
Health checks
Volumes for persistent storage

Example:

services:
  postgres:
    image: postgres:16.11-alpine3.22
    container_name: postgres
    restart: unless-stopped
    ports:
      - "5432:5432"
    env_file:
      - ../../.env
      - ../../.env.development.local
    volumes:
      - pg_volume:/var/lib/postgresql/data:rw
      - ../postgres/postgres.conf:/etc/postgresql/postgresql.conf:ro
      - ../postgres/init-scripts:/docker-entrypoint-initdb.d:ro
    command: [ "postgres", "-c", "config_file=/etc/postgresql/postgresql.conf", "-c", "log_statement=none", "-c", "log_min_duration_statement=1000", "-c", "log_connections=on", "-c", "log_disconnections=on" ]
    user: "70:70" # Postgres user
    healthcheck:
      test: [ "CMD-SHELL", 'pg_isready -U "$${POSTGRES_USER:-postgres}" -d "$${POSTGRES_DB:-postgres}" -h localhost || exit 1' ]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s
    stop_grace_period: 120s
    networks:
      - project_network

  pgadmin:
    image: elestio/pgadmin:latest
    container_name: pgadmin
    restart: unless-stopped
    ports:
      - "5050:8080"
    env_file:
      - ../../.env
      - ../../.env.development.local
    volumes:
      - pgadmin_volume:/var/lib/pgadmin:rw
    depends_on:
      - postgres
    networks:
      - project_network

networks:
  project_network:
    driver: bridge

volumes:
  pg_volume:
    driver: local
  pgadmin_volume:
    driver: local

Development environments usually need visibility, so logging and access remain more open.

5. Production Compose File

Production requires a stricter setup.
This file includes:

Resource limits
Security enhancements
Custom network settings
Logging configuration
No PGAdmin
No unnecessary services

Example:

services:
  postgres:
    image: postgres:16.11-alpine3.22
    container_name: postgres
    restart: unless-stopped
    ports:
      - "5432:5432"
    env_file:
      - ../../.env
      - ../../.env.production.local
    volumes:
      - pg_volume:/var/lib/postgresql/data:rw
      - ../postgres/postgres.conf:/etc/postgresql/postgresql.conf:ro
      - ../postgres/init-scripts:/docker-entrypoint-initdb.d:ro
    command: [ "postgres", "-c", "config_file=/etc/postgresql/postgresql.conf", "-c", "log_statement=none", "-c", "log_min_duration_statement=1000", "-c", "log_connections=on", "-c", "log_disconnections=on" ]
    user: "70:70" # Postgres user
    healthcheck:
      test: [ "CMD-SHELL", 'pg_isready -U "$${POSTGRES_USER:-postgres}" -d "$${POSTGRES_DB:-postgres}" -h localhost || exit 1' ]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s
    stop_grace_period: 120s
    networks:
      - project_network
    security_opt:
      - no-new-privileges:true
    shm_size: "512mb"
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "5"
    deploy:
      resources:
        limits:
          cpus: "1.5"
          memory: 1G
        reservations:
          cpus: "0.5"
          memory: 512M
    labels:
      - "com.docker.compose.service=postgres"
      - "maintainer=your.dev.mail@mail.com"

networks:
  project_network:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: ma_bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16
    labels:
      - "com.docker.compose.network=project_name"

volumes:
  pg_volume:
    driver: local
    labels:
      - "com.docker.compose.volume=pg_volume"

Production setups focus on stability, performance, and security.

6. Running PostgreSQL with NPM Scripts

To simplify the workflow, the package.json includes convenient commands:

"scripts": {
  "docker-dev:up": "docker compose -f ./infra/docker/docker-compose-dev.yml -p project_name up -d",
  "docker-dev:down": "docker compose -f ./infra/docker/docker-compose-dev.yml -p project_name down",
  "docker:up": "docker compose -f ./infra/docker/docker-compose.yml -p project_name up -d",
  "docker:down": "docker compose -f ./infra/docker/docker-compose.yml -p project_name down"
}

Now starting PostgreSQL is as simple as:

npm run docker-dev:up

And stopping:

npm run docker-dev:down

The same applies to production.

7. Conclusion

Using separate Docker Compose files for development and production provides a cleaner and safer workflow. Your development environment becomes flexible, while the production environment stays stable and optimised.

This approach also ensures:

Reproducible environments
Clear separation of roles and permissions
Easier onboarding for other developers
Stronger security controls
Scalable and maintainable infrastructure

You can now use PostgreSQL with confidence in any setup.

useSyncExternalStore in React — The Right Way to Subscribe to External Data

Saiful Islam — Sun, 12 Oct 2025 16:26:31 +0000

Starting with React 18, a new hook called useSyncExternalStore was introduced.
At first glance, it might look confusing — why do we need it when we already have useState, useEffect, or useRef?

The answer lies in React’s new concurrent rendering model.

When your component depends on data from an external source (like browser events, a global store, or even a WebSocket connection), React needs a way to read that data consistently — even during complex renders or Suspense transitions.

That’s where useSyncExternalStore comes in.

⚙️ What is `useSyncExternalStore`?

useSyncExternalStore is a low-level React hook designed to let components safely subscribe to external data sources.

It ensures:

React always reads a consistent snapshot of the external state.
Avoids tearing — a bug where different components read inconsistent versions of external state.
Works correctly with Concurrent Mode and Server Components.

🧩 The Hook Signature

const snapshot = useSyncExternalStore(
  subscribe,
  getSnapshot,
  getServerSnapshot?
);

Here’s what each argument means:

subscribe(callback)
A function that registers a listener. React will call this callback whenever the external data changes.
getSnapshot()
Returns the current value of the external data.
getServerSnapshot()
(Optional) Returns a fallback snapshot during server-side rendering (SSR).

React uses getSnapshot() during render, and re-renders the component if subscribe() notifies it that something changed.

🧠 Why Not Just Use `useEffect`?

Before React 18, we used something like this:

const [isOnline, setIsOnline] = useState(navigator.onLine);

useEffect(() => {
  function updateStatus() {
    setIsOnline(navigator.onLine);
  }

  window.addEventListener("online", updateStatus);
  window.addEventListener("offline", updateStatus);

  return () => {
    window.removeEventListener("online", updateStatus);
    window.removeEventListener("offline", updateStatus);
  };
}, []);

This works fine in normal rendering, but can fail in concurrent scenarios (e.g., during Suspense, streaming SSR, or concurrent updates).
React might read outdated data or re-render unnecessarily.
useSyncExternalStore fixes this problem by providing synchronised reads of external state.

💻 Example: Tracking Online/Offline Status

Let’s create a reusable hook using useSyncExternalStore:

import { useSyncExternalStore } from "react";

// 1️⃣ Subscribe to browser online/offline events
function subscribe(callback: () => void) {
  window.addEventListener("online", callback);
  window.addEventListener("offline", callback);

  return () => {
    window.removeEventListener("online", callback);
    window.removeEventListener("offline", callback);
  };
}

// 2️⃣ Snapshot getter
function getSnapshot() {
  return navigator.onLine;
}

// 3️⃣ Optional SSR fallback
function getServerSnapshot() {
  return true; // assume online on the server
}

// 4️⃣ Our custom hook
export function useOnlineStatus() {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

Now we can use this hook anywhere:

import React from "react";
import { useOnlineStatus } from "./useOnlineStatus";

export default function NetworkStatus() {
  const isOnline = useOnlineStatus();

  return (
    <div
      style={{
        padding: "2rem",
        textAlign: "center",
        fontFamily: "sans-serif",
      }}
    >
      <h1>
        You are currently:{" "}
        <span style={{ color: isOnline ? "green" : "red" }}>
          {isOnline ? "Online" : "Offline"}
        </span>
      </h1>
    </div>
  );
}

🧩 How It Works

subscribe() tells React how to listen for external changes. When an event happens, React calls the stored callback.
getSnapshot() reads the current external value. React calls it whenever it needs the latest state.
When the external source changes, React re-renders the component with the latest snapshot.
No risk of race conditions or stale state, even in concurrent rendering.

⚡ Other Use Cases

useSyncExternalStore can be used for:

Subscribing to a custom store (like Zustand or Redux)
Watching WebSocketupdates
Reacting to localStorage/sessionStorage changes
Integrating with browser APIs (media queries, geolocation, etc.)

Example with localStorage:

function subscribe(callback: () => void) {
  window.addEventListener("storage", callback);
  return () => window.removeEventListener("storage", callback);
}

function getSnapshot() {
  return localStorage.getItem("theme") || "light";
}

export const useThemeStore = () =>
  useSyncExternalStore(subscribe, getSnapshot, () => "light");

🧭 Key Takeaways

✅ useSyncExternalStore lets React safely read external data.
✅ Prevents stale state issues in concurrent rendering.
✅ Perfect for browser APIs, custom stores, and global events.
✅ Always use it when your component reads state outside React.

🧩 Conclusion

useSyncExternalStore might seem complex at first, but it’s the correct way to subscribe to data outside React’s control — whether that’s browser state, global stores, or server signals.

By using it, your components stay predictable, synchronised, and ready for React’s future.

✨ Improve Your Developer Lifecycle with Husky, lint-staged, and commitlint

Saiful Islam — Wed, 30 Apr 2025 10:16:06 +0000

As a developer, especially when managing code standards, your workflow matters.

You can write great code, but if you:

forget to format it before committing,
skip linting,
or leave vague commit messages like update or fix bug

It all snowballs into a messy codebase that's hard to maintain and collaborate on.

Let me introduce you to three tools that can drastically improve your developer lifecycle:
✅ Husky
✅ lint-staged
✅ commitlint

These tools help enforce discipline and automation without slowing you down, and I've integrated them into my last project.

🔧 What is Husky?

Husky is a tool for managing Git hooks — scripts that run automatically during Git events like pre-commit, commit-msg, pre-push, etc.

Think of it as your personal assistant that runs checks or commands every time you or your teammates interact with Git.

✅ Why Use Husky?

Prevent bad code from being committed.
Run tests, lint, or format files before commits.
Block invalid commits before they reach your repo.

🎯 What is lint-staged?

lint-staged runs linters (or any command) on only the staged files (files that you’re about to commit), not your entire codebase.

✅ Why Use lint-staged?

It's super fast.
You don’t accidentally commit unformatted or buggy code.
It keeps your commits clean and atomic.

📌 Example Use Cases:

Run Prettier and ESLint only on changed files.
Validate Markdown or config files before committing.

📝 What is commitlint?

commitlint checks if your commit messages meet a defined convention, like Conventional Commits.

✅ Why Use commitlint?

Keeps commit messages consistent and meaningful.
Useful for changelogs, release automation, and team collaboration.
Helps new developers follow the project's commit rules.

🚀 Real-World Setup in My Turborepo Project

I’ve used these tools in my own Turborepo-based MERN monorepo containing:

apps/frontend (Next.js)
apps/backend (Express.js)
apps/extension
packages/ui

Let’s walk through how to configure each tool with code examples:

📁 `.lintstagedrc` Configuration

{
  "apps/backend/**/*.{js,ts}": [
    "prettier --write --config ./apps/backend/.prettierrc.mjs",
    "eslint --max-warnings 0 --config ./apps/backend/eslint.config.mjs"
  ],
  "apps/extension/**/*.{js,jsx,ts,tsx}": [
    "prettier --write --config ./apps/extension/.prettierrc.mjs",
    "eslint --max-warnings 0 --config ./apps/extension/eslint.config.js"
  ],
  "apps/frontend/**/*.{js,jsx,ts,tsx}": [
    "prettier --write --config ./apps/frontend/.prettierrc.mjs",
    "eslint --max-warnings 0 --config ./apps/frontend/eslint.config.js"
  ],
  "packages/ui/**/*.{js,jsx,ts,tsx}": [
    "prettier --write --config ./apps/frontend/.prettierrc.mjs",
    "eslint --max-warnings 0 --config ./apps/frontend/eslint.config.js"
  ],
  "*.md": ["prettier --write"]
}

📁 `.commitlintrc.json` Configuration

{
  "extends": ["@commitlint/config-conventional"],
  "rules": {
    "type-enum": [
      2,
      "always",
      [
        "ci",
        "chore",
        "docs",
        "feat",
        "fix",
        "perf",
        "refactor",
        "revert",
        "style",
        "assets",
        "test"
      ]
    ]
  }
}

✅ This enforces commit types like feat, fix, docs, chore, etc.

🔴 Invalid: updated code
✅ Valid: feat: add login screen

📁 Husky Git Hooks

You can install and enable Husky with:

pnpm dlx husky install
pnpm pkg set scripts.prepare="husky install"
git add . && git commit -m "chore: setup husky"

husky/pre-commit

npx lint-staged --allow-empty

→ Runs prettier and eslint only on staged files.

husky/commit-msg

npx --no-install commitlint --edit

npx --no-install commitlint --edit

husky/pre-push

npm run test && npm run build

→ Prevents pushing broken builds.

🧠 Summary: Why You Should Use These Tools

Husky

What it Does: Hooks into Git to run scripts
Why it Matters: Enforces quality and automation at each Git stage

Lint-staged

What it Does: Lints only changed files
Why it Matters: Keeps commits clean without slowing you down

Commitlint

What it Does: Validates commit messages
Why it Matters: Ensures consistent commit history for teams & tooling

Monorepo vs Polyrepo: Choosing the Right Structure for Your MERN Stack Project

Saiful Islam — Sun, 27 Apr 2025 22:56:23 +0000

In modern software development, project structure matters a lot. Whether you are a solo full-stack developer or working in a large team, choosing between Monorepo and Polyrepo can significantly impact your productivity and codebase management.

Today, let's dive into:

What is Monorepo and Polyrepo?
How Turborepo and pnpm workspaces help manage Monorepo?
Why solo/fullstack developers should choose Monorepo?
Why large teams often prefer Polyrepo?

🚀 What is Monorepo?

A Monorepo is a single repository that stores the code for multiple apps or packages.

Example:

apps/client (React frontend)
apps/server (Express backend)
packages/*-config (shared config. Example: typescript config, prettier config, eslint config)

✅ Advantages:

Shared code easily
Single place for versioning and dependency management
Unified CI/CD pipeline
Easy refactoring across apps

🏢 What is Polyrepo?

A Polyrepo is multiple repositories, each responsible for a separate app or service.

Example:

frontend-repo
backend-repo

✅ Advantages:

Clear separation of teams
Independent release cycles
Specific access control

⚙️ How Turborepo + pnpm Workspace Helps Monorepo

Turborepo: Smart task running, build caching, and pipeline orchestration.
pnpm Workspace: Handles dependencies between apps efficiently without duplication.
With Turborepo, you can run and build only the parts of the project that changed.
With pnpm Workspace, all dependencies are installed once, and shared efficiently.

Result: Fast, lightweight, developer-friendly Monorepo management.

👨‍💻 Which One Should You Choose?

Solo fullstack developer use monorepo
Small team of fullstack developers use monorepo
Separate frontend and backend teams use polyrepo
Independent services use polyrepo

💬 Real Talk for Fullstack Developers:

If you are building a MERN Stack project (MongoDB, Express, React, Node.js) and you are working alone as like me or with a small fullstack team — use Monorepo.

Why?

Faster local development.
Easier dependency sharing (e.g., types, API schemas).
Single PR for changes affecting frontend + backend.

"As a fullstack developer, Monorepo feels like home. Everything in one place. Easy to manage. Easy to scale."

🧱 How to Structure MERN Monorepo (Quick Example)

my-monorepo/
│
├── apps/
│   ├── client/       # React app
│   └── server/       # Express API
│
├── packages/
│   └── *-configs/       # all config packages
│
├── turbo.json
├── pnpm-workspace.yaml
└── README.md

🧠 Conclusion

Choosing between Monorepo and Polyrepo depends on your team structure and workflow.

🔵 Solo fullstack or small fullstack team → Monorepo (with Turborepo + pnpm).
🔴 Separate frontend/backend teams → Polyrepo.

Use the right structure and tools to maximize your efficiency 🚀!

Setting Up Redux in Next.js 15 with Typescript

Saiful Islam — Tue, 25 Feb 2025 13:34:42 +0000

When working with global state management in Next.js 15, integrating Redux efficiently is crucial. Instead of directly wrapping the entire app inside Provider, it's best to create a dedicated provider component that manages Redux (and other global providers). This ensures better modularity, scalability, and cleaner architecture.

In this blog, we’ll set up Redux in Next.js 15 with a structured provider approach.

1️⃣ Creating the Root Layout (`RootLayout.tsx`)

The RootLayout.tsx file is the entry point for our Next.js application. Here, we wrap the app inside a custom MainProvider, which will hold all global providers (Redux, Auth, Theme, etc.).

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en" className="dark" style={{ colorScheme: "dark" }}>
      <body className="antialiased w-full min-h-screen overflow-x-hidden">
        <MainProvider>{children}</MainProvider>
      </body>
    </html>
  );
}

💡 Why use MainProvider?

This approach ensures that all global providers are separated from the layout, making it easier to manage and extend.

2️⃣ Creating `MainProvider.tsx`

The MainProvider component serves as the central place to wrap all providers. Currently, it only includes ReduxProvider, but you can add Auth, Theme, or other providers later.

"use client";
import ReduxProvider from "./ReduxProvider";

const MainProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  return <ReduxProvider>{children}</ReduxProvider>;
};

export default MainProvider;

🚀 Modular Architecture

This approach ensures we can extend providers easily in the future without modifying RootLayout.tsx.

3️⃣ Setting Up `ReduxProvider.tsx`

Next, we create ReduxProvider.tsx, which initializes Redux and ensures the store remains persistent.

"use client";
import { useRef } from "react";
import { Provider } from "react-redux";
import { store, AppStore } from "@/lib/redux/store";

const ReduxProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const storeRef = useRef<AppStore | null>(null);

  if (!storeRef.current) {
    storeRef.current = store();
  }

  return <Provider store={storeRef.current}>{children}</Provider>;
};

export default ReduxProvider;

✅ Why useRef?

We use useRef to prevent reinitializing the Redux store on every render, ensuring better performance.

4️⃣ Setting Up Redux Store (`store.ts`)

Now, let’s configure our Redux store inside lib/redux/store.ts.

import { configureStore } from "@reduxjs/toolkit";
import favoriteReducer from "./features/favorite/favoriteSlice";

export const store = () => {
  return configureStore({
    reducer: {
      favorite: favoriteReducer,
    },
  });
};

export type AppStore = ReturnType<typeof store>;
export type RootState = ReturnType<AppStore["getState"]>;
export type AppDispatch = AppStore["dispatch"];

🔥 Dynamic Store Initialization

Instead of exporting a singleton store, we use a factory function (store()), which allows Next.js server actions and middleware integration.

5️⃣ Creating Hooks for Redux (`redux.hooks.ts`)

Instead of importing useDispatch and useSelector directly, let’s create typed Redux hooks.

import { useDispatch, useSelector, useStore } from "react-redux";
import type { RootState, AppDispatch, AppStore } from "@/lib/redux/store";

export const useAppDispatch = useDispatch.withTypes<AppDispatch>();
export const useAppSelector = useSelector.withTypes<RootState>();
export const useAppStore = useStore.withTypes<AppStore>();

🛠 Typed Redux Hooks

This ensures better TypeScript support and avoids repetitive type definitions.

6️⃣ Creating a Redux Slice (`favoriteSlice.ts`)

Let’s create a Redux slice for handling favorite items inside features/favorite/favoriteSlice.ts.

import { createSlice, nanoid, type PayloadAction } from "@reduxjs/toolkit";
import { useAppSelector } from "@/hooks/redux.hooks";

interface FavoriteProductType {}

interface InitialStateType = {
  favoriteProduct: FavoriteProductType[]
};

const initialState: InitialStateType = {};

const favoriteSlice = createSlice({
  name: "favorites",
  initialState,
  reducers: {
    addFavorite: (state, action: PayloadAction<FavoriteProductType>) => {}
  },
});

export const useFavoriteProduct = () =>
  useAppSelector((state) => state.favorite);

export const { addFavorite } = favoriteSlice.actions;
export default favoriteSlice.reducer;

🛒 Scalable State Management

Using Redux slices ensures better modularity when adding new features.

Conclusion

By following this structured approach, we’ve successfully integrated Redux into Next.js 15 while keeping the architecture clean and scalable.

🔹 Key Takeaways:
✅ Use a dedicated MainProvider to wrap all global providers.
✅ Use a factory function for Redux store to allow future scalability.
✅ Create typed Redux hooks for better TypeScript support.
✅ Use useRef in ReduxProvider to prevent unnecessary reinitialization.

Now, Redux is seamlessly integrated into Next.js 15! 🚀

Previous Blogs You Might Find Useful

📌 Next.js 15 API Error Handling
📌 Zod Validation in Next.js 15

Using React Context API in Next.js 15 for Global State Management

Saiful Islam — Sun, 23 Feb 2025 14:21:02 +0000

In modern Next.js applications, state management is essential for maintaining global UI states like modals, sidebars, and theme toggles. While Redux and Zustand are powerful options, React Context API is a lightweight and built-in solution for simpler global states.

In this guide, we’ll build a global state manager in Next.js 15 using Context API and TypeScript, with a custom hook for seamless usage.

Step 1: Create a Context for Global State

We start by creating a StateContext to manage a simple open state (e.g., for a modal or sidebar):

📌 `StateContext.tsx`

"use client";
import { createContext, useCallback, useMemo, useState } from "react";

interface StateContextProps {
  open: boolean;
  handleSetOpen: VoidFunction;
}

const StateContext = createContext<StateContextProps | null>(null);

const StateContextProvider: React.FC<{ children: React.ReactNode }> = ({
  children,
}) => {
  const [open, setOpen] = useState<boolean>(false);

  const handleSetOpen = useCallback(() => setOpen((prev) => !prev), []);

  const contextValue = useMemo<StateContextProps>(
    () => ({ open, handleSetOpen }),
    [open, handleSetOpen]
  );

  return (
    <StateContext.Provider value={contextValue}>
      {children}
    </StateContext.Provider>
  );
};

export { StateContextProvider, StateContext };

🔹 Why This Works:
✅ Uses useCallback to optimize state updates.
✅ Uses useMemo to prevent unnecessary re-renders.
✅ Provides open and handleSetOpen globally.

Step 2: Create a Custom Hook for Accessing Context

Instead of using useContext(StateContext) every time, we create a custom hook to simplify access.

📌 `useStateData.tsx`

"use client";
import { StateContext } from "@/contexts/StateContext";
import { useContext } from "react";

export default function useStateData() {
  const context = useContext(StateContext);
  if (!context) {
    throw new Error("useStateData must be used within a StateContextProvider");
  }
  return context;
}

🔹 Why This is Useful:
✅ Encapsulates useContext to avoid repetitive code.
✅ Throws an error if used outside StateContextProvider.

Step 3: Implement Context in a Next.js 15 Application

Now, let’s use the context in a Next.js 15 component.

📌 `layout.tsx`

import { StateContextProvider } from "@/contexts/StateContext";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <StateContextProvider>{children}</StateContextProvider>
      </body>
    </html>
  );
}

✅ Ensures the context is available throughout the app.

Use the Context in a Component

📌 `ToggleButton.tsx`

"use client";
import useStateData from "@/hooks/useStateData";

export default function ToggleButton() {
  const { open, handleSetOpen } = useStateData();

  return (
    <button
      onClick={handleSetOpen}
      className="px-4 py-2 bg-blue-600 text-white rounded-md"
    >
      {open ? "Close Sidebar" : "Open Sidebar"}
    </button>
  );
}

📌 `Sidebar.tsx`

"use client";
import useStateData from "@/hooks/useStateData";

export default function Sidebar() {
  const { open } = useStateData();

  return (
    <aside
      className={`fixed top-0 left-0 h-full w-64 bg-gray-900 text-white transform ${
        open ? "translate-x-0" : "-translate-x-full"
      } transition-transform`}
    >
      <p className="p-4">Sidebar Content</p>
    </aside>
  );
}

Final Integration in a Page

📌 `page.tsx`

import ToggleButton from "@/components/ToggleButton";
import Sidebar from "@/components/Sidebar";

export default function HomePage() {
  return (
    <main className="flex flex-col items-center justify-center min-h-screen">
      <ToggleButton />
      <Sidebar />
    </main>
  );
}

✅ Now, clicking the button toggles the sidebar state globally!

Final Thoughts

🚀 Why Use Context API for Global UI State?
✅ Built into React – No need for external state libraries.
✅ Works perfectly in Next.js 15.
✅ Great for UI state like modals, sidebars, and themes.

Simplifying API Promise Handling in Next.js 15

Saiful Islam — Mon, 17 Feb 2025 06:57:38 +0000

In modern Next.js 15 applications, API routes often deal with asynchronous operations like database queries, authentication, and data fetching. Handling these properly requires structured error management to avoid unexpected crashes.

In our previous blogs, we built:

A structured API response helper → serverResponse Read here
A request body parser → getJsonBodyData Read here

Now, we’ll take it one step further by creating a universal API promise resolver to eliminate try-catch repetition across all API routes.

Why Use a Promise Resolver for API Routes?

❌ Without it, every API function needs a try-catch block, leading to redundant code.
❌ Error handling becomes inconsistent, making debugging harder.
❌ Missed edge cases might cause APIs to crash unexpectedly.

✅ With a reusable promise resolver, we centralize error handling, reduce boilerplate, and ensure clean API code.

Building the `serverAsyncResolve` Helper in Next.js 15

Step 1: Creating the Promise Resolver Function

Let’s build a universal try-catch wrapper for Next.js 15 API routes:

import type { NextResponse } from "next/server";
import serverResponse from "@/helpers/server-helper/serverResponse";
import type { ServerResponseType } from "@/types";

export default async function serverAsyncResolve<T>(
  asyncCallback: () => Promise<NextResponse<ServerResponseType<T>>>,
): Promise<NextResponse<ServerResponseType<T>>> {
  try {
    return await asyncCallback();
  } catch (err) {
    if (err instanceof Error) {
      switch (err.name) {
        default:
          return serverResponse({
            success: false,
            error: err.message,
            status: 500,
          });
      }
    }
    return serverResponse({
      success: false,
      error: "Something went wrong",
      status: 500,
    });
  }
}

🔹 This function wraps API logic inside a single async callback.
🔹 All errors are handled centrally, avoiding redundant try-catch blocks in multiple APIs.

Step 2: Using `serverAsyncResolve` in an API Route

Here’s an example of how to use it in a PUT request handler:

export async function PUT(req: Request) {
  return serverAsyncResolve(async () => {
    const body = await getJsonBodyData<LoginSchemaType>(req);

    return serverResponse({
      success: true,
      message: "Login successful",
      status: 200,
    });
  });
}

📌 Key Takeaways:
✔️ The API handler only focuses on business logic.
✔️ The async callback handles errors automatically.
✔️ The serverResponse function Read previous blog ensures consistent responses.

Benefits of This Approach

✅ Reduces boilerplate – No need to write try-catch in every API route.
✅ Improves error management – Centralized error handling ensures API stability.
✅ Enhances readability – API functions focus only on business logic.

By combining serverResponse, getJsonBodyData, and serverAsyncResolve, we ensure that API routes in Next.js 15 are structured, readable, and maintainable.

💡 Have you used a similar pattern in your API routes? Let me know in the comments!

Simplifying Request Body Handling in Next.js 15

Saiful Islam — Mon, 17 Feb 2025 06:25:58 +0000

When working with API routes in Next.js 15, handling different types of request payloads (JSON, FormData, and Raw text) can be frustrating. Developers often write repetitive code to extract data from req.json(), req.formData(), or req.text().

To simplify this process, we’ll create a set of utility functions that make request body handling more structured and error-proof. These functions will also integrate with the serverResponse function we built in our previous blog to maintain consistent API responses.

Why Use a Request Body Helper?

❌ Manually parsing request bodies in every API route leads to redundant code.
❌ Missing or invalid payloads can cause unexpected runtime errors.
❌ Inconsistent error messages make debugging difficult.

✅ With reusable helpers, we ensure cleaner code, standardized error handling, and better DX (Developer Experience).

Building the Request Body Helper in Next.js 15

Step 1: Creating the `ServerError` Class

First, let’s define a custom error class to handle different request body errors:

export class ServerError extends Error {
  constructor(message: string, name: string) {
    super(message);
    this.name = name;
  }
}

📌 This allows us to throw custom errors when request bodies are missing or invalid.

Step 2: Creating Utility Functions for Parsing Request Bodies

Now, we’ll write functions to handle different request body types.

import { ServerError } from "@/helpers/server-helper/ServerError";

export async function getJsonBodyData<T>(req: Request): Promise<T | null> {
  try {
    return req.json() as T | null;
  } catch {
    throw new ServerError("JSON Payload is required", "BodyError");
  }
}

export async function getFormData<T>(req: Request): Promise<T | null> {
  try {
    return req.formData() as T | null;
  } catch {
    throw new ServerError("FORM Payload is required", "BodyError");
  }
}

export async function getRawBody(req: Request): Promise<string> {
  try {
    return req.text();
  } catch {
    throw new ServerError("TEXT Payload is required", "BodyError");
  }
}

✅ Each function automatically throws an error if the required payload is missing or invalid.
✅ Works with TypeScript for better type safety.

Step 3: Integrating with the `serverResponse` Function

In our previous blog, we built a reusable serverResponse function to ensure consistent API responses. Now, let’s use it in an API route.

import serverResponse from "@/helpers/serverResponse";
import { getJsonBodyData } from "@/helpers/request-helper";

export async function POST(req: Request) {
  try {
    const body = await getJsonBodyData<{ email: string; password: string }>(req);

    if (!body || !body.email || !body.password) {
      return serverResponse({
        success: false,
        message: "Missing required fields",
        status: 400,
      });
    }

    // Simulated user creation
    const user = { id: 1, email: body.email };

    return serverResponse({
      success: true,
      message: "User created successfully",
      data: user,
      status: 201,
    });
  } catch (error) {
    return serverResponse({
      success: false,
      message: error instanceof ServerError ? error.message : "Internal Server Error",
      error: error.name || "UnknownError",
      status: 500,
    });
  }
}

📌 Now, all API routes will follow a structured error-handling pattern!

Conclusion

With this helper function setup:

✔️ Less boilerplate when handling request payloads.
✔️ Standardized error handling using ServerError.
✔️ Consistent API responses with serverResponse.

If you haven’t read the previous blog, I recommend checking it out first to see how serverResponse works!

💡 What’s your approach to handling API request payloads? Let me know in the comments!

DEV Community: Saiful Islam

useSearchNavigate: Type-Safe URL State Without the Drift

The Problem

The Mental Model

How to Use It

Setup

Pattern 1: Read the value in any child

Pattern 2: Paginate with an updater

Pattern 3: Reset paging and skip history

Pattern 4: Clearing a value removes it from the URL

Anti-pattern

When to Use It

How It Works Under the Hood

Conclusion

useDebouncedCallback: Debounce Without the Stale Closure

The Problem

The Mental Model

How to Use It

Search as the user types

Save a draft after the user pauses

Keep a listener subscribed once

Anti-pattern

When to Use It

How It Works Under the Hood

Conclusion

useCallbackRef: A Stable Callback That Never Goes Stale

The Problem

The Mental Model

How to Use It

Pattern 1: A timer that must survive every render

Pattern 2: A listener that outlives the render

Pattern 3: A callback handed to a non-React instance

Pattern 4: A stable prop for a memoized child

The one thing not to do

When to Use It

How It Works Under the Hood

1. useRef(callback) seeds the desk before the first shift

2. useMemo(…, []) makes the identity stable and allocates once

3. useEffect with no dependency array updates after paint

4. The read is deferred to call time

5. The constraint and the assertion

The timeline

Effect ordering

Cost

A note on server rendering

Compared to useEffectEvent

Conclusion

useAsRef: The Latest Value Without the Re-Subscribe

The Problem

The Mental Model

How to Use It

Pattern 1: A long-lived effect that needs current props

Pattern 2: Handing a callback to a non-React system

Pattern 3: A stable event handler that reads current values

Pattern 4: Read-then-write for back-to-back updates

The one thing not to do

When to Use It

How It Works Under the Hood

1. useRef<T>(props) — stable identity, seeded with the first value

2. useIsomorphicLayoutEffect — update after commit, before paint

3. Why not just assign during render?

4. Why the effect ordering matters

The timeline

Cost

A note on server rendering

Conclusion

Setting Up PostgreSQL with Docker Compose for Development and Production

1. Folder Structure

2. Custom PostgreSQL Configuration

3. Database Initialisation with init.sql

4. Development Compose File

5. Production Compose File

6. Running PostgreSQL with NPM Scripts

7. Conclusion

useSyncExternalStore in React — The Right Way to Subscribe to External Data

⚙️ What is useSyncExternalStore?

🧩 The Hook Signature

🧠 Why Not Just Use useEffect?

💻 Example: Tracking Online/Offline Status

🧩 How It Works

1. `useRef(callback)` seeds the desk before the first shift

2. `useMemo(…, [])` makes the identity stable and allocates once

3. `useEffect` with no dependency array updates after paint

Compared to `useEffectEvent`

1. `useRef<T>(props)` — stable identity, seeded with the first value

2. `useIsomorphicLayoutEffect` — update after commit, before paint

⚙️ What is `useSyncExternalStore`?

🧠 Why Not Just Use `useEffect`?

📁 `.lintstagedrc` Configuration

📁 `.commitlintrc.json` Configuration

1️⃣ Creating the Root Layout (`RootLayout.tsx`)

💡 Why use `MainProvider`?

2️⃣ Creating `MainProvider.tsx`

3️⃣ Setting Up `ReduxProvider.tsx`

✅ Why `useRef`?

4️⃣ Setting Up Redux Store (`store.ts`)

5️⃣ Creating Hooks for Redux (`redux.hooks.ts`)

6️⃣ Creating a Redux Slice (`favoriteSlice.ts`)

📌 `StateContext.tsx`

📌 `useStateData.tsx`

📌 `layout.tsx`

📌 `ToggleButton.tsx`

📌 `Sidebar.tsx`

📌 `page.tsx`

Building the `serverAsyncResolve` Helper in Next.js 15

Step 2: Using `serverAsyncResolve` in an API Route

Step 1: Creating the `ServerError` Class

Step 3: Integrating with the `serverResponse` Function