How to support Reusable State in Effects

[bvaughn]

Note: We wrote a new page documenting this behavior in detail on the Beta website: https://beta.reactjs.org/learn/synchronizing-with-effects#how-to-handle-the-effect-firing-twice-in-development.

---

Hope this is helpful. Sorry some links from there are 404 because other pages are still being written.

Overview

If you have not yet read the previous post about changes to StrictMode, you can find it here.

Let’s start by taking a look at an example Component:

function ExampleComponent(props) {
  useEffect(() => {
    // Effect setup code...

    return () => {
      // Effect cleanup code...
    };
  }, []);

  useLayoutEffect(() => {
    // Layout effect setup code...

    return () => {
      // Layout effect cleanup code...
    };
  }, []);

  // Render stuff...
}

This component declares some effects to be run on mount and unmount. Normally these effects would only be run once (after the component is initially mounted) and the cleanup functions would be run once (after the component is unmounted). In React 18 Strict Mode, the following will happen:

• React renders the component.
• React mounts the component
  • Layout effect setup code runs.
  • Effect setup code runs.
• React simulates the component being hidden or unmounted.
  • Layout effect cleanup code runs
  • Effect cleanup code runs
• React simulates the component being shown again or remounted.
  • Layout effect setup code runs
  • Effect setup code runs

As long as an effect cleans up after itself (by returning a cleanup method when necessary) this should generally not cause problems. Most effects have at least one dependency. Because of this they are probably already resilient to running more than once and may not require any changes.

Effects that only run on mount will likely require changes though. At a high level, the types of effects that will mostly likely require some modification fall into two buckets:

• Effects that require cleanup when unmounting.
• Effects that should only run once (either on mount or when a dependency changes).

Effects that require cleanup should have symmetry.

Whether you’re adding event listeners or interacting with some imperative API– as a general rule, if an effect returns a cleanup function then it should mirror the setup function. Many components today use a variation of the pattern shown below.

// A Ref (or Memo) is used to init and cache some imperative API.
const ref = useRef(null);
  if (ref.current === null) {
  ref.current = new SomeImperativeThing();
}

// Note this could be useLayoutEffect too; same pattern.
useEffect(() => {
  const someImperativeThing = ref.current;
  return () => {
    // And an unmount effect (or layout effect) is used to destroy it.
    someImperativeThing.destroy();
  };
}, []);

If the code above gets unmounted and remounted, the imperative thing will likely be broken. (After all, it was destroyed after the first unmount.) To fix this, we need to (re)initialize the imperative thing on mount.

// Don't use a Ref to initialize SomeImperativeThing!

useEffect(() => {
  // Initialize an imperative API inside of the same effect that destroys it.
  // This way it will be recreated if the component gets remounted.
  const someImperativeThing = new SomeImperativeThing();

  return () => {
    someImperativeThing.destroy();
  };
}, []);

Sometimes other functions (like event handlers) also need to interact with the imperative thing. In that case, a ref can be used to share the value.

// Use a Ref to hold the value, but initialize it in an effect.
const ref = useRef(null);

useEffect(() => {
  // Initialize an imperative API inside of the same effect that destroys it.
  // This way it will be recreated if the component gets remounted.
  const someImperativeThing = ref.current = new SomeImperativeThing();

  return () => {
    someImperativeThing.destroy();
  };
}, []);

const handeThing = (event) => {
  const someImperativeThing = ref.current;
  // Now we can call methods on the imperative API...
};

Although not as common, the imperative API may also need to be shared with other components. In that case, a lazy initialization function can be used to expose the API.

// This ref holds the imperative thing.
// It should only be referenced by the current component.
const ref = useRef(null);

// This lazy init function ref can be shared with other components,
// although it should only be called from an effect or an event handler.
// It should not be called during render.
const getterRef = useRef(() => {
  if (ref.current === null) {
    ref.current = new SomeImperativeThing();
  }
  return ref.current;
});

