Then your code hits production. A field from the API endpoint comes back as null instead of a string. You were expecting an array, and it comes back as undefined, expecting an object and receiving a number. Suddenly, you're faced with an error screen, a crashed UI, or worse, silent data corruption that nobody notices until a user complains.

This is a common and preventable bug in JavaScript development. The fix doesn't require a third-party library or a complete architecture overhaul. It requires a small set of utility functions and the discipline to use them when needed.

This article shows you how to build a resilient application using four TypeScript guard utilities that'll make your codebase more reliable: safeArray, safeString, safeNumber, and safeObject. The utilities are framework-agnostic, so whether you're working in React, plain JavaScript, or anything in between, you can drop them straight into your codebase.

Table of Contents

• The Problem

• Why This Problem Exists

• The Solution: Safe Access Utilities

• How Each Utility Works

• How to Use Them in Practice

• Best Practices

• Things to Avoid

• Bonus: Combine Them into a safeData Helper

• Conclusion

Prerequisites

Before diving in, you should have:

• A working knowledge of TypeScript. You don't need to be an expert, but you should be comfortable with types, interfaces, and generics

• Familiarity with JavaScript and its built-in type-checking methods, like typeof and Array.isArray.

The Problem

JavaScript is a loosely typed language. It will let you call .map() on something that isn't an array, access properties on null, and do arithmetic with NaN. All of this, without throwing an error until it's too late. The language doesn't push back. It just breaks quietly.

TypeScript helps, but only up to a point. It checks types at compile time, not at runtime. So when external data arrives from an API, a form submission, local storage, or a third-party SDK, TypeScript has already left the building. Whatever your interface says, the actual value at runtime is whatever JavaScript received.

Here's what that looks like in practice:

// This looks fine. It is not fine.
type User = {
  id: number;
  name: string;
  tags: string[];
};

function displayUser(user: User) {
  const upperName = user.name.toUpperCase();
  const tagList = user.tags.map((tag) => `#${tag}`);
  return { upperName, tagList };
}

If user.name comes back as null, calling .toUpperCase() crashes your application. If user.tags is undefined, calling .map() crashes your application, too. Both scenarios are entirely possible when you're consuming a real API, and TypeScript won't warn you because you told it to trust the type.

Wait! I hear you saying, "I can use optional chaining to stop my app from crashing". This is correct, like the example below:

// This looks better. But...
type User = {
  id: number;
  name: string;
  tags: string[];
};

function displayUser(user: User) {
  const upperName = user?.name?.toUpperCase?.();
  const tagList = (user?.tags || [])?.map((tag) => `#${tag}`); 
  return { upperName, tagList };
}

But there are issues with the above approach. Firstly, upperName will return undefined if user.name isn't a string. Secondly, the user?.tag || [] guards for undefined and null values alone. What if an object gets returned? {...}?.map(...)? Do you see the real issue now?

So user?.name?.toUpperCase?.() safely handles cases where user, name, or even toUpperCase itself might not exist. This is handy when dealing with uncertain data shapes, but it doesn't handle data mismatch.

Why This Problem Exists

The blame sits squarely with JavaScript's type system, or rather, its lack of one.

JavaScript has a handful of primitive types and a few rules that seem reasonable until you look at them closely. For example, typeof null returns "object", typeof [] also returns "object", and typeof NaN returns "number". These aren't edge cases. They're the language.

Here's a quick illustration of how easily JavaScript misleads you:

typeof null;        // "object" — not "null"
typeof [];          // "object" — not "array"
typeof NaN;         // "number" — NaN is technically a number
Array.isArray([]);  // true — this is the correct check
isNaN("hello");     // true — because "hello" coerces to NaN
Number.isNaN("hello"); // false — this is the correct check

TypeScript layers a static type system on top of this, catching many mistakes before your code runs. But static analysis only works on code you've already written. The moment data crosses the network boundary or comes from localStorage, a URL parameter, a third-party script, or any source outside your codebase, TypeScript's guarantees stop.

When you write something like this:

const data = await response.json() as User;

You're not validating anything. You're telling the TypeScript compiler, "I promise this is a User" . The compiler accepts that promise and stops checking. But if the API returns null for a field, sends a string where you expected a number, or omits a property entirely, JavaScript will proceed anyway and your code will break at the first operation that assumes otherwise.

This gap between "what TypeScript thinks the data is" and "what the data actually is at runtime" is where most production data bugs live. The fix is to stop trusting the type assertion and start validating the data yourself.

