DEV Community

Cover image for React Project Architecture
Ezran Bayantemur
Ezran Bayantemur

Posted on • Updated on

React Project Architecture

I’ve been developing applications with React for a long time and I’m loving it more and more. React is such an amazing library for creating application architecture and it’s plan. It’s offering the opportunity of applying basic software principles (like SOC , like SOLID ..) on our project and keeping codebase clean even if our project scale grows. Especially after hooks it’s became so yummy!

In this article I wanted to talk about how can you create project structure and architecture with React. You can think it’s will be mixed article of best practices and React basics. Of course they are not “rules” or something else, you can go on however you want, I just want to light some blub on mind :)
It will be a little long article but I think it will be helpful.
In addition; I’m gonna give examples on React Native but you can think exactly the same struct on web, ReactJS.

If you ready, let’s go! 🤟

Originally I wrote this article on Medium and I'm planning to share some article and translate my old Turkish articles for you people. If you wanna support me you can give me clap on there and keep me rock!

city-route

Navigation

Navigation is the backbone of the application. The cleaner and the balanced you keep it, that much easy to integrate when new requirements, new pages comes and that much less time to spend for “Where and how I’m gonna implement the new changes?” question.

When you developing an application, all the project architecture is reveales on the design phase. All the questions like; Which screens will gonna be? Which purpose will it serve? How will the pages be grouped in the application? finds their answers and; at this point, you can create the navigation architecture. You can create entire architecture with looking at the screen designs.

If your application has screens with different purposes you can gather them on a separate Stack architecture. For example, if application has main modules like profile, messaging, timeline;

- App
   - ProfileStack
   - MessageStack
   - TimeLineStack
...
...
...
- ProfileStack
   - ProfilePage
   - UpdatePreferencesPage
   - AddNewPhotoPage
- MessageStack
   - InboxPage
   - NewMessagePage
   - TrashCanPage
- TimelineStack
   - TimelinePage
   - PostPage
   - CommentsPage
   - LikesPage
Enter fullscreen mode Exit fullscreen mode

you can create a structure something like that.
Main navigator has Profile, Message and Timeline stacks. In this way, main modules of our application are certain and they have separated sub screens.

For example; MessageStack module is related only to messaging section and tomorrow, if it need any new screen, updating only that section will do the work. We can navigate from any screen to anywhere. react-navigation gives us the limitless freedom about it, only we should do our planning well.

The is no limit to nested stacking. Modules with has similar context can gather to same stack structure. For example; if notification page in settings section holds 3 of 4 page; you can gather them on the same Stack. Because seeing the pages with NotificationPreferences, NotificationDetail, BlockedAppNotifications names on the SettingsStack is not well-doing thing. They sounds like they need Notifications stack. Besides, placing them like this, means we will gonna implement every new page with same navigation idea. After all we should stick on a certain development method, right? What if tomorrow 10 paged modules comes?

A project dies because of not following certain development way or following the wrong development way.

electronic-component

Components

When you develop a module, complexity feel structures or open for reusability structures should be design as separate components.

While developing a page or module with React, always consider to divide. React gives you this opportunity and you should use it as much as you can. Your current component may look simple today, you may not think to divide it but the person who gonna develop it after you, if keep developing it like that and if that component grows like 200–300 loc (line of code), revise it will took much more time than develop it.

It’s like the toilet, you should leave it like you wanna find it.

Then, when should divide a component?

While creating a design of an app, a fixed design principle is select for appealing to the eye. Buttons, inputs, modals has always a consistent design and looks like each other. Instead of ten different button design you’d see ten different variation of one button. This is consistency, it creates signature of application on users eye memory and you’d (actually, you should) create your consistent component structure while these looking at designs.

For example; if there is a button design which is using so frequently, you can create it’s variation and store it on general component directory. Also you can store on the same directory the components which is not using anywhere else but smells like reusable.

