DEV Community: Johannes Kettmann

Path To A Clean(er) React Architecture (Part 8) - How Does React-Query Fit Into The Picture?

Johannes Kettmann — Fri, 19 Jul 2024 10:32:25 +0000

The unopinionated nature of React is a two-edged sword:

On the one hand, you get freedom of choice.
On the other hand, many projects end up with a custom and often messy architecture.

This article is the eigth part of a series about software architecture and React apps where we take a code base with lots of bad practices and refactor it step by step.

Previously,

we created the initial API layer and extracted fetch functions
added data transformations
separated domain entities and DTOs
introduced infrastructure services using dependency injection and
separated business logic and domain logic from the components.

This helped us in isolating our UI code from the server, make business logic independent of the UI framework, and increase testability.

But we didn’t introduce one of the most important tools in production react apps yet: react-query or another server state management library.

That’s the topic of this article.

Problematic code example 1: Manually managing server data
1. The problem: Boilerplate & state management
2. The solution: Creating a react-query hook
Problematic code example #2: Business logic and react-query
1. The problem: Duplicate requests
2. The solution: Using react-query data and mutations
Next Refactoring Steps

Before we start a quick side note: I won’t go through the setup of react-query nor will I explain its features in detail. I assume you’re familiar with that. If not you can use the docs or one of the many tutorials out there.

Also if you haven’t read the other articles of this series I recommend doing so before you continue.

Problematic code example 1: Manually managing server data

Let’s have a look at a problematic code example. Here’s a component that fetches the currently signed-in user and renders a form in a dialog that allows the user to reply to a message (aka shout).

You can find the complete source code including all changes here.

import { useEffect, useState } from "react";

import { isAuthenticated as isUserAuthenticated } from "@/domain/me";
import UserService from "@/infrastructure/user";

...

export function ReplyDialog({
  recipientHandle,
  children,
  shoutId,
}: ReplyDialogProps) {
  const [open, setOpen] = useState(false);
  const [isLoading, setIsLoading] = useState(true);
  const [isAuthenticated, setIsAuthenticated] = useState(false);
  const [hasError, setHasError] = useState(false);

  ...

  useEffect(() => {
    UserService.getMe()
      .then(isUserAuthenticated)
      .then(setIsAuthenticated)
      .catch(() => setHasError(true))
      .finally(() => setIsLoading(false));
  }, []);

  if (hasError || !isAuthenticated) {
    return <LoginDialog>{children}</LoginDialog>;
  }

  async function handleSubmit(event: React.FormEvent<ReplyForm>) {
      // we'll look at this code later 
  }

  return (
    <Dialog open={open} onOpenChange={setOpen}>
      {/* the rest of the component */}
    </Dialog>
  );
}

The problem: Boilerplate & state management

If you ever used react-query you probably know the problem.

We manually manage the loading and error state which leads to boilerplate code.
At the same time, we don’t even cache the API response which will lead to duplicate API requests.

These are just two things that react-query can help us with.

The solution: Creating a react-query hook

Here’s the query hook that we can replace the useEffect with.

import { useQuery } from "@tanstack/react-query";

import UserService from "@/infrastructure/user";

export function getQueryKey() {
  return ["me"];
}

export function useGetMe() {
  return useQuery({
    queryKey: getQueryKey(),
    queryFn: () => UserService.getMe(),
  });
}

The query function calls the UserService (created in an earlier article) that returns the transformed API responses instead of the DTOs. Anyway, that doesn’t matter much here.

Now, we can simply use the new query hook instead of the useEffect in the component.

import { useState } from "react";

import { useGetMe } from "@/application/queries/get-me";
import { useReplyToShout } from "@/application/reply-to-shout";
import { isAuthenticated } from "@/domain/me";

...

export function ReplyDialog({
  recipientHandle,
  children,
  shoutId,
}: ReplyDialogProps) {
    const [open, setOpen] = useState(false);
  const [isLoading, setIsLoading] = useState(true);
  const [replyError, setReplyError] = useState<string>();
  const replyToShout = useReplyToShout();
  const me = useGetMe();

  if (me.isError || !isAuthenticated(me.data)) {
    return <LoginDialog>{children}</LoginDialog>;
  }

  async function handleSubmit(event: React.FormEvent<ReplyForm>) {
    // we'll look at this code in a bit 
  }

  return (
    <Dialog open={open} onOpenChange={setOpen}>
      {/* the rest of the component */}
    </Dialog>
  );
}

We not only got rid of a lot of boilerplate code like the error and loading state handling. We also get response caching, retries, and a lot more features out of the box.

To summarize, we use the query hook as sort of proxy between the component and the service layer.

Ok, this was a pretty simple example. But what about something more complex?

Problematic code example #2: Business logic and react-query

In the previous code examples we didn’t look at the submit handler. Here it is:


import { useReplyToShout } from "@/application/reply-to-shout";

...

export function ReplyDialog({
  recipientHandle,
  children,
  shoutId,
}: ReplyDialogProps) {
    ...

    const replyToShout = useReplyToShout();

  async function handleSubmit(event: React.FormEvent<ReplyForm>) {
    event.preventDefault();
    setIsLoading(true);

    const message = event.currentTarget.elements.message.value;
    const files = Array.from(event.currentTarget.elements.image.files ?? []);

    const result = await replyToShout({
      recipientHandle,
      message,
      files,
      shoutId,
    });

    if (result.error) {
      setReplyError(result.error);
    } else {
      setOpen(false);
    }
    setIsLoading(false);
  }

  return (
    <Dialog open={open} onOpenChange={setOpen}>
      {/* the rest of the component */}
    </Dialog>
  );
}

In a previous article, we extracted a bunch of business logic from the submit handler into the useReplyToShout function highlighted above.

Currently, the useReplyToShout hook provides a couple of services functions to the replyToShout function by dependency injection.

import { useCallback } from "react";

import { hasExceededShoutLimit } from "@/domain/me";
import { hasBlockedUser } from "@/domain/user";
import MediaService from "@/infrastructure/media";
import ShoutService from "@/infrastructure/shout";
import UserService from "@/infrastructure/user";

...

const dependencies = {
  getMe: UserService.getMe,
  getUser: UserService.getUser,
  saveImage: MediaService.saveImage,
  createShout: ShoutService.createShout,
  createReply: ShoutService.createReply,
};

export async function replyToShout(
  { recipientHandle, shoutId, message, files }: ReplyToShoutInput,
  { getMe, getUser, saveImage, createReply, createShout }: typeof dependencies
) {
  const me = await getMe();
  if (hasExceededShoutLimit(me)) {
    return { error: ErrorMessages.TooManyShouts };
  }

  const recipient = await getUser(recipientHandle);
  if (!recipient) {
    return { error: ErrorMessages.RecipientNotFound };
  }
  if (hasBlockedUser(recipient, me.id)) {
    return { error: ErrorMessages.AuthorBlockedByRecipient };
  }

  try {
    let image;
    if (files?.length) {
      image = await saveImage(files[0]);
    }

    const newShout = await createShout({
      message,
      imageId: image?.id,
    });

    await createReply({
      shoutId,
      replyId: newShout.id,
    });

    return { error: undefined };
  } catch {
    return { error: ErrorMessages.UnknownError };
  }
}

export function useReplyToShout() {
  return useCallback(
    (input: ReplyToShoutInput) => replyToShout(input, dependencies),
    []
  );
}

The problem: Duplicate requests

The replyToShout function sends multiple API requests. Among them calls to UserService.getMe(...) and UserService.getUser(...). But this data has already been fetched in other parts of the app and thus exists in the react-query cache.

Additionally, we again have to manage the loading state manually.

The solution: Using react-query data and mutations

In the previous example we already introduced a query hook useGetMe. Now let’s add another one to get a user based on their handle.

import { useQuery } from "@tanstack/react-query";

import UserService from "@/infrastructure/user";

interface GetUserInput {
  handle?: string;
}

export function getQueryKey(handle?: string) {
  return ["user", handle];
}

export function useGetUser({ handle }: GetUserInput) {
  return useQuery({
    queryKey: getQueryKey(handle),
    queryFn: () => UserService.getUser(handle),
  });
}

Then we create the required mutation hooks. Here an example hook that creates a shout.

import { useMutation } from "@tanstack/react-query";

import ShoutService from "@/infrastructure/shout";

interface CreateShoutInput {
  message: string;
  imageId?: string;
}

export function useCreateShout() {
  return useMutation({
    mutationFn: (input: CreateShoutInput) => ShoutService.createShout(input),
  });
}

Now we can use these hooks inside the useReplyToShout hook.

As a first step, we replace the dependencies object by a TypeScript interface and adjust the replyToShout function accordingly.

import { Me, hasExceededShoutLimit, isAuthenticated } from "@/domain/me";
import { Image } from "@/domain/media";
import { Shout } from "@/domain/shout";
import { User, hasBlockedUser } from "@/domain/user";

import { useCreateShout } from "../mutations/create-shout";
import { useCreateShoutReply } from "../mutations/create-shout-reply";
import { useSaveImage } from "../mutations/save-image";
import { useGetMe } from "../queries/get-me";
import { useGetUser } from "../queries/get-user";

...

interface Dependencies {
  me: ReturnType<typeof useGetMe>["data"];
  recipient: ReturnType<typeof useGetUser>["data"];
  saveImage: ReturnType<typeof useSaveImage>["mutateAsync"];
  createShout: ReturnType<typeof useCreateShout>["mutateAsync"];
  createReply: ReturnType<typeof useCreateShoutReply>["mutateAsync"];
}

export async function replyToShout(
  { shoutId, message, files }: ReplyToShoutInput,
  { me, recipient, saveImage, createReply, createShout }: Dependencies
) {
  if (!isAuthenticated(me)) {
    return { error: ErrorMessages.NotAuthenticated };
  }
  if (hasExceededShoutLimit(me)) {
    return { error: ErrorMessages.TooManyShouts };
  }

  if (!recipient) {
    return { error: ErrorMessages.RecipientNotFound };
  }
  if (hasBlockedUser(recipient, me.id)) {
    return { error: ErrorMessages.AuthorBlockedByRecipient };
  }

  try {
    let image;
    if (files?.length) {
      image = await saveImage(files[0]);
    }

    const newShout = await createShout({
      message,
      imageId: image?.id,
    });

    await createReply({
      shoutId,
      replyId: newShout.id,
    });

    return { error: undefined };
  } catch {
    return { error: ErrorMessages.UnknownError };
  }
}

Next, we need to rewrite the useReplyToShout hook.

Instead of simply providing the dependencies object to the replyToShout function and returning it, we

gather all dependencies via the query and mutation hooks
return a mutateAsync function (the name is random but makes the API of the hook consistent with react-query mutation hooks)
merge the loading states of all the query and mutation hooks
merge the errors of both query hooks.

interface UseReplyToShoutInput {
  recipientHandle: string;
}

export function useReplyToShout({ recipientHandle }: UseReplyToShoutInput) {
  const me = useGetMe();
  const user = useGetUser({ handle: recipientHandle });
  const saveImage = useSaveImage();
  const createShout = useCreateShout();
  const createReply = useCreateShoutReply();

  return {
    mutateAsync: (input: ReplyToShoutInput) =>
      replyToShout(input, {
        me: me.data,
        recipient: user.data,
        saveImage: saveImage.mutateAsync,
        createShout: createShout.mutateAsync,
        createReply: createReply.mutateAsync,
      }),
    isLoading:
      me.isLoading ||
      user.isLoading ||
      saveImage.isPending ||
      createShout.isPending ||
      createReply.isPending,
    isError: me.isError || user.isError,
  };
}

With this change the API requests to get me and user are sent as soon as the ReplyDialog component is rendered. At the same time, both responses can be delivered from the cache if the data has been fetched previously.

Once the user replies to a shout they don’t have to wait for these requests anymore improving the overall user experience.

Another advantage of this approach: While we use react-query for server data management we can test the replyToShout function and all its business logic in isolation.

With these changes we can now simplify our ReplyToDialog component. We don’t need the isLoading and hasError states anymoreas those are provided by the adjusted useReplyToShout hook.

import { useState } from "react";

import { useGetMe } from "@/application/queries/get-me";
import { useReplyToShout } from "@/application/reply-to-shout";
import { LoginDialog } from "@/components/login-dialog";
import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Textarea } from "@/components/ui/textarea";
import { isAuthenticated } from "@/domain/me";

...

export function ReplyDialog({
  recipientHandle,
  children,
  shoutId,
}: ReplyDialogProps) {
  const [open, setOpen] = useState(false);
  const [replyError, setReplyError] = useState<string>();
  const replyToShout = useReplyToShout({ recipientHandle });
  const me = useGetMe();

  if (me.isError || !isAuthenticated(me.data)) {
    return <LoginDialog>{children}</LoginDialog>;
  }

  async function handleSubmit(event: React.FormEvent<ReplyForm>) {
    event.preventDefault();

    const message = event.currentTarget.elements.message.value;
    const files = Array.from(event.currentTarget.elements.image.files ?? []);

    const result = await replyToShout.mutateAsync({
      recipientHandle,
      message,
      files,
      shoutId,
    });

    if (result.error) {
      setReplyError(result.error);
    } else {
      setOpen(false);
    }
  }

    ...

  return (
    <Dialog open={open} onOpenChange={setOpen}>
      {/* the rest of the component */}
    </Dialog>
  );
}

Another advantage of extracting the business logic to the useReplyToShout hook becomes obvious now:

We changed the underlying mechanism of server data management inside the hook quite a bit. But still the adjustments in the component were minimal.

Next Refactoring Steps

That was it for this time. We succesfully integrated react-query into our React applications architecture. Next time we’ll refactor the folder structure a bit to match a more common feature-driven folder structure.

Path To A Clean(er) React Architecture (Part 7) - Domain Logic

Johannes Kettmann — Fri, 05 Jul 2024 12:00:00 +0000