The Solution: Safe Access Utilities

The fix is to validate data at the boundary. The moment the expected data enters your application, check it before you pass it anywhere else.

These four functions do exactly that:

export function safeArray<T>(prop: unknown): T[] {
  if (Array.isArray(prop)) {
    return prop as T[];
  } else {
    return [] as T[];
  }
}

export function safeString(prop: unknown, fallback = ""): string {
  if (typeof prop === "string") {
    return prop;
  } else {
    return fallback;
  }
}

export function safeNumber(prop: unknown, fallback = 0): number {
  if (typeof prop === "number" && !isNaN(prop)) {
    return prop;
  } else {
    return fallback;
  }
}

export function safeObject<T extends object>(
  prop: unknown,
  fallback = {} as T,
): T {
  if (prop !== null && typeof prop === "object" && !Array.isArray(prop)) {
    return prop as T;
  }
  return fallback;
}

Each function accepts unknown, which forces you to validate the value before using it. Each one returns a safe default if the input isn't what you expected. No crashes, no silent undefined, and no cryptic runtime errors.

You can drop these into any JavaScript or TypeScript project: React app, a Node.js API, a vanilla TypeScript module, or wherever you're handling external data.

How Each Utility Works

safeArray

export function safeArray<T>(prop: unknown): T[] {
  if (Array.isArray(prop)) {
    return prop as T[];
  } else {
    return [] as T[];
  }
}

This checks whether prop is actually an array using Array.isArray. If it is, you get it back typed as T[]. If it's anything other than an array like null, undefined, a string, or whatever, you get back an empty array.

This matters because of the JavaScript quirk you saw above: typeof [] returns "object", which means a naive typeof check wouldn't catch this. Array.isArray handles it correctly.

safeString

export function safeString(prop: unknown, fallback = ""): string {
  if (typeof prop === "string") {
    return prop;
  } else {
    return fallback;
  }
}

This function uses typeof to confirm that the value is a string. The optional fallback parameter lets you specify a meaningful default. For example, "Unknown" instead of an empty string, when displaying a user's name.

safeNumber

export function safeNumber(prop: unknown, fallback = 0): number {
  if (typeof prop === "number" && !isNaN(prop)) {
    return prop;
  } else {
    return fallback;
  }
}

The key detail here is !isNaN(prop). Because typeof NaN === "number" is true in JavaScript, skipping this check means you could return NaN and cause downstream calculation failures. This function guards against that.

safeObject

export function safeObject<T extends object>(
  prop: unknown,
  fallback = {} as T,
): T {
  if (prop !== null && typeof prop === "object" && !Array.isArray(prop)) {
    return prop as T;
  }
  return fallback;
}

This one requires three conditions due to JavaScript's quirks. typeof null === "object" is true. typeof [] === "object" is also true. So this function explicitly excludes both. What you get back is guaranteed to be a plain object and nothing else.

How to Use Them in Practice

Normalising API Responses (Plain TypeScript)

The best place to use these utilities is in the function that processes your API response before the data reaches any other part of your application. This works the same way, whether in a React app, a Node.js service, or a plain TypeScript module.

// lib/users.ts
import { safeArray, safeString, safeNumber, safeObject } from "@/utils/safe";

type User = {
  id: number;
  name: string;
  email: string;
  tags: string[];
};

function normaliseUser(raw: unknown): User {
  const obj = safeObject<Record<string, unknown>>(raw);

  return {
    id: safeNumber(obj.id),
    name: safeString(obj.name, "Unknown User"),
    email: safeString(obj.email),
    tags: safeArray<string>(obj.tags),
  };
}

async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  const data = await response.json();
  return normaliseUser(data);
}

By the time your code receives the User object, every field is guaranteed to be the type you declared. Nothing downstream has to wonder whether name might be null or tags might be undefined.

In a React Component (Defensive Rendering)

Sometimes you receive data directly in a component, from props, context, or a query result, and you don't control normalisation upstream. In that case, wrap the values at the point of use.

import { safeArray, safeString, safeNumber, safeObject } from "@/utils/safe";

type ProductProps = {
  product: unknown;
};