useEffect(() => {
  // This component doesn't need to (re)create the imperative API.
  // Any code that needs it will do this automatically by calling the getter.

  return () => {
    // It's possible that nothing called the getter function,
    // in which case we don't have to cleanup the imperative code.
    if (ref.current !== null) {
      ref.current.destroy();
      ref.current = null;
    }
  };
}, []);

If you’re unsure about which of the above patterns to use for a particular component, ask us and we’ll help.

Effects that should only run once can use a ref.

Effects that do not require cleanup– even mount effects– might not require any changes to work with the new semantics. Let’s look at an effect that logs impressions to a server.

useEffect(() => {
  SomeTrackingAPI.logImpression();
}, []);

This effect is meant to log that a user has seen a particular piece of content. What should happen if the content is hidden and then shown again? Should it log a second impression? (That is what the effect would do today if switching tabs remounted the view.) Usually that's the behavior you want, so you don't need to change anything in the code above.

In the rare case where hiding and showing content again doesn't count as a new impression, we could use a ref.

const didLogRef = useRef(false);

useEffect(() => {
  // In this case, whether we are mounting or remounting,
  // we use a ref so that we only log an impression once.
  if (didLogRef.current === false) {
    didLogRef.current = true;

    SomeTrackingAPI.logImpression();
  }
}, []);

However, usually that is not needed.

The examples above don’t cover every case.

This note covers some of the most common high-level patterns but it’s not an exhaustive list. We plan to write about less common cases in the future. In the meanwhile, if you’re unsure of whether your effect should run more than once– or if your effect doesn’t match one of the patterns shown above– ask us and we’ll help.

Related posts

For more information on the changes to React 18 StrictMode, see:

• Adding StrictEffects to StrictMode
• Testing with Reusable State in StrictMode

[markerikson]

I actually think that the "strict effects" thing is going to be a much bigger breaking change in the ecosystem than Concurrency:

const didLogRef = useRef(false);

useEffect(() => {
  // In this case, whether we are mounting or remounting,
  // we use a ref so that we only log an impression once.
  if (didLogRef.current === false) {
    didLogRef.current = true;

    SomeTrackingAPI.logImpression();
  }
}, []);

We've all been trained for the last two years that useEffect(cb, []) is how we mimic cDM (yes, yes, I know "they're not the same thing!"), and how to fetch once on render.

if I'm reading these pages right:

• In prod, this would only run more than once if the component gets Suspense-hidden or similar
• But it's going to double-run inside of <StrictMode>
• And all the CRA templates and such come with <StrictMode> on by default

So, I foresee a lot of people getting confused at "why did my API call run twice?" here.

I almost see a need for an official useRunThisOnlyOnceOnMountNoKiddingIMeanIt() hook recipe that can be copy-pasted to do the ref+effect combination above

Also, as a side note, this initial code snippet seems odd:

const getterRef = useRef(() => {
  if (ref.current === null) {
    ref.current = new SomeImperativeThing();
  }
  return ref.current;
});

I was pretty sure that useRef doesn't take a callback per se, at least not in the "run this code" sense - it just does const ref = {current: initialValue}; internally ( per this line in ReactFiberHooks.js).

I think the hooks docs show doing that lazy init while rendering specifically, as the rare edge cases it's legal to mutate while rendering:

https://reactjs.org/docs/hooks-faq.html#how-to-create-expensive-objects-lazily

I assume that's the intended usage pattern here rather than a callback.

edit

Actually, maybe I misread what the "lazy init function" is here. Is it supposed to be something that's manually called elsewhere? I think I can sorta see how that pattern would work, just not something I'm used to seeing.

[TkDodo]

What causes the abort in the scenario you're describing? Is it user code? Some abstraction? RQ itself?

• react-query provides the AbortSignal
• the user forwards the AbortSignal to fetch
• react-query cancels the AbortSignal when the last observer unmounts
• fetch cancels the network request itself
• react-query reverts the query back to its previous state (idle)
• which then causes a new observer mount to trigger another state change (loading) + another fetch