But, if there is a component which using only one screen, it’s better to be store it on the same directory with the related screen. Let’s give an example;
If graph and table components will gonna use only and only by analysis screen and if it will gonna completely stick by analysis logic, then it’s better be keep it on the same directory. Because the modules are which needs each others should be close to each other. But in that example, list modal and button components can be store on general components and call from there. They created because of that.

Then, our file directory will gonna be like;

- components
   - Button
      - Button.tsx
      - Button.style.ts
      - Button.test.tsx
      - Button.stories.tsx
      - index.ts
   - ListModal
      - ListModal.tsx
      - ListModal.style.ts
      - ListModal.test.tsx
      - ListModal.stories.tsx
      - index.ts
...
...
- pages
   - Analyze
      - components
         - AnalyzeGraph
            - AnalyzeGraph.tsx
            - AnalyzeGraph.style.ts
            - AnalyzeGraph.test.tsx
            - AnalyzeGraph.stories.tsx
            - index.ts
         - AnalyzeDataTable
            - AnalyzeDataTable.tsx
            - AnalyzeDataTable.style.ts
            - AnalyzeDataTable.test.tsx
            - AnalyzeDataTable.stories.tsx
            - index.ts
      - Analyze.tsx
      - Analyze.style.tsx
      - index.ts
Enter fullscreen mode Exit fullscreen mode

that.

Components that are related to the analysis module and will only serve it are locating near that module.

Note: While naming, giving the related module name as prefix is much better choice, I think. Because you may need another graph and table component on completely different module and if you give just DataTable as the name, you may have ten different DataTable component and you can have some hard time to find which component using on which module.

A second way: styling stage

The most main base principle of writing clean code is giving the right name to variable and values. Styles are our values too and they should naming right. While writing a style for a component, the more you give right names, the more you write a maintainable code. Because the person who will continue to develop it after, will be easily find which styles belongs to where.

If you use same prefix so frequently while naming the styles, then you should consider that part as another component.
So if your UserBanner.style.ts file looks like that;

contanier: {...},
title: {...},
inner_container: {...},
avatar_container: {...},
avatar_badge_header: {...},
avatar_title: {...},
input_label:  {...},
Enter fullscreen mode Exit fullscreen mode

you may feel you need a component like Avatar.tsx. Because if there is a grouping while styling stage then it’s mean a growing structure coming. There is no need to repeat 3 or 5 times for consider a structure as an another component. You can follow it while coding and make inference.

In addition; there is no rule to all component should have logic. The more you divide the module, the more you control it and more you can write tests.

Let it be a little road tip 🧳

glowy-hooks

Hooks

Structures which are plays a role on lifecycle and represents a work logic, should be abstract as a hook.

For that, they need to have their own logic and as like on the definition, they should be on the lifecycle.

The main reason of it is the reducing the work weight on general structure and creating reusable work parts. Just as we create custom components for reducing code complexity; custom hooks can be create for the same way. Important thing is being sure of created structure and it working correctly.

How we understand that we need a custom hook?

Let explain it with an example;

Think that you need a search structure on project scope. You need a SearchBox component which will gonna be able to usable from everywhere and using fuse.js package for search action. First, let’s implement search structure to two example component.

(I didn’t keep codes too long but you can think that three point sections are own parts of the component)

function ProductPage() {
  const fuse = new Fuse<Product>(data, searchOptions);
  const [searchKey, setSearchKey] = useState<string>("");
  const [searchResult, setSearchResult] = useState<Product[]>([]);
  ...
  ...

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

    if (searchKey === "" || typeof searchKey === "undefined") {
      return setSearchResult([...data]);
    }

    const result = fuse.search(searchKey);

    if (!result) {
      return;
    }

    setSearchResult(result.map((r) => r.item));
  }, [data, searchKey]);

  ...
  ...

  function search(pattern: string) {
    setSearchKey(pattern);
  }

  ...
  ...

  return (
    <Layout>
      <ProductSearchBox onSearch={setSearchKey} />
      <ProductInfo />
      ...
      ...
      <View>
        <ProductDetail />
        <List data={searchResult} item={ProductCard} />
      </View>
      ...
      ...
    </Layout>
  );
}