The unopinionated nature of React is a two-edged sword:

On the one hand, you get freedom of choice.
On the other hand, many projects end up with a custom and often messy architecture.

This article is the seventh part of a series about software architecture and React apps where we take a code base with lots of bad practices and refactor it step by step.

Previously,

This helped us in isolating our UI code from the server, make business logic independent of the UI framework, and increase testability.

But we’re not done yet.

In this article, we’ll focus on the core of our application: the domain.

Domain logic is code that operates on the domain models like a user object. That may sound abstract but we’ll see what it means in some hands-on examples. The goal is to isolate this logic from our components, move it to a specific place in the repository, and unit test it.

If you’ve ever wondered where you can place certain parts of logic if not a utility file or a custom hook this might be an interesting read.

Problematic code example: Domain logic inside a component
The problem: Mixed concerns and low testability
The solution: Extracting logic to the domain layer
1. Step 1: Creating functions in the domain layer
2. Step 2: Updating the component
3. Step 3: Unit testing domain logic
Another Problematic code example
1. The problem: Mixture of domain and business logic
2. The solution: Creating functions in the domain layer
The pros and cons of extracting domain logic
1. Advantages
2. Disadvantages
Next refactoring steps

Problematic code example: Domain logic inside a component

Let’s have a look at a problematic code example. Here’s a component that renders a list of Shouts (aka Tweets or Posts).

You can find the source code before and after this refactoring. Addtionally you can find an overview of all the changes for this article here.

// src/components/shout-list/shout-list.tsx

import { Shout } from "@/components/shout";
import { Image } from "@/domain/media";
import { Shout as IShout } from "@/domain/shout";
import { User } from "@/domain/user";

interface ShoutListProps {
  shouts: IShout[];
  images: Image[];
  users: User[];
}

export function ShoutList({ shouts, users, images }: ShoutListProps) {
  return (
    <ul className="flex flex-col gap-4 items-center">
      {shouts.map((shout) => {
        const author = users.find((u) => u.id === shout.authorId);
        const image = shout.imageId
          ? images.find((i) => i.id === shout.imageId)
          : undefined;

        return (
          <li key={shout.id} className="max-w-sm w-full">
            <Shout shout={shout} author={author} image={image} />
          </li>
        );
      })}
    </ul>
  );
}

The component receives a list of shouts together with a list of users and images that belong to these shouts.
It iterates over the shouts.
For each of the shouts it gets the corresponding author and the image.
Finally it returns a list item element for each shout.

The problem: Mixed concerns and low testability

The problematic lines of this component find the author and image of a Shout.

const author = users.find((u) => u.id === shout.authorId);
const image = shout.imageId
  ? images.find((i) => i.id === shout.imageId)
  : undefined;

These are operations on the user and image entities. Namely this code defines how the user and image lookup work in our application.

Additionally there’s a possibility that a Shout doesn’t have an image. Because of that we need a ternary expression. From my perspective that’s not the most beautiful or readable code.

The solution: Extracting logic to the domain layer

In an earlier article, we created a domain layer holding the core models of our application like User or Image as TypeScript interfaces. This turns out to be a great place to put logic that operates on domain entities.

Let me show you…

Step 1: Creating functions in the domain layer

Taking the example code above we can create a new domain function called getUserById:

// src/domain/user/user.ts

export interface User {
  id: string;
  handle: string;
  avatar: string;
  info?: string;
  blockedUserIds: string[];
  followerIds: string[];
}

export function getUserById(users?: User[], userId?: string) {
  if (!userId || !users) return;
  return users.find((u) => u.id === userId);
}

In this example, we make the function more flexible than required by making both parameters optional. From my experience, this is especially useful when you work with asynchronous data or with libraries like react-query.

We can do the same for the image:

// src/domain/media/media.ts

export interface Image {
  id: string;
  url: string;
}

export function getImageById(images?: Image[], imageId?: string) {
  if (!imageId || !images) return;
  return images.find((i) => i.id === imageId);
}

Step 2: Updating the component

Now in the component the advantages become evident:

// src/components/shout-list/shout-list.tsx

import { Shout } from "@/components/shout";
import { Image, getImageById } from "@/domain/media";
import { Shout as IShout } from "@/domain/shout";
import { User, getUserById } from "@/domain/user";

...

export function ShoutList({ shouts, users, images }: ShoutListProps) {
  return (
    <ul className="flex flex-col gap-4 items-center">
      {shouts.map((shout) => (
        <li key={shout.id} className="max-w-sm w-full">
          <Shout
            shout={shout}
            author={getUserById(users, shout.authorId)}
            image={getImageById(images, shout.imageId)}
          />
        </li>
      ))}
    </ul>
  );
}

The code is more readable because the reader’s brain doesn’t have to translate the users.find(...) functions in to ID lookups.
We got rid of the ternary expression further improving readability.
The logic is now much simpler to test.

What do I mean by “simpler to test”?

Step 3: Unit testing domain logic

In the original code we’d have to test the logic by passing different versions of the shouts, users, and images props. Here a quick reminder of the original code:

export function ShoutList({ shouts, users, images }: ShoutListProps) {
  return (
    <ul className="flex flex-col gap-4 items-center">
      {shouts.map((shout) => {
        const author = users.find((u) => u.id === shout.authorId);
        const image = shout.imageId
          ? images.find((i) => i.id === shout.imageId)
          : undefined;

        return (
          <li key={shout.id} className="max-w-sm w-full">
            <Shout shout={shout} author={author} image={image} />
          </li>
        );
      })}
    </ul>
  );
}

Here specifically we’d have to provide different test cases for Shouts that contain an imageId and that don’t. We might even want to test other edge cases like a missing author or so. On top of that we’d have to test the component with e.g. React Testing Library which creates additional overhead.

Compared to that writing unit tests for our new domain functions is very straightforward:

// src/domain/media/media.test.ts

import { describe, expect, it } from "vitest";

import { getImageById } from "./media";

const mockImage = {
  id: "1",
  url: "test",
};

describe("Media domain", () => {
  describe("getImageById", () => {
    it("should be able to get image by id", () => {
      const image = getImageById([mockImage], "1");
      expect(image).toEqual(mockImage);
    });

    it("should return undefined if image is not found", () => {
      const image = getImageById([{ ...mockImage, id: "2" }], "1");
      expect(image).toEqual(undefined);
    });

    it("should return undefined if provided images are not defined", () => {
      const image = getImageById(undefined, "1");
      expect(image).toEqual(undefined);
    });

    it("should return undefined if provided image id is not defined", () => {
      const image = getImageById([mockImage], undefined);
      expect(image).toEqual(undefined);
    });
  });
});

We can test all the possible branches without any setup code as often required by React Testing Library and these tests are blazing fast.

This can provide the opportunity to remove some (more expensive) integration tests that would otherwise be required.

Another Problematic code example

Let me try to solidify this approach with another example. In a previous article, we have a hook that exposes a use-case function as a way to remove business logic from a component. This function

first runs a few lines of validation logic
followed by a series of service calls.

// src/application/reply-to-shout/reply-to-shout.ts

import { useCallback } from "react";

import MediaService from "@/infrastructure/media";
import ShoutService from "@/infrastructure/shout";
import UserService from "@/infrastructure/user";

...

export async function replyToShout(
  { recipientHandle, shoutId, message, files }: ReplyToShoutInput,
  { getMe, getUser, saveImage, createReply, createShout }: typeof dependencies
) {
  const me = await getMe();
  if (me.numShoutsPastDay >= 5) {
    return { error: ErrorMessages.TooManyShouts };
  }

  const recipient = await getUser(recipientHandle);
  if (!recipient) {
    return { error: ErrorMessages.RecipientNotFound };
  }
  if (recipient.blockedUserIds.includes(me.id)) {
    return { error: ErrorMessages.AuthorBlockedByRecipient };
  }

  try {
    let image;
    if (files?.length) {
      image = await saveImage(files[0]);
    }

    const newShout = await createShout({
      message,
      imageId: image?.id,
    });

    await createReply({
      shoutId,
      replyId: newShout.id,
    });

    return { error: undefined };
  } catch {
    return { error: ErrorMessages.UnknownError };
  }
}

export function useReplyToShout() {
  return useCallback(
    (input: ReplyToShoutInput) => replyToShout(input, dependencies),
    []
  );
}

The problem: Mixture of domain and business logic

The problematic lines of code are in the data validation:

const me = await getMe();
if (me.numShoutsPastDay >= 5) {
  return { error: ErrorMessages.TooManyShouts };
}

const recipient = await getUser(recipientHandle);
if (!recipient) {
  return { error: ErrorMessages.RecipientNotFound };
}
if (recipient.blockedUserIds.includes(me.id)) {
  return { error: ErrorMessages.AuthorBlockedByRecipient };
}

These are again operations on domain entities: User and Me (the current user).

The solution: Creating functions in the domain layer

And again we can move this logic to the domain layer:

// src/domain/me/me.ts

import { User } from "@/domain/user";

export const MAX_NUM_SHOUTS_PER_DAY = 5;

export interface Me extends User {
  numShoutsPastDay: number;
}

export function hasExceededShoutLimit(me: Me) {
  return me.numShoutsPastDay >= MAX_NUM_SHOUTS_PER_DAY;
}

Now the domain is responsible for deciding whether or not a user has exceeded the shout limit. This allows us to remove implementation details such as

the number of shouts allowed
the interval for this threshold (in this case one day)

from the code that’s closer to the UI.

We can do the same with the check of the blockedUserIds:

// src/domain/user/user.ts

export interface User {
  id: string;
  handle: string;
  avatar: string;
  info?: string;
  blockedUserIds: string[];
  followerIds: string[];
}

...

export function hasBlockedUser(user?: User, userId?: string) {
  if (!user || !userId) return false;
  return user.blockedUserIds.includes(userId);
}

The use-case function now reads simpler and as mentioned contains less implementation details related to the domain (e.g. how many times a user can shout in a given interval).

// src/application/reply-to-shout/reply-to-shout.ts

import { hasExceededShoutLimit } from "@/domain/me";
import { hasBlockedUser } from "@/domain/user";

