Designing a React App from Scratch
Today APIs are designed to serve many different client apps, and business logic has moved to the client. Front-end development is no longer just about building interfaces, it's an art of programming!
These days MVC is slowly becoming hick “outdated”, APIs are designed to be shared by many different client apps (web app, mobile app or desktop app), and quite a lot of business logic has moved to the client app. Front-end development is no longer just about building interfaces, it’s an art and a bag of tricks of programming 😎.
Small note: this post assumes you already have some experience coding with React and are looking for, or building, a new architecture for a large, scalable web app.
One fine day, your company decides to tear everything down and rebuild the whole system into something bigger to keep up with the company’s business growth 😏, more maintainable & scalable than the old pile of sh!t code, and finally picks React. You’ve surely played with React a lot, otherwise you wouldn’t have picked it 😏, but there’s still plenty to decide in the front-end stack. React is basically just a view library and a lot of things don’t come with it (if you don’t want to make many choices, use a framework like Ạngular or Vue instead 😏 though of course they’re not as customizable and optimizable). State management, routing, localization, styling and UI, deployment and build scripts… Do you need a PWA (Progressive Web App) or SSR (Server-side Rendering)?
Fortunately unfortunately, you have a lot of freedom when deciding the parts of your React stack. If you know exactly what you’re doing (the requirements), you can even set everything up in a day or less. Otherwise it can take a week, or a few months weeks until everything runs smoothly. In this post I only cover architecting in a relatively ideal context, because if it’s not ideal there’s way too much to write 😂.
Before you start, analyze carefully and keep the code simple
Analyzing requirements and needs should be the first thing you do whenever you start something new. Whether the project is small or large, write the requirements down clearly and think as if you didn’t have it yet 😂. Of course, requirements can change often, sometimes even the direction and purpose of the project 😂, but that’s the future and nobody can predict it. It’s best to predict only a little so you don’t wear yourself out 😂.
To ship a decent first version of the product (MVP: Minimum Viable Product), it’s best to keep the code simple, only use the tools and libraries you need, and don’t overcomplicate things or show off 😂. Every developer loves trying and using new stuff, but not at this point (the start of the project) 😂.
About the team and people
I’ve set up quite a few projects, and one truth I’ve learned is: nothing is worse than starting a project while making your teammates research too many new technologies 😂. Imagine someone joining the project midway and having to spend 2-3 months researching before they can jump in. 😂 A typical example is adopting GraphQL for a project 😂 (everyone knows it’s mostly better than REST in large projects, but how many people have actually learned it, and learning it isn’t quick either 😞, if you decide to adopt it and the whole team has to bury themselves in research then… 😏).
Besides, JavaScript itself is an extremely messy language 😂, so common patterns and best practices matter a lot when coding together in a large project. If applied well, the project’s JS code will be easy to read, understand and maintain, otherwise the only option is to tear it down and build something else 😥. For example, just think about the JS code you wrote 6 months or a year ago 😂. So make sure your teammates know the best practices and the shared conventions of the project, apply eslint strictly & check the linter before allowing commits using husky, or use typescript, for example. It helps a lot in a large team.
Choosing libraries for the app, which one is the best? 😳
The answer: the library that you and your team know how to use and understand best, seriously 😂. If you know Redux well, use Redux for State Management. Or if you and your team work with MobX more, just use MobX. A stack or library is only truly good when the developers understand it and know how to make the most of it. I’m not saying you shouldn’t use new libs. I love learning new ones, but I only use them in personal projects and low-stakes projects where small mistakes are acceptable 😏. Learning a new library is not just burying your face in its docs, sometimes different libs have different approaches and different patterns that take time to master 😕.
Well actually, adding a few new libs is fine 😏, but make sure it won’t hurt the project’s progress and quality much, or make life hard for your teammates. Whether you like it or not, you have to think about the other developers on the team. “A good developer knows how to code. A great developer knows how to work in a team.” 😎 It’s better if your team has a lot in common technically, it makes development faster and smoother (on the other hand, it’s a disaster to put a team that only codes jQuery together with a React team without careful conventions 😂 it’d surely be a mess). Popular technologies (popular, not too old or outdated!) can speed up development a lot when the team scales in headcount.
My choices of libraries
For projects with large, important business and high stability needs, I don’t like using things in “beta” or “experimental” stages (sitting around waiting for an issue’s pull request to be approved 😒). Instead quality, reliability and scalability are the top priorities you need to focus on 😏. Below are some of the ones I picked.
Dev stack and Toolkits
Setting up a React project from scratch with Webpack and Babel is pretty fun and interesting, and cool too but to make it easier, I’ll use the create-react-app script first to design the main parts of the project, then eject and mount it back with webpack and babel, which seems better. Create-react-app v2 is really good lately (much better than v1) and supports most features small and medium apps need, but it still doesn’t seem to integrate with server-side rendering or do code chunking well, so I configure webpack & babel myself 😂 (also with webpack I can actively configure aliases or work with env files, which is a joy). As for SSR, it can be written in any language (Java, Go or .NET all work 😂), but here I pick Node.js and Express for simplicity, and for fetching API data on SSR for SEO, I use react-frontload and fetch. For React dev, webpack-dev-server with Hot Reload Module, Redux Dev Tool and Redux-Logger seem fine.
Besides, the requirement from the start is to rebuild a scalable app with SSR, PWA and its own build script, integrated with Docker too, so eject to be safe 😏. That said, honestly the webpack and babel config is still quite painful to this day 😂.
Decision: Webpack, React-Loadable, Babel, ReactDOM Server and Node.js Express for Server-side Rendering
UI Library
This is the hardest part to choose with tons of UI libraries out there 😂, like Material-UI or Ant Design. One small note: pick UI libraries that are properly built for React. I once happened to code in a React project that used MaterializeCSS, which works with jQuery to manipulate the real DOM, so it easily conflicts with React’s virtual DOM. In my opinion you shouldn’t use it 😂.
Bootstrap 4 is also available as a UI library: Reactstrap. I really like Bootstrap, but I had used reactstrap before and found it pretty messy and not well built, so I’ll probably wait for the bootstrap guys to reach version 4. In the end I picked AntDesign because I tried it and it’s pretty good (even though it’s Chinese), the design language is decent, it has lots of ready-made components and API support up to the teeth, and the documentation is detailed and proper too, approved 😍. Note: after using and optimizing it, I found its svg icon set a bit heavy when fully imported, which increases the bundle.js size considerably 😂, but it’s fine, we can customize the bundle with webpack 😏, anyway that’s for later.
Decision: Ant Design