function ProductCard({ product }: ProductProps) {
  const p = safeObject<Record<string, unknown>>(product);
  const name = safeString(p.name, "Unnamed Product");
  const price = safeNumber(p.price);
  const tags = safeArray<string>(p.tags);

  return (
    <div className="product-card">
      <h3>{name}</h3>
      <p>${price.toFixed(2)}</p>
      <ul>
        {tags.map((tag) => (
          <li key={tag}>{tag}</li>
        ))}
      </ul>
    </div>
  );
}

Even if product arrives as null or a completely unexpected shape, this component will render a fallback state instead of crashing.

With React Query

If you're using React Query, you can normalise data inside the select option, which transforms the raw API response before it reaches your component.

import { useQuery } from "@tanstack/react-query";
import { safeArray, safeString, safeNumber, safeObject } from "@/utils/safe";

type Order = {
  id: number;
  status: string;
  total: number;
  items: string[];
};

function normaliseOrder(raw: unknown): Order {
  const obj = safeObject<Record<string, unknown>>(raw);
  return {
    id: safeNumber(obj.id),
    status: safeString(obj.status, "pending"),
    total: safeNumber(obj.total),
    items: safeArray<string>(obj.items),
  };
}

function useOrder(orderId: string) {
  return useQuery({
    queryKey: ["order", orderId],
    queryFn: () =>
      fetch(`/api/orders/${orderId}`).then((res) => res.json()),
    select: normaliseOrder,
  });
}

The select callback runs after the query resolves and before the data is cached. Your useOrder hook always returns a properly shaped Order, regardless of what the API actually sent back.

With a React Context Provider

Context is a place where unsafe data can silently propagate through your entire component tree. Normalise it at the provider level so every consumer is protected.

import { createContext, useContext, useEffect, useState } from "react";
import { safeArray, safeString, safeObject } from "@/utils/safe";

type AppConfig = {
  theme: string;
  features: string[];
};

const defaultConfig: AppConfig = {
  theme: "light",
  features: [],
};

const ConfigContext = createContext<AppConfig>(defaultConfig);

function ConfigProvider({ children }: { children: React.ReactNode }) {
  const [config, setConfig] = useState<AppConfig>(defaultConfig);

  useEffect(() => {
    fetch("/api/config")
      .then((res) => res.json())
      .then((raw: unknown) => {
        const obj = safeObject<Record<string, unknown>>(raw);
        setConfig({
          theme: safeString(obj.theme, "light"),
          features: safeArray<string>(obj.features),
        });
      });
  }, []);

  return (
    <ConfigContext.Provider value={config}>{children}</ConfigContext.Provider>
  );
}

export function useConfig() {
  return useContext(ConfigContext);
}

One normalisation step at the provider level protects every component that consumes the context.

In a Node.js API Route

These utilities are just as useful on the backend. If your Node.js API receives a request body, you can't trust that the client sent what you expected. Validate it at the point of entry.

// routes/orders.ts (Express)
import { safeArray, safeString, safeNumber, safeObject } from "../utils/safe";

type OrderPayload = {
  userId: number;
  notes: string;
  itemIds: number[];
};

function parseOrderPayload(raw: unknown): OrderPayload {
  const obj = safeObject<Record<string, unknown>>(raw);
  return {
    userId: safeNumber(obj.userId),
    notes: safeString(obj.notes),
    itemIds: safeArray<number>(obj.itemIds),
  };
}

app.post("/orders", (req, res) => {
  const payload = parseOrderPayload(req.body);

  if (!payload.userId) {
    return res.status(400).json({ error: "userId is required" });
  }

  // proceed with validated payload
});

The same four utilities, the same pattern. Just a different runtime environment.

Best Practices

As with anything, there are some best practices that'll help you use these utilities well and correctly.

First, normalise at the boundary, not inside every function. The best place to call these utilities is in your data-fetching layer, API handlers, or integration points, just once, before the data spreads. If you're calling safeString in five different places for the same field, that's a sign the normalisation belongs upstream.

Second, use meaningful fallbacks. The default fallbacks (empty string, 0, empty array, and empty object) are safe, but sometimes misleading. For a user's display name, safeString(name, "Anonymous") is more informative than safeString(name). Think about what makes sense for each field in your domain.

Third, keep your type definitions honest. If a field can realistically be null or undefined from your data source, reflect that in your types and use these utilities to handle it. Typing a field as string when it might be null just papers over the problem. These utilities work best when your types reflect the reality of what you receive.

Finally, create a normalisation module. Put all your normaliser functions in one place, for example, src/lib/normalise.ts. This keeps the defensive logic centralised, easy to test, and out of your application logic.

Things to Avoid

