DEV Community: Saeed Mosavat

React Hydration explained

Saeed Mosavat — Fri, 28 Jun 2024 16:27:37 +0000

If you are a frontend developer and have some experience with React, you may have heard the term "Hydration". In this article we will explore what it is, why we need it and how it works.

This is what the official react documentation says about hydration:

In React, “hydration” is how React “attaches” to existing HTML that was already rendered by React on a server environment. During hydration, React will attempt to attach event listeners to the existing markup and take over rendering the app on the client.

"React on the server", you may wonder! "Wasn't react a client-side thing?"
Well, not anymore. This is 2024 and we even have Server Components now (how crazy is that?!)

There is a lot of things going on in this definition that we will cover in this post. Let's start with why and how react is rendered on the server.

React on the server

Traditionally, a react application is a tiny HTML with a giant JavaScript including react code itself and the application code that uses react. when this JavaScript runs, it will populate the HTML with some meaningful and interactive content (our app).

<html>
  <head>
    <title>React App</title>
    <script src="the/giant/app.bundle.js" ></script>
  </head>
  <body>

    <div id="root"></div>

  </body>
</html>

We can send this tiny HTML to the users, their browser will download and run the JavaScript code, which will populate that "root" div element and then they'll have the running application. No matter what page the user is looking for, it can always start from the same HTML above. This is actually how Create React App works.

There are two things to consider:

Every time a user opens our website, they will see a blank page followed by a spinner for a while. The blank page is not surprising because we have sent them an empty HTML! But even after receiving that HTML, it takes some time to download the js files (still showing a blank page) and even when js files are downloaded and our application runs, it usually needs some data from the server to show the page content, so we show spinners while waiting for that data. It kinda sucks, right?
Humans are not the only users of our websites, robots are visiting too. Like the Google Bot.
But unfortunately, robots have more work to do than humans and they will not wait for our stupid spinners to finish. (Well actually sometimes they do, but they do it later in a "less busy" time and we don't want to rely on that).

So, in order to keep both humans and robots happy about our website, we should give them the real HTML they are looking for the moment they request a page. Just like the good old-fashioned websites. And since our application is rendered by react, we need a way to "pre-render" the app on the server to get that HTML.

For simplicity let's imagine our App only has one page (so we can ignore "routing" on the server) and this is the corresponding component:

const App = () => {
  const [product, setProduct] = useState(null);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    fetch("/product")
      .then((res) => res.json())
      .then((data) => setProduct(data))
      .finally(() => setIsLoading(false));
  }, []);

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return <div>{product.name}</div>;
};

So, we need to run our react App on the server to get the final HTML that the user wants to see and then return that HTML as the response to the clients request for the page.
React provides a renderToString method specifically for this purpose. All we have to do is to pass it the JSX element for the root of our App and get the rendered app as HTML. then we can send back this HTML to the client:

import { renderToString } from 'react-dom/server';

const html = renderToString(<App />);

But, there is a small problem. Our app calls an asynchronous API to fetch the data and render something meaningful. However, there is no way for react's renderToString method to know this logic and to know how much it should wait for the App to finish all data fetches and re-renders until the final meaningful content is rendered. So it just lets the app to render once and before executing any useEffects or re-renders, it returns the resulting HTML. Oops!

In our example the result will be something like this:

<html>
  <body>

    <div id="root">
       <div>Loading...</div>
    </div>

  </body>
</html>

This is obviously not desired. The solution to this is to provide the data that is needed for the App at the time we want to render the App. So we have to make some slight improvements:

const App = (props) => {
  const [product, setProduct] = useState(props.initialProduct);
  const isInitialized = !!props.initialProduct;
  const [isLoading, setIsLoading] = useState(!isInitialized);


  useEffect(() => {
    if(!isInitialized) {
      fetch("/product")
        .then((res) => res.json())
        .then((data) => setProduct(data))
        .finally(() => setIsLoading(false));
    }
  }, [isInitialized]);

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return <div>{product.name}</div>;
};

const response = await fetch("/product");
const data = await response.json();

const html = renderToString(<App initialProduct={data}/>);

And now we get the correct HTML that shows the product details.

Back to the client

So far the client has received the content-full HTML, along with the js files to run the react app. Robots are happy now, but it's not the case for our human users because React is not happy! When React loads, it tries to render the <App> and create something called "Virtual DOM" (just think of it as a copy of the page document, managed by react). Virtual DOM is the single source of truth for React and all its changes will be reflected on the browser DOM. so it has to make sure the browser DOM matches the virtual DOM to begin with. But in our example, react app has started with a loading state in the first render on the client (because here we don't have any value to pass to <App> as initialPrduct prop) while the browser DOM has the product details. React has to get rid of anything that it doesn't acknowledge in the document, so it removes the page and shows the loading state again! We are back to square one!

