Next JS and Modular Architecture

Modular architecture in Next JS, sharing my experience

Marco A. García - 04/01/2024

Architecture? Modules? Why complicate things?

First of all, what is Next JS? On its own website, it is defined as The React Framework for the Web, making it a React framework (the most popular, in fact).

So, what’s the problem? Well, the problem is that React gives too much freedom to the programmer. But is this really a problem?

Analyzing the issue

The problem isn’t React, nor the great freedom it gives developers when programming, no. The problem lies in how developers abuse this freedom.

Let’s analyze, for example, a piece of PHP code that abuses the freedom the language offers:

<?php

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $conn = mysqli_connect("localhost", "root", "password", "my_database");

    if ($conn) {
        $name = $_POST['name'];
        $surname = $_POST['surname'];
        $age = $_POST['age'];

        $query = "INSERT INTO users (name, surname, age) VALUES ('$name', '$surname', $age)";

        if (mysqli_query($conn, $query)) {
            echo "User successfully registered.";
        } else {
            echo "Error registering user: " . mysqli_error($conn);
        }

        mysqli_close($conn);
    } else {
        die("Database connection error");
    }
}

?>

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>User Registration</title>
</head>
<body>
    <form method="post" action="">
        <label for="name">Name:</label>
        <input type="text" name="name" required>
        <br>
        <label for="surname">Surname:</label>
        <input type="text" name="surname" required>
        <br>
        <label for="age">Age:</label>
        <input type="number" name="age" required>
        <br>
        <input type="submit" value="Register">
    </form>
</body>
</html>

Although it works at first glance, here we can start noticing bad practices:

Lack of code modularization, making it hard to reuse.
Lack of separation of concerns; database interaction and the view are in the same file.

Now, does this mean PHP is a bad language? Or that all PHP code will have bad practices? No, as it is possible to write excellent code in PHP, but it is the developer’s responsibility.

By the way, I have nothing against PHP. I love PHP, when it’s well done ❤️.

Now, let’s look at the following React code I came across:

import React, { useState } from "react";

const NameAndAgeForm = () => {
  const [data, setData] = useState({ name: "", age: 0 });

  const handleInputChange = (e) => {
    const { name, value } = e.target;
    setData((prevData) => ({ ...prevData, [name]: value }));
  };

  const handleFormSubmit = (e) => {
    e.preventDefault();

    if (data.name && data.age > 0) {
      alert(`User registered: ${data.name}, ${data.age} years`);
    } else {
      alert("Error registering user: verify the fields.");
    }
  };

  return (
    <div>
      <form onSubmit={handleFormSubmit}>
        <label>Name:</label>
        <input
          type="text"
          name="name"
          value={data.name}
          onChange={handleInputChange}
          required
        />
        <br />
        <label>Age:</label>
        <input
          type="number"
          name="age"
          value={data.age}
          onChange={handleInputChange}
          required
        />
        <br />
        <button type="submit">Register</button>
      </form>
    </div>
  );
};

export default NameAndAgeForm;

What’s the problem here? While we are not directly interacting with the database as we did with the PHP example, we are falling into the same bad practices:

Lack of code modularization, as the data management for this form cannot be reused in other parts of the application. It’s tightly coupled.
Lack of separation of concerns; data handling and the view are in the same file.

So, is the problem React or Next JS?

Well, the truth is, the problem isn’t with either, but with the bad practices developers have with different technologies, whether it’s React, Next, Remix, Java, or Laravel.

Having seen the above, what if we analyze a project structure proposal with modular architecture for Next JS? Let’s go.

Modular Architecture in Next JS

Let’s start by identifying two entities: modules and functionalities.

Each module will have one or more functionalities. For example: We have the User module with the functionalities save and delete.

- User
    - save
    - delete

Now, let’s start with a basic Next JS project structure:

(src)
- components
- pages
- utils
- styles

From here, we can start adding our own structure. Let’s begin by creating a modules folder where our modules will be created.

Inside modules, and following the same example of User, we’ll create a folder user. This will store the functionalities of our User module.

Inside user, we’ll create two more folders: save and delete, each corresponding to one of the functionalities of our module.

The result should look like this:

(src)
- components
- modules
    - user
        - save
        - delete
- pages
- utils
- styles

Now that we have the module structure, how should the files inside each functionality folder look? Easy, we’ll use up to six files based on our needs:

View (tsx)
Custom hook for the view (ts)
Form (tsx)
Custom hook for the form (ts)
Form schema (ts)
Context (tsx)

Let’s create an example with our save functionality. What do we need? Well, we need a view. This view will have a form that will consume its own custom hook, which will use a schema to validate data input. We’ve got it; the files should be:

(src/modules/user/save)
- useUserSave.ts
- useUserSaveForm.ts
- useUserSave.schema.ts
- UserSaveForm.tsx
- UserSaveView.tsx

Do you notice a pattern? Exactly, each file is self-descriptive regarding its module, functionality, and responsibility. This way, we achieve better code segmentation, well-defined responsibilities, and modularization to reuse this logic elsewhere in our application.

Now let’s see the initial composition of each file:

For these examples, formik is used for form management, zod for data validation, and zod-formik-adapter for adapting zod schemas in formik. You can use these tools or others you prefer. The key is to separate and modularize our components.

useUserSave.ts

// Hook to manage view data
export const useUserSave = () => {
  return {};
};

useUserSaveForm.ts

// Hook to manage form data
import { toFormikValidationSchema } from "zod-formik-adapter";
import { useFormik } from "formik";
import { userSaveSchema, type UserSaveType } from "./useUserSave.schema.ts";

const initialValues: UserSaveType = {
  name: "",
};

export const useUserSaveForm = () => {
  const formik = useFormik({
    initialValues,
    validationSchema: toFormikValidationSchema(userSaveSchema),
    onSubmit: (values: UserSaveType) => {
      console.log(values);
    },
  });

  return {
    formik,
  };
};

useUserSave.schema.ts

// Schema to validate form data from the form hook
import { z } from "zod";

export const userSaveSchema = z.object({
  name: z.string({
    required_error: "Name is required",
  }),
});

export type UserSaveType = z.infer<typeof userSaveSchema>;

UserSaveForm.tsx

// Form UI, consuming useUserSaveForm
import { useUserSaveForm } from "./useUserSaveForm";

export const UserSaveForm = () => {
  const { formik } = useUserSaveForm();

  return null;
};

UserSaveView.tsx

// View UI, consuming useUserSave
export const UserSaveView = () => {
  return null;
};

Do I have to create the structure manually?

No, not at all. Given my need for better structure, not only in Next JS projects but in the React ecosystem in general, I created magen. Magen (Module Architecture Generator) is a module generator for creating React applications. This library helps create boilerplate code for both the frontend and backend, but there’s no better way to understand it than by trying it.

To do so, you can run:

npx magen@latest

You don’t need to install it locally. After running this command, magen will ask you a series of questions based on the needs of the module you want to create, and that’s it; you’ll have the boilerplate code to develop your new functionality with a modular architecture.

Using magen in terminal

Magen folder structure

Conclusion

We’ve seen the benefits of using a modular architecture in our Next JS projects and how magen can help us achieve this.

Magen’s code can be found in this GitHub repository. Feel free to submit a pull request; we’d love to review it!

Contact

Feel free to reach out through my social media.