export async function replyToShout(
  { recipientHandle, shoutId, message, files }: ReplyToShoutInput,
  { getMe, getUser, saveImage, createReply, createShout }: typeof dependencies
) {
  const me = await getMe();
  if (hasExceededShoutLimit(me)) {
    return { error: ErrorMessages.TooManyShouts };
  }

  const recipient = await getUser(recipientHandle);
  if (!recipient) {
    return { error: ErrorMessages.RecipientNotFound };
  }
  if (hasBlockedUser(recipient, me.id)) {
    return { error: ErrorMessages.AuthorBlockedByRecipient };
  }

Finally, we again can test this logic with simple unit tests:

// src/domain/user/user.test.ts

import { describe, expect, it } from "vitest";

import { getUserById, hasBlockedUser } from "./user";

const mockUser = {
  id: "1",
  handle: "test",
  avatar: "test",
  numShoutsPastDay: 0,
  blockedUserIds: [],
  followerIds: [],
};

describe("User domain", () => {
  describe("getUserById", () => { ... });

  describe("hasBlockedUser", () => {
    it("should be false if user has not blocked the user", () => {
      const user = { ...mockUser, blockedUserIds: ["2"] };
      const hasBlocked = hasBlockedUser(user, "3");
      expect(hasBlocked).toEqual(false);
    });

    it("should be true if user has blocked the user", () => {
      const user = { ...mockUser, blockedUserIds: ["2"] };
      const hasBlocked = hasBlockedUser(user, "2");
      expect(hasBlocked).toEqual(true);
    });

    it("should be false if user is not defined", () => {
      const hasBlocked = hasBlockedUser(undefined, "2");
      expect(hasBlocked).toEqual(false);
    });

    it("should be false if user id is not defined", () => {
      const hasBlocked = hasBlockedUser(mockUser, undefined);
      expect(hasBlocked).toEqual(false);
    });
  });
});

The pros and cons of extracting domain logic

Let’s quickly discuss some of the advantages and disadvantages of this approach.

Advantages

Less utility functions: Without the domain layer it’s often unclear where you put logic like the above. From my experience it’s typically scattered around the components or you can find it in utility files. Utility files can become problematic though as they easily turn into a dumping ground for all kinds of shared code.
Readability: While it’s not a lot users.find(({ id }) => id === userId) requires a bit of cognitive overload to translate this into a ID lookup. Reading getUserById(users, userId) instead is much more descriptive. That’s especially effective if you many of these lines grouped together (e.g. at the top of a component).
Testability: You can often find code that uses if/switch statements or ternaries. Each of these mean that there are multiple test branches to be covered. It can be much easier to write unit tests for all the edge cases and reduce the number of integration tests to the ones being strictly necessary.
Reusability: Often these small pieces of logic might not seem worthy of being extracted into separate functions. Then they are repeated in the code indefinitely. But a small change of requirements can easily lead to a bigger refactoring.
Search-ability: It’s not that simple to run a global search on e.g. users.find(({ id }) => id === userId). The code might be written in different ways with different variable names. A global search for getUserById is straightforward though.

Disadvantages

Training: Not every developer is used to thinking in different kinds of logic. So documentation and training might be required if you want to keep your code base consistent.
Overhead: As you’ve seen in one of the examples above, we made some of the domain functions more flexible than required by the specific component (here we made the users and userId parameters of the getUserById function optional). Since we also covered these cases with unit tests we introduced more code than required leading to more maintenance effort. At the same time, this can save your butt if you e.g. suddenly encounter unexpected response data from the server.

Next refactoring steps

Until now we didn’t introduce any other tool than React itself. From my perspective, this was important as it can be difficult to transfer knowledge from one tech stack to another if things are mingled together.

But now it’s time to confront the reality of production React apps.

One of the most common tools used in the wild is react-query (or another server state management library like RTK query or SWR). How do these fit into our architecture? That’s the topic of the next article.

Path To A Clean(er) React Architecture (Part 6) - Business Logic Separation

Johannes Kettmann — Fri, 21 Jun 2024 12:00:00 +0000

The unopinionated nature of React is a two-edged sword:

On the one hand, you get freedom of choice.
On the other hand, many projects end up with a custom and often messy architecture.

This article is the sixth part of a series about software architecture and React apps where we take a code base with lots of bad practices and refactor it step by step.

Previously,

All this to isolate our UI code from the server and increase testability.

But we’re not done yet.

In this article, we’re moving closer to the components. From my experience, in many React apps, there’s no real separation between business logic and UI code. There’s no consensus about where to put logic so it often ends up in the component, a custom hook, or a utility file. This can lead to code that is hard to understand and difficult to test.

And that’s exactly what we’ll address here.

Problematic code example: Business logic mixed with UI logic

Let’s have a look at a problematic code example. Here’s a component that renders a form with a submit handler attached. The submit handler

updates some UI state
checks some pre-conditions regarding the users involved
saves an image and creates a reply
and finally updates the UI state again.

// src/components/shout/reply-dialog.tsx

import MediaService from "@/infrastructure/media";
import ShoutService from "@/infrastructure/shout";
import UserService from "@/infrastructure/user";

...

const ErrorMessages = {
  TooManyShouts:
    "You have reached the maximum number of shouts per day. Please try again tomorrow.",
  RecipientNotFound: "The user you want to reply to does not exist.",
  AuthorBlockedByRecipient:
    "You can't reply to this user. They have blocked you.",
  UnknownError: "An unknown error occurred. Please try again later.",
} as const;

export function ReplyDialog({
  recipientHandle,
  children,
  shoutId,
}: ReplyDialogProps) {
  const [open, setOpen] = useState(false);
  const [isLoading, setIsLoading] = useState(true);
  const [replyError, setReplyError] = useState<string>();

  ...

  async function handleSubmit(event: React.FormEvent<ReplyForm>) {
    event.preventDefault();
    setIsLoading(true);

    const me = await UserService.getMe();
    if (me.numShoutsPastDay >= 5) {
      return setReplyError(ErrorMessages.TooManyShouts);
    }

    const recipient = await UserService.getUser(recipientHandle);
    if (!recipient) {
      return setReplyError(ErrorMessages.RecipientNotFound);
    }
    if (recipient.blockedUserIds.includes(me.id)) {
      return setReplyError(ErrorMessages.AuthorBlockedByRecipient);
    }

    try {
      const message = event.currentTarget.elements.message.value;
      const files = event.currentTarget.elements.image.files;

      let image;
      if (files?.length) {
        image = await MediaService.saveImage(files[0]);
      }

      const newShout = await ShoutService.createShout({
        message,
        imageId: image?.id,
      });

      await ShoutService.createReply({
        shoutId,
        replyId: newShout.id,
      });

      setOpen(false);
    } catch (error) {
      setReplyError(ErrorMessages.UnknownError);
    } finally {
      setIsLoading(false);
    }
  }
  return (
    <Dialog open={open} onOpenChange={setOpen}>
      {/* more JSX here */}
    </Dialog>
  );
}

Fairly straightforward, right? There’s quite a bit of code inside the submit handler but what can we do!?

The problem: Mixed concerns and low testability

The thing is that the component has quite a lot of responsibilities. Some of these fall well into the concern of a UI component like

rendering the UI (doh),
handling the submit event,
or updating the loading or error state.

But much of the code in the submit handler has nothing to do with UI.

Most of the code is data validation and orchestrating calls to services / Rest APIs. That’s business logic and can be isolated from the UI framework.

Imagine we wanted to migrate from React to any other future UI library. We’d have to untangle this mixture of UI and business logic.

Ok, that’s an unlikely event far in the future.

More urgent is this question: How would you test this component?

Do I hear “integration tests”? I know, integration tests have become very popular in the React community. Especially thanks to React Testing Library and its premise to test an application from the user’s perspective.

But in this case, we would need to jump through a few hoops to test all the different branches. Each return statement represents one branch. Plus the catch block at the end.

So we have test scenarios like:

A user who shouted more than 5 times and one that didn’t.
A recipient that doesn’t exist and one that has blocked the current user.
Failing API requests in the services that trigger the catch block.
And finally the happy path.

Yes, we can test this with integration tests. We could mock the requests with e.g. Mock Service Worker. Then we’d render the app, fill in the form inputs, click the submit button, and check that the UI shows the correct result.

But this is relatively complex as we need to set up different mock requests. Additionally, these tests would be relatively slow as we’d have to walk through the same UI interactions for each test.

Let’s have a look at an alternative approach.

The solution: Extracting business logic and using dependency injection

Similar to the previous article, the idea is to move the business logic unrelated to the UI to a separate function. We then create a custom hook to facilitate dependency injection. This helps us simplify our tests: No need for an integration test for each branch. Instead we can unit test the business logic.

Step 1: Extracting business logic to a use-case

We start by extracting all the business logic into a new function in a new file.

// src/application/reply-to-shout.ts

import MediaService from "@/infrastructure/media";
import ShoutService from "@/infrastructure/shout";
import UserService from "@/infrastructure/user";

interface ReplyToShoutInput {
  recipientHandle: string;
  shoutId: string;
  message: string;
  files?: File[] | null;
}

const ErrorMessages = {
  TooManyShouts:
    "You have reached the maximum number of shouts per day. Please try again tomorrow.",
  RecipientNotFound: "The user you want to reply to does not exist.",
  AuthorBlockedByRecipient:
    "You can't reply to this user. They have blocked you.",
  UnknownError: "An unknown error occurred. Please try again later.",
} as const;

export async function replyToShout({
  recipientHandle,
  shoutId,
  message,
  files,
}: ReplyToShoutInput) {
  const me = await UserService.getMe();
  if (me.numShoutsPastDay >= 5) {
    return { error: ErrorMessages.TooManyShouts };
  }

  const recipient = await UserService.getUser(recipientHandle);
  if (!recipient) {
    return { error: ErrorMessages.RecipientNotFound };
  }
  if (recipient.blockedUserIds.includes(me.id)) {
    return { error: ErrorMessages.AuthorBlockedByRecipient };
  }

  try {
    let image;
    if (files?.length) {
      image = await MediaService.saveImage(files[0]);
    }

    const newShout = await ShoutService.createShout({
      message,
      imageId: image?.id,
    });

    await ShoutService.createReply({
      shoutId,
      replyId: newShout.id,
    });

    return { error: undefined };
  } catch {
    return { error: ErrorMessages.UnknownError };
  }
}

Now this function contains no code related to the UI or React (except for maybe the error messages that could be replaced by some kind of error codes). Even if we migrated to another UI framework we could keep this code without any changes.

A quick side note: In this series of articles we roughly follow the Clean Architecture. In this context, the business logic we extracted is referred to as “application logic” or “use cases” belonging to the “application layer”.

To keep things clear, we create the file in a new global application folder. Later we’ll restructure this project to use a feature-driven folder structure. But for now it’s easier to separate the different layers in their respective folders.

Anyway, let’s continue with the refactoring.

With all this logic isolated in a separate function, the component’s submit handler is much slimmer now.

// src/components/shout/reply-dialog.tsx

async function handleSubmit(event: React.FormEvent<ReplyForm>) {
  event.preventDefault();
  setIsLoading(true);

  const message = event.currentTarget.elements.message.value;
  const files = Array.from(event.currentTarget.elements.image.files ?? []);

  +const result = await replyToShout({
  +  recipientHandle,
  +  message,
  +  files,
  +  shoutId,
  +});

  if (result.error) {
    setReplyError(result.error);
  }
  setOpen(false);
  setIsLoading(false);
}

Alright, we covered our potential future “let’s migrate to another UI framework” scenario. But testability-wise not much changed. So let’s tackle that.

Step 2: Custom hook for dependency injection

The replyToShout function uses a couple of services to send API requests.

// src/application/reply-to-shout.ts

import MediaService from "@/infrastructure/media";
import ShoutService from "@/infrastructure/shout";
import UserService from "@/infrastructure/user";

export async function replyToShout({ ... }) {
  const me = await UserService.getMe();
  const recipient = await UserService.getUser(recipientHandle);

  ...

  let image;
  if (files?.length) {
    image = await MediaService.saveImage(files[0]);
  }

  const newShout = await ShoutService.createShout({ ... });
  await ShoutService.createReply({ ... });
}

This means it “has dependencies” on these services. That makes testing the replyToShout function difficult. We’d have to mock the service modules or the REST API used in the services.

Dependency injection to the rescue.

Dependency injection is a common pattern used to increase testability. Sounds complicated but actually it’s quite simple:

We adjust the function to accept a new “dependencies” parameter with the relevant service functions.
Then we create a custom hook that “injects” these dependencies.

import { useCallback } from "react";

import MediaService from "@/infrastructure/media";
import ShoutService from "@/infrastructure/shout";
import UserService from "@/infrastructure/user";

...

// We create the dependencies as a separate object using the services.
// This way it's already typed and we don't need another TS interface.
const dependencies = {
  getMe: UserService.getMe,
  getUser: UserService.getUser,
  saveImage: MediaService.saveImage,
  createShout: ShoutService.createShout,
  createReply: ShoutService.createReply,
};

// The replyToShout function accepts the dependencies as second parameter.
// Now the code that calls this function decides what to provide as e.g. getMe.
// This is called inversion of control and helps with unit testing.
export async function replyToShout(
  { recipientHandle, shoutId, message, files }: ReplyToShoutInput,
  { getMe, getUser, saveImage, createReply, createShout }: typeof dependencies
) {
  const me = await getMe();
  if (me.numShoutsPastDay >= 5) {
    return { error: ErrorMessages.TooManyShouts };
  }

  const recipient = await getUser(recipientHandle);
  if (!recipient) {
    return { error: ErrorMessages.RecipientNotFound };
  }
  if (recipient.blockedUserIds.includes(me.id)) {
    return { error: ErrorMessages.AuthorBlockedByRecipient };
  }

  try {
    let image;
    if (files?.length) {
      image = await saveImage(files[0]);
    }

    const newShout = await createShout({
      message,
      imageId: image?.id,
    });

    await createReply({
      shoutId,
      replyId: newShout.id,
    });

    return { error: undefined };
  } catch {
    return { error: ErrorMessages.UnknownError };
  }
}

// This hook is just a mechanism to inject the dependencies. A component can
// use this hook without having to care about providing the dependencies.
export function useReplyToShout() {
  return useCallback(
    (input: ReplyToShoutInput) => replyToShout(input, dependencies),
    []
  );
}

Note that this file became a bit “dirty”. If we followed the Clean Architecture by the book the application layer shouldn’t contain any references to the UI framework. This file contains code that is specific to the UI framework though (here by exporting a hook and applying useCallback). So this file isn’t completely clean. But I think we can be pragmatic here.

Anyway, as we’ll see in a bit it’s now straightforward to test the replyToShout function.

If you think this looks more and more like a typical react-query hook, I agree. In one of the next articles, we’ll introduce react-query into the picture. But for now let’s stay tool-agnostic.

Step 3: Unit testing the business logic

Since we use dependency injection we can now simply create mock functions and pass those to the replyToShout function. We then assert that the correct error is returned or that the service functions received the correct values.

import { beforeEach, describe, expect, it, vitest } from "vitest";

import { createMockFile } from "@/test/create-mock-file";

import { ErrorMessages, replyToShout } from "./reply-to-shout";

const recipientHandle = "recipient-handle";
const shoutId = "shout-id";
const message = "Hello, world!";
const files = [createMockFile("image.png")];

const imageId = "image-id";
const newShoutId = "new-shout-id";

// The mock data and service functions below could be moved to centralized 
// factory functions. This would simplify managing test data on a larger scale.
const mockMe = {
  id: "user-1",
  handle: "me",
  avatar: "user-1.png",
  numShoutsPastDay: 0,
  blockedUserIds: [],
  followerIds: [],
};

const mockRecipient = {
  id: "user-2",
  handle: recipientHandle,
  avatar: "user-2.png",
  numShoutsPastDay: 0,
  blockedUserIds: [],
  followerIds: [],
};

const mockGetMe = vitest.fn().mockResolvedValue(mockMe);
const mockGetUser = vitest.fn().mockResolvedValue(mockRecipient);
const mockSaveImage = vitest.fn().mockResolvedValue({ id: imageId });
const mockCreateShout = vitest.fn().mockResolvedValue({ id: newShoutId });
const mockCreateReply = vitest.fn();

const mockDependencies = {
  getMe: mockGetMe,
  getUser: mockGetUser,
  saveImage: mockSaveImage,
  createShout: mockCreateShout,
  createReply: mockCreateReply,
};

describe("replyToShout", () => {
  beforeEach(() => {
    Object.values(mockDependencies).forEach((mock) => mock.mockClear());
  });

  it("should return an error if the user has made too many shouts", async () => {
    mockGetMe.mockResolvedValueOnce({ ...mockMe, numShoutsPastDay: 5 });

    const result = await replyToShout(
      { recipientHandle, shoutId, message, files },
      mockDependencies
    );

    expect(result).toEqual({ error: ErrorMessages.TooManyShouts });
  });

  it("should return an error if the recipient does not exist", async () => {
    mockGetUser.mockResolvedValueOnce(undefined);

    const result = await replyToShout(
      { recipientHandle, shoutId, message, files },
      mockDependencies
    );

    expect(result).toEqual({ error: ErrorMessages.RecipientNotFound });
  });

  it("should return an error if the recipient has blocked the author", async () => {
    mockGetUser.mockResolvedValueOnce({
      ...mockRecipient,
      blockedUserIds: [mockMe.id],
    });

    const result = await replyToShout(
      { recipientHandle, shoutId, message, files },
      mockDependencies
    );

    expect(result).toEqual({ error: ErrorMessages.AuthorBlockedByRecipient });
  });

  it("should create a new shout with an image and reply to it", async () => {
    await replyToShout(
      { recipientHandle, shoutId, message, files },
      mockDependencies
    );

    expect(mockSaveImage).toHaveBeenCalledWith(files[0]);
    expect(mockCreateShout).toHaveBeenCalledWith({
      message,
      imageId,
    });
    expect(mockCreateReply).toHaveBeenCalledWith({
      shoutId,
      replyId: newShoutId,
    });
  });

  it("should create a new shout without an image and reply to it", async () => {
    await replyToShout(
      { recipientHandle, shoutId, message, files: [] },
      mockDependencies
    );

        expect(mockSaveImage).not.toHaveBeenCalled();
    expect(mockCreateShout).toHaveBeenCalledWith({
      message,
      imageId: undefined,
    });
    expect(mockCreateReply).toHaveBeenCalledWith({
      shoutId,
      replyId: newShoutId,
    });
  });
});

Now we covered all the edge cases of the replyToShout use case with blazing fast unit tests. No need to mock half a dozen different user responses and run through all UI interactions for each of those branches.

With a bit more effort we could even use TypeScript as another layer of safety net. But that would go too far for this time. We’ll cover it in a future article.

Still, let me explain quickly:

Currently we can pass anything we want as mock dependencies. But that can cause a mismatch between the parameters and return types of the real service functions and the mocks. And that again can lead to situations where all our unit tests pass but the application as a whole breaks.

This scenario is usually covered by integration or end-to-end tests. Since these test the features integrated into the larger system a mismatch between mocks and actual implementation quickly becomes evident.

Ok, that’s it for this refactoring. Let me quickly wrap up with a summary of the pros and cons.

Advantages and disadvantages of business logic in use cases

We discussed the advantages already. Here a quick summary:

Isolating business logic from the UI makes it independent of the UI framework.
Using dependency injection makes it easy to test the logic.
Removing logic from the components let’s them focus on their responsibility: the UI.
Plus you finally have a place to put your business logic apart from util functions and custom hooks.

But what about the disadvantages?

To be honest, I don’t see many. But here are a few thoughts:

There’s a bit of overhead because we created a custom hook for dependency injection.
This kind of separation is only valuable if you in fact have logic. You don’t need it for a simple API request.
It might not be that simple to distinguish between different types of logic. At least it took me a while to become better at identifying logic that’s worth being extracted.
We introduced an architecture that is not very common in React apps so new developers have to get used to it.

Overall the advantages in this case outweigh any potential disadvantages from my perspective.

Next refactoring steps

This time we talked a lot about business or application logic. Next time, we’ll take a step closer to the core and focus on domain logic.

In fact, we’ve seen this logic mixed with out business logic in the use case function replyToShout.

The next step is to move this kind of logic to the domain layer.

Path To A Clean(er) React Architecture (Part 5) - Infrastructure Services & Dependency Injection For Testability

Johannes Kettmann — Fri, 07 Jun 2024 11:34:00 +0000

Liquid syntax error: Tag '{% https://youtu.be/WfJcNvTabO4 %}' was not properly terminated with regexp: /\%\}/