Dehydration to rescue

To address the above issue and prevent a loading state on the client and keeping the already fetched data on the page, we should somehow transfer the fetched data on the server to the client. This way the client has everything it needs to take over the rendering of the App that has started on the server.
What if We could send the server data in a JSON string alongside the rendered HTML. Let's assume the server has put this script in the HTML:

<script>
  window._data = '{ "id": 1, "name": "some product name" }';
</script>

We can then use it to bootstrap the app like this:

// index.jsx

const dataFromServer = JSON.parse(window._data);

ReactDOM.render(
  <App initialProduct={dataFromServer} />
  document.getElementById("root")
);

This process of sending the data required for hydration from server to client is called dehydrarion. Frameworks like Next.js handle this process seamlessly for you. You can inspect the window.__NEXT_DATA__.props object in the console of a Next.js website to see it in action.

Conclusion

In summary, hydration is a crucial process in React applications that allows for a seamless transition between server-rendered HTML and the fully interactive client-side application. By sending the necessary data alongside the initial HTML, we can avoid an unnecessary loading state on the client and ensure a smooth user experience. This approach improves initial load times, enhances SEO, and provides a more responsive application for users.

Stop writing API functions

Saeed Mosavat — Sat, 17 Sep 2022 23:22:15 +0000

If you are developing a front-end application which uses a back-end with RESTFUL APIs, then you have got to stop writing functions for each and every endpoint!

RESTFUL APIs usually give you a set of endpoints to perform CRUD (Create, Read, Update, Delete) actions on different entities. We usually have a function in our project for each of these endpoints and these functions do a very similar job, but for different entities. For example, let's say we have these functions:

// apis/users.js

// Create
export function createUser(userFormValues) {
  return fetch("/users", { method: "POST", body: userFormValues });
}

// Read
export function getListOfUsers(keyword) {
  return fetch(`/users?keyword=${keyword}`);
}

export function getUser(id) {
  return fetch(`/users/${id}`);
}


// Update
export function updateUser(id, userFormValues) {
  return fetch(`/users/${id}`, { method: "PUT", body: userFormValues });
}

// Destroy
export function removeUser(id) {
  return fetch(`/users/${id}`, { method: "DELETE" });
}

and a similar set of functions may exist for other entities like City, Product, Category, ... . However, we can replace all of these functions with a simple function call:

// apis/users.js
export const users = crudBuilder("/users");

// apis/cities.js
export const cities = crudBuilder("/regions/cities");

And then use it like this:

users.create(values);
users.show(1);
users.list("john");
users.update(values);
users.remove(1);

"But Why?" you may ask

Well, there are some good reasons for that:

It reduces the lines of code - code that you have to write and someone else has to maintain when you leave the company.
It enforces a naming convention for the API functions, which increases code readability and maintainability. You may have seen function names like getListOfUsers, getCities, getAllProducts, productIndex, fetchCategories etc. that all do the same thing: "get the list of an entity". With this approach you'll always have entityName.list() functions and everybody on your team knows that.

So, let's create that crudBuilder() function and then add some sugar to it.

A very simple CRUD builder

For the simple example above, the crudBuilder function would be so simple:

export function crudBuilder(baseRoute) {
  function list(keyword) {
    return fetch(`${baseRoute}?keyword=${keyword}`);
  }

  function show(id) {
    return fetch(`${baseRoute}/${id}`);
  }

  function create(formValues) {
    return fetch(baseRoute, { method: "POST", body: formValues });
  }

  function update(id, formValues) {
    return fetch(`${baseRoute}/${id}`, { method: "PUT", body: formValues });
  }

  function remove(id) {
    return fetch(`${baseRoute}/${id}`, { method: "DELETE" });
  }

  return {
    list,
    show,
    create,
    update,
    remove
  }
}

It assumes a convention for API paths and given a path prefix for an entity, it returns all the methods required to call CRUD actions on that entity.

But let's be honest, we know that a real-world application is not that simple! There are lots of thing to consider when applying this approach to our projects:

Filtering: list APIs usually get lots of filter parameters
Pagination: Lists are always paginated
Transformation: The API provided values may need some transformation before actually being used
Preparation: The formValues objects need some preparation before being sent to the API
Custom Endpoints: The endpoint for updating a specific item is not always `${baseRoute}/${id}`

So, we need a CRUD builder that can handle more complex situations.

The Advanced CRUD Builder

Let's build something that we can really use in our everyday projects by addressing the above issues.

Filtering