Likewise, there are some practices you should avoid.

First, don't use these utilities as a substitute for a proper data contract. If your entire codebase is wrapping every value in safeString because your data sources are wildly inconsistent, the real fix is a contract, an OpenAPI spec, a shared schema, Zod validation, or at minimum, documented response shapes. These utilities handle edge cases and runtime surprises, not systemic chaos.

Second, don't skip the safeObject wrapper. It's tempting to cast straight to any and access properties directly. Avoid this. The as any cast defeats TypeScript entirely, and accessing properties on an unknown value will cause a compile error anyway. Use safeObject to unwrap the value first, then access its fields safely.

Next, don't chain these utilities without extracting intermediate values. Something like safeString(safeArray(raw)[0]) might seem compact, but it's harder to read and debug. Extract intermediate values into clearly named variables instead.

And finally, don't skip validation just because you control the data source. "I wrote the API, so I know what it returns" is a reasonable position right up until a schema migration, a nullable column addition, or an unconsidered edge case proves otherwise. Trust the utilities, not your memory.

Bonus: Combine Them into a safeData Helper

If you find yourself calling all four utilities together frequently, which you will once you start normalising API responses consistently, you can compose them into a single fluent helper.

// utils/safeData.ts
import { safeArray, safeString, safeNumber, safeObject } from "./safe";

type SafeDataAccessors = {
  string: (key: string, fallback?: string) => string;
  number: (key: string, fallback?: number) => number;
  array: <T>(key: string) => T[];
  object: <T extends object>(key: string, fallback?: T) => T;
};

export function safeData(raw: unknown): SafeDataAccessors {
  const obj = safeObject<Record<string, unknown>>(raw);

  return {
    string: (key, fallback = "") => safeString(obj[key], fallback),
    number: (key, fallback = 0) => safeNumber(obj[key], fallback),
    array: <T>(key: string) => safeArray<T>(obj[key]),
    object: <T extends object>(key: string, fallback = {} as T) =>
      safeObject<T>(obj[key], fallback),
  };
}

Your normalisation functions then read cleanly, whether you're in a React hook, an Express route, or anywhere else:

import { safeData } from "@/utils/safeData";

function normaliseUser(raw: unknown) {
  const d = safeData(raw);
  return {
    id: d.number("id"),
    name: d.string("name", "Unknown User"),
    email: d.string("email"),
    tags: d.array<string>("tags"),
  };
}

This is a thin abstraction: no magic, just less repetition. Use it if your normalisation functions are getting verbose. Skip it if the direct utility calls are clear enough for your team.

Conclusion

JavaScript's loose type system and TypeScript's compile-time-only guarantees leave a gap at every data boundary. External data — from APIs, request bodies, local storage, third-party scripts — arrives at runtime with no guarantee it matches the shape you declared. These four utilities close that gap.

safeArray, safeString, safeNumber, and safeObject each accept unknown, validate the actual type, and return a safe fallback if the value isn't what you expected. They work in React components, Node.js routes, custom hooks, context providers, and any other JavaScript or TypeScript context where data enters your application.

The pattern is simple: validate at the boundary, trust inside. Normalise your data once, at the point it enters your codebase, and everything downstream can focus on its actual job instead of defending against bad inputs.

And the main difficulty isn’t necessarily what went wrong – it’s pinpointing where it went wrong.

React offers powerful ways to change state, but it doesn’t specify who or what caused those changes. In large apps with many layers of components, hooks, and contexts, this lack of insight can turn simple bugs into frustrating, time-consuming puzzles.

This is where more innovative debugging methods become crucial. Before now, the go-to solution was to sprinkle console.log calls at key points or to fall back to DevTools.

But these days, you can write a small but powerful utility function that can catch the criminal involved in the crimes against your codebase. This utility function can log changes, display meaningful stack traces, and work smoothly with useState, useReducer, Context providers, and custom hooks. And all of the above can occur while remaining invisible in production.

This article guides you through how to use this helper function to improve clarity, minimise guesswork, and debug efficiently without affecting performance or code cleanliness in your live environment.

Table of Contents

• The Problem

• Why This Problem Exists

• My Solution: createDebugSetter

  • Practical Examples of createDebugSetter

• Best Practices for using createDebugSetter

• Things to Avoid

• Bonus: How to Convert createDebugSetter to a Hook

• Conclusion

The Problem