so I guess - all of the above 😅

Here is a short reproduction with react-query v3.33.7 and react-18 in strict mode. You can see the two requests going out - the first one being cancelled.

https://codesandbox.io/s/query-cancellation-fk29h

[sebmarkbage]

I am not aware that you cannot cancel requests with http2?

Canceling can affect 1) whether a fetch is even sent in the first place, 2) it can stop things on the actual network from clogging the internet pipes, e.g. by canceling the TCP/IP connection or telling the server to stop sending data 3) cancel CPU work from processing the data when it gets back and issuing callbacks.

Often cancellation is just for the last 3rd step. That's similar to what we had before AbortSignal where people just do if (!canceled) doStuff(). It can be useful for Promises and a lot of code isn't well suited for prioritization but the React stack + postTask + priority hints etc. makes it possible to better ensure that this CPU doesn't interfere with higher priority. If it's properly prioritized there's no point in NOT doing this work if you might want to use it since you already have the data on device.

However, there can also be benefits to canceling over the network to avoid the network bandwidth being busy when you need it for other things. Ideally you can use prioritization here too and instead of cancelling you just lower the priority and then increase the priority later. There are proposals for this.

Requests first get added to a network queue. If the network is busy, it stays in this queue and then later gets sent. If you cancel the request before it gets to the end of the queue, you don't even issue the request. With HTTP/1.1 this was common because you're limited to 6 or so connections open per domain (for DDOS reasons). So if you already had a few requests to other content pending, you'd be queued and if you are able to cancel the request you ended up never paying for it.

You can also abort a request after it has been sent, but in practice the roundtrip to communicate that you need to close it takes too long so by the time you close it you already have the response. It is useful for very long running connections though.

The problem with HTTP2 is that you don't have to wait for a response to come back if you already have a connection open. You can send the request on a connection that is still waiting on other responses. This means that you're basically always able to send a request very early. The queue doesn't fill up. To close it, you'd need to tell the server that you don't need it anymore (RST_STREAM) but by the time the server gets the message, it might have already started sending it because of the latency of the roundtrip.

This makes aborting much less effective. It's still useful for very slow connections and servers but for most cases it doesn't work in practice. You're basically going to end up with the bytes on your machine eventually. So then the question becomes if you want to ignore those bytes that you already received or if you want to put them to good use.

[gaearon]

My described problem comes when the request is aborted via AbortSignal. I guess technically we could defer the aborting and wait a bit to see if a new observer mounts in the next couple of milliseconds, but I'm rather reluctant to add that just to account for strict effects.

So I think the core of our argument is that deferring is a good idea in general, not just for strict effects. Because, for example, if you switch between <A /> and <B />, both of which issue the same request, it can get reused even if the user uses the abort signal. Seb's point about the aborting not being as useful (or even desirable) in the future still applies. But seems like adding some e.g. 100ms delay would improve things in short term and also help strict effects be less surprising to your consumers.

[sebmarkbage]

Yea, I'd say that if your strategy builds on time based heuristics then it does make sense to extend it a bit.

Slight nit though. It's not the only possible solution. Our proposed built-in solution (for Suspense data) doesn't use a timer as the heuristic. Instead it uses an explicit boundary to define the Caching semantics for a whole subtree.

That avoids the problem because switching between <A /> and <B /> as opaque components would still share the same Cache if they're in the same subtree.

In theory you could build a similar orchestrator but it's not possible to integrate it with Suspense in user space and I haven't really seen that modeled in any existing library anyway.

[TkDodo]

Thank you for the great discussion, let's see how it plays out. I'm not against delaying query cancellation a bit, but since its an opt in feature, I'd probably wait and see if it is a big deal for users or not :)

[chantastic]

Thanks @bvaughn for documenting these common patterns for improving effects. I love seeing these use cases enumerated with increasing complexity.