First, we should be able to handle more complicated filtering in out list function. Each entity list may have different filters and the user may have applied some of them. So, we can't have any assumption about the shape or values of applied filters, but we can assume that any list filtering can result in an object that specifies some values for different filter names. For example to filter some users we could have:

const filters = {
  keyword: "john",
  createdAt: new Date("2020-02-10"),
}

On the other hand, we don't know how these filters should be passed to the API, but we can assume (and have a contract with API providers) that each filter has a corresponding parameter in the list API which can be passed in the form of "key=value" URL query params.

So, we need to know how to transform the applied filters into their corresponding API parameters to create our list function. This can be done with passing a transformFilters parameter to the crudBuilder(). An example of that for users could be:

function transformUserFilters(filters) {
  const params = []
  if(filters.keyword) {
    params.push(`keyword=${filters.keyword}`;
  }
  if(filters.createdAt) {
    params.push(`created_at=${dateUtility.format(filters.createdAt)}`;
  }

  return params;
}

Now, we can use this parameter to create the list function.

export function crudBuilder(baseRoute, transformFilters) {
  function list(filters) {
    let params = transformFilters(filters)?.join("&");
    if(params) {
      params += "?"
    }
    return fetch(`${baseRoute}${params}`);
  }
}

Transformation and Pagination

The data received from the API may need some transformation before being usable in our app. For example we may need to transform the snake_case names to camelCase or to transform some date string into users timezone etc.
Also, we need to handle pagination.

Let's assume that all paginated data from APIs have the following shape (Standardized by the API provider):

{
  data: [], //list of entity objects
  pagination: {...}, // the pagination info
}

So all we need to know is how we should transform a single entity object. Then we can loop over the objects of the list to transform them. To do that, we need a transformEntity function as a parameter to our crudBuilder:

export function crudBuilder(baseRoute, transformFilters, transformEntity) {
  function list(filters) {
    const params = transformFilters(filters)?.join("&");
    return fetch(`${baseRoute}?${params}`)
      .then((res) => res.json())
      .then((res) => ({
        data: res.data.map((entity) => transformEntity(entity)),
        pagination: res.pagination,
      }));
  }
}

And we are done with the list() function.

Preparation

For create and update functions, we need to transform the formValues into the format that the API expects. For example, imagine we have a city select in our form that selects a City object. but the create API only needs the city_id. So, we would have a function that does something like this:

const prepareValue = formValues => ({city_id: formValues.city.id})

This function may return a plain object or a FormData depending on the use-case and can be used to pass data to API like:

export function crudBuilder(
  baseRoute,
  transformFilters,
  transformEntity,
  prepareFormValues
) {
  function create(formValues) {
    return fetch(baseRoute, {
      method: "POST",
      body: prepareFormValues(formValues),
    });
  }
}

Custom Endpoints

There are some rare situations that the API endpoint for some action on an entity doesn't follow the same convention. For example instead of having `/users/${id}` to edit a user, we have to use `/edit-user/${id}`. For these cases we should be able to specify a custom path.

Here, we allow the override of any path used in crud builder. Note that the paths for show, update and remove actions may depend on some info from the entity object, so we have to use a function and pass the entity object to get the path.

We need to get these custom paths in an object and fallback to our default paths if nothing specified. Something like:

const paths = {
  list: "list-of-users",
  show: (userId) => `users/with/id/${userId}`,
  create: "users/new",
  update: (user) => `users/update/${user.id}`,
  remove: (user) => `delete-user/${user.id}`
}

The Final CRUD Builder

This is the final code to create CRUD API functions.

export function crudBuilder(
  baseRoute,
  transformFilters,
  transformEntity,
  prepareFormValues,
  paths
) {

  function list(filters) {
    const path = paths.list || baseRoute;
    let params = transformFilters(filters)?.join("&");
    if(params) {
      params += "?"
    }
    return fetch(`${path}${params}`)
      .then((res) => res.json())
      .then((res) => ({
        data: res.data.map((entity) => transformEntity(entity)),
        pagination: res.pagination,
      }));
  }

  function show(id) {
    const path = paths.show?.(id) || `${baseRoute}/${id}`;

    return fetch(path)
      .then((res) => res.json())
      .then((res) => transformEntity(res));
  }

  function create(formValues) {
    const path = paths.create || baseRoute;

    return fetch(path, {
      method: "POST",
      body: prepareFormValues(formValues),
    });
  }

  function update(id, formValues) {
    const path = paths.update?.(id) || `${baseRoute}/${id}`;

    return fetch(path, { method: "PUT", body: formValues });
  }

  function remove(id) {
    const path = paths.remove?.(id) || `${baseRoute}/${id}`;

    return fetch(path, { method: "DELETE" });
  }

    return {
    list,
    show,
    create,
    update,
    remove
  }
}