React’s state system is powerful, but it hides too much information when something goes wrong – for example, when an unexpected update happens or a component re-renders endlessly. React doesn’t tell you what triggered the update, what changed, or why it happened. This lack of visibility creates several challenges.

The first is that you can’t easily see which component, function, or effect initiated a state update. In large applications, where the same state may be modified from multiple places, this quickly turns debugging into guesswork. Without clear traces, developers often sprinkle console.log throughout their code to find the source of a single update.

Secondly, React lacks a built-in method for directly comparing previous and current values. This complicates diagnosing whether a bug stems from an incorrect calculation, a faulty API response, or erroneous business logic. The challenge increases with nested objects, arrays, or shared context.

Thirdly, Context updates can trigger re-renders across the entire tree, even for components wrapped in memoisation. But React doesn’t explain why a particular provider changed, leaving teams to wonder what triggered the cascade.

Finally, infinite loops caused by effects, unstable dependencies, or repeated setState calls provide no clues in the console. You only see symptoms like “loading…” repeating endlessly, with no indication of the source.

All of this makes debugging complex React apps frustrating, slow, and often misleading without additional tools or structured techniques.

Why This Problem Exists

React intentionally conceals its internal update process to keep the framework fast and predictable.

Because of this:

• setState() doesn’t report where it was called from

• Context re-renders can originate from anywhere.

• State overrides can happen silently.

• Debugging often relies on manually adding console logs.

In large applications, this lack of visibility makes it nearly impossible to trace unexpected state changes.

My Solution: createDebugSetter

A small helper function, createDebugSetter, wraps your state setter and logs:

• The label of the state

• The new value

• A complete stack trace showing exactly where the update originated

And best of all, it automatically disables itself in production using NODE_ENV so there’s no impact on your live app.

createDebugSetter

export function createDebugSetter(
  label: string,
  setter:
    | React.Dispatch<React.SetStateAction<unknown>>
    | React.Dispatch<unknown>
): React.Dispatch<React.SetStateAction<unknown>> | React.Dispatch<unknown> {
  // In production, return the original setter unchanged
  if (import.meta.env.PROD /* vite-react */) {
    return setter;
  }

  // Create a wrapper that logs before calling the original setter
  return (value: React.SetStateAction<unknown> | unknown) => {
    // Log the state change
    console.groupCollapsed(
      `%c🔄 [${label}] State Update`,
      "color: #adad01; font-weight: bold;"
    );
    console.log("🆕 New value:", value);
    console.trace("📍 Update triggered from:");
    console.groupEnd();

    // Call the original setter
    setter(value);
  };
}

The function above is a debugging wrapper for React state setters that logs during development.

It takes two parameters: a label for identification and the setState function you want to debug. In development mode, every state update triggers a collapsible console log that shows the new value and the stack trace of the update's origin. In production, the hook skips entirely and returns the original setter unchanged, ensuring zero runtime overhead in deployed applications.

How it does it:

 // In production, return the original setter unchanged
  if (import.meta.env.PROD /* vite-react */) {
    return setter;
  }

In production, the createDebugSetter function returns the React setState as-is. This is because we don’t want to log anything when our code is running in a production environment. Here, we’re using the import.meta.env.PROD from React-vite. It returns a Boolean value that tells us if it’s in the production environment or not.

If it’s not in production, we return the modified setter below.

// Create a wrapper that logs before calling the original setter
  return (value: React.SetStateAction<unknown> | unknown) => {
    // Log the state change
    console.groupCollapsed(
      `%c🔄 [${label}] State Update`,
      "color: #adad01; font-weight: bold;"
    );
    console.log("🆕 New value:", value);
    console.trace("📍 Update triggered from:");
    console.groupEnd();

    // Call the original setter
    setter(value);
  };

This new setter function first logs a collapsible console group with the label and emoji. Then it shows the new value being set. After that, it displays a stack trace showing where the update was triggered. Lastly, it calls the original setter to actually update the state.

Practical Examples of createDebugSetter

Let’s now see how createDebugSetter can be used in several places within a codebase.

Context Providers

You can use createDebugSetter within a Context provider to log state changes when setState is called. This can help log and trace state changes whenever setState is called in a Context Provider anywhere in the application.

import { createContext, useContext, useState, type ReactNode } from "react";
import { createDebugSetter } from "../utils/createDebugSetter";

interface User {
  name: string;
  email: string;
  role: string;
}