I'm imagining landing on a doc like this while debugging some strict effects errors and it feels very approachable.

[jbachhardie]

So, if I'm reading this right effects might get fired and cleaned up multiple times but useRef values will still only ever initialised once? I can see that being another point of confusion for people in what is already maybe the most confusing part of React which is trying to coordinate with imperative things through a combination of refs and effects.

I feel like it would be useful to have an effect hook that triggered when the useRef value gets initialised and cleans up basically right before that ref value would get GCed (obviously it could not take any dependencies). This would be interesting for things like child components announcing their existence and non-existence through context to some parent which needs to keep a list of them to coordinate something (animation comes to mind as a place I've had to use this technique)

[gaearon]

That's the intent, yes.

[Skn0tt]

Sounds like you're describing how callback refs work?

This is the first time I've heard about callback refs. Is there a reason the docs why there's nothing in the docs about using this with function components? Especially for refs, it's non-obvious to me that it works so similar.

(might be worth moving to a separate thread).

[gaearon]

The docs are in need of a very serious rewrite, which is in progress now. I'll keep this in mind for it.

[gaearon]

I've tried to play around with the experimental release on the codesandbox ( https://codesandbox.io/s/practical-bose-5tfli?file=/src/App.js ) but I don't see "strict effects" being reexecuted at the moment at all. Is this already enabled in the latest experimental release? Note that callback ref is being reexecuted on Fast Refresh (rightfully so).

Good catch. This seems like an omission.

I started facebook/react#21590 with a fix but it's a UK holiday so I'll get back to it tomorrow.

[gaearon]

OK, the latest @next and @experimental have Strict Effects on in Strict Mode: https://codesandbox.io/s/gifted-darkness-o319o?file=/src/App.js. Thank you for flagging this.

[Andarist]

Sometimes other functions (like event handlers) also need to interact with the imperative thing. In that case, a ref can be used to share the value.

Example with getterRef is slightly confusing because it lacks some context how this should be used. I suspect how this could be used but I think this is a somewhat novelle pattern so a more full example would be appreciated. I don't think that passing "getters" through props is common nowadays, so it adds a new thing to the "what a prop can be" bag. I know that there is no real restriction in regards to what props can be and what they can't be but nevertheless there is a somewhat common understanding that props are usually plain values (or "resolved" ones), callbacks and, from time to time, refs. This makes the concept of props simple.

If you’re unsure about which of the above patterns to use for a particular component, ask us and we’ll help.

I wonder - shouldn't those patterns be provided by React itself? A lot of this complexity~ comes from the React model of hooks, render, and closures, which becomes a specific kind of programming that is not commonly seen in other fields/frameworks etc. I expect that this kind of thing makes the learning curve harder, both for newcomers and even for experienced developers. And if people just copy-paste those things into their projects they might easily lose the context behind those lines of codes after a while. I feel like this also makes it harder to quickly scan the code because more in-depth analysis is required to recognize something as being XYZ pattern and additional time should be spent to validate if that's "just" that or maybe if some additional code has been added to it.

[Andarist]

@rachelnabors do you have any links/materials that could be read on how this model relates to paradigms known in the mobile world? I'm really curious about this.

[rachelnabors]

@Andarist I don't have any one-to-one comparison articles in my back pocket, but have a look at how Android devs learn about state and composition/rendering: https://developer.android.com/jetpack/compose/lifecycle

This is much closer to how we'll be teaching how React renders UI trees from components in lockstep with state changes

[gaearon]

To be fair, Jetpack is fairly new. (Just like SwiftUI is.) I wouldn't say existing mobile devs are necessarily familiar with it.

[alvarlagerlof]

To be fair, Jetpack is fairly new.

To be clear to people coming here later. Jetpack is a suite of libraries. It has been out for a while. Compose is a declarative UI framework which is a part of Jetpack. Compose is still in beta.

[gaearon]

Oh I didn't know that, thanks for clarifying!

[wardpeet]

Is there already work ongoing to think about new eslint-rules to help developers guide away from these "broken" practices or is this a bit too soon?

as I read it correctly, don't do ref updates inside a render, always do them in a useEffect or ref function? As we could probably detect 90% of these use-cases pretty easily.

[wardpeet]

Yes but still possible. As a new developer, the hooks paradigm is new and you don't learn this in CS classes (at least I didn't) so the more tooling we have to help devs to move to "correct" patterns the better