Path To A Clean(er) React Architecture - Domain Entities & DTOs

Johannes Kettmann — Fri, 24 May 2024 11:00:00 +0000

The unopinionated nature of React is a two-edged sword:

On the one hand you get freedom of choice.
On the other hand many projects end up with a custom and often messy architecture.

This article is the fourth part of a series about software architecture and React apps where we take a code base with lots of bad practices and refactor it step by step.

Previously, we created the initial API layer and extracted fetch functions and data transformations. This way we already removed a lot of implementation details related to API requests from the UI code.

But we’re not done yet.

In this article, we prevent raw response data structures from entering UI code by introducing a domain layer and DTOs. Another step towards a cleaner architecture.

Bad Code: Data Structures Of API Responses In UI Code
What is the problem?
1. We use data structures defined by the API
2. Tight coupling of UI code to server API
Solution: Introducing domain entities and DTOs
1. The domain model
2. DTOs and data transformations
The good and the bad
1. Pros: Cleaner architecture, more resilience, better separation
2. Cons: More code, more complexity
3. Conventions and automation
Next refactoring steps

Bad Code: Data Structures Of API Responses In UI Code

Let’s have a look at a problematic code example. Here is a user profile component that fetches data from an API and renders it.

// src/pages/user-profile.tsx

import UserApi from "@/api/user";
import { User } from "@/types";

interface UserProfileProps {
  handle: string;
}

export function UserProfile({ handle }: UserProfileProps) {
  const [user, setUser] = useState<User>();

  useEffect(() => {
    UserApi.getUser(handle)
      .then((user) => setUser(user));
  }, [handle]);

  return (
    <section>
      <img
        src={user.attributes.avatar}
        alt={`${user.attributes.handle}'s avatar`}
      />
      <h1>@{user.attributes.handle}</h1>
      <p>({user.relationships.followerIds.length} follower)</p>
      <p>{user.attributes.info || "Shush! I'm a ghost."}</p>
    </section>
  );
}

If you’re thinking we should use a library for server state management like react-query instead of manually fetching data in a useEffect: You’re right. But for now let’s stay tool-agnostic. We’ll get to react-query in a future article.

What is the problem?

The UI code uses an unnecessarily nested data structure for the user object. We have

user.attributes.xyz or
user.relationships.followerIds

multiple times. Here’s the TypeScript interface:

// src/types/index.ts

export interface User {
  id: string;
  type: "user";
  attributes: {
    handle: string;
    avatar: string;
    info?: string;
  };
  relationships: {
    followerIds: string[];
  };
}

Similar data structures can be found all over the project even inside components deep inside the component tree.

But what’s the reason for this nesting?

We use data structures defined by the API

Turns out the user data is directly returned from the fetch function we created in an earlier article:

// src/api/user.ts

import { User } from "@/types";
import { apiClient } from "./client";

async function getUser(handle: string) {
  const response = await apiClient.get<{ data: User }>(`/user/${handle}`);
  const user = response.data.data;
  return user;
}

export default { getUser };

And inspecting the network requests we can see that this data structure is defined by the server.

The server seems to be using the popular JSON:API standard which is a great way to build APIs. But should we really use these data structures in the frontend?

Tight coupling of UI code to server API

The problem is: By passing the data coming from the API directly to the components we tightly couple the UI to the server. The response data doesn’t reflect the data structure of the (user) entity but is merely a data-transfer object (DTO).

DTO is a useful pattern as you can model the data according to the needs of the consumer. You can include additional data that isn’t included in the original database model like relationships.followerIds.

But exposing the DTO to the UI components leads to unnecessary complexity by accessing fields via user.attributes.xyz or object destructuring that bloats the code base like

const {
  handle,
  avatar,
} = user.attributes;
const {
    followerIds
} = user.relationships;

Apart from the immediate extra complexity we also make the complete UI code dependent on changes of the server API.

Imagine the backend folks decide to ditch the JSON:API standard. Suddenly there are no user.attributes anymore. But we sprinkled them all over the UI code. So just because the server API changed we now have to adjust like 90% of the frontend code as well.

Solution: Introducing domain entities and DTOs

The domain model

We start by creating a new TypeScript interface that simplifies the User . In this case we just flatten the API data structure.

// src/domain/index.ts

export interface User {
  id: string;
  handle: string;
  avatar: string;
  info?: string;
  followerIds: string[];
}

Side note: Here we introduced a new folder on the root level called domain. The domain is a concept reflecting the core of the business used e.g. in the Clean Architecture or Domain Driven Design (DDD).

Instead of the data structures returned by the API let’s use the domain model in our component.

// src/pages/user-profile/user-info.tsx

import UserApi from "@/api/user";
import { User } from "@/domain";

interface UserProfileProps {
  handle: string;
}

export function UserProfile({ handle }: UserProfileProps) {
  const [user, setUser] = useState<User>();

  useEffect(() => {
    UserApi.getUser(handle)
      .then((user) => setUser(user));
  }, [handle]);

  return (
    <section>
      <img
        src={user.avatar}
        alt={`${user.handle}'s avatar`}
      />
      <h1>@{user.handle}</h1>
      <p>({user.followerIds.length} follower)</p>
      <p>{user.info || "Shush! I'm a ghost."}</p>
    </section>
  );
}

Great, we got rid of the annoying user.attributes and user.relationships simplifying our code a bit.

But more importantly, we decoupled our UI code from the server making it more resilient against external changes.

Great improvement, but we’re not done yet. UserApi.getUser(handle) still returns the nested data structure coming from the API.

DTOs and data transformations

The current fetch function in our API layer simply returns the API data.

// src/api/user.ts

import { User } from "@/types";
import { apiClient } from "./client";

async function getUser(handle: string) {
  const response = await apiClient.get<{ data: User }>(`/user/${handle}`);
  const user = response.data.data;
  return user;
}

export default { getUser };

With our components expecting the domain model we need some changes here as well.

We start by defining the model of the data transfer object (DTO) in the API layer.

// src/api/user/dto.ts

export interface UserDto {
  id: string;
  type: "user";
  attributes: {
    handle: string;
    avatar: string;
    info?: string;
  };
  relationships: {
    followerIds: string[];
  };
}

From now on this data structure is only used inside the API layer and is not to be exposed to the rest of the application code.

Thus we need to transform the API response data to the domain model. A simple function will do the job.

// src/api/user/transform.ts

import { User } from "@/domain";
import { UserDto } from "./dto";

export function dtoToUser(dto: UserDto): User {
  return {
    id: dto.id,
    avatar: dto.attributes.avatar,
    handle: dto.attributes.handle,
    info: dto.attributes.info,
    followerIds: dto.relationships.followerIds,
  };
}

Next, we apply this function to the response data before returning it to the component.

// src/api/user/api.ts

import { apiClient } from "../client";
import { UserDto } from "./dto";
import { dtoToUser } from "./transform";

async function getUser(handle: string) {
  const response = await apiClient.get<{ data: UserDto }>(`/user/${handle}`);
  const userDto = response.data.data;
  return dtoToUser(userDto);
}

export default { getUser };

The good and the bad

Pros: Cleaner architecture, more resilience, better separation

From an architectural perspective the new code is a lot cleaner:

The data structures coming from the API are only used in the API layer as DTOs.
The UI code is effectively isolated from the server’s REST API.
Most of the application code uses shared domain models.

This way the code is more resilient and concerns are separated.

Cons: More code, more complexity

But this decoupling also comes with a cost: Boilerplate.

For each entity we need to add one domain model, at least one DTO, and one transformer function. We have more code and a lot more files in our code base.

Also the level of complexity increased. At least for developers who aren’t familiar with the code base or its architecture.

Conventions and automation

Once you get used to the architecture everything is quite clear though thanks to the conventions and consistency.

The transformer files contain data transformation functions.
The API files handle the requests.
The domain layer contains the application wide data structures.

And while the boilerplate problem exists you can also automate the creation of some of these files depending on your tech stack.

For example:

For fullstack TypeScript applications you can use shared domain models on the server and the client e.g. in a monorepo or by moving them in a separate npm package.
If you have a REST API that is well-documented with OpenAPI you can automatically generate your domain models or DTOs.
Depending on the data structures in the API responses you might not need DTOs and data transformations. You can always introduce them later if the REST API changes.

Next refactoring steps

You may have realized that we’re slowly adding responsibilities to the API fetch functions, like getUser. It’s not only responsible for sending API requests but also for transforming response data.

// src/api/user/api.ts

async function getUser(handle: string) {
  const response = await apiClient.get<{ data: UserDto }>(`/user/${handle}`);
  const userDto = response.data.data;
  return dtoToUser(userDto);
}

export default { getUser };

Here’s another example from the code base:

In the next article of this series we will use the repository pattern to move some of these responsibilities away from the fetch functions.

Path To A Clean(er) React Architecture - API Layer & Data Transformations

Johannes Kettmann — Fri, 10 May 2024 11:00:00 +0000

The unopinionated nature of React is a two-edged sword:

On the one hand you get freedom of choice.
On the other hand many projects end up with a custom and often messy architecture.

This article is the third part of a series about software architecture and React apps where we take a code base with lots of bad practices and refactor it step by step.

Previously, we created the initial API layer and extracted fetch functions that can be used in the components. This way we already removed a lot of implementation details related to API requests from the UI code.

But we’re not done yet.

In this article, we identify data transformations in the component that can be moved to the API layer. Another step towards a cleaner architecture.

Bad Code - Example 1: API responses inside UI code
1. What is the problem?
2. Solution: Use data transformations in the API layer
Bad Code - Example 2: Data transformations in UI code
1. What is the problem?
2. Solution: Move data transformation logic to the fetch function
Bad Code - Example 3: Transformation of input data
1. What is the problem?
2. Solution: Move transformation of input data to API layer
Next refactoring steps

Bad Code - Example 1: API responses inside UI code

Let’s have a look at a problematic code example. Here is a user profile component that fetches data from two different endpoints.

Can you identify the problem?

import { useEffect, useState } from "react";
import { Navigate, useParams } from "react-router";

import UserApi from "@/api/user";
import { LoadingSpinner } from "@/components/loading";
import { ShoutList } from "@/components/shout-list";
import { UserResponse, UserShoutsResponse } from "@/types";

import { UserInfo } from "./user-info";