interface UserContextType {
  user: User | null;
  setUser: React.Dispatch<React.SetStateAction<User | null>>;
  login: (name: string, email: string) => void;
  logout: () => void;
}

const UserContext = createContext<UserContextType | undefined>(undefined);

export function UserProvider({ children }: { children: ReactNode }) {
  const [user, setUserOriginal] = useState<User | null>(null);

  // Wrap setter with debug functionality
  const setUser = createDebugSetter(
    "UserContext",
    setUserOriginal
  ) as React.Dispatch<React.SetStateAction<User | null>>;

  const login = (name: string, email: string) => {
    setUser({
      name,
      email,
      role: "user",
    });
  };

  const logout = () => {
    setUser(null);
  };

  return (
    <UserContext.Provider value={{ user, setUser, login, logout }}>
      {children}
    </UserContext.Provider>
  );
}

In the above code sample, we create a modified setUserOriginal called setUser that uses createDebugSetter under the hood. We then expose it to the context value instead of setUserOriginal .

Whenever setUser is called, it triggers createDebugSetter which does its job of checking the environment the code is running in, and returns a modified setter that will call setUserOriginal after the logging process, or will return setUserOriginal as-is.

This is useful because Context updates can trigger many re-renders. This reveals exactly who changed the shared state.

useState

As you saw in the Context provider example above, we can use the same technique in regular components that use React state setters (just as in Context providers). We log and trace the value. It also shows where it was triggered from within the component or application.

import { useState } from "react";
import { useDebugSetter } from "../hooks/useDebugSetter";

export function UseStateExample() {
  const [count, setCountOriginal] = useState(0);
  const [name, setNameOriginal] = useState("React");

  // Wrap setters with debug functionality
  const setCount = useDebugSetter("Counter", setCountOriginal);
  const setName = useDebugSetter("Name", setNameOriginal);

  const handleIncrement = () => {
    setCount(count + 1);
  };

  const handleDecrement = () => {
    setCount(count - 1);
  };

  const handleNameChange = () => {
    setName(name === "React" ? "Vite" : "React");
  };

  return (
    <div
      style={{
        padding: "20px",
        border: "1px solid #ccc",
        borderRadius: "8px",
        margin: "10px",
      }}
    >
      <h2>useState Example</h2>
      <p>Open the console to see debug logs when state changes.</p>

      <div style={{ marginTop: "15px" }}>
        <p>
          Count: <strong>{count}</strong>
        </p>
        <button onClick={handleIncrement} style={{ marginRight: "10px" }}>
          Increment
        </button>
        <button onClick={handleDecrement}>Decrement</button>
      </div>

      <div style={{ marginTop: "15px" }}>
        <p>
          Name: <strong>{name}</strong>
        </p>
        <button onClick={handleNameChange}>Toggle Name</button>
      </div>
    </div>
  );
}

This works exactly like the Context providers example. The only differences are that the component uses the setCount and setName functions out of the box in buttons and related components. Also, unlike the Context provider, this component has local state that can be passed to its child components if needed.

This is ideal for monitoring unforeseen local state changes or loops triggered by effects.

useReducer

React reducers are used to calculate complex logic before updating the state. This can introduce unwanted side effects during the complex phase. createDebugSetter can help in debugging, as shown below:

import { useReducer } from "react";
import { createDebugSetter } from "../utils/createDebugSetter";

interface CounterState {
  count: number;
  step: number;
}

type CounterAction =
  | { type: "increment" }
  | { type: "decrement" }
  | { type: "reset" }
  | { type: "setStep"; step: number };

function counterReducer(
  state: CounterState,
  action: CounterAction
): CounterState {
  switch (action.type) {
    case "increment":
      return { ...state, count: state.count + state.step };
    case "decrement":
      return { ...state, count: state.count - state.step };
    case "reset":
      return { ...state, count: 0 };
    case "setStep":
      return { ...state, step: action.step };
    default:
      return state;
  }
}