export default ProductPage;
Enter fullscreen mode Exit fullscreen mode
function MemberPage() {
  const fuse = new Fuse<Member>(data, searchOptions);
  const [searchKey, setSearchKey] = useState<string>("");
  const [searchResult, setSearchResult] = useState<Member[]>([]);
  ...
  ...

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

    if (searchKey === "" || typeof searchKey === "undefined") {
      return setSearchResult([...data]);
    }

    const result = fuse.search(searchKey);

    if (!result) {
      return;
    }

    setSearchResult(result.map((r) => r.item));
  }, [data, searchKey]);

  ...
  ...

  function search(pattern: string) {
    setSearchKey(pattern);
  }

  ...
  ...

  return (
    <Layout>
      <MemberSearchBox onSearch={setSearchKey} />
      ...
      ...
      <View>
        <Header />
        <List data={searchResult} item={MemberCard} />
      </View>
      ...
      ...
    </Layout>
  );
}

export default MemberPage;
Enter fullscreen mode Exit fullscreen mode

When we look at to our components the main thing that we notice there is the same search structure were implemented and clearly code repeat can be seen. If there is so much code repeat on a structure, that means something going wrong out there.

In addition to that; when someone opens any file, it gonna want see only and only filename related code. When you open CommentsScreen.tsx file, you wish to see just comment related codes, not any other grouped logic. Yes, on the example our search structure is related with Product and Member components and they working for them. But they represent a their own logic from now and furthermore, they can be convert reusable structure. Because of that we need custom hook or component structures.

Back to example; there is a clearly use of state for search action and it’s takes a place on the lifecycle. When user start to type to the search input, that string storing on the searchKey state and when it takes update main list also filtering too.

 So how we can design it much better?

We can gather our search structures on a hook named useSearch. We should create such a hook that is not dependent to any module and has reusable structure for freely use anywhere.

Because we’ll gonna use fuse.js for search, we can send out data and search criteria as input and we can return search result and search function which will gonna trigger later.

Then, the hook that we gonna create is;

interface Props<T> {
  data?: Readonly<T[]>;
  options?: Fuse.IFuseOptions<T>;
}

interface ReturnType<P> {
  search: (s: string) => void;
  result?: P[];
}

function useSearch<K>({data, options}: Props<K>): ReturnType<K> {
  const fuse = new Fuse<K>(data || [], options);
  const [searchKey, setSearchKey] = useState<string>('');
  const [searchResult, setSearchResult] = useState<K[]>(data || []);

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

    if (searchKey === '' || typeof searchKey === 'undefined') {
      setSearchResult([...data]);
      return;
    }

    const result = fuse.search(searchKey);

    if (!result) {
      return;
    }

    setSearchResult(result.map(r => r.item));
  }, [data, searchKey]);

  function search(pattern: string) {
    setSearchKey(pattern);
  }

  return {search, result: searchResult};
}

export default useSearch;
Enter fullscreen mode Exit fullscreen mode

will be this.

With TypeScript support our hook can be used with types. With that we can send and receive any type while using it. Work flow inside hook is same as we talked before, you’ll see when check out the codes.

If we want to use it on our components;

function ProductPage() {
  const {result, search} = useSearch<Product>(data, searchOptions);
  ...
  ...

  return (
    <Layout>
      <ProductSearchBox onSearch={search} />
      <ProductInfo />
      ...
      ...
      <View>
        <ProductDetail />
        <List data={result} item={ProductCard} />
      </View>
      ...
      ...
    </Layout>
  );
}

export default ProductPage;
Enter fullscreen mode Exit fullscreen mode
function MemberPage() {
  const {result, search} = useSearch<Member>(data, searchOptions);
  ...
  ...

  return (
    <Layout>
      <MemberSearchBox onSearch={search} />
      ...
      ...
      <View>
        <Header />
        <List data={result} item={MemberCard} />
      </View>
      ...
      ...
    </Layout>
  );
}

export default MemberPage;
Enter fullscreen mode Exit fullscreen mode