export function UserProfile() {
  const { handle } = useParams<{ handle: string }>();

  const [user, setUser] = useState<UserResponse>();
  const [userShouts, setUserShouts] = useState<UserShoutsResponse>();
  const [hasError, setHasError] = useState(false);

  useEffect(() => {
    if (!handle) {
      return;
    }

    UserApi.getUser(handle)
      .then((response) => setUser(response))
      .catch(() => setHasError(true));

    UserApi.getUserShouts(handle)
      .then((response) => setUserShouts(response))
      .catch(() => setHasError(true));
  }, [handle]);

  if (!handle) {
    return <Navigate to="/" />;
  }

  if (hasError) {
    return <div>An error occurred</div>;
  }
  if (!user || !userShouts) {
    return <LoadingSpinner />;
  }

  return (
    <div className="max-w-2xl w-full mx-auto flex flex-col p-6 gap-6">
      <UserInfo user={user.data} />
      <ShoutList
        users={[user.data]}
        shouts={userShouts.data}
        images={userShouts.included}
      />
    </div>
  );
}

For completion, these are the fetch functions used in the component: UserAPI.getUser() and UserAPI.getUserShouts()

export interface UserResponse {
  data: User;
}

async function getUser(handle: string) {
  const response = await apiClient.get<UserResponse>(`/user/${handle}`);
  return response.data;
}

export interface UserShoutsResponse {
  data: Shout[];
  included: Image[];
}

async function getUserShouts(handle: string) {
  const response = await apiClient.get<UserShoutsResponse>(
    `/user/${handle}/shouts`
  );
  return response.data;
}

What is the problem?

We have the raw response data structures inside the component. But if you think about it, the UI code

shouldn’t care that the User object is returned as response.data
shouldn’t need to know that the shouts are in response.data and the images inside response.included.

Imagine we pass these response data structures to a dozen or more components in a larger project. Now imagine that the API changes the data structure. We’d have to adjust all of those components one by one.

Additionally, the code would be more readable if we wouldn’t have to deal with all those data and included fields anymore. Name it user, shout, or image instead.

To summarize: All this knowledge can be hidden inside the API layer as this is where we deal with API responses and the fetch functions should return the final User, Shout, or Image data structures.

Solution: Use data transformations in the API layer

The goal is to remove all code related to API response data structures from the component.

The solution is to use data transformations in the fetch functions:

export interface UserResponse {
  data: User;
}

async function getUser(handle: string) {
  const response = await apiClient.get<{ data: User }>(`/user/${handle}`);
  // first `.data` comes from axios
  const user = response.data.data;
  return user;
}

export interface UserShoutsResponse {
  data: Shout[];
  included: Image[];
}

async function getUserShouts(handle: string) {
  const response = await apiClient.get<UserShoutsResponse>(
    `/user/${handle}/shouts`
  );
  const shouts = response.data.data;
  const images = response.data.included;
  return { shouts, images };
}

Now the fetch functions return the actual data structures like User, Shout, or Image.

This allows us to remove the response data structures from the component:

export function UserProfile() {
  const { handle } = useParams<{ handle: string }>();

  const [user, setUser] = useState<User>();
  const [shouts, setShouts] = useState<Shout[]>();
  const [images, setImages] = useState<Image[]>([]);
  const [hasError, setHasError] = useState(false);

  useEffect(() => {
    if (!handle) {
      return;
    }

    UserApi.getUser(handle)
      .then((user) => setUser(user))
      .catch(() => setHasError(true));

    UserApi.getUserShouts(handle)
      .then(({ shouts, images }) => {
        setShouts(shouts);
        setImages(images);
      })
      .catch(() => setHasError(true));
  }, [handle]);

  ...

  return (
    <div className="max-w-2xl w-full mx-auto flex flex-col p-6 gap-6">
      <UserInfo user={user} />
      <ShoutList users={[user]} shouts={shouts} images={images} />
    </div>
  );
}

As you can see, all the code related to responses has vanished from the component. Not to forget that we got rid of the nasty data and included fields.

At the same time, the only changes so far are

we returned some nested fields instead of the complete response
we renamed some fields.

Clearly things can be more complex. So let’s look at another example.

Bad Code - Example 2: Data transformations in UI code

Here’s another component of the example project: it’s a feed that shows the newest “Shouts” (aka Tweets) to a user.

import FeedApi from "@/api/feed";
import { LoadingView } from "@/components/loading";
import { ShoutList } from "@/components/shout-list";
import { FeedResponse, Image, User } from "@/types";

export function Feed() {
  const [feed, setFeed] = useState<FeedResponse>();
  const [hasError, setHasError] = useState(false);

  useEffect(() => {
    FeedApi.getFeed()
      .then((feed) => setFeed(feed))
      .catch(() => setHasError(true));
  }, []);
  if (hasError) {
    return <div>An error occurred</div>;
  }
  if (!feed) {
    return <LoadingView />;
  }

  const users = feed.included.filter((u): u is User => u.type === "user");
  const images = feed.included.filter((i): i is Image => i.type === "image");
  return (
    <div className="w-full max-w-2xl mx-auto flex flex-col justify-center p-6 gap-6">
      <ShoutList shouts={feed.data} users={users} images={images} />
    </div>
  );
}

We can again see that the response is stored in the component. And as before the fetch function directly returns the API response data structure.

async function getFeed() {
  const response = await apiClient.get<FeedResponse>("/feed");
  return response.data;
}

What is the problem?

Ok, this looks pretty much like the same problem. Apart from these two lines of code:

const users = feed.included.filter((u): u is User => u.type === "user");
const images = feed.included.filter((i): i is Image => i.type === "image");

Apparently, we again have to deal with an included field. But this time, that array not only contains images but also users. And the above two lines are data transformation logic that separate objects of type user and image.

Meaning we have data transformation logic inside the component.

But the component

- shouldn’t care that the `included` field in the feed response contains users and images
- shouldn’t need to know that it can distinguish the users and images by their `type` field.

Note: You think the response data structure with the data field and the included field with mixed data types looks weird? You might not have encountered the popular JSON:API standard yet.

Solution: Move data transformation logic to the fetch function

Again, the goal is to remove this logic from the component.

The solution is simple: we move the two lines to the fetch function.

import { FeedResponse, Image, User } from "@/types";

import { apiClient } from "./client";

async function getFeed() {
  const response = await apiClient.get<FeedResponse>("/feed");
  const shouts = response.data.data;
  const users = response.data.included.filter(
    (u): u is User => u.type === "user"
  );
  const images = response.data.included.filter(
    (i): i is Image => i.type === "image"
  );
  return { shouts, users, images };
}

export default { getFeed };

Now the fetch function returns the actual data structures User, Shout, and Image and doesn’t expose API responses to the UI code anymore.

The component becomes a lot simpler:

import { useEffect, useState } from "react";

import FeedApi from "@/api/feed";
import { LoadingView } from "@/components/loading";
import { ShoutList } from "@/components/shout-list";
import { Image, Shout, User } from "@/types";

export function Feed() {
  const [feed, setFeed] = useState<{
    shouts: Shout[];
    images: Image[];
    users: User[];
  }>();
  const [hasError, setHasError] = useState(false);

  useEffect(() => {
    FeedApi.getFeed()
      .then((feed) => setFeed(feed))
      .catch(() => setHasError(true));
  }, []);

  if (hasError) {
    return <div>An error occurred</div>;
  }

  if (!feed) {
    return <LoadingView />;
  }
  return (
    <div className="w-full max-w-2xl mx-auto flex flex-col justify-center p-6 gap-6">
      <ShoutList shouts={feed.shouts} users={feed.users} images={feed.images} />
    </div>
  );
}

Now the component directly gets the users, shouts, and images. It has no knowledge of the API responses anymore.

Great, our code becomes more streamlined. But so far we only focused on response data. What about input data like request bodies?

Bad Code - Example 3: Transformation of input data

Here’s yet another component: A dialog that allows the user to reply to another user’s shout (aka tweet).

import MediaApi from "@/api/media";
import ShoutApi from "@/api/shout";
import UserApi from "@/api/user";

...

export function ReplyDialog({ children, shoutId }: ReplyDialogProps) {
  const [open, setOpen] = useState(false);
  const [isLoading, setIsLoading] = useState(true);
  const [isAuthenticated, setIsAuthenticated] = useState(false);
  const [hasError, setHasError] = useState(false);

  ...

  async function handleSubmit(event: React.FormEvent<ReplyForm>) {
    event.preventDefault();
    setIsLoading(true);
    try {
      const message = event.currentTarget.elements.message.value;
      const files = event.currentTarget.elements.image.files;
      let imageId = undefined;
      if (files?.length) {
        const formData = new FormData();
        formData.append("image", files[0]);
        const image = await MediaApi.uploadImage(formData);
        imageId = image.data.id;
      }
      const newShout = await ShoutApi.createShout({
        message,
        imageId,
      });
      await ShoutApi.createReply({
        shoutId,
        replyId: newShout.data.id,
      });
      setOpen(false);
    } catch (error) {
      console.error(error);
    } finally {
      setIsLoading(false);
    }
  }

  // a form using the handleSubmit function is rendered here
  return (
    ...
  );
}

The chained requests are a problem for the future. Here we focus on the preparation of the input data. Particularly, the image upload.

What is the problem?

It appears that the MediaApi expects the image to be added to a FormData object.

But is this something the component should be concerned with?
Why should it matter to the UI code whether the image is uploaded using form data or any other mechanism?

Let’s imagine we wanted to switch to another cloud storage like AWS S3? We’d most likely have to adjust the component code as well.

And since other places like the user profile are likely to upload images as well we’d have to adjust multiple parts of the codebase just because the underlying image storage changed.

We can do better.

Solution: Move transformation of input data to API layer

Similar to the previous examples, let’s move the data transformation to the API layer. Here’s the adjusted MediaApi.uploadImage() function:

import { Image } from "@/types";

import { apiClient } from "./client";

async function uploadImage(file: File) {
  const formData = new FormData();
  formData.append("image", file);

  const response = await apiClient.post<{ data: Image }>("/image", formData);
  const image = response.data.data;
  return image;
}

export default { uploadImage };

The fetch function in the API layer now expects a File as input. The exact upload mechanism is hidden from the component.

This simplifies the component code quite a bit:

export function ReplyDialog({ children, shoutId }: ReplyDialogProps) {
  const [open, setOpen] = useState(false);
  const [isLoading, setIsLoading] = useState(true);
  const [isAuthenticated, setIsAuthenticated] = useState(false);
  const [hasError, setHasError] = useState(false);

  ...

  async function handleSubmit(event: React.FormEvent<ReplyForm>) {
    event.preventDefault();
    setIsLoading(true);
    try {
      const message = event.currentTarget.elements.message.value;
      const files = event.currentTarget.elements.image.files;
      let image;
      if (files?.length) {
        image = await MediaApi.uploadImage(files[0]);
      }
      const newShout = await ShoutApi.createShout({
        message,
        imageId,
      });
      await ShoutApi.createReply({
        shoutId,
        replyId: newShout.data.id,
      });
      setOpen(false);
    } catch (error) {
      console.error(error);
    } finally {
      setIsLoading(false);
    }
  }

  // a form using the handleSubmit function is rendered here
  return (
    ...
  );
}

The component is still responsible getting the files from the event target and passing only the first one files[0] to the media API. The rest of the heavy lifting is handled by the API.

Next refactoring steps

We took another step closer towards a cleaner React architecture. Data transformations are now handled by the API layer.

But there’s still room for improvement. For example, the fetch functions still pass the data structures User, Shout, or Image as they are returned from the API.

And look at this example. Ain’t pretty, right?

{
    "id": "shout-1",
    "type": "shout",
    "createdAt": 1713455132695,
    "attributes": {
        "authorId": "user-1",
        "text": "The world sucks!!!!",
        "likes": 5,
        "reshouts": 0
    },
    "relationships": {
        "replies": [
            "shout-3"
        ]
    }
}

In the next article, we will introduce a domain layer that will help us get rid of this complexity.

Path To A Clean(er) React Architecture - API Layer & Fetch Functions

Johannes Kettmann — Fri, 26 Apr 2024 12:04:00 +0000

The unopinionated nature of React is a two-edged sword:

On the one hand you get freedom of choice.
On the other hand many projects end up with a custom and often messy architecture.

This article is the second part of a series about software architecture and React apps where we take a code base with lots of bad practices and refactor it step by step.

Previously, we extracted an API client to share common configuration like the API base URL between all requests in the application.

In this article, we want to focus on separating API related code from the UI components.

Bad Code: Mixed API and UI code

Let’s have a look at the bad code example. Here’s the result of the first refactoring step from the previous article: a component that fetches data from two API endpoints and renders the data.

import { useEffect, useState } from "react";
import { useParams } from "react-router";
import { apiClient } from "@/api/client";
import { LoadingSpinner } from "@/components/loading";
import { ShoutList } from "@/components/shout-list";
import { UserResponse, UserShoutsResponse } from "@/types";
import { UserInfo } from "./user-info";

export function UserProfile() {
  const { handle } = useParams<{ handle: string }>();

  const [user, setUser] = useState<UserResponse>();
  const [userShouts, setUserShouts] = useState<UserShoutsResponse>();
  const [hasError, setHasError] = useState(false);

  useEffect(() => {
    apiClient
      .get<UserResponse>(`/user/${handle}`)
      .then((response) => setUser(response.data))
      .catch(() => setHasError(true));

    apiClient
      .get<UserShoutsResponse>(`/user/${handle}/shouts`)
      .then((response) => setUserShouts(response.data))
      .catch(() => setHasError(true));
  }, [handle]);

  if (hasError) {
    return <div>An error occurred</div>;
  }

  if (!user || !userShouts) {
    return <LoadingSpinner />;
  }

  return (
    <div className="max-w-2xl w-full mx-auto flex flex-col p-6 gap-6">
      <UserInfo user={user.data} />
      <ShoutList
        users={[user.data]}
        shouts={userShouts.data}
        images={userShouts.included}
      />
    </div>
  );
}

Why is this code bad?

It’s simple: API requests and UI code are mixed. A bit of API code here, a bit of UI there.

But in fact, for the UI it shouldn’t matter how it get’s the data:

