An isomorphic effect cannot exist.

[jungpaeng]

Describe the issue

A useIsomorphicLayoutEffect hook was added in PR #149.
This hook is designed to bypass the warning that occurs when using useLayoutEffect on the server, and instead run useLayoutEffect when the code is executed in the browser.

However, there's an important point that needs to be addressed here. If you look at the implementation of useIsomorphicLayoutEffect, you'll see that it attempts to use useEffect in server environments.
But React does not execute useEffect on the server at all — meaning that the fallback to useEffect is entirely unnecessary.

The core issue here is that the name isomorphic may give users the impression that the hook behaves identically across both the server and the client. In reality, this is not the case. The actual purpose of this hook is simply to suppress warnings during SSR (Server-Side Rendering).

Frankly, I would go as far as to call this kind of hook an anti-pattern.
Using useLayoutEffect in server environments can cause problems, and React issues a warning specifically to prevent this.

However, the name useIsomorphicLayoutEffect may mislead users into thinking it allows them to use useLayoutEffect without warning — when in reality, it's just being run in the browser, as usual.

Because of this, there is a growing sentiment in favor of using a more explicit hook like the following:

import { useLayoutEffect } from "react";

export function useClientLayoutEffect(
  ...args: Parameters<typeof useLayoutEffect>
) {
  if (typeof document === "undefined") return;

  useLayoutEffect(...args);
}

The code may require some adjustments in detail, but I trust the intent is clear.

I propose deprecating useIsomorphicLayoutEffect and introducing useClientLayoutEffect instead.

Additional context

The issue described here — the problems caused by useIsomorphicLayoutEffect — is explained in great detail in the article linked below.
If you're interested, I highly recommend giving it a read.

https://smoores.dev/post/no_such_thing_isomorphic_layout_effect/

[seungrodotlee]

Thanks for the explanation — I’ve reviewed it thoroughly!

I agree with what you said.
As you pointed out, useIsomorphicLayoutEffect doesn’t actually provide isomorphic behavior despite its name, and that can definitely cause confusion for users.

I also think it is a great idea to deprecate this hook and instead introduce a new one with a clearer name, like useClientLayoutEffect.
For users who are used to the conventional useIsomorphicLayoutEffect naming, we could still expose the same hook name, but include a deprecation notice that communicates the underlying issue and guides them toward using a more appropriately named alternative.

I’ll take care of this update and submit a PR within the week. Thanks again!

[jiji-hoon96]

Here's your translation

I was also considering this pattern for my implementation. After reviewing various approaches, I agree that we need a hook like useIsomorphicLayoutEffect to handle SSR/CSR differences.

However, since this behavior isn't truly isomorphic across environments (as effects don't run during SSR), I think useClientLayoutEffect might be a more accurate name. This name better communicates that it's designed for client-side layout effects with SSR compatibility.

I'm wondering though if typeof document !== 'undefined' or typeof document !== 'noop' is optimal for environment detection. This works in most cases, but are there edge cases we should consider? For example:

• Could there be environments where document exists but doesn't behave as expected?
• Would checking for typeof window !== 'undefined' or typeof window !== 'noop' or a more explicit server environment flag be more reliable?