My 5 favourite updates from the new React documentation

So you read the article title and are probably asking yourself “How can she possibly have a favourite thing about tech docs?” Or, you read the new React docs and are with me in saying that they are an awesome response to a much needed revamp!

React has come a long way over the last 10 years and the framework has undergone some major changes in the way it works. The legacy docs didn’t favour new developers who had to learn React twice - once with class components and then once again with Hooks. The new docs teach modern React and have a much better structure with more interactive examples, opinions and a better colour scheme (imo 😂). There are a lot of changes so, I wanted to outline my favourite things and why:

1. RIP Class Components

To start, I was very happy to see the recommendation to deprecate the use of class components and shift the focus to Functional components.

The reason being, Class components introduced complexity due to their verbose syntax and the need to understand concepts like this and lifecycle methods (e.g componentDidMount). Functional components, however, can be more performant because they don't carry the overhead of class instances. Furthermore, functional components are much easier to test as they are more predictable and have fewer side effects compared to class components (and we all love anything thats easier to test 😉)

Even though I’m sure most of you were probably already using functional components, the new docs offer a great guide on how to migrate.

Here you can see a basic example in practice:

Class component

Functional component

2. Destructuring Props

Another recommendation that comes hand-in-hand with the deprecation of class components is advice on how to pass props. Previously, this.props was how you accessed all of the properties passed to a component. Even though this can still be used, as it is Javascript, the use of this can be ambiguous. Especially, when dealing with functional components, where this doesn't refer to the component instance.

I'm very glad to see the docs recommending destructuring of props! Even though destructuring was released in ES6 there was no mention of it in the legacy docs, despite many developers preference when reading props.

As you can see, in the example below, it's more readable and allows you to only pass the required props instead of passing the entire parent props object.

Old documentation

New documentation

3. Getting hooked in

The old documentation introduced hooks but it didn't emphasise their importance or encourage developers to adopt them as the primary way to manage state and side effects in React applications. Additionally, it assumed you were coming from a “background of class components” and focused on teaching hooks assuming you were migrating. Now, with its own dedicated section the new docs really highlight the benefits of hooks to promote code reuse, modularisation, and better separation of logic.

Im also grateful for the whole dedicated section to the proper use of the useEffect hook. The hook has tripped me up many times because when not handled correctly it can lead to memory leaks and other unexpected behaviour.

For example, a memory leak I’ve seen when using useEffect is when a component subscribes to an event, but fails to unsubscribe when the component is “unmounted”.

The code snippet below shows an example with a websocket. If you don't unsubscribe from the WebSocket's onmessage, even when the component is unmounted, the WebSocket connection will continue to receive and handle messages, even though the component is no longer in use. Over time, this can lead to a buildup of unnecessary connections and event handlers, consuming memory and potentially causing performance issues.

useEffect(() => {
  const ws = new WebSocket('wss://example.com');
  ws.onmessage = (event) => {
    // handle message
  };

  // useEffect hook cleanup function that unsubscribes from the WebSocket's onmessage event

  return () => {
    ws.close();
  };
}, []);

The new docs explain how to avoid performance issues like unnecessary re-renders and infinite loops. They also address one of the common mistakes developers make, which is forgetting to clean up any side effects.

4. Some Context on Context API

Previously, in the legacy docs, the Context API was just one of the topics within the Advanced guides. Unless you went digging, you wouldn't have been introduced to it as one of the core ways to handle deep passing of data. I really like that, in the new docs, Context is recommended as a way to manage state as its one of the best ways to avoid prop drilling.

The power of the Context API is that it is one of the only ways to manage state within React without an external library such as Redux or MobX. So if context isn’t new, you might ask, what about the new docs makes me happy? Well, developers like me who may have been using it as my state management tool for smaller projects, won’t be met with as much resistance, as now it is recommended as one of the use cases.

I also really appreciate the example of how to use the useReducer hook with the Context API as the previous docs didn’t have an example on how to handle complex state logic.

Tip: When implementing the context API, it's good practice to create your own hook to use the context. This is demonstrated below:

Context.js

export const useMyContext = () => useContext(MyContext);

Component.js

const { myData } = useMyContext();

5. A new way to create and build

Finally, I’m so thankful to see the updated docs recommend common production-grade frameworks including Next.js, Remix, Gatsby, and Expo as the best way to build for React.

The old docs had no opinion on using a framework and recommended create-react-app as the best place to start, even though this isn’t being actively maintained. The new docs appreciate that React is community driven and its great to see them supporting these popular community frameworks.

This recommendation of frameworks, particularly Next.js (which allows you to build server-side-rendered React applications with ease) comes coupled with a dedicated docs section for Server APIs. This is awesome to see as SSR offers several benefits over client-side rendering, such as increased performance, better search engine optimization (SEO), and improved user experience and there is definitely a trend in SSR React apps. Even though the framework most likely calls these APIs for us, it’s great to see the detailed explanation.

I may be a little biased in putting this particular point as 4 years ago I had helped build a website with JS disabled in the browser and I really struggled to find documentation on the intricacies of how React and Next.js worked under the hood. If only I had the new docs then 😂!

Summary

Thank-you for reading, I hope you found this useful! Congratulations to the React team, they have done a great job with the docs. I know they are looking for feedback through their survey and issue tracker, but I’d also love to hear your thoughts on the new docs and let me know what your favourite features are in the comments below 👇