As it can see from now search structure is abstracted from the components. Both code complexity is reduced and whenever we need a search structure we have a custom hook on our hands.

With that we created a much more clean and testable structure.

By the way, like I said; hooks can be create for dependent on a context or generic use as like as components. On that example we created custom hook for general use but we can create custom hooks for specific job or context. For example for data fetching or manipulating on specific page you can create your own hook and abstract that job from the main component.

I mean;

- hooks
   - useSearch
      - useSearch.ts
      - useSearch.test.tsx
      - index.ts
...
...
- pages
   - Messages
      - hooks
         - useMessage
            - useMessage.ts
            - useMessage.test.tsx
            - index.ts
         - useReadStatus
            - useReadStatus.tsx
            - useReadStatus.test.tsx
            - index.ts
      - Messages.tsx
      - Messages.style.tsx
      - index.ts
Enter fullscreen mode Exit fullscreen mode

While useSearch using on the project scale; useMessage is responsible for data fetching, useReadStatus is using for subscriber read status on a message. Same logic as on the components.

And that’s Hooks 🔗

On the Clean Code book; there is such a good description for single-responsibility requirement of a function. If we use it for React: A component or a hook should do one thing, should do it only, and should do it well.

data-neuron

 Context

You should create different context structure for the modules which can’t communicate directly but connected from the content.

Context shouldn’t be considered like “all the wrapper around entire project”. When complexity of project increase; structures which has connection with logic are increase in number too and these parts should keep separated from the each other. Context takes the role of communication between these parts. For example; if you need communication in components and pages on the messaging module; you can create MessagesContext structure and create independent work logic by wrap it to only messaging module. In the same app if you have Nearby module which you can find friends around you and if it has numerous work parts; you can create NearbyContext and abstract it from the others.

So, if we need a structure like, global, accessible on anywhere; can’t we wrap main app with a context?

Of course you can.

That’s why global state management stands for.

On this point the main thing that you should be careful is not to overload a context. You shouldn’t wrap the app with only the AppContext and put all the states like user info, style theme and messaging. Because you’ve already create work modules for them and can clearly see they are different structures.

In addition; context updates every component which connected to it on any state update.

In example; you’ve created member and messages states on AppContext and you listen only member state on Profile.tsx and only messages state on MessageList.tsx component. When you receive a new message and update the messages state; Profile page will take the update too. Because it listen the AppContext and there is a update on the context which is related (which is actually not). Do you think there is a really relation between messages and profile modules? Why there is an update should be happen on the profile section when new message comes? That means an unnecessary refresh (render, update, however you want name it) and when they grow like an avalanche, they will cause so much performance problems.

Because of that reason you should create different context for different work content and keep safe the entire logic structure. Even a more reason; when the application take a step to the maintenance phase, the person who will care the update on any module, should be able the select related context easily and understand the architecture with no pain. Actually right here the most base teaching of clean code principle comes into play again; the right variable naming as we just mentioned.

When you naming your context on the right way, your structure will be go on healthy too. Beacuse the person who sees the UserContext will be know that it should take or put the user info from here. It will know not to manage the works about settings or messaging from the UserContext. Because of this, the clean code principles are really important discipline.

Also, users have opened an issue about Context API back before and they wanted; components which are listens states from the Context, should take refresh only when the subscribed states updated, just like Redux. This answer of Dan Abramov is actually summarizes the working logic of the Context API very well.

A component which listens a Context should must need that Context. If you see an unnecessary state which you called from a Context; this mean either this state has no place on that Context or you set that Context structure wrong. It’s all about the architecture that you created.

While using Context, always be sure for that your components really need the states which are you called. You will be less likely to make mistakes.

For a little example;

[ App.tsx ]
<AppProvider> (member, memberPreferences, messages, language)
  <Navigation />
</AppProvider>
Enter fullscreen mode Exit fullscreen mode

If we separate;

[ App.tsx ]
<i18nProvider> (language)
  <MemberProvider> (member, memberPreferences)  
    <Navigation />
  </MemberProvider>