- It shouldn’t care whether a GET, a POST, or a PATCH request is sent.
- It shouldn’t care what the exact path of the endpoint is.
- It shouldn’t care how the request parameters are passed to the API.
- It shouldn’t even really care whether it connects to a REST API or a websocket.

All of this should be an implementation detail from the perspective of the UI.

Solution: Extract functions that connect to the API

Extracting functions that connect to the API to a separate place will greatly help decouple API related code from UI code.

These functions will hide the implementation details like

- the request method
- the endpoint path or
- the data types.

In order to have a clear separation we will locate these functions in a global API folder.

// src/api/user.ts

import { User, UserShoutsResponse } from "@/types";
import { apiClient } from "./client";

async function getUser(handle: string) {
  const response = await apiClient.get<{ data: User }>(`/user/${handle}`);
  return response.data;
}

async function getUserShouts(handle: string) {
  const response = await apiClient.get<UserShoutsResponse>(
    `/user/${handle}/shouts`
  );
  return response.data;
}

export default { getUser, getUserShouts };

Now we use these fetch functions inside the component.

import UserApi from "@/api/user";

...

export function UserProfile() {
  const { handle } = useParams<{ handle: string }>();

  const [user, setUser] = useState<User>();
  const [userShouts, setUserShouts] = useState<UserShoutsResponse>();
  const [hasError, setHasError] = useState(false);

  useEffect(() => {
    if (!handle) {
      return;
    }

    UserApi.getUser(handle)
      .then((response) => setUser(response.data))
      .catch(() => setHasError(true));

    UserApi.getUserShouts(handle)
      .then((response) => setUserShouts(response))
      .catch(() => setHasError(true));
  }, [handle]);

  ...

Why is this code better? Decoupling of UI and API code

You’re right. The code changes aren’t huge. We basically moved a bit of code around. The result might initially look like somewhat cleaner component code.

// before
apiClient.get<UserResponse>(`/user/${handle}`)

// after
UserApi.getUser(handle)

But in fact, we started to effectively decouple the UI code from API related functionality.

I’m not getting tired of repeating myself: now the component doesn’t know a lot of API related details like

- the request method `GET`
- the definition of the data type `UserResponse`
- the endpoint path `/user/some-handle`
- or that the handle is passed to the API as URL parameter.

Instead it calls a simple function UserApi.getUser(handle) that returns a typed result wrapped in a promise.

Additionally, we can reuse these fetch functions in multiple components or for different rendering approaches like client-side or server-side rendering.

Next refactoring steps

Yes, we took a big step forward separating our UI code from the API. We introduced an API layer and removed many implementation details from the UI component.

But we still have considerable coupling between the API layer and our components. For example, we transform the response data inside the components:

Now, this might not be the most impressive example. So let’s look at another one from the same code base:

Here we can see how the response of the feed has an included field that contains users and images.

Not pretty, but sometimes we have to deal with such APIs.

But why should the component know?

Anyway, we’ll deal with that in the next article.

Path To A Clean(er) React Architecture - A Shared API Client

Johannes Kettmann — Fri, 12 Apr 2024 11:24:35 +0000

The unopinionated nature of React is a two-edged sword:

On the one hand you get freedom of choice.
On the other hand many projects end up with a custom and often messy architecture.

This article is the beginning of a series about software architecture and React apps where we take a code base with lots of bad practices and refactor it step by step.

Here we start by extracting common API request configuration from components to a shared API client. The changes to the code are small, but the impact on maintainability over the long run will be huge. Let’s start by looking at a code example.

Bad code: Hard-coded API request configuration all over the place
Why is this code bad?
Solution: A shared API client
Why is this code better?
Next refactoring steps: Introducing an API layer
PS: Shared API client with fetch

As an alternative to the text based content below you can also watch this video.

Bad code: Hard-coded API request configuration all over the place

Here is one component of the example project: a component that fetches data from two API endpoints and renders the data.

This is just one component but there are many more API calls in the code.

import axios from "axios";
import { useEffect, useState } from "react";
import { useParams } from "react-router";

import { LoadingSpinner } from "@/components/loading";
import { ShoutList } from "@/components/shout-list";
import { UserResponse, UserShoutsResponse } from "@/types";

import { UserInfo } from "./user-info";

export function UserProfile() {
  const { handle } = useParams<{ handle: string }>();

  const [user, setUser] = useState<UserResponse>();
  const [userShouts, setUserShouts] = useState<UserShoutsResponse>();
  const [hasError, setHasError] = useState(false);

  useEffect(() => {
    axios
      .get<UserResponse>(`/api/user/${handle}`)
      .then((response) => setUser(response.data))
      .catch(() => setHasError(true));

    axios
      .get<UserShoutsResponse>(`/api/user/${handle}/shouts`)
      .then((response) => setUserShouts(response.data))
      .catch(() => setHasError(true));
  }, [handle]);

  if (hasError) {
    return <div>An error occurred</div>;
  }

  if (!user || !userShouts) {
    return <LoadingSpinner />;
  }

  return (
    <div className="max-w-2xl w-full mx-auto flex flex-col p-6 gap-6">
      <UserInfo user={user.data} />
      <ShoutList
        users={[user.data]}
        shouts={userShouts.data}
        images={userShouts.included}
      />
    </div>
  );
}

Why is this code bad?

This code uses the same setup for each API request (here the base path /api as example).

The problem: if we changed the API to e.g. use a different version in the path like /api/v2 we’d have to change every request. If we wanted to add an application-wide header (e.g. for authentication) we’d have to add it everywhere.

This is unmaintainable especially in larger projects with lots of API calls.

Additionally any change to API requests in general would come with a risk that we’d miss updating one of the requests and break parts of the application.

But what’s the solution?

Solution: A shared API client

Sharing the foundational request config between all requests is key. To achieve this we first extract all axios references to a shared file.

// /src/api/client.ts

import axios from "axios";

export const apiClient = axios.create({
  baseURL: "/api",
});

This is just a simple example. We could add more common configuration to this api client like application-wide headers or logic that passes a token from local storage to the request.

Anyway.

Now we use our new API client in the component.

import { apiClient } from "@/api/client";

...

export function UserProfile() {
  const { handle } = useParams<{ handle: string }>();

  const [user, setUser] = useState<UserResponse>();
  const [userShouts, setUserShouts] = useState<UserShoutsResponse>();
  const [hasError, setHasError] = useState(false);

  useEffect(() => {
    apiClient
      .get<UserResponse>(`/user/${handle}`)
      .then((response) => setUser(response.data))
      .catch(() => setHasError(true));

    apiClient
      .get<UserShoutsResponse>(`/user/${handle}/shouts`)
      .then((response) => setUserShouts(response.data))
      .catch(() => setHasError(true));
  }, [handle]);

  ...
}

You’re right, this doesn’t seem like a big change, so…

Why is this code better?

Let’s imagine this scenario: the API base path changes from /api to /api/v2.

This is common when breaking changes have to be introduced in the API. With our shared API client we only need to update a single line in the code.

// /src/api/client.ts

import axios from "axios";

export const apiClient = axios.create({
  baseURL: "/api/v2",
});

And as mentioned, we could easily add app-wide headers or even middleware to e.g. copy a token from local storage to the request headers.

Not only that! We also started to isolate the UI code from the API. Fetching data became a bit simpler:

apiClient.get<UserResponse>(`/user/${handle}`)

Now the UI

doesn’t know about the base path /api
doesn’t know that we use Axios for data fetching.

These are implementation details that the UI shouldn’t care about.

While these are important changes we’re far from done yet.

Next refactoring steps: Introducing an API layer

Ok, the shared API client already improved the code big time.

But if you think the code still doesn’t look good, I agree with you. Using a shared API client we started to decouple our UI from API related code.

But look how much knowledge about the API is still inside the component!

In the upcoming weeks, we’ll continue this refactoring journey to a clean(er) React architecture.

PS: Shared API client with fetch

While I used axios in this example there’s no requirement for it.

In fact, axios adds to your app’s bundle size while fetch is supported natively. So there’s good reason to ditch it.

fetch unfortunately doesn’t come with the same convenience though so we need a bit more code to create a sharable “instance”.

const API_BASE_URL = '/api';

export const apiClient = async (endpoint, options = {}) => {
  const config = {
    method: 'GET', // Default to GET method
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...(options.headers || {}),
    },
  };

  return fetch(`${API_BASE_URL}${endpoint}`, config);
};

This API client function ensures a default setup for each request while keeping the overall fetch API intact.

It might be worth creating a more abstract API client though. For example, you can also create a more Axios-like API with a JavaScript class.

class APIClient {
  constructor(baseURL) {
    this.baseURL = baseURL;
  }

  async request(url, options) {
    const response = await fetch(`${this.baseURL}${url}`, options);
    if (!response.ok) {
      const error = new Error('HTTP Error');
      error.status = response.status;
      error.response = await response.json();
      throw error;
    }
    return response.json();
  }

  get(url) {
    return this.request(url, {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
      },
    });
  }

  post(url, data) {
    return this.request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    });
  }

  // You can add more methods (put, delete, etc.) here as needed
}

export const apiClient = new APIClient('/api');

This API client can now be used like below.

import { apiClient } from './apiClient';

// To make a GET request to `/api/user/some-user-handle
apiClient.get('/user/some-user-handle')
  .then(data => console.log(data))
  .catch(error => console.error('Fetching user failed', error));

// To make a POST request
apiClient.post('/login', { username: "some-user", password: "asdf1234" })
  .then(data => console.log(data))
  .catch(error => console.error('Login failed', error));

React useEffect and objects as dependency - 4 approaches to avoid unnecessary executions

Johannes Kettmann — Fri, 22 Mar 2024 13:34:00 +0000

React’s useEffect hook can lead to tricky situations. If you’re not careful it can cause unnecessary executions of the effect or even infinite re-renders. Especially when using objects as dependencies.

In this blog post, you'll see four different approaches to using an object as a useEffect dependency. All have their pros and cons, from being simple yet ineffective, to ugly yet efficient.

The problem
Approach 1: Spread object values
Approach 2: Manually pass each value
Approach 3: Third-party useDeepCompareEffect hook
Approach 4: Stringifying the object
Summary

The problem

Let me walk you through a simplified example I encountered while working on a coding task.

function useGetProducts(filters: Record<string, string>) {
  useEffect(() => {
    syncFilters(filters);
  }, [filters]);

  // ... rest of the hook
}

function ProductList() {
  const products = useGetProducts({ brand: "Nike", color: "red" });
  return (
    <div>
      {products.map((p) => (
        <ProductCard key={p.id} {...p} />
      ))}
    </div>
  );
}

Now, at first glance, this looks all fine. However, using the params object as a dependency of the useEffect is problematic.

Can you see it?

Have a look at how we pass the filters object from the ProductList component to theuseGetProducts hook.