export function UseReducerExample() {
  const [state, dispatchOriginal] = useReducer(counterReducer, {
    count: 0,
    step: 1,
  });

  // Wrap dispatch with debug functionality
  const dispatch = createDebugSetter("CounterReducer", dispatchOriginal);

  return (
    <div
      style={{
        padding: "20px",
        border: "1px solid #ccc",
        borderRadius: "8px",
        margin: "10px",
      }}
    >
      <h2>useReducer Example</h2>
      <p>Open the console to see debug logs for reducer actions.</p>

      <div style={{ marginTop: "15px" }}>
        <p>
          Count: <strong>{state.count}</strong>
        </p>
        <p>
          Step: <strong>{state.step}</strong>
        </p>

        <div style={{ marginTop: "10px" }}>
          <button
            onClick={() => dispatch({ type: "increment" })}
            style={{ marginRight: "10px" }}
          >
            Increment (+{state.step})
          </button>
          <button
            onClick={() => dispatch({ type: "decrement" })}
            style={{ marginRight: "10px" }}
          >
            Decrement (-{state.step})
          </button>
          <button
            onClick={() => dispatch({ type: "reset" })}
            style={{ marginRight: "10px" }}
          >
            Reset
          </button>
          <button
            onClick={() =>
              dispatch({ type: "setStep", step: state.step === 1 ? 5 : 1 })
            }
          >
            Toggle Step ({state.step === 1 ? "1→5" : "5→1"})
          </button>
        </div>
      </div>
    </div>
  );
}

dispatchOriginal, which is the main dispatch function, is replaced with a custom function called dispatch that uses createDebugSetter. When the custom dispatch function is called, it does the job of createDebugSetter and by extension, the job of dispatchOriginal .

This is perfect for logging reducer actions and understanding complex state transitions.

Custom Hooks

Custom hooks are not left out of the equation, as they can use setState in some cases. They’re also capable of running complex logic that could backfire when updating state.

import { useState, useEffect } from "react";
import { useDebugSetter } from "../hooks/useDebugSetter";

// Custom hook that manages a timer
function useTimer(initialSeconds: number = 0) {
  const [seconds, setSecondsOriginal] = useState(initialSeconds);
  const [isRunning, setIsRunningOriginal] = useState(false);

  // Wrap setters with debug functionality
  const setSeconds = useDebugSetter("Timer.seconds", setSecondsOriginal);
  const setIsRunning = useDebugSetter("Timer.isRunning", setIsRunningOriginal);

  useEffect(() => {
    if (!isRunning) return;

    const interval = setInterval(() => {
      setSeconds((prev) => prev + 1);
    }, 1000);

    return () => clearInterval(interval);
  }, [isRunning, setSeconds]);

  const start = () => setIsRunning(true);
  const stop = () => setIsRunning(false);
  const reset = () => {
    setSeconds(0);
    setIsRunning(false);
  };

  return {
    seconds,
    isRunning,
    start,
    stop,
    reset,
  };
}

export function CustomHookExample() {
  const timer = useTimer(0);

  const formatTime = (seconds: number) => {
    const mins = Math.floor(seconds / 60);
    const secs = seconds % 60;
    return `${mins.toString().padStart(2, "0")}:${secs
      .toString()
      .padStart(2, "0")}`;
  };

  return (
    <div
      style={{
        padding: "20px",
        border: "1px solid #ccc",
        borderRadius: "8px",
        margin: "10px",
      }}
    >
      <h2>Custom Hook Example</h2>
      <p>Open the console to see debug logs for internal hook state changes.</p>

      <div style={{ marginTop: "15px" }}>
        <p style={{ fontSize: "24px", fontWeight: "bold" }}>
          {formatTime(timer.seconds)}
        </p>
        <p>
          Status: <strong>{timer.isRunning ? "Running" : "Stopped"}</strong>
        </p>

        <div style={{ marginTop: "15px" }}>
          <button
            onClick={timer.start}
            disabled={timer.isRunning}
            style={{ marginRight: "10px" }}
          >
            Start
          </button>
          <button
            onClick={timer.stop}
            disabled={!timer.isRunning}
            style={{ marginRight: "10px" }}
          >
            Stop
          </button>
          <button onClick={timer.reset}>Reset</button>
        </div>
      </div>
    </div>
  );
}

As shown in previous examples, setSecondsOriginal and setIsRunningOriginal are replaced with setSeconds and setIsRunning. The latter uses the createDebugSetter helper function. This enables console log statements to be printed every second for better visualisation.

Custom hooks often hide multiple internal updates, making it hard to see exactly where each begins.

Best Practices for Using createDebugSetter

When using helper functions like createDebugSetter, it’s best to keep in mind why you’re actually using them. For our purpose here, we’re using it to debug a React application. So I’ll share some tips that will help with this debugging process.

Use Clear Labels

Using labels that can say where createDebugSetter was triggered from is a step in the right direction. Detailed labels will help you better understand where and why the issue may be occurring. Also, keep in mind that the createDebugSetter utility function could be used in several places in your application, and improper labelling could make debugging difficult.