</i18nProvider>
...
...
...
[ MessageStack.tsx ]
<MessagesProvider> (messages)
  <Stack.Navigator>
    <Stack.Screen .../>
    <Stack.Screen .../>
    <Stack.Screen .../>
  </Stack.Navigator>
</MessagesProvider>
Enter fullscreen mode Exit fullscreen mode

that it would be much better. As you can guess we split MessagesProvider but we didn’t put it to entry point. Because i18n and Member providers are needed for general access but Messages will gonna use only for message scope and it will trigger update only that part. So we can expect the message context to update the message section, right?

 Conclusion

Well, I tried to explain some the lifeblood issues of React a little in my own way. I hope it was a good and helpful article for you readers.
As like I said on top, React is really amazing library for creating this kind of architectures. When you wish to work clean, it offers you opportunities as much as it can. You can create useful and good performance web/mobile application with quality codebase.
If you have any feedbacks I would love to hear them.
See you soon on next article, be careful and stay safe! ✌

🎙

“Clean code always looks like it was written by someone who cares”
― Michael Feathers

validation

Discussion (41)

Collapse
jonrandy profile image
Jon Randy

Lucky you, I'm hating it more by the day 🤮

Collapse
spock123 profile image
Lars Rye Jeppesen

It's so messy, it feels old

Collapse
dhruvindsddev profile image
Dhruvin

Wait until you try angular

Thread Thread
cgatian profile image
Chaz Gatian

You litterally need to pull in so many libraries in order to get a React app off the ground.... Axios, Formik, Yup, a CSS modules lib just to name a few! I wouldn't recommend React for anyone building an app with more than 10 people. Once you go beyond that 10, everyone's opinions start entering into the codebase and you get a hodgepodge of component patterns just littered everywhere.

Thread Thread
cgatian profile image
Chaz Gatian

The funny thing is, a lot of the suggestions made in the OP are things Angular has been doing since day one. In fact, I think React needs to adopt even more of the patterns. For example, lets talk naming conventions. Making a component with /MyWidget/index.tsx is undesirable, make it components/my-widget.component.tsx. Also, stop placing hooks in a generic hooks.ts, use my-widget.hooks.ts.

Thread Thread
kachidk profile image
Victor Nwanguma • Edited on

You don't need formik or yup, to start a react app, for you to talk about axios like that means you don't fully understand what axios does (Axios is a promise based HTTP client for the browser and Node.js. Axios makes it easy to send asynchronous HTTP requests to REST endpoints and perform CRUD operations. It can be used in plain JavaScript or with a library such as Vue or React.).

The only thing important to start a react app with, is a styling library (css modules, styled components, emotion and styled jsx) which is not so complusory and a routing library (react-router).

If your code base is littered because of different people's opinions it's not because of the flexibility of React (which I enjoy).

It's because you have not established rules in your team guiding how the codebase should be

Collapse
dhruvindsddev profile image
Dhruvin

Why hate?

Collapse
jonrandy profile image
Jon Randy

Principally - JSX... It's a total abomination. Like being back in the bad old days of PHP all over again

Thread Thread
jonrandy profile image
Jon Randy

Also, the hooks stuff... feels like an ugly hack to patch over bad design

Thread Thread
jonrandy profile image
Jon Randy

I've used Vue and RiotJS also - and they're soooo much nicer to work with - totally intuitive, especially RiotJS which just feels like a natural extension to vanilla HTML/JS

Thread Thread
spock123 profile image
Lars Rye Jeppesen

Agree.. Angular (modern) is also amazing.
Built in native support for Observables and Typescript is just amazing.

Thread Thread
dhruvindsddev profile image
Dhruvin

Agreed jsx does feel like php, but it is so quick to prototype and provides so much better project structure as compared to angular where you need to create html + js + cs, uuh so many files to work with.
I have no experience with vuejs, would to recommend to learn it ?

Thread Thread
dhruvindsddev profile image
Dhruvin

ps, by project structure I mean the flexibility to add anything anywhere, there are no strict rules to follow.

Thread Thread
jonrandy profile image
Jon Randy • Edited on