[gaearon]

Is there already work ongoing to think about new eslint-rules

Maybe, though I personally haven't seen it. I think @bvaughn was working on a DEV warning for this but I'm not sure if we made a decision to add it or not.

It's a bit tricky because this pattern is legit:

const ref = useRef()
if (ref.current === undefined) {
  ref.current = ...
}

It's ok because it only gets initialized once. So you're not mutating something that anybody cares about yet.

[bvaughn]

I think @bvaughn was working on a DEV warning for this

Yup, see facebook/react/pull/18545. This warning hasn't been enabled for 18 yet (enableUseRefAccessWarning is still false). Not sure what our plans are here.

[Andarist]

as I read it correctly, don't do ref updates inside a render, always do them in a useEffect or ref function?

If I understand this correctly then updating refs in event handlers is also OK (just mentioning for completeness)

[bvaughn]

That's correct, @Andarist. Event handlers are safe places to update refs and/or to schedule state updates.

[markerikson]

original comment moved to its own question:

• How do we help the community better understand "side effects" and consequences beyond "rules"?

[gaearon]

This seems like it could be a separate Q&A since it's unrelated to Strict Effects?

[markerikson]

Done!

[eps1lon]

"auto focus" and subsequent restore focus

We have a modal component that, when closed, returns focus to the element that had focus before focus moved into the modal. Since we have arbitrary children i.e. we don't know which element will receive focus (when the modal is opened) we capture the element that should have its focus restored on close via event.relatedTarget in the first focus event we register.

Minimal implementation

function Modal({ children }) {
  const restoreFocus = React.useRef(null);

  function handleFocus(event) {
    if (restoreFocus.current === null) {
      restoreFocus.current = event.relatedTarget;
    }
  }

  React.useEffect(() => {
    return () => {
      if (restoreFocus.current !== null) {
        restoreFocus.current.focus();
        restoreFocus.current = null;
      }
    };
  }, []);

  return <div onFocus={handleFocus}>{children}</div>;
}

This works in React 17. However, it only works in React 18 with Strict Effects when focus moved into the modal in an effect. When focus moves into the modal via autoFocus attribute, Strict Effects will run the cleanup function thus restoring focus but not move focus back into the modal.

I've created a codesandbox that illustrates the problem space with a naive implementation for autoFocus, layout effect and passive effect: https://codesandbox.io/s/react-18-autofocus-with-strict-effects-xfyp0?file=/src/index.js

There may be other attributes that trigger side-effects suffering from similar problems.

[Sardor-M]

Thanks for your answer, i was getting confused of whether it works in older version of React 17 or not. It was helpful for me :)

[Andarist]

I didn't think about this for a while since I'm not using this project on a daily basis nowadays. But once upon a time, I was actively using Redux-Saga. When hooks were released we got requests from people to expose some kind of useSaga hook - we never did it, we have shared some proof of concepts on codesandbox etc but nothing official has been published.

I think though that the idea itself was quite neat and it resurfaced in my mind recently because a new maintainer has volunteered to help with the project. I don't think implementing this is now quite possible though (or at least not without serious drawbacks.

The problem is that Redux Saga is heavily-based on generators (but the same problem, even worse, applies to async functions) - those are inherently stateful and can't easily be restarted/put in the same state.

Generators are actually quite neat in the sense that they put the calling "runtime" in charge of the execution so we could store all resolved values in memory and "reexecute" them later in a pure fashion to put the generator in the same "state" (in an event sourcing fashion, sort of) but, let's be honest, this isn't a good solution as it potentially has some serious memory implications.