function ProductList() {
  const products = useGetProducts({ brand: "Nike", color: "red" });
  ...

During each render, this object is created from scratch. The useEffect internally compares the dependencies by reference. And since the reference to the filters object is different for each render, the effect would be run with every render as well.

This is less than ideal, but not that easy to spot.

Approach 1: Spread object values

A simple solution is to spread all values of this object as dependencies.

function useGetProducts(filters: Record<string, string>) {
  useEffect(() => {
    syncFilters(filters);
  }, [...Object.values(filters)]);

  // ... rest of the hook
}

Technically, this isn't problematic, because the effect is run whenever one of the values of the params object changes. But we get a lint warning, and would have to disable it to commit our code.

While disabling warnings isn't necessarily a huge problem, this could lead us to forget about a missing dependency later if we, for example, add another filter. This could then lead to a hard-to-find bug.

Approach 2: Manually pass each value

Another approach is to destructure each filter and pass it as a separate dependency.

function useGetProducts(filters: Record<string, string>) {
  const { brand, color } = filters;
  useEffect(() => {
    syncFilters({ brand, color });
  }, [brand, color]);

  // ... rest of the hook
}

But this is a bit tedious, and we might forget to add a new parameter if new filters are introduced. Also, in our case, this doesn’t really work as the filters object could contain any string as key.

Approach 3: Third-party useDeepCompareEffect hook

Another approach is using this useDeepCompareEffect created by Kent C. Dodds. This hook is similar to the native useEffect, but instead of comparing the dependencies by reference, it makes a deep comparison of all values inside an object.

Let's give it a try. First, we install the dependency.

npm i use-deep-compare-effect

Then, we replace the useEffect with a new useDeepCompareEffect hook. We can now simply pass the filters object as a dependency, and the effect won't be run on every render anymore.

function useGetProducts(filters: Record<string, string>) {
  useDeepCompareEffect(() => {
    syncFilters(filters);
  }, [filters]);

  // ... rest of the hook
}

The problem with this hook? When we remove a required dependency like the params object, we don't get a lint warning about missing dependencies.

So, this isn't really better than our destructuring approach before.

Approach 4: Stringifying the object

A final approach that I saw Dan Abramov recommend somewhere is stringifying the object and parsing it again inside the useEffect.

function useGetProducts(filters: Record<string, string>) {
  const json = JSON.stringify(filters);
  useEffect(() => {
    const filters = JSON.parse(json);
    syncFilters(filters);
  }, [json]);

  // ... rest of the hook
}

This works well with small and not too deeply nested objects that don't contain function values. Honestly, it doesn't look that great, but combines all of the advantages: It decreases the risk of forgetting to add filters and the risk of forgetting to add a dependency in the future. All while keeping the ESLint check intact.

The main problem with this approach is that we lose the type of the filters object inside the useEffect.

So inside the useEffect we need to manually assign the type again.

function useGetProducts(filters: Record<string, string>) {
  const json = JSON.stringify(filters);
  useEffect(() => {
    const filters: Record<string, string> = JSON.parse(json);
    syncFilters(filters);
  }, [json]);

  // ... rest of the hook
}

Summary

A useEffect in React can be tricky. Especially when you need to use an object as a dependency. In this blog post we covered 4 techniques to avoid unnecessary executions of the effect by

spreading the object values
manually adding the values
using the third-party useDeepCompareEffect
stringifying the object.

All approaches have their pros and cons and it depends on the situation which one makes most sense for you.

React Code Review - Unraveling A Tightly Coupled Component & Mixed Responsibilities (Incl Video)

Johannes Kettmann — Sat, 09 Mar 2024 13:05:00 +0000

This blog post is a code review of a pull request from a student of the React Job Simulator.

We’ll see how the filter component in the screenshot below is tightly coupled to the pagination of its parent component.

After the code review, we’ll refactor the component to unravel this coupling so each component focuses on its own responsibilities.

The Task
The Code
Tight Coupling Of The Filter Component To Its Parent
Refactoring The Filter Component
Refactoring The Parent Component
Summary

If you'd rather watch the video version of this code review here you go.

The Task

The page in the screenshot above shows a list of issues. This list is paginated, meaning it only shows some of the issues immediately. The user needs to navigate to the next page of the list to see the next set of issues.

The student's task here was to implement the filter at the top.

The filter has three fields. Two select inputs, so the user can filter for a certain issue status and level, plus a text input that allows filtering for a project name.

The Code

This is the Filter component as it was implemented by my student.

import { useEffect, useState } from "react";
import { Level, Status } from "@api/issues.types";
import { useFilter } from "../context/filter-context";
import styles from "./filter.module.scss";

interface FilterProps {
  navigateToPage: (
    newPage: number,
    status: Status,
    Level: Level,
    projectName: string,
  ) => void;
}

export function Filter({ navigateToPage }: FilterProps) {
  const { setStatus, setLevel, setProjectName, status, level, projectName } =
    useFilter();
  const [name, setName] = useState(projectName);

  useEffect(() => {
    if (projectName === "") setName("");
  }, [projectName]);

  return (
    <form
      className={styles.filter}
      onSubmit={(e) => {
        e.preventDefault();
        if (setStatus && setLevel && setProjectName) {
          setStatus(status);
          setLevel(level);
          setProjectName(projectName);
        }
        navigateToPage(1, status, level, name);
      }}
    >
            {/* THE FILTER INPUTS */}
        </form>
    );
}

The code looks solid. Let’s start dissecting it step by step.

const { setStatus, setLevel, setProjectName, status, level, projectName } =
    useFilter();

The component uses a custom hook that returns the filter values and allows updating them. This is a great approach as all the logic for handling the filters is encapsulated in this hook. The component doesn’t care whether the values are stored in a local state, context, or the URL.

Let’s move to the next lines:

const [name, setName] = useState(projectName);

useEffect(() => {
  if (projectName === "") setName("");
}, [projectName]);

For some reason, the project name filter is stored in a separate state variable, which is initialized with a value returned from the custom hook. The state is also updated by the useEffect, specifically when the project name is empty. I'm not sure why this is necessary, so usually I’d dig a bit deeper. But since it's not the main concern of this review, let's ignore it here.

return (
  <form
    className={styles.filter}
    onSubmit={(e) => {
      e.preventDefault();
      if (setStatus && setLevel && setProjectName) {
        setStatus(status);
        setLevel(level);
        setProjectName(projectName);
      }
      navigateToPage(1, status, level, name);
    }}
  >
        {/* THE FILTER INPUTS */}
    </form>
);

The filter inputs are wrapped in a form with a submit handler attached. The handler updates the filter values by calling the functions returned by the custom hook. After updating the filter values, the navigateToPage function is called. It sets the page to 1 and passes the new filter values.

So it seems that this code is responsible for resetting the pagination to the first page of the issue list whenever the filter values change.

Tight Coupling Of The Filter Component To Its Parent

Since the navigateToPage function is a prop, this is where the Filter component is coupled to its parent. Besides this function, there's nothing that connects the Filter component to the pagination of the issue list.

If you think about it there’s actually no reason why resetting the pagination should be the responsibility of the Filter component. It doesn’t “know” that it’s used on a paginated page. And it should be possible to use it on a page without pagination.

Refactoring The Filter Component

The idea of the following refactoring is that the resetting of the pagination should be the responsibility of the parent. This again will decouple the filter component from the rest of the page.

The first step is to rename the prop. onFilterChange is a much more neutral name that moves the responsibility for any action triggered by a filter change to the parent.

export function Filter({ onFilterChange }: FilterProps) {

return (
  <form
    onSubmit={(e) => {
      // ...
      onFilterChange(1, status, level, name);
    }}
  >

The new name already suggests that we should only pass the filters to the onFilterChange callback. So let's remove the new page param.

<form
  onSubmit={(e) => {
    // ...
    onFilterChange(status, level, name);
  }}
>

Now we decoupled the pagination functionality from the filter updates in this component.

It might look like a small change, but the filter component is now much more "pure". We could use it now in other places that have nothing to do with pagination.

My next suggestion is to group the filters in one object instead of splitting them into separate parameters.

<form
  onSubmit={(e) => {
    // ...
    onFilterChange({ status, level, name });
  }}
>

This way it'll be much easier to add new filter parameters in the future.

This change also enables another valuable refactoring. We can introduce a shared Filters type that can be reused by other parts of the app.

interface Filters {
  status: Status;
  level: Level;
  projectName: string;
}

interface FilterProps {
  onFilterChange: ({ status, level, projectName }: Filters) => void;
}

I added the type to the component file here, but I'd recommend moving it to a higher level. This way it's obvious that it's a shared type and can be used by other parts of the app and different layers like the API requests as well.

Refactoring The Parent Component

Finally, we need to adjust the parent component as well. In this case, it's the IssueList component.

import { useRouter } from "next/router";
import type { Level, Query, Status } from "@api/issues.types";
import { Filter } from "../filter";
import styles from "./issue-list.module.scss";

export function IssueList() {
  const router = useRouter();

  const page = Number(router.query.page || 1);
  const navigateToPage = (
    newPage: number,
    status: Status,
    level: Level,
    projectName: string,
  ) => {
    const query: Query = { page: newPage };
    if (status) query.status = status;
    if (level) query.level = level;
    if (projectName) query.project = projectName;

    router.push({
      pathname: router.pathname,
      query: { ...query },
    });
  };

  return (
    <div>
      <div className={styles.issueOptions}>
        <Filter onFilterChange={navigateToPage} />
      </div>
            {/* THE REST OF THE COMPONENT HERE */}

The first change is to use the shared Filter type.

import { Filter, type Filters } from "../filter";

export function IssueList() {
  // ...

  const navigateToPage = (
    newPage: number,
    filters: Filters,
  ) => {
    const { status, level, projectName } = filters;
    const query: Query = { page: newPage };
    if (status) query.status = status;
    if (level) query.level = level;
    if (projectName) query.project = projectName;

    router.push({
      pathname: router.pathname,
      query: { ...query },
    });
  };

You can see that it's much neater, as we don't have to redefine the type of the filters all over again.

The next problem is that the navigateToPage function isn’t just updating the page but the filter values in the URL as well. That should be the responsibility of the Filter component or the custom useFilters hook. So let’s adjust that.

const navigateToPage = (newPage: number) => {
  router.push({
    pathname: router.pathname,
    query: { 
            ...router.query,
            page: newPage,
        },
  });
};

Now this looks a lot cleaner. The navigateToPage function really only updates the page while copying the existing URL query parameters.

The last step is to adjust the props we pass to the Filter component.

<Filter onFilterChange={navigateToPage} />

We can't directly pass the navigateToPage function anymore. Instead, we use an inline function that accepts the filters and passes them onto navigateToPage, along with a new page value of 1.

<Filter onFilterChange={() => navigateToPage(1)} />

Again, here we can see that we introduced a clear separation of concerns.

The filter component is responsible for handling the filters, while the IssueList component is responsible for any action after the filters are updated, like resetting the page to 1.

Summary

In this code review, we saw that the filter component was tightly coupled to the pagination of the issue list. These couplings aren’t easy to spot. And in this case, the refactoring wasn't huge. But removing unnecessary coupling in your code can have huge effects on maintainability in the long run.

I hope you enjoyed this small code review and refactoring session. I’m planning to turn this into a series of code reviews. So if you're interested in getting a review of your own code, leave a comment with a screenshot of the code or a link to a GitHub repository or a pull request below the video mentioned at the top.

And, if you want to get hands-on experience on a production-grade codebase and professional workflows, join the React Job Simulator.

React Riddles: The Mysterious Case of the Untracked Clicks

Johannes Kettmann — Fri, 21 Jul 2023 11:00:00 +0000

In this series, you confront real-world React mysteries. It's an opportunity to test your skills and flex your debugging muscles on realistic problems that you could encounter on the job and during job interviews.

Recently, I encountered a perplexing bug affecting our analytics data on my day job. We noticed something strange - in certain instances, our tracking events would fire up perfectly, but at other times, they wouldn't activate at all. It was a mysterious problem that needed solving, and it all started with the way we were tracking clicks on a button.

If you’re rather a video person you can watch the complete review and refactoring session here.

The Mystery

Allow me to share an example of our button tracking code for better clarity (you can find the complete code here on StackBlitz):

import { useRef } from "react";
import { useTracking } from "./use-tracking";
import { Button } from "./button";
import { ReactComponent as EditIcon } from "./edit.svg";

export function User() {
  const containerRef = useRef<HTMLDivElement>(null);
  useTracking(containerRef, "user-profile", { authStatus: "authenticated" });

  return (
    <div ref={containerRef}>
      <Button data-tracking-id="edit">Edit</Button>
      <Button data-tracking-id="edit-icon" icon={<EditIcon />} />
    </div>
  );
}

This tracking system relied on a useTracking hook. To keep things simple, I'll share a more straightforward version of it:

import { MutableRefObject, useEffect } from "react";

export function useTracking(
  containerRef: MutableRefObject<HTMLElement | null>,
  containerId: string,
  trackingParams?: Record<string, string>
) {
  useEffect(() => {
    // container not yet mounted
    if (!containerRef.current) {
      return;
    }
    const container = containerRef.current;

    // the callback that sends the tracking event
    const listener = (event: Event) => {
      // get the tracking id from the data attribute (e.g. data-tracking-id="button-1")
      const target = event.target as HTMLElement;
      const trackingId = target.dataset.trackingId;

      // Send tracking event
      if (trackingId) {
        console.log(`Tracking ${containerId} ${trackingId}`);
        window.tracking.push([containerId, trackingId, trackingParams]);
      }
    };

    container.addEventListener("click", listener);
    return () => {
      container.removeEventListener("click", listener);
    };
  }, [containerRef, containerId, trackingParams]);
}

This system worked like a charm, that is, until we started incorporating more icon buttons:

export function User() {
  const containerRef = useRef<HTMLDivElement>(null);
  useTracking(containerRef, "user-profile", { authStatus: "authenticated" });

  return (
    <div ref={containerRef}>
      <Button data-tracking-id="edit">Edit</Button>
      <Button data-tracking-id="edit-icon" icon={<EditIcon />} />
    </div>
  );
}

And then, our mysterious bug reared its ugly head: why on earth was the tracking event firing for the text button but not for the icon button?

Let's dig into this curious issue in the next section.

A Quick Note Before We Begin

As you venture into this blog post, I encourage you to treat it not just as a read, but as an interactive exercise. As we journey through a real-world bug in our code, try to come up with your own solutions before you continue to the next section. Trust me; it's more fun and informative this way!

This isn't just a casual recommendation. The problem at hand is similar to those you might encounter during a job interview for a developer role. Working through it on your own will give you a taste of real-world challenges and offer valuable practice for such scenarios. It's not just about the specific bug; it's also about flexing those problem-solving muscles and honing your analytical skills.

Moreover, this exercise even incorporates a touch of algorithmic thinking - a vital skill in the realm of programming. So put on your thinking caps and dive right in. Let's crack this bug together!

Debugging the Issue

Debugging in the world of programming can be a complex task, but the most straightforward way to begin here is to set a breakpoint using Chrome dev tools. This allows us to observe the behavior of our code while it's running and catch any irregularities.

When we click on the “Edit” text button, we see that the trackingId is indeed defined, which enables the tracking event to fire as expected.

However, a different story unfolds when we click on the icon button: the trackingId comes out as undefined.

So, why isn’t the `trackingId` defined when clicking on the icon button?

Here's a bit of a mystery for you. Can you figure out the answer before moving on?

Unmasking the culprit

It took me a bit to grasp this during my investigation, but the answer lies in the specifics of the click event. When we click on the SVG icon, we're actually interacting with the SVG element itself.

But here's the catch: our tracking ID isn't set on the SVG element - it's set on the button, which is the parent element.

So, how can we solve this?

I encourage you to give it a shot before moving forward.

This could well be one of these real-world algorithm questions you’ll ask in a job interview!

First, let's understand how the useTracking hook works

In our component, we pass a reference to the container element to the hook.

Within the hook, we attach a click listener to this container.

Now, it's crucial to note that this listener isn't triggered only when we click on the container element itself. Due to the bubbling nature of events in JavaScript, this listener is activated for any clicks on its child elements. So, if we click one of the buttons, the click event propagates to the container, triggering the listener. Inside this listener, we retrieve the data attribute trackingId from the event target and only fire the tracking event if trackingId is defined.

Here's where the issue arises: when we click the text button, the event target is the button element, which possesses a tracking ID. However, when we click on the icon inside the button, the event target becomes the svg element, which doesn't have a tracking ID.

Now that we've outlined the issue, we can move on to the solution. But are you sure you don't want to give it a shot on your own first?

The solution: Recursion to the rescue

The first thought you might have is to check both the event target and its parent element for a tracking ID. You're on the right track, but there's a twist: if you click on the icon button often enough, you might hit the path element within the svg. In this case, the parent’s parent would be the element with the tracking ID.

We want to create a tracking hook that works universally, even with complex elements like clickable cards that have many nested child elements. The solution? Use a recursive approach to explore each parent element of the original event target until we locate an element with a data-tracking-id attribute.

function getTrackingId(element: HTMLElement | null) {
  // Stop condition: the previous element doesn't have a parent.
  // We're at the root of the tree.
  if (!element) {
    return null;
  }
  const trackingId = element.dataset.trackingId;
  // Stop condition: we return when the element has a tracking ID
  if (trackingId) {
    return trackingId;
  }
  // continue recursively traversing the tree
  return getTrackingId(element.parentElement);
}

Now, we can use this function to retrieve the tracking ID from any parent element.

export function useTracking(
  ...

  useEffect(() => {
    const listener = (event: Event) => {
      const target = event.target as HTMLElement;

      // use the new recursive function to get the tracking ID from
      // any parent element
      const trackingId = getTrackingId(target);

      if (trackingId) {
        console.log(`Tracking ${containerId} ${trackingId}`);
        window.tracking.push([containerId, trackingId, trackingParams]);
      }
    };

    ...

And voila, it works!

However, this recursive approach does come with a minor drawback. Suppose we click on a child of a tracking container that we don't want to track. In that case, we'll still traverse all the parent elements even though we're not interested in this click event. For some apps, this might cause performance issues. However, for most apps, this should be manageable, as there typically aren't thousands of parent elements to go through.

A Sneak Peek at What's Next

Just when you think we've squashed that bug and our code is as clean as a whistle, a wild mystery appears! Yes, you heard it right. Hidden within the nooks and crannies of our code is another bug, patiently waiting to be discovered.

But worry not! We're not going to leave you hanging. This intrigue sets the stage for our next blog post, where we'll embark on yet another bug-hunting adventure. We'll take our detective hats out once again and get down to dissecting this elusive code miscreant.

So, stay tuned and gear up for another round of digital troubleshooting. We'll dig deeper, learn more, and emerge victorious once again in our journey through the fascinating world of code! Until then, happy coding!

You got the job! Now what? - Strategies to pass the probation period

Johannes Kettmann — Fri, 26 May 2023 11:30:00 +0000

In today's increasingly digital world, a significant number of junior developers are vying for coveted roles in the tech industry. The competition is steep, with computer science graduates, bootcamp alumni, and self-taught developers all striving for the same opportunities. As a result, you may find yourself sending out hundreds of applications, only to receive a handful of responses in return.

When you do finally land a job offer, it often comes with a probation period, typically ranging from one to six months. This is the employer's chance to see your skills in action, to ascertain if you are indeed a good fit for their team. But it's also your time to prove your worth. If you don't meet the mark, the harsh reality is that it's relatively easy for them to let you go.

That said, securing that first job and successfully navigating through the probation period can have a substantial impact on your career trajectory. Once you've gained a year or two of experience, landing subsequent jobs becomes exponentially easier. So, this initial phase can be seen as a crucial stepping stone to a prosperous career in tech.

However, an important question arises here: how do you ensure your survival through this probation period? The truth is, it depends.

What You Can Expect on Your First Job
1. Scenario One: Proper Onboarding Including Mentoring
2. Scenario Two: No Structured Onboarding, but a Helpful Team
3. Scenario Three: Being Thrown into the Deep End
Practical Steps to Ensure Success During Your Probation Period
1. Preparation before your first day: Reducing cognitive load
2. The first days on the job: Clarify expectations and establish a timeline
3. Striking the Right Balance Between Asking for Help and Becoming Independent
4. Humility Over Arrogance
Conclusion

What You Can Expect on Your First Job

The experience you'll have during your probation period is heavily influenced by several factors, including the team you join, its size, resources, and its onboarding, management, and mentoring practices. To illustrate this, let's consider three different scenarios through the experiences of three junior developers: Sam, Maria, and David.

Scenario One: Proper Onboarding Including Mentoring

Sam's journey starts in a team where there is a well-structured onboarding process, including mentoring. He begins by shadowing and pair-programming with more experienced developers. This direct experience with senior colleagues allows him to learn quickly, absorb best practices, and become familiar with the team's workflow.

After a couple of weeks, Sam starts to work on small tasks that are suitable for his level. This transition is smooth and structured, ensuring he feels comfortable and prepared. This scenario is most common in larger teams that can allocate resources to develop a structured onboarding process, including mentors, onboarding buddies, and suitable tasks for junior developers.

Scenario Two: No Structured Onboarding, but a Helpful Team

Maria, on the other hand, joins a team where there is no structured onboarding process. The team lacks the resources and time to prepare suitable tasks or spend much time on pair programming and mentoring. She finds herself working on tasks independently just days into the job, a stark contrast to Sam's experience.

Yet, even without a structured process, Maria's team is eager to help. The experienced developers are supportive and approachable, providing her with guidance and assistance when she needs it, even though they can't dedicate significant time to pair programming due to their own deadlines.

Scenario Three: Being Thrown into the Deep End

David's experience is quite different. He finds himself in a team that either lacks the resources to support him or simply doesn't prioritize it. He experiences a "sink or swim" approach. He is expected to learn on the fly and become productive without much assistance, a very stressful situation for any junior developer.

If David manages to adapt and deliver, he'll survive. If not, he may not make it past the probation period. This is a challenging scenario, but it's also one that can spur rapid growth—if he can handle the pressure.

Practical Steps to Ensure Success During Your Probation Period

While you may not have much influence over the scenario you find yourself in, you can take proactive steps to set yourself up for success. Here's how:

Preparation before your first day: Reducing cognitive load

Regardless of the scenario, you're likely to be overwhelmed by the wealth of new things to learn: the potentially enormous and unfamiliar codebase, new technologies, complex project setups, workflows, team dynamics, and processes. The first few days can be especially challenging with an influx of information from numerous meetings. The goal of preparation is to expose you to as many elements as possible upfront, thus reducing cognitive load during your initial days and weeks.

Researching the tech stack and workflow: Reach out to your future team member or contact in the company, expressing your desire to prepare. Ask them about the tech stack and workflows they use, such as Scrum or Kanban. Learn and practice the tech stack as much as possible and read about the workflows. The goal is not to fully understand everything. But this early exposure will help familiarize you with the basics, making them less daunting when you officially start.
Understanding the company and domain: If possible, test out the product or application. Familiarize yourself with the company through LinkedIn and its website, and read about the industry and the company's competitors. This will help you better understand the company-specific words and industry-specific language used during your onboarding. This again will help reduce cognitive load during your first days.

The first days on the job: Clarify expectations and establish a timeline

As a new hire, especially as a junior developer, you'll require resources from more experienced team members. The most important expectation, therefore, is for you to become productive and independent. The timeline for this varies significantly, as seen in the different scenarios presented earlier.

Understanding the expectations of your team leads and managers is crucial. It gives you direction and guidelines. During onboarding meetings, ask a simple question: "What would make me a successful hire at the end of the probation period (after 1 month/6 months)?" This will establish a timeline of expectations and encourage the other person to reflect on their expectations.

But don't limit your queries to your managers; your peers can also provide valuable insights. In the first few days, it's beneficial to be proactive and set up short meetings with each team member to get to know them. This not only helps establish a relationship but also gives you the chance to ask about their expectations. These conversations can provide a broader perspective and help you understand what it takes to be successful on the team from multiple viewpoints.

After all, your teammates have been in your shoes before and may have practical advice on how to navigate this new terrain. Plus they might be part of your evaluation at the end of your probational period.

Striking the Right Balance Between Asking for Help and Becoming Independent

Striking the right balance between asking for help and becoming independent can be tricky. There's no set rule, like "asking 10 questions a day is too much." It depends on the team's expectations, the task you're working on, and the project's complexity.

There are two extremes of junior developers:

One rarely asks questions, maybe due to shyness, embarrassment, over-confidence, or a reluctance to disturb seniors. They might take longer to learn and become productive, and at some point, they could block other developers from doing their work.
On the other end is the developer who always asks questions. They seem eager to learn at first, but the number of questions doesn't decrease even after weeks. They constantly need assistance and don't seem to do their own research. Their questions lack detail and initiative, like "The product image doesn't work. What am I doing wrong?" This pattern indicates a lack of striving for independence, which could become a burden to the team.

In summary, asking too few questions can prolong your learning curve and delay your productivity. Asking too many can consume excessive resources and hinder your growth toward independence. Striking the right balance is key.

Humility Over Arrogance

Most junior developers approach their first job with a healthy dose of humility, recognizing the magnitude of what they don't yet know. However, there are some who, despite their inexperience, carry an air of arrogance, thinking they know it all. It's essential to note that this attitude can be counterproductive.

As a new developer, you might have high expectations for what "production-level code" should look like, only to discover that a lot of it seems to be held together with proverbial duct tape. This can be shocking, but there are many valid reasons for it:

Tight Deadlines and Priorities: In the real world, there isn't always time to write the most elegant code. Deadlines and business priorities often dictate a need for speed over perfection.
Evolution and Scaling: Codebases evolve over time. What was once the perfect solution may no longer fit as the project scales, leading to layers of fixes and patches.
Team Changes: Developers with different coding styles and preferences come and go. The original intention behind certain pieces of code may be long forgotten, adapted over time to "make it work" with new features.

So, instead of adopting a judgmental attitude and wanting to rewrite everything, remember that a long-running project has a history. Things are the way they are not because previous developers were incompetent (though this can be a fun topic for gossip), but because software development is a complex and evolving process.

Humility is key. Recognize that there's always more to learn and that understanding the "why" behind existing code can be as valuable as writing new code. This approach will make you a better developer and a more appreciated team member.

Conclusion

Navigating the probation period of your first tech job can seem daunting, but with thoughtful preparation, clear communication, and the right attitude, you can successfully secure your place in the industry.

Let's recap the main points we've covered:

Expectations: Depending on the size, resources, and practices of the team you join, the expectations and timeframes for you to meet these expectations can vary significantly. We outlined three scenarios to illustrate potential environments you may encounter.
Preparation: Before your first day, try to familiarize yourself with the tech stack, workflow, company, and domain. This will help reduce cognitive overload during your initial days.
Communication: During the first few days on the job, clarify expectations and establish a timeline for your progress. Be proactive, reach out to your team members, and build relationships.
Balance: Try to strike the right balance between asking for help and working independently. Neither extreme—asking too few questions or asking too many—is beneficial.
Professionalism: Lastly, approach your job with humility, not arrogance. Recognize that there's always more to learn, and understand that existing code might be the way it is due to many reasons, including time constraints and evolving project requirements.

Starting a new job in the tech industry can be overwhelming, but remember, everyone has been in your shoes at some point. The probation period is a chance for you to learn, grow, and demonstrate your potential. It's an opportunity to set the foundation for your career, and with the right attitude and approach, you can turn it into a launching pad for your success.

DEV Community: Johannes Kettmann

Path To A Clean(er) React Architecture (Part 8) - How Does React-Query Fit Into The Picture?

Table Of Contents

Problematic code example 1: Manually managing server data

The problem: Boilerplate & state management

The solution: Creating a react-query hook

Problematic code example #2: Business logic and react-query

The problem: Duplicate requests

The solution: Using react-query data and mutations

Next Refactoring Steps

Path To A Clean(er) React Architecture (Part 7) - Domain Logic

Table Of Contents

Problematic code example: Domain logic inside a component

The problem: Mixed concerns and low testability

The solution: Extracting logic to the domain layer

Step 1: Creating functions in the domain layer

Step 2: Updating the component

Step 3: Unit testing domain logic

Another Problematic code example

The problem: Mixture of domain and business logic

The solution: Creating functions in the domain layer

The pros and cons of extracting domain logic

Advantages

Disadvantages

Next refactoring steps

Path To A Clean(er) React Architecture (Part 6) - Business Logic Separation

Problematic code example: Business logic mixed with UI logic

The problem: Mixed concerns and low testability

The solution: Extracting business logic and using dependency injection

Step 1: Extracting business logic to a use-case

Step 2: Custom hook for dependency injection

Step 3: Unit testing the business logic

Advantages and disadvantages of business logic in use cases

Next refactoring steps

Path To A Clean(er) React Architecture (Part 5) - Infrastructure Services & Dependency Injection For Testability

Path To A Clean(er) React Architecture - Domain Entities & DTOs

Table Of Contents

Bad Code: Data Structures Of API Responses In UI Code

What is the problem?

We use data structures defined by the API

Tight coupling of UI code to server API

Solution: Introducing domain entities and DTOs

The domain model

DTOs and data transformations

The good and the bad

Pros: Cleaner architecture, more resilience, better separation

Cons: More code, more complexity

Conventions and automation

Next refactoring steps

Path To A Clean(er) React Architecture - API Layer & Data Transformations

Table Of Contents

Bad Code - Example 1: API responses inside UI code

What is the problem?

Solution: Use data transformations in the API layer

Bad Code - Example 2: Data transformations in UI code

What is the problem?

Solution: Move data transformation logic to the fetch function

Bad Code - Example 3: Transformation of input data

What is the problem?

Solution: Move transformation of input data to API layer

Next refactoring steps

Path To A Clean(er) React Architecture - API Layer & Fetch Functions

Bad Code: Mixed API and UI code

Why is this code bad?

Solution: Extract functions that connect to the API

Why is this code better? Decoupling of UI and API code

Next refactoring steps

Path To A Clean(er) React Architecture - A Shared API Client

Table Of Contents

Bad code: Hard-coded API request configuration all over the place

Why is this code bad?

Solution: A shared API client

Why is this code better?

Next refactoring steps: Introducing an API layer

PS: Shared API client with fetch

React useEffect and objects as dependency - 4 approaches to avoid unnecessary executions

Table Of Contents

The problem

Approach 1: Spread object values

Approach 2: Manually pass each value

So, why isn’t the `trackingId` defined when clicking on the icon button?