Find what you need 🔍 How to structure your React projects

published by Jens-Uwe Lössl on 9/14/2024

What is relevant when thinking about react project structure?

Before thinking about how, we should make clear what is the goal of structuring a React project and what we are trying to archive.

At first, we should see the way, how we organize our code as a tool to communicate the architecture and the business language of our application. We want to create a structure that is easy to maintain, scale, but is easy to understand. Also, the structure of the project is like a map for developers, where to find what they are looking for and where to implement parts of the feature. So the folder structure needs to fit to the project that your are building.

Do not overthink!

That’s the recommendation from the react team. I can subscribe to the core of this message. When you build something small, focus on getting it done. Also, there is a concept of incremental architecture. You can reorganise a small project whenever you feel like. You can change folder structures, split components without a major afford in a small application.

When your projects grows, your project structure will grow with it. You will see patterns that are repeating and you will see parts of your application that are growing. This is the time to iterate and refactor.

What to do in a business context?

When you are part of a organisation, you build something that need to be maintained for a long time, you need to think more about your project structure. In this case, I like to “zoom out” and take a look on the business? What parts of the application needs to be tested? What is the test strategy? Is the organization growing and is there a need in building a design system? How experienced is the development team? How much state do you will have in the client?

Next step, is to decide on a frontend architecture that fulfill the gathered requirements. If you have a department that is responsible for the design. You want to use the terminology that they are using in your codebase. So when they are using atomic design, you also want to reflect this approach in your project structure, because it enables developers to communicate very specific.

Also important is how your requirements are getting defined: If they have the form of: “When X happens, Y should happen.”, you might want to use an architecture that works with events (for example Flux or an Event Driven Architecture). When a domain expert can find their explanation in your code - than this is good code.

What parts has a frontend of a common business application?

Business application usually has different parts that need to interact with each other:

• Routing
• Pages
• UI components
• Backend communication
• Business specific logic(for example validation, and access control)
• State management

The question is now, how can we separating those thing:

Feature Slices

A feature slice is a part of the application that is responsible for a specific feature. It contains all the parts that are needed to implement this feature. This includes the UI components, the business logic, the state management and the backend communication within one folder. The advantage is that on the first level of the folder structure it make clear, what the application can do, and what problems it solves. I have the feeling that ths approach only works well if your application only consists of independent feature, and you are actively avoiding to share implementation details - this is a little bit against the philosophy of react components and their possibility to reuse them. Where to put a button? In a separate module?

By Architecture

Every piece of software has some architectural choices. My goto is to put this choice on the first level. So if you decided on a Flux Architecture you might want to have a folder called ‘Flux’. If you are using a layered architecture, the first level will become the of the folder structure can communicate this decision. On next level I like to communicate the domain model. So when multiple teams are working on the project the responsibilities are clear. I am also using ‘Atomic design’ as a design workflow. So my components can be found in folders called ‘Atom’ and ‘Molecule’ that are not connected to a domain. ‘Organism’ and ‘Page’ usually include are connected to business logic, so these components will be placed in the domain folders.

You might wonder, how to deal with shared logic? My first take is to avoid any ‘common helper’ functions if you can. If there is no way of avoiding it, than I have on first level a folder called ‘Framework’. The idea is, that the ‘Framework’ folder can be split out of the project and also be served as an npm package. An example you can find here: react-observable-tools. I includes basic hooks that I use for connecting rxjs with react.

Summary

The most important part is to let it involve with your project size, the requirements and your experience. You can start with a simple structure and improve it step by step. Don’t take short cuts when writing your code, so focus an writing good and simple components. It will keep the doors open for future refactoring. Follow common rules, especially the ‘Single-Responsibility-Principle’ and you will be ready for every requirement that might come.