State management
Simple, I pick Redux, because I’ve mostly worked with it so far 😂. Redux’s architecture and approach are pretty simple, and Redux is also built to work well with functional programming, very clear and easy to understand. Besides Redux there are a few less popular options like Flux (developed by Facebook, Redux took its architecture from Flux but is easier to use), or MobX (less popular than Redux).
Once you’ve mastered Redux’s architecture, you can freely choose the accompanying libs. Here I pick redux-thunk, reselect, redux-form (to manage form state easily; Ant Design actually has this built in, but it’s useful for custom forms); redux-saga is also pretty good, but it’s a bit too complex with a lot of API docs, and not many devs have experience with it, so I skipped it.
Decision: Redux, Reselect, Redux Thunk (middleware), Redux Form, Redux Logging (middleware), Redux DevTool
Suggested reading: Redux from a functional programming perspective
Localization
To set up multiple languages for the app I use redux-i18n, which is built into redux and pretty easy to use, plus a few previous projects already used it. There’s also a more popular lib, react-i18next, which is also easy to use.
Decision: Redux-i18n
Routing
For routing, react-router is a popular choice that works well in most projects. Its concept is a bit harder to grasp compared to the routers of Angular or Vue. Note that if you want to optimize by chunking code per Route (used with React-Loadable), you should write the Routing part carefully.
Decision: React-Router
Linter, Convention, Structure
Defining conventions and a Linter is an important step in building a code base, to ensure stable development and maintainability. For the Linter, I use eslint with some preset configs from airbnb, customized a bit. For lint checks, I use husky, lintstaged and prettier to check code lint and block commits and pushes when the code isn’t Lint-valid. Everything works great if you use VSCode with a few extensions pre-installed.
For Project Organization, there are quite a few ways that fit the app’s business and each team’s taste. I decided to implement Feature Based because it’s easy to scale and easy to code in a large project with many components. You can read more about this approach here: https://medium.com/@alexmngn/how-to-better-organize-your-react-applications-2fd3ea1920f1.
For the API/service caller, I chose to implement it in a separate code base repo, let’s call it API SDK, written in TypeScript. To scale, the Caller should be split out so it can be applied across many repos later without duplicating code, and to keep it encapsulated. Decision: write it as a separate lib repo and use axios for the caller.
For Unit Tests, I pick Jest and Enzyme because they’re quite popular for testing React apps.
For containerize and dockerize, a single Dockerfile is enough. With SSR it gets a bit more complex, and building with yarn (thanks to parallel and cache) or npm ci (cache stored in the git repo -> fits my use case of building docker images) seems faster than npm; read more about npm ci vs npm install here. It also integrates pretty well with Jenkins CI/CD (see the file below in the P/S section). When you need to go big, you can easily deploy as containers to a Kubernetes Cluster (using Google Kubernetes Engine, for example), you’ll have a load balancer (Nginx Ingress) and can create as many instances as you want 😏.
Read more: Deploying a containerized web application by Google Kubernetes Engine
So is it scalable yet? 😂
Which direction to scale depends on each project’s business, and you have to decide it yourself 😏. Basically it should be easy to expand (can be deployed as a container app), easy to develop (linter and convention), easy to extend components (structure), and the code should be highly reusable. In my personal opinion, to scale you should structure and organize the source code with expansion in mind (feature based, for example), design and place helpers and utils in suitable places (to import and reuse in many places), not duplicate code, wrap frequently called functions and have reusable components, apply Higher-Order Functions to bootstrap abstraction, and solve the CSS conflict problem (CSS War) between components with styled-components, for example. A code base that is easy to read and understand, clean, and highly customizable -> easily handles requirement changes, with a clear set of conventions and documenting, lint-valid everywhere… and so on and so forth.
Feature Based:
|-- project-name
| |-- src
| | +-- common
| | |-- features
| | | |-- home
| | | | +-- redux
| | | | |-- index.js
| | | | |-- DefaultPage.js
| | | | |-- DefaultPage.less
| | | | |-- route.js
| | | | |-- styles.less
| | | | |-- ...
| | | +-- feature-1
| | | +-- feature-2
| | +-- styles
| --- tools
| | +-- plugins
| --- scripts
| | |-- build.js
| | |-- start.js
| | |-- ...
|-- .eslintrc
|-- .gitignore
|-- ...
Read more about 4 ways to style React components.
Read the post about scaling on huydx’s blog. The conclusion: To build a “scalable” system, you only need 4 steps: guess -> test -> improve -> guess again, and I’m still just loitering in this loop 😂. The 2 benchmark (testing) tools I use often are Google Pagespeed and Lighthouse.
Summary
You’ll be fine if you stick with popular libs (not the latest) or follow existing best practices and patterns. We don’t need to pick truly new libraries, because: “business always comes first”, and so we need things that are reliable and better for the team, things that keep everything on track and moving faster.
A few more important factors: using libs with a large community and long-term support is better for the development process. You’ll get support from other developers around the world via stackoverflow and github pages, and issues can be fixed and merged very quickly by contributors.
P/S: I applied that code base to one of my side-projects, click https://github.com/gosu-team/fptu-fe if you want to see the codebase.
