DEV Community: juanIgnacioEchaide

Migrating UI library shouldn't be a pain in the stack (3)

juanIgnacioEchaide — Tue, 06 Dec 2022 17:05:02 +0000

The segregated UI

After all the codebase we’ve been designing we can start with our UI development.

Our domain is set and we should be able to code the front of the front, sort of speak.

I provide to you two examples. The first one uses styled-components as third party library.

I think is the best choice because it could be combined with many other style tools (Tailwind, Material UI, and almost every one of them).

Bear in mind we are trying to have the less amount of UI components.

Our DOM should not be frequently updated and the solution to address this necessity relies mostly in a reusable grid component.

Like a film set of a TV show, we need a thin layer that leaves space to the children like windows in a wall.

Those children are the ones that update when UI events take place, but the grid keeps in cache until that happens reducing computing efforts at maximum.

I made my choose for an atom design folder architecture inside UI folder which distributes component in increasing granularity.

My personal choice is to gather the atoms I will reuse in a molecule in a single file with the same name, but you could organize it differently.

Let’s see the case of Grid atoms (src\UI\atoms\Grid.tsx) most precisely the main container:

const Container = styled.div`
  display: grid;
  height: 100vh;
  grid-template-rows: 0.2fr 0.5fr 2fr 0.2fr;
  grid-template-areas:
    'nav nav nav nav'
    'sidebar content content content'
    'sidebar main main main'
    'footer footer footer footer';  
  text-align: center;
  grid-gap: 0.25rem;
  transition: all 0.25s ease-in-out;
  @media (max-width: 550px) {
    grid-template-columns: 1fr;
    grid-template-rows: 0.4fr 0.4fr 2.2fr 1.2fr 0.5fr;
    grid-template-areas:
      'nav'
      'content'
      'main'
      'sidebar'
      'footer';
  }
  color: white;

Styled components allows us to handle the display property like a grid defining the template grid areas which is extremely useful for our purpose.

Also, we could manage at the same component file the media queries to define how that template areas will behave in different viewports according to each device type. This is a very simple example this media queries should be robust enough to deliver a nice UX.

The rest of the children will have our Grid as parent and will perform as our static layout conforming one single molecule.

These are nothing else but empty boxes which its main concern is to layout our view once for all at the first load.

Our first UX molecule looks like this:

import { GridTemplateProps } from '../../common/models/props'
import { NavBar, ContentBox, Details, Main, SideBar, Footer, Container } from '../atoms/Grid'

const Grid = ({
  nav,
  main,
  details,
  side,
  footer,
}: GridTemplateProps): JSX.Element => {
  return (
    <Container>
      <NavBar>{nav}</NavBar>
      <ContentBox>
        <Details>{details}</Details>
      </ContentBox>
      <Main>{main}</Main>
      <SideBar>{side}</SideBar>
      <Footer>{footer}</Footer>
    </Container>
  )
}

export { Grid }

In almost every case this children are static components without any particular implementation because routes or pages names, title of the app, and footer data won’t change.

The Page Template, our only element to be render as a container component will then have a return statement that looks like this:

  return (
    <Grid
      nav={<Title/>}}
      main={!atHomeView() && <ItemsList items={items} />}
      details={<Details currentPage={currentPage} />}
      side={<SideMenu setView={setView} />}
      footer={<Title/>}
    />
  )

That component encapsulates the entire logic of render of our App.
But in order to make it work correctly we need to make a few observations regarding the effect hooks that the optimum update requires.

First thing we must implement is the correct consumption of the data stored in context.

This feature implies the use of the context which is not a big deal if you already have work with useContext before:

  const { state, dispatch } = useContext(QueryContext)

A good practice could be returning the data of the context as well as exposing the functions declare inside with a custom hook, to avoid several definitions of this useContext.

In our case where we only have one single element as page it doesn’t represent any trouble.

Remember: declaring variables just once and calling only as needed is essential to obtain a performant product in React.

We are able to access the whole state, but we want just part of it to be available at our PageTemplate component’s state according to the view.

That’s the reason why we need to implement a logic to dynamically retrieve that relevant section automatically. This is the concern of the getViewState function:

  /* retrieve the relevant section of state by current view */
const getViewState = (state: BaseState) => {
    return state[state?.view as keyof BaseState]
}

A simple function using computed properties passed as parameter to return that particular entity state and not the whole object which still at our context available for every component tree of our App.

We want to populate the state of the page component only with the items that should be displayed in that route.

We want this to happen only in two scenarios. By the time of mounting, of course, populating state with the “allQuery” of that view. And any time that the state suffers a change. This should only happen after a dispatch to the store (e.g.: a user sets a parameter and the value of that parameter on state changes).

Just like this (src\pages\home\Home.tsx):

  const [items, setItems] = useState<AnyBusinessEntity[]>([])

  useEffect(() => {
    if (state) {
      setItems(getItemsByView())
    }
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [state])

Nothing different from what you already know about useEffect. However, this is a good opportunity to make an observation.

You might find that I disabled the exhaustive dependency from my lintern.

That’s because following the common criteria we should include the getItemsByView signature.

In our case that will lead to an infinite loop and crash. This way anytime state changes (e.g.: the user chooses other view) the relevant children of our page component will re-render.

And there it is our layout first shot at “/starship”, rendering only names of each starship:

I told you that all the cool details on UI will be missing, but decoupling is done already. The green square shows the only two components that re-render any time the view changes.

I suggest you tracking this behaviour with the react devtools in your browser at “components”. From this point you could improve the UX as much as you want.

Owning your atoms

One thing I consider useful is to own your atoms, specifically boxes or containers.

That’s because we are considering huge UI changes such as a migration from a library or total redesign in case of our clients’ rebranding, etc.

Could be really annoying to “lose” your most simple div containers and re start from zero ground again.

Also, we can take advantage of the effort of designing of our base components to make development better experience: faster, easier to test, and more legible.

Let’s see (because of reasons of extension) the return statement of our BaseBox component (src\UI\atoms\Box.tsx):

  return (
    <div
      style={{
        display: "flex",
        width: `${w?.toString()}vw`,
        height: `${h?.toString()}vh`,
        flexDirection: setFlexDir(column, row),
        placeItems: placeItems ? placeItems : none,
        justifyContent: setJustifyContent(),
        alignItems: setAlignItems(),
        background: bg ? bg : none,
        borderRadius: rounded ? "7px" : none,
        padding: p ? px(p) : none,
        paddingTop: pt ? px(pt) : none,
        paddingBottom: pb ? px(pb) : none,
        paddingLeft: pl ? px(pl) : none,
        paddingRight: pr ? px(p) : none,
        margin: m ? px(m) : none,
        marginTop: mt ? px(mt) : none,
        marginBottom: mb ? px(mb) : none,
        marginLeft: ml ? px(ml) : none,
        marginRight: mr ? px(mr) : none,
        fontSize: px(fs),
        overflowY: "scroll"
      }}
    >
      {children}
    </div>
  );

This way we are making an abstraction that release us from using stylesheets separately and including a lot of code in each case.
Let’s suppose we want to right a container that has justify-content: space-around, scrollable on the “y” axis, a grey background, full height, and rounded borders.

Using our abstraction, we could define this type of box for containing list in our app. Then might looks like this:

const ListBox = ({ children }: any) => {
  return (
    <BaseBox justifySpaceAround h={100} bg="grey" scrollY rounded>
      {children}
    </BaseBox>
  )
}

Memoizing the list of items

One last thing to make all this example work right is required: memoization.

The ItemList component could lead us to an infinite loop if we let it go just like that.

Because state changes much more times than we want our item list to change. The solution to this is using Memo higher level API.

This enhancement is not only saving us from a preventive error is also allowing us to optimize our app.

Every time that a list of items is retrieved if that list doesn’t change, after all the reactive updates we designed, the already stored in cache list will be rendered.

This means that if a user visits a view, goes to another, and then come back, our view won’t re-render. React will show the already computed values saving a lot of effort to the client browser.

We declare our component in the usual way. This is a good opportunity to handle the loading scenario to give the user feedback during load.

And then we wrap up that component with the memo high order component a default export it to be injected in our PageTemplate and Grid component. Like this:

const ItemsListComponent = ({ items }: ItemsListProps): JSX.Element => {
  if (!items?.length) {
    return <div>loading...</div>
  }

  return (
    <BaseBox h={66} scrollY justifySpaceAround>
      {items?.map((i: any) => (
        <p key={setKeyByType(i)}>{i.name}</p>
      ))}
    </BaseBox>
  )
}

const ItemsList = React.memo(ItemsListComponent)

export { ItemsList }

Do not forget to set the View!

As I told you before despite we are leaving to react-router-dom the routing of our app we must set the view while our user clicks and redirects to another view.

We need two changes for that. The atom of our links in the side menu should receive a click function that dispatches the current view to our query provider state:

const SideMenu = ({ setView }: SideMenuProps) => (
  <SideContainer>
    {RoutesStack?.map((i) => (
      <SideLink
        style={{ paddingTop: "5vh" }}
        key={i.name}
        onClick={() => setView(i.name)}
        to={i.path}
      >
        {i.name}
      </SideLink>
    ))}
  </SideContainer>
);

export { SideMenu };

Finally, we obtained a UI that looks like this

Material UI example

As I told you this is a raw layout without any look and feel. The equivalent of the Grid we worked with styled-components but now with Material UI, with all the differences regarding implementation and library’s boiler plate, looks like this:

const Layout = ({ nav, sideMenu, main, footer }: LayoutProps) => {
  const classes = useStyles()

  return (
    <div className={classes.root}>
      <Grid container spacing={0}>
        <Grid item xs={12}>
          <Box className={classes.nav}>{nav}</Box>
        </Grid>
        <Grid item xs={3}>
          <Box className={classes.sideMenu}>{sideMenu}</Box>
        </Grid>
        <Grid item xs={9}>
          <Box className={classes.main}>{main}</Box>
        </Grid>
        <Grid item xs={12}>
          <Box className={classes.footer}>{footer}</Box>
        </Grid>
      </Grid>
    </div>
  )
}

export { Layout }

Then this is the look & feel with Material UI

Conclusions

You must realize by now that much of the logic that we implemented these the same that third-party libraries use the practice.

ReactQuery, Redux, Recoil, and many others work just the same as the logic that we've implemented in our monolith.

Why not just inject those dependencies?

Libraries always have a cost: slower deploys, peer-dependencies issues, risk of deprecation, and finally in a small project like our example too many code blocks that will never be called with a performance leak and memory waste. The last ones also imply much money earned if we are working serverless.

On the other hand, the approach that we chose leaves to us the responsibility of unit testing. The object literals structure make things easier also in that matter, because we just need to test that a value in an object is a function signature or a call.

Most of it is static allowing simple assertions to cover all scenarios repeating the same test approach.

Scalability with coverage results to be easier because of the same reason, pure repetition. You can also use features like jest.Each with a table.

A webapp split in several micro-frontends is also a good reason to avoid too much dependency injection from third parties reducing maintenance cost.

I am convinced that this approach is useful because each single view project should be small and recurrently deploy and in cases where the UI components come from an internal library but in an external project a decoupling will prevent too much refactoring.

In the end this is just a prove of how flexible React is and invitation to try innovative architecture following the most accepted principles.

Thanks!

Migrating UI library shouldn't be a pain in the stack (2)

juanIgnacioEchaide — Tue, 06 Dec 2022 17:04:50 +0000

State rules

We want to obtain a segregable or splittable UI decoupling the business logic as much as possible from UI components.

We said that all the api calls will result a reaction to state changes. That’s the reason why we need to be able to access this state from anywhere.

Context API is a great tool for that. You could choose a third party library for state-management such as Redux, ReactQuery, Recoil, and others.

Even when those are great tools with different pros and cons in each case I decided to use Context API because it comes with the React megalibrary. We won’t nothing else than ReactJS to manage our state.

This way we are going to have a QueryProvider. This high order component will wrap up the entire App and allow us to access the state to read and/or modify it from every component avoiding prop-drilling and code repetition.

This provider will have a reactive logic itself listening to the VIEW we are navigating and the parameters user selects.

The main concern is strictly to provide interaction with the state. But it must update itself to release UI components from the responsibility of triggering API calls.

It will handle the UseQueryByView custom hook we analysed before and a reducer that receive actions and manages the updates of state.

We create a Context as usual and declare the provider with its value (the state indeed and the dispatch function from reducer). Nothing different from a regular context (src\context\query\QueryProvider.tsx):

const QueryContext =  createContext<ContextValue<BaseState>>(defaultContextValue);

const QueryProvider = ({ children }: any) => {
  const [state, dispatch] = useReducer(BaseReducer, defaultState);
  const viewPath = getLocationPath();
  const value = { state, dispatch };

We can destructure the dynamic queries from our hook this way:

  const {
    allQuery,
    byPageQuery,
    byIdQuery,
    searchQuery,
    updateDispatch,
    displayGenericError,
    setView,
  } = UseQueryByView();

And there is only one thing left to make it work, the logic that reacts to state changes triggering calls.

This is the concern of the fetchDataByPage function, which I divided into three little conditioned blocks for the three scenarios I wanted to handle.

With no parameters at all the “allQuery” of the corresponding view should be triggered.

If the id parameter with a value different from default 0 the byIdQuery should be triggered.

If the page parameter changes it does the proper thing with byPageQuery.

It's very important to be strict with the updates. The comments on useEffect’s dependency arrays, memorization and useCallback usage are essential to obtain the wanted result.

But also, if you play changing them you will found out that infinite loops and preventive crashes come around.

Having ownership means to have full responsibility and not just simply rely on the library and usual boilerplate.

Let’s see how it is implemented the allQuery block (src\context\query\QueryProvider.tsx):

  const fetchDataByPage = useCallback(() => {
    if (state?.view && state?.view !== VIEW.HOME) {
      if (state?.pageParam === 0) {
        allQuery(state?.view)
          .then((data: SwapiResponse<People | Planet | Starship>) => {
            const payload = setUpdatePayload(data);
            return dispatch(updateDispatch(state?.view, payload));
          })
          .catch((err) => dispatch(displayGenericError()));
      }
    }
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [state?.view, state?.pageParam]);

A little thing to mention is the setUdatePayload function that models our payload to correctly store it in our state.

Strictly speaking it is like a little mapper than transform the structure retrieved by services into a data model our business logic needs.

The returned type is precisely de UpdatePayload. Please bear in mind these details because they are key to simplify the handling data.

/* abstraction to partially update state for pagination */
const setUpdatePayload = (data: SwapiResponse<any>): UpdatePayload<any> => {
    return {
        currentPage: getPageFromUri(data?.next) - 1,
        nextPage: getPageFromUri(data?.next),
        prevPage: getPageFromUri(data?.previous),
        results: data?.results,
        nextUri: data?.next,
        prevUri: data?.previous,
    } as unknown as UpdatePayload<any>
}

Finally, let’s see the most important of the state management in the way we implemented our context, the reducer (src\context\query\BaseReducer.ts).

This reducer works with a switch structure but you could implement it as object literals as we did for our queryByView.

The switched value is a constant stored in an enum call ActionType (src\common\constants\context.ts):

enum ActionType {
    SetLoading = "setLoading",
    SetError = "SetError",
    SetView = "SetView",
    SetPrevUri = "SetPrevUri",
    SetNextUri = "SetNextUri",
    ClearError = "ClearError",
   {…}
}

First part of the BaseReducer handles the UI aspects and navigation:

const BaseReducer = (state: BaseState, action: Action): BaseState => {

    switch (action.type) {
        //// UI FLAGS & NAVIGATION 
        case ActionType.SetLoading: return {
            ...state,
            loading: action.payload
        }
        case ActionType.SetError: return {
            ...state,
            error: true,
            errorMessage: action.payload
        }
        case ActionType.ClearError: return {
            ...state,
            error: false,
            errorMessage: ''
        }
        case ActionType.SetView: return {
            ...state,
            view: action.payload
        }
{…}
}

The most important of those actions is to set the view, our key to guide all our state changes.

The main target is to have available the flags of loading, error, etc., on state and then render whatever you want to communicate that state to users thru UI components.

The second part of this reducer handles the update of the items data retrieved from the Star Wars API:

        ///// POPULATES PERSISTENT GLOBAL STATE 
        case ActionType.UpdatePeople: return {
            ...updateAfterLoad(StateEntity.People, action.payload, state)
        }
        case ActionType.UpdateSpecies: return {
            ...updateAfterLoad(StateEntity.Species, action.payload, state)
        }
        case ActionType.UpdatePlanets: return {
            ...updateAfterLoad(StateEntity.Planets, action.payload, state)
        }

        {. . .}

The updateAfterLoad function that we return with spread operator makes the dynamic update by the corresponding entity, populating the portion of the state with the proper payload, and of course we return an entire state.

Because our reducer has to be a pure function that keeps the previous state merged with the update made by the current action we need to pass as parameter the full state.

Let’s see the function (src\common\utils\helpers.ts):

/* abstraction to partially update state after response */
const updateAfterLoad = (
    entity: StateEntity, 
    payload: any, 
    state: BaseState, 
    currentPage?: number, 
    totalPages?:number
    ) => {
    return {
        ...state,
        [entity]: payload.results,
        loading: false,
        error: false,
        errorMessage: '',
        prevPage: payload.previous,
        nextPage: payload.nextPage,
        currentPage: payload.currentPage,
        nextUri: payload.nextUri,
        prevUri: payload.prevUri,
        displayed: {
            ...state.displayed,
            [entity]: payload.results
        },
    } as BaseState
};

A constant of StateEntity is used as a computed property to match the entity state we want to overwrite, this way we can reuse this logic in our reducer for every case of items to be displayed.

Also because of the backend pagination of the API we are using we need to keep track of it in the state.

Like all the rest of this example we try to take the most advantage of abstraction, generics, and computed properties as possible to not repeat code.

Services layer

I personally like so much the layer stratification of the application from Clean Architecture.

The architecture I am proposing here follow this principle. Our UI layer is yet to be done but of course our target is to implement it segregated enough to not suffer future migrations or changes.

The data layer is represented for our QueryProvider partially.

A good practice would be to create another context that properly addresses the data modelling and related issues as a child of the QueryProvider, listening the state and transforming data into static content to be provided or served to the UI layer.

We are going to manage these issues on the PageTemplate component (our only page, strictly speaking).

Our services layer consists of an axios instance:

const apiClient = axios.create({
  baseURL: URI.BASE,
  responseType: "json",
  headers: {
    "Content-Type": "application/json"
  },
});

An object named api contains keys for each screen, and values with the signatures of each API Call. You might splitted if you are working folder architecture which segregates modules or features isolated. I decided to declare one single object to keep the monolith structure. Like this (src\services\apiClient.ts)

const api = {
    people: {
        getAll: (): Promise<AxiosResponse<SwapiResponse<any>>> => {
            const data = apiClient.get(URI.PEOPLE);
            return data
        },
        getByPage: (page: number): Promise<AxiosResponse<SwapiResponse<People>>> => {
            const data = apiClient.get(`${URI.PEOPLE}/?page=${page}`);
            return data
        },
        getById: (id: string | number): Promise<AxiosResponse<SwapiResponse<People>>> => {
            const data = apiClient.get(`${URI.PEOPLE}/${id}`);
            return data
        },
        search: (params: string ): Promise<AxiosResponse<SwapiResponse<People>>> => {
            const data = apiClient.get(`${URI.PEOPLE}?search=${params}`);
            return data
        },
{…}
    },

This instance also admits interceptors that allows to manage centrally some response’s code.

This is useful if you are working end to end with API Rest.

If you are using GraphQL or other tools that do not follow API Rest codes you could design your own interceptors to differentiate each case in the 400 code that Graph use to retrieve when the query is bad structured, or parameters are missing.

The best practice is to have your own error dictionary, like the queryByView object and the viewStateLogic type we’ve seen before.

// centralized error handling thru interceptors
apiClient.interceptors.response.use(
  (response: AxiosResponse) => response,
  async (error: AxiosError) => {
    if (!error.response) {
      return Promise.reject(error);
    }
    switch (error.response.status) {
      case 401:
        throw Error("Unauthorized user");
      default:
        throw Error(error.message.toString());
    }
  }
);

export { apiClient };

There is another layer of abtraction inside the services layer consisting of one file per endpoint and the implementation of the concrete call.

I consider this layer fundamental to be really open to changes in the service layer despite this concrete example does not necessary requires it. Let’s see the case of people screen:

import { api } from "./api"

const getPeopleById = async (id: string | number) => {
    const { data } = await api.people.getById(id)
    return data
}

const getAllPeople = async () => {
    const { data } = await api.people.getAll()
    return data
}

const getPeopleByPage = async (page: number) => {
    const { data } = await api.people.getByPage(page)
    return data
}

const searchPeople = async (params: string) => {
    const { data } = await api.people.search(params)
    return data
}

export { getPeopleById, getAllPeople, getPeopleByPage, searchPeople }

typescript
This services layer could be implemented differently, of course. You might decide to go for a custom hook in the way of a useFetch to be reused in each call. It is not the core hypothesis we are trying to prove, and it does not conflict if is properly segregated.

Side by side with routing

This is our last step before dive into UI aspects and the reusability we are after to.

I decided to work the routing of our example with react-router-dom.

Nothing different from standard codebase except for two considerations:
a) our routes are also views stored in the state and,
b) we are going to render one single element for every routes. We are trying not only to have a segregable UI, also we need an optimized one.

We are going to work with one single template component cached in our browser exclusively updating the items we want to display at lists.

This decision will also make our job easier if we decide for any reason to migrate our UI third party libraries or even if a design change comes up avoiding the rework we might have if the logic we put in our monolith would be at our components.

The AppRouter component is the one concerned of routing the views and updating the render items (src\AppRouter.tsx):

import React from "react";
import { BrowserRouter as Router, Route, Routes } from "react-router-dom";
import { ROUTES } from "./common/constants";
import { VIEW } from "./common/constants/uri";
import Home from "./pages/home/Home";

const RoutesStack = [
  { path: ROUTES.BASE, view: VIEW.DEFAULT, name: VIEW.DEFAULT },
  { path: ROUTES.HOME, view: VIEW.HOME, name: VIEW.HOME },
  { path: ROUTES.PEOPLE, view: VIEW.PEOPLE, name: VIEW.PEOPLE },
  { path: ROUTES.PLANETS, view: VIEW.PLANETS, name: VIEW.PLANETS },
  { path: ROUTES.STARSHIP, view: VIEW.STARSHIP, name: VIEW.STARSHIP },
  { path: ROUTES.FILMS, view: VIEW.FILMS, name: VIEW.FILMS },
  { path: ROUTES.VEHICLES, view: VIEW.VEHICLES, name: VIEW.VEHICLES },
  { path: ROUTES.SPECIES, view: VIEW.SPECIES, name: VIEW.SPECIES },
];

const AppRouter = () => {
  return (
    <Router>
      <Routes>
        {RoutesStack.map((route) => (
          <Route path={route.path} element={<Home/>} key={route.path} />
        ))}
      </Routes>
    </Router>
  );
};

export { AppRouter, RoutesStack };

I declared an array with the RoutesStack not using the Routes structure react-router-dom provides to not repeat the element we are going to render.

This way our app always is at the same component not only at the same index.html page.

This container is good enough for a webapp where you only to display items. But you could enhance it in a more complex way with several templates.

he other consideration regarding routes and views has to be take into account when we redirect thru the click function of the respective route.

We have to trigger both functions: react-router-dom linkng and the dispatch to store of the corresponding view. If we go side-by-side with routing all our monolith will provide us with its benefits.

To be continued on Part III

Migrating UI library shouldn't be a pain in the stack (1)

juanIgnacioEchaide — Tue, 06 Dec 2022 17:04:27 +0000

Keep your React app opened to style changes

The issue. The lead-lined lifejacket

Every time that a project starts we must make a decision of which UI library to use, or we can take the hardest road of making our own "lib".

I personally recommend the second choice because you will have full ownership of your components, without deprecation risk or unexpected incompatibilities with other third-party libraries.

However, we must consider the state of the project. This approach could not be the best for an MVP or a project with less than 2 years.

Changes and obstacles will come up and we might consider needing to migrate.

Then, we found ourselves between two awful possibilities:
a) injection of a lot of dependencies that will look good but with high performance and maintenance cost,
b) facing a gigantic refactor that will result in almost developing everything since the beginning again.

Our UI library was supposed to make us easy to float avoiding a lot of code, but it made us sink in re-work.

I will give you some guidelines through this article (divided in three parts) to enough split your code to make UI migration possible with reasonable effort.

Our core concept is represented in this chart:

The case study: little Star Wars app

I will take one of the most used challenges for recruiting which is the Star Wars API. It’s a simple example, just one of thousands of possibilities.

I encourage you to innovate and try to design a new and creative architecture that allows you to easily migrate UI libraries.

Even when the architecture of this example does not follow an orthodox model it does rely on SOLID principles, clean or onion architecture, flux architecture, and React’s good practices.

This architecture I’m proposing is nothing else but an extension of the criteria that the React mega library as well as third-party dependencies most used with it rely on.

The target of this article is to stimulate all those that find React a fascinating tool to dare to create, dare to innovate.

The monolith

We will rely on two JavaScript (and TypeScript) typical features that will allow us to work dynamically with the values we use computed properties and object literals.

Bear in mind that JS and TS strength is managing arrays and objects.

Our decoupled monolith will have another feature which it’s inspired in flux architecture.

We are going to trace every behaviour by its view. Our guide will be a simple string value contained in a simple Enum data structure TS provides us.

Even when some other features will be triggered by another state values (e.g.: API call parameters) the view is our most important value.

Listening the values on state behaviour will be triggered only when an update of these values take place. Same criterion for the update of UI components.

The target is to have absolute control of update, and make it work as a reaction of UI events such as navigation or parameter selection reducing unpredictability as much as possible.

Disclaimers

This intent might not be the best for your first React App.

We will design our codebase very differently from current standards and even when I am confident of the guidelines I am following is yet to be fully tested and discussed.

On the other hand, I must assume you already work with React and have some experience developing applications in general because of extension limits.

You will not see pretty UI designs here. It is not possible to achieve all goals in the case study example.

We will conform ourselves with behaviour and functioning dependency injection from third party UI libraries, and nothing else. I will leave to you the UI design to make it look cool.

The point I am wanting to prove is that decoupling itself, then all UX and UI aspects taking place on representational components must be left outside.

Finally, I will not explain every line of the codebase but the most representative of each block so you can continue to dive into it by yourself.

To offer a fully functional example I had to develop much more code than an article could fully explain.

Nevertheless, I tried to be enough consistent to make the project easy to understand with a few hints I will give here.

Yes, there is a repo

You will find at this link the repo with the codebase we will follow in the current article:

I wanted to provide a practical way to comprehend the point I am trying to make.

That’s the reason why you will find only the domain I have referred to before and nothing else regarding UI component but a simple screen writing the data on state.

I want you to see by yourself the monolith with our frontend business logic is autonomous enough to sustain itself.

The decoupling works by the time that our app works without crashing even when do not render any proper representational component to give a nice UX.

But to entirely prove the assertion behind this article you will find in the following branch, the first UI example using styled-components. (Remember to run an install every time you switch).

The second example with representational components using third-party libraries works with Material UI.

Actually, both libraries combine perfectly despite I give separated examples just to make clear the core concepts.

The theatre of operations

There is a sort of city hall of our architecture. And one of its corner stones is the following object literals which a partially paste below (src\hooks\query\QueryByView.ts):

    [VIEW.PEOPLE]: {
      allQuery: () => {
        return getAllPeople();
      },
      byPageQuery: (page: number) => {
        return getPeopleByPage(page);
      },
      byIdQuery: (id: number) => {
        return getPeopleById(id);
      },
      searchQuery: (stringParam: string) => {
        return searchPeople(stringParam);
      },
      updateFn: (data: UpdatePayload<People>): Action => {
        return QueryActions.UpdatePeople(data) as Action;
      },
    },
    //{. . .}
      },
    },
  };

The object is much bigger but it is just a repetition of this section.

We have a computed property as key. This means that is value is computed dynamically, JavaScript compiler look for the key inside the object comparing with a value provided as parameter, and “stops” when it matches a key (view).

The values inside this object are objects themselves and its keys are the query types we will use in each API URL.

The Star Wars API results to be very comfortable to be worked this way: one URL per entity and every endpoint has its own “getAll”, “getById”, “getByPage”, etc.

The object value has a signature as keys, it actually works as a segregated interface opened to extension and closed to changes following SOLID.

Don’t be confused because of the object structure.

Every signature has an arrow function as value which triggers the proper API call declared at the service layer we will soon analyze.

We can keep consistency thru the ViewQueries type (src\common\models\entities.ts):

type ViewQueries = Record<VIEW | any, ViewStateLogic>

ViewQueries type is a Record type like a “dictionary”, a collection of key-value pairs that stores data or logic. As we said our keys are Views (src\common\constants\uri.ts):

enum VIEW {
    DEFAULT = "",
    HOME = "home",
    PEOPLE = "people",
    PLANETS = "planets",
    STARSHIP = "starship",
    FILMS = "films",
    VEHICLES = "vehicles",
    SPECIES = "species",
    SEARCH = "search"
}

And our values are a type I called ViewStateLogic (src\common\models\entities.ts)

type ViewStateLogic = {
    allQuery: () => APICall;
    byPageQuery: (
        page: number
    ) => APICall;
    byIdQuery: (
        id: number
    ) => APICall;
    searchQuery: (stringParam: string) => APICall;
    updateFn: (data: UpdatePayload<AnyBusinessEntity>) => Action;
}

It’s a simple type that works as our interface and in almost every case is an APICall type I declared:

type APICall = Promise<SwapiResponse<AnyBusinessEntity>>

A promise of a SwapiResponse type, an abstraction that keeps the structure of the response our API delivers and allows us to reuse it with generic definition of the entity we are retrieving which could be a single one or an array of it (src\common\models\entities.ts).

type SwapiResponse<T> = {
    count: number,
    next: string | null,
    previous: string | null,
    results?: T[] | T
}

The generic entity we could retrieve is a AnyBusinessEntity, an alternative type that encapsulates all entities referred to our business logic, this way (src\common\models\entities.ts):

type AnyBusinessEntity = People | Specie | Starship | Planet | Vehicle | Film;

There is one signature of each object value of the queryByView object that is not an API call.

Is the dispatch that allows to send the retrieved values to our state.

I decided to include the signature of the corresponding dispatch function in each case to make the development faster and easier.

The main concern of this object is to integrate the logic thru signatures that calls definitions correctly splitted.

I will resume this subject in our next title regarding state management.

We explained the object literals which is one of our business logic’s cornerstones so far.

But it is a static object, a machine that waits for its operator. Then is when the custom hooks who handles it (UseQueryByView) comes into action.

I divided it on two parts: the API Calls and the dispatch functions, like this (src\hooks\query\UseQueryByView.tsx):

  // API CALLS
  const allQuery = (viewScene: VIEW) => {
    return queryByView[viewScene]?.allQuery();
  };

  const byPageQuery = (viewScene: VIEW, page: number) => {
    return queryByView[viewScene]?.byPageQuery(page);
  };

  const byIdQuery = (viewScene: VIEW, id: number) => {
    return queryByView[viewScene]?.byIdQuery(id);
  };

  const searchQuery = (viewScene: VIEW, stringParam: string) => {
    return queryByView[viewScene]?.searchQuery(stringParam);
  };

All those functions receive a VIEW as a parameter, that value permits to dynamically compute the key that matches on our queryByView object.

We need and optional chaining of the property inside de object value we access when computed value matches to avoid any error.

May seems tricker than needed but keeping everything dynamic will help us to make our UI components extremely reusables and with the less updates as possible.

Ideally I want to use one single template that dynamically updates reacting to UI events.

Our target is to have a set of queries automatically triggered and/or available to do so as a response to user behaviour depending on the screen we are navigating, nothing else.

Second part of the UseByQuery hook gathers the dispatch functions. This is crucial because the behaviour of our app concerning the relationship with API depends on state changes:

  // TO BE DISPATCHED
  const updateDispatch = (
    viewScene: VIEW,
    data: UpdatePayload<AnyBusinessEntity>
  ) => {
    return queryByView[viewScene]?.updateFn(data) as Action;
  };

I will resume the explanation of the three last functions. They are stored in QueryActions object which is our next title’s subject.

The first one called updateDispatch receives the VIEW to navigate the object literals queryByView, but also structures a payload data to be stored on our state dynamically thru the UpdatePayload type.

When the VIEW matches the key in the object literals triggers the specific update function and sends the payload structured by this type with generics again to reuse code (src\common\models\entities.ts):

type UpdatePayload<T> = {
    currentPage: number,
    nextPage: number,
    prevPage: number,
    results: T[],
    nextUri: string | null,
    prevUri: string | null
}

I recommend you following the same steps of this and the incoming titles using breakpoints in your browser.

Depurating functioning code will make things clearer than any explanation by written.

All the abstraction and dynamic approach appears to be too much effort but keep in mind that all this is oriented to make scalability a piece of cake.

It is hard to design but easy to make securely and consistently grow. The basis of a project is key to take the most advantage of available resources on the future.

To be continued on Part II