Using the name of the component or area that calls it as the label for createDebugSetter can also be a good pointer for clear labelling, as shown below.

// Bad
createDebugSetter("aaa", setUser)
createDebugSetter("1", setUser)

// Good 
createDebugSetter("UserContextProvider", setUser)
createDebugSetter("From UserContextProvider", setUser)
// Too long but can still work
createDebugSetter("From UserContextProvider in user-context.tsx file", setUser)

Use createDebugSetter Only in Dev Mode

Using createDebugSetter only in a development environment can prevent many headaches. It’s not a good practice to mistakenly expose or log sensitive data in production. Also, logging in production can cause cluttering.

Use createDebugSetter with React DevTools

The createDebugSetter may not be enough for some complex bugs. You can use createDebugSetter and React DevTools for a more powerful/thorough debugging session. Although createDebugSetter cannot be directly integrated with React DevTools, it shows who triggered the update, whereas React DevTools displays what was re-rendered.

Place createDebugSetter in utils

createDebugSetter is a utility function, as I have mentioned above. This means you should place it in a utils folder so any team member can access and use it when needed across your React application.

Things to Avoid

1. Avoid using debug setters in production builds. While they are safe, unnecessary logs can slow down debugging tools. Also, sensitive credentials could be logged mistakenly. There are professional tools you can use, such as Sentry, that let you trace errors and debug your app effortlessly.

2. Don’t conditionally wrap setter functions within components. Perform wrapping outside renders to prevent the creation of new setter identities.

3. Don’t rely on it to replace proper state architecture. This tool helps identify issues, but doesn’t fix poor state design.

4. Don’t depend solely on console logs. Use it as part of a broader debugging workflow, not as the only strategy.

Bonus: How to Convert createDebugSetter to a Hook

Converting to a Hook

The plain createDebugSetter function works, but it creates a new wrapper function on every render when used inside React components. By converting it into a custom hook with useCallback, we can ensure that the wrapper function maintains a stable reference across re-renders, preventing unnecessary performance overhead and making it safe to use in dependency arrays.

Here’s the hook version:

import { useCallback } from "react";

export function useDebugSetter<T>(
  label: string,
  setState: React.Dispatch<React.SetStateAction<T>>
): React.Dispatch<React.SetStateAction<T>> {
  const debugSetter = useCallback(
    (newValue: React.SetStateAction<T>) => {
      // Only log in development
      if (!import.meta.env.PROD) {
        console.groupCollapsed(
          `%c🔄 State Update: ${label}`,
          "color: #2fa; font-weight: bold;"
        );
        console.log("🆕 New value:", newValue);
        console.trace("📍 Update triggered from:");
        console.groupEnd();
      }

      setState(newValue);
    },
    [label, setState]
  );

  // In production, return the original setter (no wrapping overhead)
  // In development, return the debug wrapper
  return import.meta.env.PROD ? setState : debugSetter;
}

How the Hook Version Works

The core difference between the useDebugSetter hook and createDebugSetter is that the function is wrapped in a useCallback that logs debug information before calling the original setter. Apart from this, all other components of the functions remain the same.

Why the Hook Version is Better

The hook version is superior for component usage because it leverages useCallback memoisation of the debug wrapper. This means the function reference stays the same across renders, avoiding potential re-render cascades when the setter is passed to child components or used in useEffect dependencies.

The plain function, by contrast, generates a brand new wrapper on every render, which can break React's optimisation strategies and cause subtle bugs. In production, both versions simply return the original setter, so there's no performance difference there – but in development, the hook prevents unnecessary work.

When to Use the Hook

Use useDebugSetter whenever you're inside a React component and need to debug state updates. This covers the vast majority of cases: wrapping useState setters, passing debug setters to child components, or including them in effect dependencies.

Only reach for the plain createDebugSetter function when you're working outside React components entirely, such as in utility modules, global stores, or configuration files where hooks can't be used. For day-to-day component debugging, the hook is the right choice.

Conclusion

Debugging React state doesn’t have to be guesswork. With a simple helper, you can instantly see what changed, who changed it, where the change originated, and how your app reached that state – all without touching your production environment.

This small utility function can save hours spent searching through your codebase, making you faster, more precise, and more confident in your React application’s behaviour.

Once you adopt this approach, you’ll never debug state the old way again. 🚀