Yes, and people frequently do follow no rules... leading to the kind of trash I used to see in PHP that I hoped I'd never see again

Thread Thread
dhruvindsddev profile image
Dhruvin

Great for freelancing, nightmare for bigger companies

Thread Thread
cgatian profile image
Chaz Gatian

@dhruvindsddev In Angular you can have your HTML+TS+CSS all in one file. :)
When I open a React component I typically see 100+ lines of just hooks and startup code before getting to something interesting. When you finally make your way to the return sending back some JSX, the block is littered with different styles and opinions on how to structure, which makes it difficult to parse if it's not the style you're used to.

Thread Thread
jonrandy profile image
Jon Randy

The same with RiotJS - out of the box

Collapse
lukeshiru profile image
LUKESHIRU • Edited on

The Content Policy of DEV states that:

Posts must contain substantial content — they may not merely reference an external link that contains the full post.

Please, put the full post here or use the listings option if just want to promote.

Thanks for sharing!

Collapse
ezranbayantemur profile image
Ezran Bayantemur Author

And it's updated!

Collapse
ezranbayantemur profile image
Ezran Bayantemur Author

Sorry for the mistake, it's my first blog content on here and updating the content right now ✌️

Collapse
wagnerjw profile image
Julian W. Wagner

I just read your article on medium the other day, glad you're posting it on here too! Thanks for sharing, as a beginner/intermediate dev this helped me immensely

Collapse
ezranbayantemur profile image
Ezran Bayantemur Author

Thank you so much 🙏🏻

Collapse
akhilgautam profile image
Akhil

Where is the content? You should not drive audience to a different site.

Collapse
ezranbayantemur profile image
Ezran Bayantemur Author

Sorry for the mistake, it's my first blog post and I didn't knew the rules. I updated to post right now

Collapse
akhilgautam profile image
Akhil

Thanks for the response. 👍

Collapse
spock123 profile image
Lars Rye Jeppesen

Have you ever worked with other more modern frameworks? Let me tell you, in my opinion, React is by far the messiest of them all with regards to file/project structure.

Collapse
ezranbayantemur profile image
Ezran Bayantemur Author

Why do you think like that? I also worked with Vue and Angular but I liked React much more maintainable. We can manage our projects much more easy with it.

Collapse
dhruvindsddev profile image
Dhruvin

Yup same here, I really like working with react.

Collapse
kachidk profile image
Victor Nwanguma

That is your opinion, but there is no specific way to structure a project in any library or framework, even in php. Pick what's suits your team or you

Collapse
sargalias profile image
Spyros Argalias

Great post, thanks

Collapse
kachidk profile image
Victor Nwanguma

The funny thing is that people are complaining that "react is this react is that" if your code base is littered because of different people's opinions it's not because of the flexibility of React (which I enjoy).

It's because you have not established rules in your team guiding how the codebase should be

Collapse
guledali profile image
guledali • Edited on

What I found so appealing about react.js is everyone uses it and yet everyone uses it so differently and this can almost be meme in itself

Collapse
spock123 profile image
Lars Rye Jeppesen

It's like Macdonalds.. it's horrible food but very popular.

Collapse
jonrandy profile image
Jon Randy

Frighteningly, the 'everybody else uses it' line always seems to be the main justification to adopt it. Sadly, most tech decisions in companies boil down to business decisions

Collapse
guledali profile image
guledali

Damn🤣 🤣

Collapse
cgatian profile image
Chaz Gatian • Edited on

Good post. Thank you for sharing.

Collapse
mihailgaberov profile image
Mihail Gaberov

Hey Ezran, could this be a typo? "...light some blub on mind :)"

Collapse
johnyki79579551 profile image
johnyking

nice

Collapse
brojenuel profile image
Jenuel Oras Ganawed

After reading, its similar with vue, but for me vue is better. that is my opinion.

Collapse
gummy47 profile image
Gummy

Where is your store?

Collapse
ezranbayantemur profile image
Ezran Bayantemur Author

Sorry Gummy, I update it ✌🏻