So the only other solution that can be used is to force the user to include the "rehydration" logic in the saga's code - that has scalability and readability problems though.

Is this my real-world problem? Not quite. But I don't think that it's entirely unreasonable to discard this as a thing that some people would like to use. This is just one of the examples for which the "reusable state" becomes a problem and is limiting, potentially putting some constraints on the users because this particular thing just can't be abstracted away and hidden in a library.

Do I have a good example of when this could actually be useful? I think I do:

function EmbeddableCheckout() {
  const [state, dispatch] = useSaga(checkoutProcess)
  // ...
}

The checkout process can have multiple steps, trying to tame concurrency problems, race conditions, and all. Perhaps one could make an argument that such a checkout process should support "reusable state" from the beginning because one can refresh a page and ideally they should get back to the same state. It's not always possible to handle all of the things perfectly though - either because there is not enough time to do so or because there are some technical limitations around that. In a lot of situation the "reusable state" might also come from the backend and that initial request that checks the state might be part of the checkout process itself. It's a different problem than being able to reuse "reusable state" after the application already gets past that initial state of the process.

[Andarist]

This old demo might not showcase the full power of the pattern but it already shows how you can leverage a generator to get an implicit state machine and how you can start stateful tasks in it (a race job in this example).

Keeping the iterator in the state/ref allows us to cover part of the requirements. The "runtime" capable of executing the generator would need to understand how to restart particular async jobs (like this race), this is at least a smaller problem than "full restart".

However, one thing that we can't do with that... is a proper cleanup. Usually, the way to dispose of stuff is to call iterator.return() at the end and allow the generator to implement its specific cleanup and react to this in its finally block. We can't do that with strict effects though as that "progresses" the iterator so it wouldn't be usable when the next useEffect kicks in. There is a lack of symmetry between start & stop - with a ref we can make sure to only "start" something once but as far as I know there is no way to do the symmetric thing: to only "stop" something once.

[gaearon]

Awesome, thanks for the demo. I'll add it to a list of follow-ups to revisit and get clarity on.

[the-spyke]

The title says about reusable state, but only mentions how not to break with the new behavior. How to make your external state reusable after a re-mount if you clean it on unmount? It also should relate not only Sagas/generators, but just anything not stored in the component's state.

But it is probably hackable:

• Add useRef to get a persistent object ref acting as a key for your generator or whatever external storage you have
• Put the generator into a WeakMap using the key weakMap.set(ref, saga)
• And also register the generator in a FinalizationRegistry for a cleanup later
• To access the generator you will do weakMap.get(ref)

The ref stays in place between re-mounts, so the generator lives. When React decides to give up on the state, ref will be GCed and the generator will become eligible too. The FinalizationRegistry will call the cleanup callback and cleanup the saga.

[Andarist]

That's a clever workaround! but the timing of the cleanup call becomes unpredictable and not all engines support FinalizationRegistry

[the-spyke]

Yeah, that's why I called it a hack. I guess for a proper way to "fix" this you need to introduce some kind of a useLifecycleStage() to distinguish between various stages:

const stage = useLifecycleStage();

useEffect(() => {
  switch (state) {
    case LifecycleStage.INIT: return initSaga();
    case LifecycleStage.MOUNT: // ...
    case LifecycleStage.UNMOUNT: // ...
    case LifecycleStage.FINILIZE: return cancelSaga();
    default: return subscribe();
  }
}, [stage]);

But that means a double render on removal. To overcome this you might introduce

useInitFinilize(() => {
  // init...
  return () => cancelSaga()
});

But now there're multiple effect functions.

[denisso]

i write this example This solution is adapted to the new behavior of strict mode and react fast refresh. The solution is based on the fact that after the unmount simulation, a mount simulation will be performed, with the effects running again. Effects that have started more than once after unmounting will be launched. Every unmount, the effects trigger counter is reset to zero. Effects are identified by the name that is passed in the effect method.