DEV Community: Olexandr

I asked successful entrepreneurs about their transition from employee to founder

Olexandr — Sun, 30 Nov 2025 14:48:07 +0000

The following is the conversation with… just kidding 😄

This year, I attended the Lviv IT Arena. I met a few founders there and asked each of them to describe the very beginning of their entrepreneurial journey. If you’ve ever daydreamed about starting something on your own but didn’t know where to begin, you’ll see that even successful founders once stood exactly where you are.

In this article, you won’t find polished success stories. This is where you’ll get to know how the leap from employee to founder truly feels like.

I don't dare to take more of your time, so the first question is…

How did you cope with the switch from employee to founder?

What did the transition period look like for you?

Anton Avrynskyi, CEO & co-founder of Liki24 (former Deputy Chief Executive Officer, IT-Enterprise): The first thing you need when moving from employee to business owner is a financial cushion.

You should have enough saved to give yourself at least six months to fully switch gears without constantly worrying about money.

This buffer won’t last forever, but it makes the transition manageable.

The second thing is understanding what truly excites you. I strongly recommend going to events like IT Arena and other startup competitions. Listening to pitches and hearing different founders speak is one of the best ways to discover what resonates with you.

Oleksandr Shcherbak, CBDO & co-founder of Lilo (former Chief Business Officer, HELSI): Frankly, it was both exciting and terrifying. You constantly wonder whether it will work or not. As an employee, you have stability, and giving that up is never easy. But I started to stagnate after the team of professionals, which I was a part of, made HELSI a major player and a market leader.

Everything was running smoothly, but I felt like the race was over.

I missed the drive and challenge, and at that point, I realized it was time to build something new.

Sergiy Danylov, Co-Founder of Anima (also Professor Assistant, Taras Shevchenko National University of Kyiv): The main challenge wasn’t the role shift. It was carrying responsibility for the people. You’re suddenly the one who has to make sure salaries get paid, and investments are found. This cycle of “I must, I must, I must” never really stops.

The hardest part is planning how long you can operate in that mode, and asking yourself whether you can bear it again and again.

Ivan Fedorenko, CEO of a few businesses: When I joined a French company, I felt comfortable, but I knew it wasn’t enough. Everything was fine, yet I felt pulled toward something different. I had so much energy at the time. I worked eight hours at my job, and in the evenings and on weekends, I was involved in two or three startups at once. Yet, I managed to avoid burnout and rarely felt exhausted.

Looking back, I think I rested by switching between different types of work, and that variety actually kept me energized during the transition from employee to founder.

Did you take a sabbatical or a long break to launch a company?

What helped you realize it was the right moment to stop and fully pursue your new career?

Anton Avrynskyi: I believe a sabbatical, when you stay employed but “take a break”, is a half measure. You’re still holding a safety net, a plan B that prevents you from going all in. For me, that approach doesn’t work. You need to make a clean break.

That’s what I did. After 15 years at the same company, first as an employee and later as a partner, I decided to leave completely.

To create something new, you have to stop doing the old thing entirely.

That was my mindset. I had some savings and sold my share in the company, which gave me a cushion.

Oleksandr Shcherbak: No, while working at HELSI, the same group that later became the founders of Lilo began discussing the idea and concept behind the new product. We held our first strategic sessions and started crystallizing the vision together with our key founder and shareholder, Samvel Akobyan.

I knew I had to switch completely once it became clear it would require full-time commitment and investment.

The transition took about six months. I worked as Commercial Director at the time, so I needed to find a replacement and hand over my responsibilities. The entire transition was smooth for both HELSI and me, and gave everyone time to prepare. Once I left, I focused on building Lilo right off the bat.

Sergiy Danylov: I didn’t take a sabbatical.

The real turning point came when I realized I couldn’t split my attention between working, teaching, and building something new any longer. I was simply running out of time.

The significant shift occurred when I was moving in a completely new direction. Around 2016, I recognized that the future of AI would rely on understanding human behavior, attention, and cognitive patterns, rather than merely on objects.

Once I identified this trend and clearly saw that the new field required my full commitment, I stopped juggling multiple roles and dedicated myself entirely to building my own company.

Ivan Fedorenko: I didn’t take a sabbatical because I felt tied to the company and responsible for delivering results. Only in the third year did I understand what was coming next. First, things finally started working the way I wanted them to. Second, I realized I could achieve more in my own company.

That clarity showed me it was time to rethink my path and build something entirely by myself.

Who did you consult with when making the decision?

Who gave you the most valuable advice? What communities or networks were helpful to you?

Anton Avrynskyi: I talked to many technical and business-minded people in my network. It’s important to share your ideas widely with developers, entrepreneurs, investors, and anyone who can challenge your thinking. I reconnected with old contacts and reached out to friends and family. I also met new people via introductions and steadily grew my talking circle.

Once I had a rough idea of what I wanted to build, I started meeting people involved in that space for feedback. You need these conversations because they help you see blind spots. Some people will tell you your idea is bad, and that’s fine. The key is not to listen to everyone, but to collect different perspectives and form a clear picture of what you want to build.

Once you find the idea that excites you the most, move quickly.

The discussion phase shouldn’t last more than a month.

I know many people who spend years exploring different notions without ever starting. As a result, their ideas just get outdated.

Oleksandr Shcherbak: I can’t name one single person who gave the most valuable advice. I gained many useful insights from different people and perspectives.

My network was crucial to my progress.

I relied on it a lot. My team and I ran informal surveys among our friends and acquaintances, asking questions like:

“What would an ideal insurance look like for you?”
“What pain points do you currently experience in healthcare?”

Those conversations helped us understand better the real user needs and shape our idea accordingly.

Sergiy Danylov: When people interview me about psychology and ask for advice, I always say the same thing:

The first rule is not to blindly follow anyone’s advice.

This doesn’t mean you should isolate yourself. You need to listen widely, stay in the field, absorb as many signals, ideas, and stories as possible. We are imitators by design. That’s how humans learn. The value comes from recombining what you see around you into something that fits your own context. So the most valuable “advice” is not a specific sentence someone told me.

At the same time, I am genuinely grateful to many people whose wisdom and experience have shaped how I think.

Ivan Fedorenko: I spoke with a friend who was one year ahead of me and had already founded his own IT company. He gave me top-notch advice:

Launch the first product version as an MVP (Minimum Viable Product) and don’t pour all your money into it.

I didn’t listen, and that was a mistake.

Later, I began studying in business schools, taking management courses, and joining accelerator programs. Those programs were especially valuable because of the networking. You meet people who fall into the same traps, and it’s easy to learn by watching peers face challenges similar to yours. And, of course, the mentors you meet along the way give you the knowledge that helps you move forward.

How did you manage your personal priorities?

Health, relationships, and personal life. What compromises did you have to make?

Anton Avrynskyi: In the first years of building my own company, I didn’t really have a life outside of work. I was obsessed with it, talking about it at home, living it every day. At that time, I already had two small kids. I tried to be present, but the reality was that 90% of my time and energy went into the business.

I don’t believe it’s possible to build something from scratch without being fully dedicated to it, at least, not in my experience. I was hands-on, creating everything from zero, and that required total focus. There was no balance in those first two years. It was roughly 90% work and 10% family, and you have to be mentally prepared for that.

The idea of balance simply doesn’t exist during the early stages.

Oleksandr Shcherbak: I used to work in a mode that doesn’t fit into the standard “9 to 5” format. I often have to adjust plans on the fly, work at a high pace, or postpone personal matters for the sake of urgent tasks. In that rhythm, launching Lilo wasn’t a dramatic shift, but it definitely increased the intensity.

The hardest part is maintaining balance between work and the time I want to dedicate to the people who matter to me - family, my close circle, and friends. The reality of building a startup means having less time to rest. But I consciously try to stay connected, pay attention to my personal life, and not lose the sense of life beyond work.

For me, it’s crucial to do something that genuinely inspires and energizes me.

When you love what you do, you have enough emotional resources even in a high-intense pace, and the rest you need is mostly physical, just to let your body keep up with the tempo your mind sets.

That’s what helps avoid burnout and stay productive without losing the support of the people closest to you.

Sergiy Danylov: Speaking as a neuroscientist rather than a founder, my general recommendation is to twist your life into a “rope of habits” that consistently pulls you toward your goals. And that rope must include plenty of rest, even though that’s especially hard for a founder.

You also need some physical activity. Unfortunately, startup life often means sitting all day, which isn’t healthy. At the same time, the very sense of purpose behind what you’re building provides enormous psychological protection.

There’s nothing more powerful for mental health than having a clear goal and meaning.

Ivan Fedorenko:

For me, startups and the process of founding companies became my main life.

Many of my friends were connected to the company, so relationships and work were intertwined.

I didn’t feel any discomfort at that time, but I often had to work nights and miss sleep, which definitely hurt my health.

How and when did you tell your colleagues about your decision to leave and start a company?

What emotional challenges came up, and how did you handle them?

Anton Avrynskyi: It was an incredibly difficult period, probably one of the hardest in my career. I had been thinking about leaving for several years before I finally decided to go. There were long months of preparation and reflection. Emotionally, it was devastating.

When I finally decided, I just had an honest conversation with the two founders. Of course, they were shocked, but we agreed I would stay for six more months to ensure a smooth transition. During that period, I worked at full capacity, covered various areas, trained colleagues, and transferred all my responsibilities.

A month before leaving, I shared the news with the rest of the team. They were also shocked, but I believe transparency and preparation are the key. You can’t just announce one day that you’re leaving tomorrow. It has to be handled carefully and respectfully.

Looking back, I’m proud of how it went. We’re still on great terms with the founders and the team. We stay in touch, help each other whenever possible, and remain friends.

My philosophy is simple: come in and leave with integrity.

Oleksandr Shcherbak: I spoke directly with the CEO of HELSI. Since I was an effective manager during my time at HELSI, we repeatedly tried to launch initiatives aimed at expanding cooperation with insurance companies, so the conversation wasn’t difficult. We had always had a good relationship, so I wanted my departure to be as smooth as possible for the company.

I approached it responsibly: trained the team, shared new ideas, and transferred all the necessary knowledge before leaving

Another important factor was that I had the best team under my leadership - mature, independent managers. By the time I left, I was no longer a “babysitter” for them, so the transition felt natural and comfortable.

This approach ensured a smooth process and helped avoid any disruptions for HELSI.

Sergiy Danylov: It was genuinely difficult.

After working for twenty years in the same place, you reach a moment when you simply stand up and walk away. That shift hits you hard.

We had an outstanding department head. He was disappointed that my partner and I were leaving, but he understood that we were stepping toward something we truly wanted. That understanding made the transition emotional but ultimately honest and respectful for everyone involved.

Ivan Fedorenko: I told my colleagues I wasn’t abandoning them. I assured them they could reach out to me anytime for questions or support.

I didn’t close the doors.

I thanked them, said I genuinely enjoyed working with them, and explained that I needed to move forward for the sake of my own path. There were no negative emotions. We ended things on an optimistic note.

Conclusion

In this article, I don’t want to provide the summary and disrupt your thoughts. I hope you will draw your own conclusions based on these conversations.

My personal takeaway can be described by this quote:

“And sacrifice scares you, but sacrifice brings growth and growth is exactly what you need. Define your priorities, forget your balance”

Continue reading

If these reflections made you curious about the practical side of building your first company, you may want to read my 10 mistakes I made as a first-time solo founder.

As usual, thank you for your time. I would appreciate it if you hit that like button, and I look forward to hearing your thoughts in the comments!

🔗 Follow me on LinkedIn

📰 Read me on the platform of your choice: Substack, DEV.to

Till next time! 👋

10 mistakes I made as a first-time solo founder

Olexandr — Thu, 23 Oct 2025 08:11:49 +0000

Once in my life, I tried to step down from the engineering role and kick off my own startup. The outcome? Well, I failed - the harsh reality of 90% of all startups.

Yet, I don’t regret it, although it was a hard time until I ran out of cash and realized the idea wasn’t as groundbreaking as it had seemed at the beginning. My price of one year building the company (while working full-time) included burnout, mental health problems, constant lack of energy, relationship issues, and an almost-lost job.

Still, I’m grateful for all the business, management, and life lessons I’ve learned during this period. Looking back now, I understand it’s perhaps the only way to learn these lessons.

NOTE: If you’re curious, my startup was called Imabulary. The idea was simple: you take a photo, the app detects the object in the photo, and generates a flashcard in your native and target languages. Then you could organize these flashcards into sets and take different quizzes on these sets. Find more in our pitch deck.

With that said, let’s dive straight into the first mistake.

1. Didn’t find a co-founder

Why it’s a problem

Managing every part of a new startup alone is exhausting.

Here’s a tiny list of things you’ll have to deal with from day one:

Tons of customer interviews per day
Pitching
Participating in incubators and accelerators
Writing code
Talking to partners and investors
Selling

Another important aspect is that most VCs prefer teams over solo founders since co-founders can diversify risks. They reasonably see solo-founded companies as more likely to fail and as those that can be led in a dictatorial or narrow-minded way.

What to do

The answer is simple! Find a partner or two.

Ideally, your business partner is your friend, classmate, or at least an acquaintance. It’s also important that you both share the same vision and have strong willpower to build a company. But watch out! Sometimes things might get so tough that they can ruin even a close friendship. I’m not saying this situation is 100% unavoidable, but be aware of such a scenario.

NOTE: But what if I don’t have the right person to be my co-founder at the moment? Don’t worry, Y Combinator (one of the largest startup accelerators in the world) created a Co‑Founder Matching Platform. This is the place where you can find a business partner even if you don’t have a business idea yet.

2. Became a CEO instead of CTO

Why it’s a problem

This one comes from the first point. Because I didn’t have a co-founder, I had to become a CEO (Chief Everything Officer).

If you’re passionate about technologies like me, you are going to feel like a fish out of water.

What to do

Same solution: find a co-founder, preferably a non-technical one (such as a product manager or marketer). Once you have a well-matched partner(s), choose a roles that best match your expertise, so everyone’s doing what they truly enjoy.

Watch out! Finding a co-founder(s) doesn’t mean you should stay isolated in your world of algorithms and patterns, avoiding real communication. It must be exactly the opposite. You have to work closely with your business partners and customers to ensure that you don’t build something that no one needs. Still, being a CTO lets you focus on technology more than on other aspects of the company.

3. Extended the team too early

Why it’s a problem

When you hire a skilled engineer, manager, marketer, or whoever else, remember: they came to do THEIR job. Don’t expect them to build YOUR business. Of course, they can give some advice or opinion in certain moments, but in 99% of the time, building the company is on you and your co-founder(s).

The people you hire obviously expect something in return. Even if you hire them for “equity”, in startup terms, that usually means for free, with a subtle hope that this equity will be worth something one day.

What to do

Verba’s founder put it well: don’t hire a full-time team unless you make $1M ARR (Annual Recurring Revenue). Until then, try to cover everything with your co-founders or use part-time freelancers if it’s faster or cheaper than if you start delving into the topic by yourself.

4. Scrum is your enemy in the early stages

Why it’s a problem

First of all, I’m not a hater of Scrum. In fact, I use this framework on every project I work on. Scrum works perfectly in companies that already have significant traction: steady revenue, clients, a growing team, investments, and so on. Meanwhile, from my experience, even lightweight Scrum slows early-stage startups without traction more than it helps. Sprint velocity, backlog grooming, and ceremonies introduce overhead that kills iteration speed long before you achieve product-market fit.

I understand that experienced Scrum masters and project managers may disagree, but your goal is to ship the MVP and sell it as quickly as possible, not to deal with all the Scrum hassles. At this stage, you’ll waste your (and worse - your teammates’) invaluable time, rather than gain real benefits from Scrum.

What to do

It’s enough to have 2-3 stand-ups per week with your team so everyone is in the loop. Avoid implementing Scrum until you have clear traction and a full-time team. Try to minimize all the calls, communicate via text, and document everything so you can quickly send a link instead of hopping on a call every time.

5. Customer development is a 1-to-1 interview, not a Google Form

Why it’s a problem

Diverse and unreliable audience - in the chats, where you probably share your customer development form, there are people with very different interests and experiences. They can be engineers, managers, or just strangers. Most of the time, people who fill out the form won’t belong to your target audience.
Superficial answers - filling the form is a formal, routine process. The majority of people won’t dive into the details, so the quality of the data you receive is questionable.
Missing context - you cannot understand the context in which the respondent is answering. You don’t see what issues really concern the user and whether their answer corresponds to the real situation.

What to do

Customer development is a critical topic, especially in early-stage startups. Unfortunately, it’s impossible to tell you everything in one article. My top three recommendations are:

Conduct 1-to-1 interviews with people you know who belong to your target audience. It will help you to avoid the problems discussed above.
Read “The Mom Test” and “The Four Steps to the Epiphany”. They’re often referenced as the Bibles of customer development.
Join eo Incubator. They provide three amazing workshops that teach you customer development from zero to hero. I’ve conducted them too, and it’s not an ad, but personal, genuine advice.

6. Conducted pre-sale too late

First of all, pre-sale != B2B deals!

In my case, “pre-sale” is the stage when we don’t have a product yet, not even an MVP, but we already try to sell it using targeted ads, landing pages, and Figma mockups. Basically, we say to leads, “Leave us your email, be among the first, collect loyalty bonuses, and help us understand the demand”.

Why it’s a problem

If you start pre-sale too late, you risk missing key information about demand, your audience, and your value proposition. You can still create a product that doesn’t meet the market needs, even though you have the information from customer development interviews. There’s no reason to limit yourself to one source if you can do both. This mix lets you create a more targeted product with a sharper value proposition that solves a narrower problem.

What to do

Conduct pre-sale after the first 15 customer development interviews, not when you’ve almost finished developing the MVP.

NOTE: The number of conducted interviews may vary and depends on how well you understand your target audience and their pain points.

Don’t be afraid that users who signed up on your landing page will forget about it or won’t use the product. Most of them wouldn’t be your customers anyway, especially paying ones.

Also, pre-sale accurately shows whether a real demand exists for your product and if you should move forward or pivot.

Don’t just take my word, here’s how Buffer did pre-sale in 2011.

7. Overbuilt the MVP

Why it’s a problem

Experienced founders would say, “Hah, classic 🚬🗿”.

And indeed, it’s a common pitfall for many startups and their first-timer founders (especially technical!). At Imabulary, we’ve spent a couple of weeks perfecting the quiz instead of shipping and selling.

The truth is, you can’t be sure anyone will buy your product. The fastest way to test it is to try to sell the MVP right away. But how can you make it if you’re fixing that stupid bug or adding “just one more feature”?

What to do

If your product doesn’t solve one precise pain point for your customer, they won’t buy it, no matter how bug-free or feature-packed it is.

In most consumer or productivity apps, users forgive early bugs if the product relieves their pain. Believe me, they will wait while you fix everything. Just don’t make them wait endlessly, of course.

How do you understand whether the MVP needs some functionality or not? If you say “Yes” to the question “Would the application fulfill its purpose if we remove this feature in the MVP?”, then you don’t need this feature.

8. Selected the wrong revenue model

Why it’s a problem

Subscription rules the SaaS world. It remains the dominant and most investor-friendly model. It’s also a predictable and understandable model for customers.

As a first-time founder, you’re better off not reinventing the revenue model until you have market traction. You may think you’ve come up with some cool monetization approach no one has guessed to implement before. But usually, such “innovative” logic makes it harder to calculate unit economics, investors reject you, and worst of all, users don’t pay.

What to do

Start with a simple, proven subscription revenue model. Then add all the other features like credits, tokens, and so on once product-market fit is stable.

You can also read this classic on subscriptions and unit economics by David Skok.

9. Operated from personal accounts

Why it’s a problem

It looks unprofessional when you pitch an investor, ask for $100K and at the end you put “bigmoneyhustla2002@gmail.com” as a contact email you created when you were 12. If you can’t spend $5 on a professional email, then why should an investor trust you with their money?

Additionally, when you register accounts at Google Cloud Platform, AWS, Play Console, AppStore Connect, and so on, you can put the name of your company instead of your first and last names.

Last but not least, it’s more convenient to keep personal and professional lives separate with two different accounts, so emails, calendars, and similar stuff don’t get mixed.

What to do

Once customer development interviews confirm the idea is worth pursuing, buy a domain and sign up for a Google Workspace account. Google isn’t mandatory; you can choose whatever provider you like. I always like to create a “myname@companyname.com” email. For example, I used “olexandr@imabulary.app” when I was building a startup.

10. I wasn’t the customer of my own product

Why it’s a problem

If you’re not tackling a hurdle you’ve personally faced or are facing now, you won’t fully understand your client’s pain. You won’t be able to create a product that solves a real-world problem for you and your users.

That’s why I believe it’s so ridiculous to ask ChatGPT, “Generate me 10 ideas for my next 1-billion-dollar startup”, or to search YouTube for startup ideas.

What to do

You have to be your first customer. Of course, it doesn’t mean that you should center the product on your narcissistic vision, because business doesn’t work like that. No one will buy your product if it’s only for one person. But, at the same time, it’s easier to stay motivated and disciplined if you benefit from your own product. Not only in terms of money, but also in terms of the value the product brings to the world.

NOTE: An yet, if you’re tackling someone else’s pain, make sure to embed yourself deeply in the user’s world - observe, interview, and test relentlessly.

Conclusion

With everything you’ve just read, can I guarantee that now you’ll succeed in your founder’s journey? Nope, unfortunately, I can’t. No one can. Every startup is unique. You can follow some pieces of advice and avoid common pitfalls and mistakes, but your way will be unrepeatable.

As I stated in the intro, 9 out of 10 startups fail, so chances are, you’ll come to nothing as well. But it doesn’t mean you should just accept this data and stop pursuing your dream. Be bold. If an idea keeps you up at night, or you’ve seen an unresolved problem you believe you can tackle, then do it.

Remember, “I’ve tried and I failed” is far better than “I didn’t try because I was too afraid”. At the end of the day, who said you can’t be one out of ten who succeeded?

Summary

Don’t build alone. Find a co-founder.
Do what you know how to do best. Don’t become Chief Everything Officer.
Hire after you have proven traction.
Don’t implement Scrum at the early stages.
Talk with customers directly. Don’t use forms for customer development.
Your early stage should look like this: idea → customer development → pre-sale → MVP → scale.
Don’t overbuild your MVP. Always ask yourself, “Would the application fulfill its purpose if we remove this feature in the MVP?”.
Don’t reinvent the ~~wheel~~ monetization. Choose a subscription revenue model and build your business model around it.
Create a corporate email to manage a company.
Try to tackle the real problem you’ve faced before.

Want more?

Check out these 3 reflective articles, where other startup founders (successful and not) share their experience:

And, of course, don’t forget to give a shot to my previous articles:

As usual, thank you for your time. I would appreciate it if you hit that like button, and I look forward to hearing your thoughts in the comments!

🔗 Follow me on LinkedIn

📰 Read me on the platform of your choice: Substack, DEV.to

Till next time! 👋

Three React MUI commandments

Olexandr — Wed, 17 Sep 2025 11:00:49 +0000

MUI (or Material UI) is a popular React library for building feature-rich UI. There are many great competitors like Ant Design, Shadcn, and so on. However, MUI is still my preferred choice when I need to create a robust enterprise frontend application. The library has a rich set of components, flexible theming capabilities, and strong accessibility out of the box.

Because MUI is powerful, things can often get messy. You’ve probably experienced this frustration firsthand:

I’ve been using the library since version 4 on many of my projects. In this article, I share 3 quick tips I learned the hard way. So you can save hours of refactoring and develop more maintainable and testable components:

Okay, let’s get started cleaning up the mess. Here’s the first rule.

Rule number uno - theme it or leave it

Always start exploring customization possibilities from global theme config.

The global theme config centralizes styles for all MUI components, ensuring consistent styling throughout the entire app. That’s why, when you make some adjustment to the Material UI component inside the global theme, it will be applied to all the instances of this component across the app.

Let’s take a button as an example. MUI’s default button is in Material Design 2 style:

But what if we want it to match GitHub’s Primer looks:

For that, we create a new theme config and customize the MuiButton component through it:

theme.tsx

// theme.tsx

import { createTheme } from "@mui/material";

export const theme = createTheme({
  components: {
    // Name of the component
    MuiButton: {
      styleOverrides: {
        root: {
          textTransform: "none",
          boxShadow: "none",
          padding: "0 12px",
          height: 32,
          borderRadius: 6,
          backgroundColor: "rgb(45, 164, 78)",
          border: "1px solid rgba(27, 31, 36, 0.15)",
        },
      },
    },
  },
});

NOTE: Always use colors from the palette. Don’t put them directly as strings into your theme config. I did to avoid a complex setup and focus strictly on the rule.

Don’t forget to use ThemeProvider to inject a custom theme into your application:

main.tsx

// main.tsx

//...
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <CssBaseline />
    <ThemeProvider theme={theme}>
      <App />
    </ThemeProvider>
  </StrictMode>
);

But what if the theme doesn’t give you enough flexibility? That’s where our second rule comes in.

Rule number two - styled component is what you do

Did you carefully investigate all the design tokens and props the theme provides and couldn’t find the desired one for the component you want to customize? It’s time to take the next step - create a styled component.

Let’s proceed with the button. Assume we want to have 2 shapes: round and square. By default, MUI doesn’t provide us with the shape property, but we can easily add it by creating a new styled component:

button.styled.ts

// button.styled.ts

import {
  Button as MuiButton,
  styled,
  type ButtonProps as MuiButtonProps,
} from "@mui/material";

// Determines whether a given prop should be forwarded to the underlying DOM element.
const shouldForwardProp = (prop: string) => {
  if (!prop || typeof prop !== "string") return false;

  return !prop.trim().startsWith("$");
};

type ButtonProps = MuiButtonProps & {
  $shape?: "round" | "square";
};

export const Button = styled(MuiButton, { shouldForwardProp })<ButtonProps>(
  ({ $shape = "square" }) => {
    const shapeStyle = {
      round: {
        borderRadius: 100,
      },
      square: {},
    };

    return shapeStyle[$shape];
  }
);

Important takeaways from the code above:

Always add dollar $ or another valid sign to the beginning of your custom property. Then use shouldForwardProp utility function to prevent the custom prop from being forwarded to the underlying DOM element. This stops MUI from throwing “Invalid attribute name: shape” in the console. Read why unknown DOM props are bad.
Use styled function from @mui/material package, not from @emotion/styled. Emotion has a different syntax and is not aware of all MUI components and internal structures, which Material UI adds on top of Emotion. That’s why you may run into errors or unsupported cases if you try to customize the MUI component directly with Emotion.

Now, make sure you import your styled Button component instead of MUI’s default one everywhere you use it:

App.tsx

// App.tsx

import { Stack } from "@mui/material";

// Import custom styled component, not MUI's one
**import { Button } from "./button.styled";**

function App() {
  return (
    <Stack p={2} spacing={1} sx={{ width: 100 }}>
      <Button variant="contained">Square</Button>
      <Button variant="contained" $shape="round">
        Round
      </Button>
    </Stack>
  );
}

export default App;

The result:

If the theme doesn’t cover your needs, you may also be tempted to use the sx prop. Here’s why creating a styled component works better.

Why not to use `sx`?

The SX prop is fine for quickly adding 2-3 theme-aware inline styles. But if you have more complex styling logic, consider using styled components, like I showed above. With this approach, you keep your styling and business logic separate, which improves readability and maintainability.

Sometimes customization goes beyond styling. In that case, it’s time for our third rule.

Style can’t solve? React component's the resolve

Pretend we have a requirement to add a sound effect every time a user clicks on the button. Styled components cannot achieve this, and MUI doesn’t provide any design tokens or capabilities for adding sound either.

When customization involves complex logic, we create a new React wrapper around the styled button:

Button.tsx

// Button.tsx

import useSound from "use-sound";
import buttonSound from "../public/button.mp3";
import type { FC } from "react";
import { type ButtonProps, Button as ButtonStyled } from "./button.styled";

export const Button: FC<ButtonProps> = (props) => {
  const [play] = useSound(buttonSound);

  return <ButtonStyled {...props} onClick={() => play()}></ButtonStyled>;
};

NOTE: To play sound, I use useSound hook. Find sound effects on freesound.org.

Now use the new button component inside your app:

App.tsx

// App.tsx

import { Stack } from "@mui/material";

// Import custom wrapper component, not MUI's or styled one
**import { Button } from "./Button";**

function App() {
  return (
    <Stack p={2} spacing={1} sx={{ width: 100 }}>
      <Button variant="contained">Square</Button>
      <Button variant="contained" $shape="round">
        Round
      </Button>
    </Stack>
  );
}

export default App;

Now that you’ve seen all three rules in action, let’s wrap it up.

Conclusion

Congratulations! 🎉

Now you know how to keep your MUI-based design system tidy. You’ve learned:

Why and how to customize components through the global theme wherever it makes sense.
In what cases use styled components.
In what cases you should create a separate React wrapper over the MUI component.

Without this hierarchy, you’ll end up mixing theme overrides, inline sx, and wrapper hacks in random places.

By applying these three easy-to-follow rules, you’re going to build design systems that are easy to maintain, test, and document. Your colleagues and future self will very likely appreciate it 🙂

Want more? 🔥

Check my previous article “React MVVM Architecture with TanStack Router: An Introduction” where I teach good old React MVVM with a modern tech stack.

Creating content like this is not an easy ride, so I hope you’ll hit that like button and drop a comment. As usual, constructive feedback is always welcome!

🔗 Follow me on LinkedIn

📰 Read me on the platform of your choice: Substack, DEV.to

Till next time! 👋

React MVVM Architecture with TanStack Router: Orchestrator

Olexandr — Fri, 22 Aug 2025 08:46:29 +0000

Earlier in this MVVM series, we discussed that blending the UI with the logic undermines maintainability and testability. So, if we cannot mix these two, how do we actually connect them?

The answer is in the final piece of the MVVM puzzle - orchestrating component (also known as the orchestrator):

TIP: If you haven’t read my MVVM Introduction yet, I highly recommend doing that first. It’ll help you understand where the orchestrator fits in the bigger picture.

In this article, you’ll learn:

What’s the orchestrating component, and what is his job.
How to create the orchestrator and combine the layers within it.
How to test the orchestrating component.

Before we begin, I want to remind, that in this MVVM series, we’re building a country quiz app. The app prompts the user with the flag, and the user has to guess the country. Once they entered and sent the answer, we save it in localStorage. Then we display the answer history in the left sidebar. You can find the source code on GitHub and the Demo on CodeSandbox.

The glue of a module

Orchestrator is a simple React component that has two main tasks:

It connects UI (represented by the view layer) with the business logic (represented by the application layer).
It serves as an entry point into the module. For example, in TanStack Router, the orchestrator can be the route’s primary component:

import { Orchestrator } from "@/modules/Module";
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/")({
  component: Orchestrator,
});

Now, how do we implement the orchestrator?

Creation of the orchestrator

Open your IDE of choice and, inside the Home module, create a new file called Home.tsx. Your folder structure will look like this:

src
└── modules
    └── Home
        ├── application
        ├── data
        ├── model
        ├── view
        ├── Home.tsx
        └── index.ts

NOTE: index.ts is for re-exporting. Now, when you import Home orchestrator, use @/modules/Home instead of @/modules/Home/Home (”Home” 2 times).

Inside Home.tsx, create a new functional React component:

export const Home: React.FC = () => {

};

Now let’s call the useQuiz hook from the application layer:

import { useQuiz } from "./application/useQuiz";

export const Home: React.FC = () => {
  const quizProps = useQuiz();
};

Last but not least, return the Quiz widget from the view layer:

import { Container } from "@mui/material";
import { Quiz } from "./view/Quiz";
import { useQuiz } from "./application/useQuiz";

export const Home: React.FC = () => {
  const quizProps = useQuiz();

  return (
    <Container sx={{ display: "flex", alignItems: "center", height: "100%" }}>
      <Quiz {...quizProps} />
    </Container>
  );
};

NOTE: I’ve also wrapped the widget in the MUI’s Container component purely for styling. The orchestrating component doesn’t depend on any UI library. Feel free to use the library of your choice or not to use any.

As a cherry on top of a pie, replace the temporary mock code in the src/routes/index.tsx with your new Home orchestrator:

import { Home } from "@/modules/Home";
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/")({
  component: Home,
});

Congratulations! You’ve created the orchestrating component for the Home module. In this component, you:

Took all the props returned by the useQuiz hook.
Provided the props to the Quiz widget.

If you had more widgets and hooks, creating the orchestrator would follow the same steps: call the hooks and pass the results to the widgets through props.

But don’t forget about complexity and scaling aspects!

Split into sub-orchestrators when needed

When a module starts wiring 5+ independent hooks and widgets like this:

import { Container, Stack, Divider } from "@mui/material";

// Application layer (business logic)
import { useProfile } from "./application/useProfile";
import { useStats } from "./application/useStats";
import { useActivity } from "./application/useActivity";
import { useNotifications } from "./application/useNotifications";
import { useTips } from "./application/useTips";

// View layer (UI widgets)
import { ProfileCard } from "./view/ProfileCard";
import { StatsCard } from "./view/StatsCard";
import { ActivityFeed } from "./view/ActivityFeed";
import { NotificationsList } from "./view/NotificationsList";
import { TipsPanel } from "./view/TipsPanel";

export const Dashboard: React.FC = () => {
  // 1. Call hooks (application layer)
  const profileProps = useProfile();           // e.g. { user, isLoading, error, refresh }
  const statsProps = useStats();               // e.g. { totals, delta, isLoading, error }
  const activityProps = useActivity();         // e.g. { items, isLoading, error }
  const notificationsProps = useNotifications(); // e.g. { items, markRead, isLoading, error }
  const tipsProps = useTips();                 // e.g. { tips, dismissTip, isLoading, error }

  // 2. Wire results to widgets (view layer)
  return (
    <Container sx={{ py: 2 }}>
      <Stack spacing={2}>
        <ProfileCard {...profileProps} />
        <Divider />
        <StatsCard {...statsProps} />
        <ActivityFeed {...activityProps} />
        <NotificationsList {...notificationsProps} />
        <TipsPanel {...tipsProps} />
      </Stack>
    </Container>
  );
};

Consider splitting them into sub‑orchestrators:

import React from "react";
import { useTips } from "./application/useTips";
import { TipsPanel } from "./view/TipsPanel";

export const Tips: React.FC = () => {
  const tipsProps = useTips(); // e.g. { tips, dismissTip, isLoading, error }
  return <TipsPanel {...tipsProps} />;
};

Then the main orchestrating component would connect other sub-orchestrators instead of hooks and widgets directly:

import { Container, Stack } from "@mui/material";
import { Tips } from "./Tips";

export const Dashboard: React.FC = () => {
  return (
    <Container sx={{ py: 2 }}>
      <Stack spacing={2}>
        {/* ...other sub‑orchestrators... */}
        <Tips />
      </Stack>
    </Container>
  );
};

Okay, we’ve discussed how to create an orchestrator and split it into more granular parts if it wires 5+ widgets and hooks. Now it’s time for tests 🧪.

Test the orchestrator

NOTE: As usual, I’m using Vitest and React Testing Library to write unit tests.

Test code for the orchestrating component is as simple as its actual implementation:

import { render, screen } from "@testing-library/react";
import { describe, it, vi, expect, beforeEach } from "vitest";

// Capture props passed to Quiz for assertions
let lastQuizProps: any = null;

// Mock the useQuiz hook to control props returned to Home
vi.mock("./application/useQuiz", () => ({
  useQuiz: vi.fn(),
}));

// Mock Quiz view to a simple component we can assert against
vi.mock("./view/Quiz", () => ({
  Quiz: (props: any) => {
    lastQuizProps = props;
    const label = props?.country?.name ?? "no-country";
    return <div data-testid="quiz">{label}</div>;
  },
}));

// Imports go after mocks to ensure the mocked modules are applied before the actual modules are imported and executed.
import { Home } from "./Home";
import { useQuiz } from "./application/useQuiz";

describe("Home", () => {
  beforeEach(() => {
    lastQuizProps = null;
  });

  it("renders Quiz with props returned by useQuiz", () => {
    const mockProps = {
      country: { flag: "https://example.com/fr.png", name: "France" },
      isLoading: false,
      error: null,
      submissionError: "",
      form: {} as any,
      onSubmit: vi.fn(),
      result: undefined,
    };

    vi.mocked(useQuiz).mockReturnValue(mockProps as any);

    render(<Home />);

    // Quiz should be rendered and receive the same props
    expect(!!screen.getByTestId("quiz")).toBe(true);
    expect(screen.getByTestId("quiz").textContent).toBe("France");
    expect(lastQuizProps).toMatchObject(mockProps);
  });

  it("renders Quiz even when country is null and loading is true", () => {
    const mockProps = {
      country: null,
      isLoading: true,
      error: null,
      submissionError: "",
      form: {} as any,
      onSubmit: vi.fn(),
      result: undefined,
    };

    vi.mocked(useQuiz).mockReturnValue(mockProps as any);

    render(<Home />);

    // Still renders Quiz and shows our fallback label
    expect(!!screen.getByTestId("quiz")).toBe(true);
    expect(screen.getByTestId("quiz").textContent).toBe("no-country");
    expect(lastQuizProps).toMatchObject(mockProps);
  });

  it("passes error from useQuiz down to Quiz", () => {
    const error = new Error("Network failed");
    const mockProps = {
      country: null,
      isLoading: false,
      error,
      submissionError: "",
      form: {} as any,
      onSubmit: vi.fn(),
      result: undefined,
    };

    vi.mocked(useQuiz).mockReturnValue(mockProps as any);

    render(<Home />);

    // Quiz is rendered and receives the error prop
    expect(!!screen.getByTestId("quiz")).toBe(true);
    expect(lastQuizProps.error).toBe(error);
  });
});

In our case, testing the orchestrating component is just passing props from hooks to widgets. No internal states or side effects. Easy and clean, just like we all enjoy!

NOTE: My task is to show you the basic principles of testing the orchestrator. I’m not focused on creating comprehensive production-ready test cases. You can add more tests for better coverage.

Testing is done! If you read my previous articles in this series, you’ve probably already guessed what’s coming next 🙂.

Homework

Create a History orchestrator inside the History module. The orchestrator should:

Take the object returned from the useHistoryList hook. This is the hook you had to create as homework in the application layer article.
Provide the object through props to the HistoryList widget. This is the widget you had to create as homework in the view layer article.

If you get stuck, check the ready task in the source code.

MVVM brainteaser is done!

Wow, just wow…

I can’t believe you’ve reached this point 🥹

You’ve not only studied the orchestrator component, you’ve finished the entire MVVM journey! By finishing this article and the whole series, you’ve learned:

How to wire the logic with the UI in the right way.
How to build more maintainable frontend applications with a clear separation of concerns.
How easy it is to test the React applications when each layer has one concrete task.

What’s next?

Go and build something cool with your new knowledge! 😄

Or you can always revisit the previous articles, in case you forgot some details:

Creating content like this is not an easy ride, so I hope you’ll hit that like button and drop a comment. As usual, constructive feedback is always welcome!

🔗 Follow me on LinkedIn

📰 Read me on the platform of your choice: Substack, DEV.to

See ya soon 👋

React MVVM Architecture with TanStack Router: Application Layer

Olexandr — Thu, 21 Aug 2025 17:22:33 +0000

When we build complex, feature-rich React applications, we tend to break the codebase into smaller components. But the problem is that as our application grows, so do our components.

At some point, you realize it’s impossible to read, maintain, or test the enormous Frankenstein that blends UI, business, and data access logic. A lot of the components like this lead to bugs, slowing down feature delivery and new devs’ onboarding difficulties.

In the previous articles, we’ve already moved UI and data parts to their appropriate layers:

Today, we study the application layer, which handles the business logic within the module:

TIP: If you haven’t read my MVVM Introduction yet, I highly recommend doing that first. It’ll help you understand where the application layer fits in the bigger picture.

In this article, you’ll learn:

How to utilize custom hooks for business logic handling.
How to validate the data we send and receive.
How to handle forms using TanStack Form. I introduced the library in the view layer article.

Random country to guess

In the data layer article, we fetched all the available countries from the REST Countries service using the findCountries method of HomeRepository. The response object of the method looks like this:

type CountryPayload = {
  flags: {
    png: string;
    svg: string;
    alt: string;
  };
  name: {
    common: string;
    official: string;
    nativeName: Record<string, {
        official: string;
        common: string;
    }>;
  };
}

Obviously, we don’t need all the fields in our simple app. It’ll be enough to have the next object:

type Country = {
  flag: string;
  name: string;
}

To get such an object, we need to map the data coming from the findCountries method. Let’s create the application layer for the Home module and add a custom hook called useQuiz:

import { useSuspenseQuery } from "@tanstack/react-query";
import { useMemo, useState } from "react";
import { homeRepositoryFactory } from "../data";

export const useQuiz = () => {
  const homeRepository = homeRepositoryFactory();
  const historyRepository = historyRepositoryFactory();

  // 1. Load the data
  const {
    data: countries,
    isLoading,
    error,
  } = useSuspenseQuery({
    ...homeRepository.findCountries(),
    // 2. Map the data to the desired structure
    select: (countries) =>
      countries.data.map((country) => ({
        flag: country.flags.png,
        name: country.name.common,
      })),
  });

  // 3. Select one random country
  // This may occasionally give the same country again. You can customize the randomizer to exclude the current one if needed.
  const randomCountry = useMemo(
    // TODO: Add empty-array guard, just in case the rest countries provider ever returns empty array
    () => countries[Math.floor(Math.random() * countries.length)],
    [countries]
  );

  // 4. State with one random country. We'll use it when we submit the form
  const [country, setCountry] = useState(randomCountry);

  // We rely on TypeScript to infer the return type of useQuiz automatically.
  return { country, isLoading, error };
}

Let’s break the hook down:

First, we load the data from the repository using useSuspenseQuery. The findCountries returns the result of the queryOptions method from TanStack Query, so we can spread it into useSuspenseQuery. > NOTE: Dive deeper into the repository pattern described in the data layer article.
Second, we map the data from the repository utilizing the select method. The method is also provided by the TanStack Query.
Then we select one random country from the array of mapped countries.
Last but not least, we save the random country in the state, so we can change the country later when the user presses the “Next country” button.

We’ve mapped the complex object into one that is much easier to work with. But imagine the third-party API provider changed the response signature. Now it has flagImages key instead of flags. If we try to map our data, we’ll get annoying “TypeError: Cannot read properties of undefined”

Wrong data shall not pass

To avoid situations above, I’ve introduced Zod in the model layer article. Before we map the data, we should validate it in the queryFn method:

import { countriesPayload } from "../model";

export const useQuiz = () => {
  const homeRepository = homeRepositoryFactory();
  const historyRepository = historyRepositoryFactory();

  const {
    data: countries,
    isLoading,
    error,
  } = useSuspenseQuery({
    ...homeRepository.findCountries(),
    queryFn: async (context) => {
      const queryFn = homeRepository.findCountries().queryFn;

      if (!queryFn) {
        throw new Error(
          "Unexpected error happened during loading the countries. Please retry after 15 minutes."
        );
      }

      const countries = await queryFn(context);

      // Parse the data from the repository
      const payload = countriesPayload.safeParse(countries.data);

      // In Suspense mode, thrown errors are caught by your error boundary
      if (!payload.success) {
        throw new Error(
          "We've received an incorrect data from our countries provider. We're already fixing this error, please retry after 15 minutes.",
          { cause: payload.error }
        );
      }

      return countries;
    },
    // ...
  });
  // ...
}

Let’s go through the process step by step:

First, we parse the data from the repository using Zod’s safeParse method.
Next, if the actual data and its Zod signature don’t match, we immediately throw an error. Then your error boundary catches it.

NOTE: We put validation in queryFn because it runs before select, ensuring only valid data reaches the mapping step.

Data from the repository is mapped and validated! Now it’s time to get the user’s answer, validate it, and save it.

Form submission

As I stated previously, to handle the form, we use TanStack Form. Inside the application layer, we must initialize the form using the useForm hook:

import { createHistoryRecordDTO, type CreateHistoryRecordDTO } from "@/modules/History/model";
import { historyRepositoryFactory } from "@/modules/History/data";
import {useForm} from '@tanstack/react-form'
import z from "zod";

export const useQuiz = () => {
  const historyRepository = historyRepositoryFactory();

  //...
  // 1. States with the result and error to check and display them in the view
  const [result, setResult] = useState<CreateHistoryRecordDTO>();
  const [submissionError, setSubmissionError] = useState("");

  // 2. Form instance initialization, answer is one default empty string value
  const form = useForm({
    defaultValues: { answer: "" },
    // 3. Specify form validator
    validators: {
      onChange: ({ value }) => ({
        fields: {
          answer: !value.answer ? "You cannot submit empty answer" : undefined,
        },
      }),
    },
    // 4. Submission logic
    onSubmit({ value }) {
      // a. Create a DTO object
      const dto = {
        flagImage: country.flag,
        countryName: country.name,
        userAnswer: value.answer,
      };

      // b. Parse DTO
      const historyDto = createHistoryRecordDTO.safeParse(dto);

      if (!historyDto.success) {
        // c. https://zod.dev/error-formatting#zflattenerror
        const error = z.flattenError(
          historyDto.error as unknown as z.ZodError<CreateHistoryRecordDTO>
        );

        // d. Retrieve the first error
        const formError = error.formErrors[0];
        const firstFieldError = Object.values(error.fieldErrors)[0][0];

        // e. Set the error
        setSubmissionError(formError || firstFieldError);

        return;
      }

      // f. Set the result
      setResult(dto);

      // g. Save the result
      // TODO: saving to localStorage can fail, add try/catch if you need it
      historyRepository.saveAnswer(historyDto.data);
    },
  });
  //...

  return { country, isLoading, form, result, error, submissionError };
}

Pretty much, I know, but nothing difficult here:

First, we create a local state with the submission result and error so the view can display them.

Next, we initialize the new form instance with an answer as the default empty string.

Third, we specify a form validator. This one simply checks whether the submitted answer isn’t empty. Form validator has nothing to do with Zod’s one. Let’s quickly compare them to understand the difference:

	TanStack Form	Zod
What it validates	Only the user’s input (answer in our case)	The whole DTO, even fields, like `flagImage` or `countryName`, that the user didn’t input but are critical for business logic
How errors are surfaced	We conveniently receive the error in the view through TanStack Form itself	We must store and provide the validation error to the view layer ourselves (we do it through the `submissionError`)

Last but not least, we define submission logic:

Create a DTO object that we’ll save in localStorage.
Parse and validate the DTO.
If validation isn’t successful, we take the first error and set it into submissionError state.
If validation is successful, we set the result into the state and save it in localStorage through the HistoryRepository.

Triggering the form submission

Okay, we’ve defined the submission logic, but how do we trigger it? A piece of cake:

import { useCallback, useMemo, useState } from "react";

export const useQuiz = () => {
  //...

  const onSubmit = useCallback(() => {
    if (!result) {
      form.handleSubmit();
    } else {
      form.resetField("answer");
      setCountry(randomCountry);
      setResult(undefined);
    }
  }, [form, result, randomCountry]);

  //...

  return { country, isLoading, form, result, error, onSubmit, submissionError };
}

As usual, let’s deconstruct what’s going on:

If there’s no result yet, we submit the form.

If there’s a result, we:

Reset the answer form field.
Set a new random country.
Set the result to undefined to be able to submit the form again.

And that’s it! We’ve successfully created the custom useQuiz hook that handles all the business logic required to make the quiz work.

But the job is not fully done yet. Remember, in the view layer article, we defined a QuizProps for the Quiz widget? Now it’s time to connect the useQuiz with the QuizProps like this:

import type { useQuiz } from "../application/useQuiz";

export type QuizProps = ReturnType<typeof useQuiz>;

This applies the trick we’ve discussed in the model layer article in practice.

With the hook created and props tweaked, it’s time to ensure the hook works as expected.

Testing

NOTE: As always, I’m using Vitest and React Testing Library to write unit tests.

Tests for useQuiz look like this:

import { renderHook } from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { useQuiz } from "../useQuiz";

// Mock dependencies
vi.mock("@/modules/History/data", () => ({
  historyRepositoryFactory: vi.fn(() => ({
    saveAnswer: vi.fn(),
  })),
}));

vi.mock("../../data", () => ({
  homeRepositoryFactory: vi.fn(() => ({
    findCountries: vi.fn(() => ({
      queryKey: ["countries"],
      queryFn: vi.fn(),
    })),
  })),
}));

vi.mock("@/modules/History/model", () => ({
  createHistoryRecordDTO: {
    safeParse: vi.fn(),
  },
}));

vi.mock("../../model", () => ({
  countriesPayload: {
    safeParse: vi.fn(),
  },
}));

vi.mock("@tanstack/react-query", () => ({
  useSuspenseQuery: vi.fn(),
}));

vi.mock("@tanstack/react-form", () => ({
  useForm: vi.fn(),
}));

describe("useQuiz Hook", () => {
  const mockRawCountriesResponse = {
    data: [
      {
        flags: { png: "https://example.com/fr.png" },
        name: { common: "France" },
      },
      {
        flags: { png: "https://example.com/de.png" },
        name: { common: "Germany" },
      },
    ],
  };

  const mockTransformedCountries = [
    { flag: "https://example.com/fr.png", name: "France" },
    { flag: "https://example.com/de.png", name: "Germany" },
  ];

  beforeEach(async () => {
    // Mock react-query - now returns already transformed data from queryFn
    const reactQuery = await import("@tanstack/react-query");
    vi.mocked(reactQuery.useSuspenseQuery).mockReturnValue({
      data: mockTransformedCountries,
      isLoading: false,
      error: null,
    } as any);

    // Mock react-form
    const reactForm = await import("@tanstack/react-form");
    vi.mocked(reactForm.useForm).mockReturnValue({
      Field: vi.fn(),
      handleSubmit: vi.fn(),
      resetField: vi.fn(),
      setFieldValue: vi.fn(),
      useField: vi.fn(() => ({
        state: { value: "", meta: { errors: [] } },
      })),
    } as any);

    // Mock model parsers - these are now used in the repository's queryFn
    const model = await import("../../model");
    vi.mocked(model.countriesPayload.safeParse).mockReturnValue({
      success: true,
      data: mockRawCountriesResponse.data,
    } as any);

    const historyModel = await import("@/modules/History/model");
    vi.mocked(historyModel.createHistoryRecordDTO.safeParse).mockReturnValue({
      success: true,
      data: {
        flagImage: "https://example.com/fr.png",
        countryName: "France",
        userAnswer: "france",
      },
    } as any);

    vi.clearAllMocks();
  });

  describe("VALID SCENARIOS", () => {
    it("should initialize with default values and random country", () => {
      const { result } = renderHook(() => useQuiz());

      expect(result.current.country).toBeDefined();
      expect(result.current.isLoading).toBe(false);
      expect(result.current.error).toBeNull();
      expect(result.current.submissionError).toBe("");
    });

    // Find the rest of the tests here: https://github.com/ole-techwood/articles/tree/mvvm/src/modules/Home/application/tests
  });

  describe("BOUNDARY CONDITIONS", () => {
    it("should handle single country in dataset", async () => {
      const singleCountry = [
        { flag: "https://example.com/fr.png", name: "France" },
      ];

      const reactQuery = await import("@tanstack/react-query");
      vi.mocked(reactQuery.useSuspenseQuery).mockReturnValue({
        data: singleCountry,
        isLoading: false,
        error: null,
      } as any);

      const { result } = renderHook(() => useQuiz());

      expect(result.current.country).toEqual(singleCountry[0]);
    });

    // Find the rest of the tests here: https://github.com/ole-techwood/articles/tree/mvvm/src/modules/Home/application/tests
  });

  describe("EDGE CASES", () => {
    it("should maintain state consistency during re-renders", () => {
      const { result, rerender } = renderHook(() => useQuiz());

      const initialCountry = result.current.country;
      rerender();

      expect(result.current.country).toBeDefined();
      expect(result.current.country).toEqual(initialCountry);
    });

    // Find the rest of the tests here: https://github.com/ole-techwood/articles/tree/mvvm/src/modules/Home/application/tests
  });
});

Yes, business logic remains the hardest part of the app to test. You have to mock a lot, and you have to think about many cases. But, hey, at least now you test your business logic in isolation from other layers of the app. This approach makes your mocks more predictable and easier.

NOTE: Keep in mind that I’ve tested only basic, valid, and edge conditions to show you the principle of testing the application layer. You might need to expand the test coverage in the production-grade systems.

Homework

Create a new useHistoryList hook that will correspond to the HistoryList view you had to build as the practice task in the view layer article. The hook should:

Fetch the history from localStorage using the getHistory method of the HistoryRepository.
Validate the history array.
Return the history or the error.

As usual, you can find the ready assignment in the source code.

Conclusion

You nailed it! 🚀

By this point, you’ve mastered business logic handling:

You’ve learned where and how to organize the business logic.
Together, we’ve considered the most common tasks for the application layer: form handling, data loading, mapping, and validation.
At the end, we’ve tested the business logic to make sure it works as expected.

With such a strong foundation, you’re now capable of implementing business logic of any complexity in your projects. All the best with that!

Want more?

TkDodo wrote React Query Selectors, Supercharged, in case you want to delve really deep into results transformation in TanStack Query.

Creating content like this is not an easy ride, so I hope you’ll hit that like button and drop a comment. As usual, constructive feedback is always welcome!

🔗 Follow me on LinkedIn

📰 Read me on the platform of your choice: Substack, DEV.to

See ya soon 👋

React MVVM Architecture with TanStack Router: View Layer

Olexandr — Thu, 21 Aug 2025 16:28:07 +0000

A clear separation between UI and business logic is absolutely crucial. It makes testing and maintaining your React components much easier. This is something I scrambled with a lot in the past. I would even avoid writing unit tests, because it was so hard to mock everything in some enormous component that included JSX, hooks, data fetching, etc., all in one.

That’s why I started delving into the clean architecture in React. After years of research, trial and error, I finally found the approach that helps me to keep my components simple, yet rich in UI and features.

Today, we’re talking about the view layer of this five-layer MVVM implementation:

In this article, you’ll learn:

How and where to keep the layout for the whole app in TanStack Router.
How and why keep your components clean.
How easy it is to test clean React components.

Shape of the whole app

TanStack Router recommends utilizing its file-based routing system. That’s why when we bootstrapped our app in the data layer article, we got the routes folder with two files:

__root.tsx - wrapper for all routes in our app.
index.tsx - main route in our app. It stands for the / path.

At the moment, let’s focus our attention on __root.tsx, because that’s where we’ll keep the layout of the app:

import { Grid } from "@mui/material";
import { Outlet, createRootRoute } from "@tanstack/react-router";

export const Route = createRootRoute({
  component: () => (
    <Grid container sx={{ height: "100vh" }}>
      <Grid
        size={3}
        sx={{
          height: "100%",
          backgroundColor: "ButtonShadow",
          overflowY: "scroll",
        }}
      >
        {/* Put here the history list once it's implemented */}
      </Grid>
      <Grid size={9}>
        <Outlet />
      </Grid>
    </Grid>
  ),
});

Let’s break it down:

First, we create a root route. The official documentation explains it: “The createRootRoute function returns a new root route instance”. The difference between the root route and the index route is that the root route doesn’t have a path, like the index route does (/ path). Root route is used to create a route tree and store the layout of the app.
Second, we define a structure of the layout using the Grid component. This component comes from the MUI library. Using it is an optional step. You can choose a different components library or skip any libraries entirely. I’ll continue utilizing MUI in all the next tutorials, because it’s just easier and quicker to develop UI with its wide range of components. With the Grid component, we defined the next layout:

Humble, but more than enough for our simple app.
The final touch is the Outlet component, which is provided by TanStack Router. The Outlet renders the next potentially matching child route. If the user has entered / in the browser’s search bar, the Outlet will render the UI matching the / path.

Good, we have the layout. Let’s fill it with the content now.

Let the users guess the country

Now that we’ve defined the layout, it’s time to focus on the Quiz widget that the user interacts with:

import {
  Button,
  Card,
  CardActions,
  CardContent,
  CardMedia,
} from "@mui/material";
import type { QuizProps } from "../model";
import { QuizForm } from "./QuizForm";
import { QuizResult } from "./QuizResult";

export const Quiz: React.FC<QuizProps> = ({
  country,
  form,
  result,
  onSubmit,
}) => {
  return (
    <Card sx={{ width: 320, margin: "0 auto" }}>
      <CardMedia
        sx={{ height: 198 }}
        image={country.flag}
        title="Country flag"
      />
      <CardContent sx={(theme) => ({ padding: theme.spacing(2, 1) })}>
        {!result ? <QuizForm form={form} /> : <QuizResult result={result} />}
      </CardContent>
      <CardActions sx={{ display: "flex", justifyContent: "end" }}>
        <Button size="small" variant="contained" onClick={onSubmit}>
          {!result ? "Submit answer" : "Next country"}
        </Button>
      </CardActions>
    </Card>
  );
};

NOTE: What’s the widget? - It is an individual component that renders the UI and responds to events. Why do I call it a widget? - It’s a Flutter-inspired name to call a React component, which already combines a couple of other smaller components. For example, Quiz widget blends Card, Button, CardContent, and so on:

Let’s break the Quiz widget step by step, just like we did with the layout:

We start by creating a functional React component typed with QuizProps, which accepts the following props:

country - the object of a randomly selected country to guess.
form - TanStack Form’s instance. TanStack Form is a headless form state manager. It includes submission, validation, composition, and other great staff. We touch on some UI aspects of the library later in this article. We also discuss form handling in the application layer article. Feel free to use any form management library if you’re not comfy with TanStack Form.
result - the result of the user’s attempt to guess the country.
onSubmit - a function that’s called when the user clicks the action button. It either submits the answer or triggers loading the next country, if the result is already shown.

For now, QuizProps can look like this:

import type { CreateHistoryRecordDTO } from "@/modules/History/model";

export type QuizProps = {
  country: any;
  form: any;
  result?: CreateHistoryRecordDTO;
  onSubmit: VoidFunction;
};

We’ll fix it when we develop the hook to handle quiz logic and apply the props trick from the model layer article.

Next, I use Card MUI’s component and its pieces to create an actual UI:

return (
  <Card sx={{ // ... }}>
    <CardMedia
      // ...
    />
    <CardContent sx={// ...}>
      // ...
    </CardContent>
    <CardActions sx={// ...}>
      // ...
    </CardActions>
  </Card>
  );

Pay attention to this line:

{!result ? <QuizForm form={form} /> : <QuizResult result={result} />}

Here we have 2 additional components: QuizForm and QuizResult. I created them because of 2 reasons:

Make the Quiz widget smaller by moving UI with different responsibilities to different widgets.
Fulfill the Single Responsibility principle of SOLID.

Let’s take a look at each widget. 👇

Answering form

Since the form is what the user sees first, let’s begin with QuizForm, the input widget responsible for capturing the answer:

import { TextField } from "@mui/material";
import type { QuizFormProps } from "../model";

export const QuizForm: React.FC<QuizFormProps> = ({ form }) => {
  return (
    <form>
      <form.Field name="answer">
        {(field) => (
          <TextField
            label="Your answer"
            variant="outlined"
            sx={{ width: "100%" }}
            error={!field.state.meta.isValid}
            helperText={field.state.meta.errors[0]}
            value={field.state.value}
            onChange={(event) => field.handleChange(event.target.value)}
          />
        )}
      </form.Field>
    </form>
  );
};

Again, it’s a stateless, logic-free functional component which expects to receive 1 property: form. This form instance is the same one passed into the Quiz widget, so the QuizFormProps can look like this:

export type QuizFormProps = Pick<QuizProps, "form">;

The next piece of code might be confusing to those unfamiliar with TanStack Form:

//...
<form>
  <form.Field name="answer">
//...

For JSX, form is just a variable in props (not the HTML tag), so form.Field works just like any namespace object. The outer <form> is a native HTML tag. JSX automatically distinguishes them, so no linter errors.

TanStack Form is a headless library, meaning we can integrate any input into it. This is what we did with TextField from MUI:

{(field) => (
  <TextField
    label="Your answer"
    variant="outlined"
    sx={{ width: "100%" }}
    error={!field.state.meta.isValid}
    helperText={field.state.meta.errors[0]}
    value={field.state.value}
    onChange={(event) => field.handleChange(event.target.value)}
  />
)}

A function with a field property exposed by TanStack Form as well. I think the code is self-descriptive enough here, but to grasp all the details, read the official Field documentation.

QuizForm is ready, great!

Right or wrong?

QuizResult displays either a success or failure message based on whether the answer is correct:

import React from "react";
import type { QuizResultProps } from "../model";
import { Alert, Stack, Typography } from "@mui/material";

export const QuizResult: React.FC<QuizResultProps> = ({ result }) => {
  return (
    <Stack>
      {result?.countryName.toLowerCase() ===
      result?.userAnswer.toLowerCase() ? (
        <React.Fragment>
          <Typography component="div" sx={{ mt: 2 }} color="success">
            Brilliant work!
          </Typography>
          <Alert variant="outlined" severity="success">
            {result?.countryName}
          </Alert>
        </React.Fragment>
      ) : (
        <React.Fragment>
          <Typography color="warning">
            No worries. Learning is a process!
          </Typography>
          <Alert variant="outlined" severity="warning">
            {result?.userAnswer}
          </Alert>
          <Typography component="div" sx={{ mt: 2 }} color="success">
            Correct answer
          </Typography>
          <Alert variant="outlined" severity="success">
            {result?.countryName}
          </Alert>
        </React.Fragment>
      )}
    </Stack>
  );
};

It expects to receive a result as a single prop, which is the type of CreateHistoryRecordDTO from the model layer article:

export type QuizResultProps = Pick<QuizProps, "result">;

Then QuizResult checks if the user’s answer is the same as an actual country name:

result?.countryName.toLowerCase() === result?.userAnswer.toLowerCase()

That’s how it decides whether to show “Brilliant work!” success message or “No worries. Learning is a process!” encouragement.

Visual Recap

Here’s a schema to reinforce how widgets are structured in the Home module:

Because widgets are regular React components, they can contain other widgets. Of course, for better performance and maintainability, it’s better to keep nesting shallow.

Folders organization

This is how your folder structure should look when you finish creating the view layer of the Home module:

src
├── modules
│   ├── History
│   └── Home
│       ├── data
│       ├── model
│       └── view
│           ├── Quiz.tsx
│           ├── QuizForm.tsx
│           ├── QuizResult.tsx
│           ├── index.ts *- index file for re-exporting*
├── routes
│   ├── __root.tsx
│   └── index.tsx

Previewing the Quiz

Now we can see the Quiz widget by displaying it on the main route. Open src/routes/index.tsx and write the next code:

import { Quiz } from "@/modules/Home/view";
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/")({
  component: Home,
});

// Temporar orchestrating component
function Home() {
  const mockField = {
    state: {
      value: "",
      meta: {
        isValid: true,
        errors: [],
      },
    },
    handleChange: () => {},
  };

  const mockForm = {
    Field: ({ children }: any) => children(mockField),
  } as any;

  const mockProps = {
    country: { flag: "https://flagcdn.com/w320/cn.png", name: "China" },
    form: mockForm,
    result: undefined,
    onSubmit: () => {},
  };

  return <Quiz {...mockProps} />;
}

This isn’t the correct way of doing such things, because:

We should not mix Orchestrator’s code with the route’s one.
Mocking is, obviously, only for testing.

We’ll fix everything step-by-step in the next articles by implementing a real form and submission handling. Also, we’ll randomly pick a country to guess and display the result.

Depending on the properties you provided, you must see the next outcomes:

Start of the quiz:
User entered correct answer:
User entered the wrong answer:

Testing

NOTE: I’m using Vitest and React Testing Library to write unit tests.

Test start of the quiz

First, let’s test the Quiz widget:

import { render, screen } from "@testing-library/react";
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import { Quiz } from "../Quiz";
import type { QuizProps } from "../../model";

// Mock Material-UI components to avoid testing library complications
vi.mock("@mui/material", () => ({
  Button: ({ children, onClick, ...props }: any) => (
    <button onClick={onClick} {...props}>
      {children}
    </button>
  ),
  Card: ({ children }: any) => <div>{children}</div>,
  CardActions: ({ children }: any) => <div>{children}</div>,
  CardContent: ({ children }: any) => <div>{children}</div>,
  CardMedia: ({ title, image }: any) => <img alt={title} src={image} />,
}));

// Mock child components
vi.mock("../QuizForm", () => ({
  QuizForm: ({ form }: any) => (
    <div data-testid="quiz-form">
      QuizForm Component - Form State: {JSON.stringify(form)}
    </div>
  ),
}));

vi.mock("../QuizResult", () => ({
  QuizResult: ({ result }: any) => (
    <div data-testid="quiz-result">
      QuizResult Component - Result: {JSON.stringify(result)}
    </div>
  ),
}));

describe("Quiz", () => {
  const mockOnSubmit = vi.fn();

  const mockCountry = {
    flag: "https://example.com/flag.png",
    name: "TestCountry",
  };

  const mockForm = {
    Field: ({ children }: any) =>
      children({ state: { value: "", meta: { isValid: true, errors: [] } } }),
    handleSubmit: vi.fn(),
    resetField: vi.fn(),
  } as any;

  const mockResult = {
    flagImage: "https://example.com/flag.png",
    countryName: "TestCountry",
    userAnswer: "TestAnswer",
  };

  beforeEach(() => {
    vi.clearAllMocks();
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  it("should render quiz form when no result is provided", () => {
    const props: QuizProps = {
      country: mockCountry,
      form: mockForm,
      result: undefined,
      onSubmit: mockOnSubmit,
    };

    render(<Quiz {...props} />);

    expect(screen.getByTestId("quiz-form")).toBeDefined();
    expect(screen.queryByTestId("quiz-result")).toBeNull();
    expect(screen.getByText("Submit answer")).toBeDefined();
  });

  it("should render quiz result when result is provided", () => {
    const props: QuizProps = {
      country: mockCountry,
      form: mockForm,
      result: mockResult,
      onSubmit: mockOnSubmit,
    };

    render(<Quiz {...props} />);

    expect(screen.getByTestId("quiz-result")).toBeDefined();
    expect(screen.queryByTestId("quiz-form")).toBeNull();
    expect(screen.getByText("Next country")).toBeDefined();
  });

    // Find other test cases here: https://github.com/ole-techwood/articles/blob/mvvm/src/modules/Home/view/tests/Quiz.test.tsx
});

Pay attention to how easy it is to test the widget when we don’t have any business logic inside. All we have to mock is the underlying components:

// Mock Material-UI components to avoid testing library complications
vi.mock("@mui/material", () => ({
  Button: ({ children, onClick, ...props }: any) => (
    <button onClick={onClick} {...props}>
      {children}
    </button>
  ),
  Card: ({ children }: any) => <div>{children}</div>,
  CardActions: ({ children }: any) => <div>{children}</div>,
  CardContent: ({ children }: any) => <div>{children}</div>,
  CardMedia: ({ title, image }: any) => <img alt={title} src={image} />,
}));

// Mock child components
vi.mock("../QuizForm", () => ({
  QuizForm: ({ form }: any) => (
    <div data-testid="quiz-form">
      QuizForm Component - Form State: {JSON.stringify(form)}
    </div>
  ),
}));

vi.mock("../QuizResult", () => ({
  QuizResult: ({ result }: any) => (
    <div data-testid="quiz-result">
      QuizResult Component - Result: {JSON.stringify(result)}
    </div>
  ),
}));

We control the widget’s behavior in tests by passing different props,
no need to mock hooks or data fetching logic:

it("should render quiz form when no result is provided", () => {
  const props: QuizProps = {
    country: mockCountry,
    form: mockForm,
    result: undefined,
    onSubmit: mockOnSubmit,
  };

  render(<Quiz {...props} />);

  expect(screen.getByTestId("quiz-form")).toBeDefined();
  expect(screen.queryByTestId("quiz-result")).toBeNull();
  expect(screen.getByText("Submit answer")).toBeDefined();
});

it("should render quiz result when result is provided", () => {
  const props: QuizProps = {
    country: mockCountry,
    form: mockForm,
    result: mockResult,
    onSubmit: mockOnSubmit,
  };

  render(<Quiz {...props} />);

  expect(screen.getByTestId("quiz-result")).toBeDefined();
  expect(screen.queryByTestId("quiz-form")).toBeNull();
  expect(screen.getByText("Next country")).toBeDefined();
});

Test the answering form

This is how we can test QuizForm:

import { render, screen } from "@testing-library/react";
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import { QuizForm } from "../QuizForm";
import type { QuizFormProps } from "../../model";

// Mock Material-UI components
vi.mock("@mui/material", () => ({
  TextField: ({ label, value, onChange, error, helperText, ...props }: any) => (
    <div>
      <label htmlFor="answer-input">{label}</label>
      <input
        id="answer-input"
        value={value}
        onChange={onChange}
        data-error={error}
        {...props}
      />
      {helperText && <span data-testid="helper-text">{helperText}</span>}
    </div>
  ),
}));

describe("QuizForm", () => {
  const mockHandleChange = vi.fn();

  const mockField = {
    state: {
      value: "",
      meta: {
        isValid: true,
        errors: [],
      },
    },
    handleChange: mockHandleChange,
  };

  const mockForm = {
    Field: ({ children }: any) => children(mockField),
  } as any;

  beforeEach(() => {
    vi.clearAllMocks();
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  it("should render form with text input field", () => {
    const props: QuizFormProps = { form: mockForm };

    render(<QuizForm {...props} />);

    expect(screen.getByLabelText("Your answer")).toBeDefined();
    expect(screen.getByRole("textbox")).toBeDefined();
  });

  // Find other test cases here: https://github.com/ole-techwood/articles/blob/mvvm/src/modules/Home/view/tests/QuizForm.test.tsx
});

Again, dead simple, we mock the MUI’s TextField component and then check different conditions by passing different values in the form prop.

Test results

Last but not least - QuizResult tests:

import { render, screen } from "@testing-library/react";
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import { QuizResult } from "../QuizResult";
import type { QuizResultProps } from "../../model";

// Mock Material-UI components
vi.mock("@mui/material", () => ({
  Stack: ({ children }: any) => <div data-testid="stack">{children}</div>,
  Typography: ({ children, color, ...props }: any) => (
    <p data-color={color} {...props}>
      {children}
    </p>
  ),
  Alert: ({ children, severity, variant }: any) => (
    <div data-testid="alert" data-severity={severity} data-variant={variant}>
      {children}
    </div>
  ),
}));

describe("QuizResult", () => {
  const mockCorrectResult = {
    flagImage: "https://example.com/flag.png",
    countryName: "France",
    userAnswer: "france",
  };

  beforeEach(() => {
    vi.clearAllMocks();
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  it("should render success message for correct answer", () => {
    const props: QuizResultProps = { result: mockCorrectResult };

    render(<QuizResult {...props} />);

    expect(screen.getByText("Brilliant work!")).toBeDefined();
    expect(screen.getByText("France")).toBeDefined();

    const successAlert = screen.getByTestId("alert");
    expect(successAlert.getAttribute("data-severity")).toBe("success");
  });

  // Find other test cases here: https://github.com/ole-techwood/articles/blob/mvvm/src/modules/Home/view/tests/QuizResult.test.tsx
});

The testing approach is the same as with the previous two widgets; nothing new here.

And that’s it, we’re done with tests! Now, when you saw the whole process of creating a view layer with widgets, I want to give you a little homework.

Study by practicing

Don’t just grind tutorials. Better implement the new knowledge, practicing right off the bat! That’s why I want you to create a HistoryList widget within the History module of the app.

Requirements:

It must be a clean React component with a single history property of the HistoryRecord[] type (we created the type in the model layer article.
It must iterate through the history array and list all the answers.
It must be integrated into the left sidebar of the layout we created earlier in the article.
Add some tests for it.
Final result should look kinda like this:

Good luck! Keep in mind, you can always find the ready variant in the source code. But really, do your best and complete the task on your own (remember, AI is your friend, not an enemy! 🙂).

Conclusion

This is it, folks! ✅

Today, we’ve discussed the view layer. In a nutshell, this is the layer our users see and interact with. So it’s essential to keep the layer and its parts clean, maintainable, and covered in tests.

Not just by reading, but by doing you:

Learned what the widget is in MVVM architecture.
Got to know how to create a layout for the whole app in TanStack Router.
Understood how to create and test the widget.

By this time, you have all the knowledge to create robust view layers utilizing MVVM architecture in production-grade systems!

What’s next?

Continue reading the next articles in the MVVM series:

Or go over the previous ones:

Creating content like this is not an easy ride, so I hope you’ll hit that like button and drop a comment. As usual, constructive feedback is always welcome!

🔗 Follow me on LinkedIn

📰 Read me on the platform of your choice: Substack, DEV.to

See ya soon 👋

React MVVM Architecture with TanStack Router: Model Layer

Olexandr — Thu, 21 Aug 2025 13:50:32 +0000

Types are playing an essential part in modern React applications. They’re the foundation for typing component props, shaping unstructured data like JSON, and defining request bodies. And that’s only the tip of the iceberg of use cases you might run into.

We, as developers, often focus so much on business logic, performance, security, and all the other critical aspects of our apps that we just forget about the type system. As the project evolves, types get messy - names are inconsistent, and there’s no clear place to store them. That hurts the developer experience. Teams start using any more commonly, and it leads to inconsistency between the backend and the frontend. As a result, bugs emerge.

Today we’re talking about the model layer, which is a part of the five-layer MVVM architecture

Its goal is to tackle all of the hurdles listed above, which means fewer bugs, zero any usage (unless it’s absolutely required), and easier refactoring.

TIP: If you haven’t read my MVVM Introduction yet, I highly recommend doing that first. It’ll help you understand where the model layer fits in the bigger picture.

In this article, you’ll learn:

How to add types to the unstructured data you receive and send to the external sources.
How to structure the data so it can be conveniently displayed on the UI.
How to organize the prop types in the MVVM style.

Before we begin, I just want to remind, that in this MVVM series, we’re building a country quiz app. The app prompts the user with the flag, and the user has to guess the name of the country. Once they entered and sent the answer, we save it in the localStorage. Then we display the answer history in the left sidebar. You can find the source code on GitHub and the Demo on CodeSandbox.

Payload: Typing the API Response

Payloads define a structure for the data your app receives from the external data source. For example, it can be a type of GET query or WebSocket channel response.

In the article explaining the data layer, we had a method called findCountries to fetch all the countries. If you remember, we’ve put any[] for the response type instead of a valid one. Now let’s create a payload for it:

import * as z from "zod/v4";

// Define an object for a single country returned from the countries API
const countryPayload = z.object({
  flags: z.object({
    png: z.string().nonempty(),
    svg: z.string().nonempty(),
    alt: z.string(),
  }),
  name: z.object({
    common: z.string().nonempty(),
    official: z.string().nonempty(),
    nativeName: z.record(
      z.string().nonempty(),
      z.object({
        official: z.string().nonempty(),
        common: z.string().nonempty(),
      })
    ),
  }),
});

// Define an array of countries
export const countriesPayload = z.array(countryPayload);

// Define a type out of countryPayload object using Zod's infer
export type CountryPayload = z.infer<typeof countryPayload>;

NOTE: Follow the link to get the structure for the payload

To define a payload object and a type, I use Zod. It allows us to perform runtime validation of the layer’s entities. This ensures malformed data from the third-party APIs never breaks the app. Later, when we work on the business logic, I will show you detailed validation examples.

Currently, we’re interested in the CountryPayload type. Without Zod, it would look like this:

export type CountryPayload = {
  flags: {
    png: string;
    svg: string;
    alt: string;
  };
  name: {
    common: string;
    official: string;
    nativeName: {
      [key: string]: {
        official: string;
        common: string;
      };
    };
  };
};

With the type created, your folder structure should look like this:

src/
├── modules/
│   └── Home/
│       └── model/
│           ├── home.dto.ts
│           └── index.ts - index file for re-exporting

Yes, it’s fine to store payload in the DTO file.

Zod is a completely optional package, and its usage depends on your project’s needs. Like I said, I’ll show you more Zod benefits later in the application layer. Meanwhile, you can specify a return type for the findCountries like this:

findCountries() {
  return this.apiService.get<CountryPayload[]>("/all?fields=name,flags");
}

DTO: Structuring Outgoing Data

DTOs, on the other hand, define a structure for the data you transfer (meaning send) to the external source. It can be a type for POST request’s body or for an object you save into IndexedDB. DTO can also represent query params for a GET request.

In HistoryRepository, we have a method saveAnswer:

saveAnswer(createHistoryRecordDto: any) {
  return this.slice
    .getState()
    .saveAnswer({ ...createHistoryRecordDto, createdAt: Date.now() });
}

Let’s define a DTO for the createHistoryRecordDto param:

import { z } from "zod";

export const createHistoryRecordDTO = z.object({
  flagImage: z.string().nonempty(),
  countryName: z.string().nonempty(),
  userAnswer: z.string().nonempty(),
});

export type CreateHistoryRecordDTO = z.infer<typeof createHistoryRecordDTO>;

Put this DTO inside the model folder of the History module, just like we did with CountryPayload in the previous section.

Equivalent without Zod:

export type CreateHistoryRecordDTO = {
  flagImage: string;
  countryName: string;
  userAnswer: string;
};

This DTO consists of 3 properties:

flagImage - URL of the flag picture, so we can display the flag near each answer.
countryName - correct name of the country.
userAnswer - name of the country the user entered.

Now we can specify a DTO type for the saveAnswer method like this:

saveAnswer(createHistoryRecordDto: CreateHistoryRecordDTO) {
  return this.slice
    .getState()
    .saveAnswer({ ...createHistoryRecordDto, createdAt: Date.now() });
}

With the DTO in place, we can send the data out safely and predictably. Now let’s look at how we shape the data inside the app using Module Types.

Module Type: Visualize Model Layer

This is the main type of the whole module. The module type holds properties to be shown on the UI. It doesn’t necessarily mean that all the properties from this type will be represented in the interface. Some properties exist for the business logic only, some can just sit there and patiently wait to be used at some point later.

Worth mentioning that sometimes module type can replace the payload, if the backend response is structured for the UI or business logic right when we receive it. If the data needs reshaping or enriching, keep the module type and the payload separate.

For example, HistoryRecord - the module type for the History module looks like this:

import { z } from "zod";
import { createHistoryRecordDTO } from "./history.dto";

// https://zod.dev/api#extend
export const historyRecord = createHistoryRecordDTO.extend({
  createdAt: z.number(),
});

// Convert historyRecord schema into Zod array, so we can validate the response from localStorage inside the application layer
export const historyRecords = z.array(historyRecord);

export type HistoryRecord = z.infer<typeof historyRecord>;

historyRecord schema inherits all the properties from createHistoryRecordDTO. It also adds one more createdAt timestamp indicating when the history record was created. HistoryRecord type infers the structure from the schema, as usual.

NOTE: Learn more about the extend function.

Equivalent without Zod:

export type HistoryRecord = CreateHistoryRecordDTO & {
  createdAt: number;
}

Use HistoryRecord inside historySlice to specify the type for the history:

import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";
import type { HistoryRecord } from "../model";

export type HistorySlice = {
  history: HistoryRecord[]; // We add type here
  saveAnswer: (result: HistoryRecord) => void; // We add type here
  clearHistory: () => void;
};

export const historySlice = create<HistorySlice>()(
  // History slice implementation
);

NOTE: We created historySlice in the data layer article.

This is how the HistoryRecord module type can be shown on the UI:

Prop types: Provide Data or Configuration to UI

These are just regular prop types you would specify for the components in your React app. For example, we have a sidebar with a history list widget. This widget should accept the following properties:

history - an array with all history records to display.
loading - a boolean value indicating whether we’re fetching the data at the moment.
error - string holding the text of the error, if any occurred.

Humbly, but enough for educational purposes. So the props type will look like this:

export type HistoryListProps = {
  history: HistoryRecord[]; // an array of module types
  loading: boolean;
  error: string;
}

NOTE: I don’t use Zod for prop types, because this is overkill. But, of course, you can do it if you have a strong reason.

Then we provide it to the component through React.FC:

export const HistoryList: React.FC<HistoryListProps> = ({ history, loading, error }) => {
  // Widget implementation
}

Easy, isn’t it? If you read my MVVM intro, you might remember I said this in the “Application Layer” section: “usually, each hook corresponds to a specific widget from the View layer”. Suppose we have a custom hook called useHistoryList. It fetches the history records from localStorage, handles loading and errors:

export const useHistoryList = () => {
  // Hook implementation

  return { history, loading, error };
};

As you can see, it returns the same set of properties that we need inside the HistoryList widget. So we can do a little trick with our HistoryListProps. Instead of specifying properties manually inside the type, we can infer them from the returning object of the useHistoryList hook:

export type HistoryListProps = ReturnType<typeof useHistoryList>;

NOTE: In the code example above, we’ve used TypeScript’s utility called ReturnType.

That one-liner isn’t just beautiful - it automatically picks up new properties from the custom hook and adds each one fully typed to your props object.

A key downside to keep in mind is that if you change the return signature of the custom hook, it will break the type and cause TypeScript linter errors. But even with this tradeoff, the object returned by the custom hook and props type will be synced. The only place to refactor is the widget.

TIP: Remember to use utils like Omit or Pick to avoid silently carrying over properties not meant for the UI.

What’s that? What if you need an additional property that the custom hook doesn’t return? I’ve got you covered:

export type HistoryListProps = ReturnType<typeof useHistoryList> & {
  customProp: string;
};

NOTE: If you’re thinking “widgets, hooks, application layer… wtf🤯,” don’t worry. You’ll get it all if you read the MVVM intro and 2 articles about application and view layers.

We had to briefly look ahead here, because it’s impossible to explain prop types in isolation without referencing the layers that use them.

Testing

NOTE: To write unit tests I’m using Vitest.

One of the reasons I tend to use Zod is that you can test model layer entities we’ve just discussed. This catches errors that TypeScript can’t, like empty strings or missing fields, which often cause runtime bugs in real-world apps. Here’s how to verify whether our DTO is correct:

import { describe, it, expect } from "vitest";
import { createHistoryRecordDTO } from "../history.dto";

describe("createHistoryRecordDTO", () => {
  it("should parse valid input", () => {
    const valid = {
      flagImage: "flag.png",
      countryName: "Ukraine",
      userAnswer: "Ukraine",
    };

    expect(createHistoryRecordDTO.parse(valid)).toEqual(valid);
  });

  it("should fail for empty strings", () => {
    const edge = {
      flagImage: "",
      countryName: "",
      userAnswer: "",
    };

    expect(() => createHistoryRecordDTO.parse(edge)).toThrow();
  });

  it("should fail for missing fields", () => {
    expect(() => createHistoryRecordDTO.parse({})).toThrow();
    expect(() =>
      createHistoryRecordDTO.parse({ flagImage: "f.png" })
    ).toThrow();
  });

  it("should fail for wrong types", () => {
    expect(() =>
      createHistoryRecordDTO.parse({
        flagImage: 123,
        countryName: true,
        userAnswer: null,
      })
    ).toThrow();
  });
});

A piece of cake! No mocks, no spies, nothing. We just use regular Zod’s syntax, which we’d use in the production code.

One more test to verify countryPayload:

import { describe, it, expect } from "vitest";
import { countriesPayload } from "../home.dto";

// Import the single country schema
const countryPayload = countriesPayload.element;

describe("countryPayload", () => {
  it("should parse valid input", () => {
    const valid = {
      flags: {
        png: "flag.png",
        svg: "flag.svg",
        alt: "Flag of Ukraine",
      },
      name: {
        common: "Ukraine",
        official: "Ukraine",
        nativeName: {
          ukr: { official: "Україна", common: "Україна" },
        },
      },
    };

    expect(countryPayload.parse(valid)).toEqual(valid);
  });

  it("should fail for empty strings in required fields", () => {
    const invalid = {
      flags: {
        png: "",
        svg: "",
        alt: "",
      },
      name: {
        common: "",
        official: "",
        nativeName: {
          "": { official: "", common: "" },
        },
      },
    };

    expect(() => countryPayload.parse(invalid)).toThrow();
  });

  it("should fail for missing fields", () => {
    expect(() => countryPayload.parse({})).toThrow();
    expect(() =>
      countryPayload.parse({ flags: { png: "a", svg: "b", alt: "c" } })
    ).toThrow();
  });

  it("should fail for wrong types", () => {
    expect(() =>
      countryPayload.parse({
        flags: "not-an-object",
        name: 123,
      })
    ).toThrow();
    expect(() =>
      countryPayload.parse({
        flags: { png: 1, svg: 2, alt: 3 },
        name: { common: [], official: {}, nativeName: null },
      })
    ).toThrow();
  });
});

In both cases, we test for:

Valid input
Empty strings
Missing fields
Incorrect types

Now that you’ve seen testing examples for both DTO and payload, here’s a small challenge to test your understanding.

A little homework

Try to add other tests for other model layer entities using the example that I’ve provided. Of course, you will find all the tests in the source code if you get stuck. But I really encourage you to try on your own, because we learn the best when we take action!

Conclusion

If there’s one thing to take away from this article, it’s this: organize your types and take care of them. It’s a common place where things often get messy. Today, we’ve looked at the model layer, its entities, and how they help you organize your types and structure your code. You’ve learned:

How to type your query bodies and responses utilizing DTOs and Payloads.
Why we need a Module Type and how it’s used across the module.

You’ve also:

Revised your knowledge about prop types and how MVVM’s hook-UI relation simplifies their maintenance.
Got to know how we can test the model layer entities, so no invalid data slips into your app, causing unexpected bugs.

Now you have everything you need to build a robust model layer and keep your types consistent and predictable throughout the system. Additionally, Zod usage will make sure the data you manipulate in different parts of your app is valid.

What’s next?

Continue reading the next articles in the MVVM series:

Or go over the previous ones:

Creating content like this is not an easy ride, so I hope you’ll hit that like button and drop a comment. As usual, constructive feedback is always welcome!

🔗 Follow me on LinkedIn

📰 Read me on the platform of your choice: Substack, DEV.to

Till next time! 👋

React MVVM Architecture with TanStack Router: Data Layer

Olexandr — Thu, 21 Aug 2025 12:40:38 +0000

When developing your frontend application, most of the time you work with the data coming from or sending it somewhere. And as discussed in this five-layer MVVM implementation, you have to use the repository for these purposes. It sits just above the network or browser APIs, providing a clean, testable interface to the rest of your app.

TIP: If you haven’t read my MVVM Introduction yet, I highly recommend doing that first. It’ll help you understand where the data layer fits in the bigger picture.

In this article, you’ll learn:

What a repository is and when to use it.
Practical implementation with the source code.
How to write unit tests for the repository.

By the end, you’ll know how to build a robust data layer that lets you scale your app without accumulating technical debt.

What is a Repository?

A repository is a common design pattern that allows you to encapsulate data-accessing logic. Some of the tasks for the repository may include:

Communicate with the external storage.
Define a type for the raw response structure (e.g., JSON) returned from the external storage.
Handle storage-related errors, so the application layer can conveniently deal with them later.
Cache the data or delegate caching responsibility to third-party libraries.

When to use Repository?

When your app has to talk to two or more external endpoints.
When you want to isolate the data accessing logic from UI or business logic.
When there’s a breaking change in a third-party API, the repository is the only place where you’ll need to make changes.

Let’s roll up our sleeves 🛠️

To make this article and all the next ones in the series more engaging, we’ll develop a country flags quiz app. It will prompt the user with the flag, and they will have to guess the country. Then the system saves the answer to the localStorage and displays the answer history in the left sidebar. You can find the source code in this GitHub repository and a Demo on CodeSandbox.

Bootstrap a new TanStack Router app using the package manager of your choice. Next, remove all the redundant files (in our case: reportWebVitals.ts, logo.svg, and so on) and you’re good to go.

Your first repository

Okay, I’m not sure it’s your first-ever repository, but at least it is in this architecture series:

import { apiServiceFactory, type APIService } from "@/shared/api";

/**
 * The repository for the Home module of the app.
 */
export class HomeRepository {
  /**
   * Classes that we inject into the repository through the constructor.
   */
  private readonly apiService: APIService;

  constructor(apiService: APIService) {
    this.apiService = apiService;
  }

  /**
   * Repository's method to find all avaliable countries.
   *
   * Notice that we didn't specify a proper type for the result 
   * of `get` method (used generic `any` instead).
   * We'll do it later in the model layer article.
   */
  findCountries() {
    return this.apiService.get<any[]>("/all?fields=name,flags");
  }
}

/**
 * Factory method to spawn a new instance of HomeRepository and avoid singletone
 *
 * It also injects `APIService` into the `HomeRepository`.
 * Keep reading to get what `APIService` is.
 */
export const homeRepositoryFactory = () => {
  const apiService = apiServiceFactory(["Home"]);

  return new HomeRepository(apiService);
};

I know, a lot of code right off the bat, but in a nutshell, the repository is usually a class with a couple of private fields, a constructor, and methods. This repository is called HomeRepository because it’s a part of the Home module where the quiz happens.

NOTE: There’s no strict rule saying a repository has to be a class. I’ll explain that in the article down below.

At the moment, your folder structure within the src directory should look like this:

src/
├── routes/
│   ├── __root.tsx
│   └── index.tsx
└── modules/
    └── Home/
        └── data/
            └── home.repository.ts

Now let’s focus on interesting tidbits 👇

Make all repositories dumb

Wait what? Don’t we, as smart developers, write smart programs for smart people? Yes, we do. But here’s the paradox: we need to make the individual parts of our programs dumb and abstract, so the whole system is intelligent. Our repository is not an exception!

A repository should never know which library you’re using: axios, fetch, or another-shiny-library. Right now, we have one repository, and things are simple. But imagine our country quiz app blew up - we raised billions, devs are no longer hungry, and they added 100+ repositories. Each one uses axios directly. One day, the CTO comes and says: “NewHypingHttpLibrary just came up, it’s 100x faster and more secure, we need to migrate ASAP”. Damn, now you are in “you vs 100-repositories-to-be-refactored-tomorrow” position.

To avoid such situations, we introduce a special class called APIService:

import { queryOptions } from "@tanstack/react-query";
import axios, { type AxiosInstance } from "axios";

/**
 * A facade over HTTP library to perform API requests.
 */
export class APIService {
  /**
   * The Axios client instance used to perform HTTP requests.
   */
  private readonly apiClient: AxiosInstance;

  /**
   * Query key provided by the consumer of the `APIService` class.
   */
  private readonly queryKey: string[];

  constructor(apiClient: AxiosInstance, queryKey: string[]) {
    this.apiClient = apiClient;
    this.queryKey = queryKey;
  }

  /**
   * Executes a GET request to the provided API endpoint
   *
   * @template D - The expected response data type.
   *
   * @param endpoint - The path to the API endpoint.
   *
   * @returns Query options object for the use with TanStack Query.
   */
  get<D>(endpoint: string) {
    return queryOptions({
      queryKey: this.queryKey,
      queryFn: () => this.apiClient.get<D>(endpoint),
    });
  }
}

/**
 * Factory function to create a configured instance of the `APIService` class.
 *
 * @param queryKey - The query key array used for caching and identifying queries.
 *
 * @returns A configured `APIService` instance ready for making API requests.
 */
export const apiServiceFactory = (queryKey: string[]) => {
  const apiClient = axios.create({
    baseURL: "https://restcountries.com/v3.1",
    adapter: "fetch",
  });

  return new APIService(apiClient, queryKey);
};

You can put api.service.ts wherever you want, but I’ll put it in src/shared/api to indicate that this is an API-related piece of code shared across the modules:

src/
├── modules/
│   └── Home/
│       └── data/
│           └── home.repository.ts
├── routes/
│   ├── __root.tsx
│   └── index.tsx
├── shared/
│   └── api/
│       ├── api.service.ts
│       └── index.ts *- index file for re-exporting*

Now HomeRepository and other repositories depend on the abstract APIService interface, not a concrete implementation. That way, you can easily replace the underlying HTTP library (like axios or fetch) or make other internal changes.

NOTE: This approach satisfies the Dependency Inversion principle of SOLID. Find out more about SOLID in TypeScript.

Querying on steroids

In the get method of APIService, you may notice that we return the result of the queryOptions function:

get<D>(endpoint: string) {
  return queryOptions({
    queryKey: this.queryKey,
    queryFn: () => this.apiClient.get<D>(endpoint),
  });
}

That’s because I propose using TanStack Query for making HTTP requests in our app. It will handle all the errors and cache the data for us, so we don’t have to write and test this logic ourselves. You can find all the benefits the library provides in the link I’ve put in the previous sentence.

NOTE: I’ll rely on TanStack Query in this article and all the next ones, though you’re free to use another data-fetching library, or not to use any.

A repository doesn’t always have to be a class

As mentioned before, a repository is an interface to communicate with the external data source. And there’s no strict rule that it has to be a class. Basically, it can be anything: a function, a class, or even JavaScript module exposing pure methods. As long as it encapsulates access to the external data, it’s fine.

For example, we agreed that we’ll save the history in localStorage. To make it easy to work with this browser API, we can use Zustand and its persist and createJSONStorage functions.

NOTE: In this article, I won’t explain how to set up Zustand. You can read the official documentation or watch this Zustand video tutorial by Cosden Solutions. You can also find the configured store on GitHub. Pay attention to where I put it!

Let’s create a historySlice that will be a part of the History module:

import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";

export type HistorySlice = {
  history: any[];
  saveAnswer: (result: any) => void;
  clearHistory: () => void;
};

export const historySlice = create<HistorySlice>()(
  persist(
    (set) => ({
      history: [],

      // Saves the user's answer to the localStorage
      saveAnswer: (answer) =>
        set((state) => ({ history: [answer, ...state.history] })),

      // Clears the history from the localStorage
      clearHistory: () => set({ history: [] }),
    }),
    {
      // localStorage key
      name: "history",

      // Tells Zustand to use localStorage as a persistent storage for our data
      storage: createJSONStorage(() => localStorage),
    }
  )
);

This is another example of an elegant repository:

We avoid calling localStorage directly, utilizing the API provided by the repository.
Each slice is a different function that we can independently develop and test.
Zustand enables reactive updates, which reduces the need for manual data synchronization between the localStorage consumers.

Now you can either use historySlice directly in your code or wrap it in HistoryRepository, which I recommend:

import { historySlice } from "./history.slice";

/**
 * Repository for managing history in browser storage.
 */
export class HistoryRepository {
  /**
   * Slice used to access the data.
   */
  private readonly slice: typeof historySlice;

  constructor(slice: typeof historySlice) {
    this.slice = slice;
  }

  /**
   * Saves a new result to the beginning of the history array.
   * 
   * Append `createdAt` timestamp to indicate when the record was created
   *
   * @param createHistoryRecordDto - The new result to save
   */
  saveAnswer(createHistoryRecordDto: any) {
    return this.slice
      .getState()
      .saveAnswer({ ...createHistoryRecordDto, createdAt: Date.now() });
  }

  /**
   * Returns an array of all saved history records.
   * If no history exists, returns an empty array.
   *
   * @returns Array of history records.
   */
  getHistory() {
    return this.slice((state) => state.history);
  }
}

/**
 * Factory function to create a HistoryRepository instance.
 *
 * @returns A new HistoryRepository instance
 */
export const historyRepositoryFactory = () =>
  new HistoryRepository(historySlice);

Keep in mind that it’s an optional step, and you can skip creating an additional class if you feel like it’s overkill for you.

Still two main reasons to do it:

Any consumer of the data layer will always know - the repository class is always the main entry point into the layer. They won’t need to care whether it’s Zustand, localStorage, or anything else under the hood.
Even better DI - you can easily replace Zustand with another state management library if you ever need it.

At this point, your modules folder structure should look like this:

src/
└── modules/
    ├── Home/
    │   └── data/
    │       └── home.repository.ts
    └── History/
        └── data/
            ├── history.repository.ts
            ├── history.slice.ts
            └── index.ts *- index file for re-exporting*

And that wraps up the repository implementation. Now let’s make sure everything behaves correctly by writing some tests 🧪.

Testing

NOTE: As a testing framework I’ll use Vitest.

First, let’s write unit tests for HomeRepository:

import type { APIService } from "@/shared/api/api.service";
import { describe, expect, it, vi } from "vitest";
import { HomeRepository, homeRepositoryFactory } from "../home.repository";

// Mock APIService
function createMockApiService(getImpl?: any): APIService {
  return {
    get: getImpl || vi.fn(),
  } as unknown as APIService;
}

describe("HomeRepository", () => {
  let apiService: APIService;

  describe("findCountries", () => {
    it("should return countries", async () => {
      const mockCountries = [
        {
          name: {
            common: "Ukraine",
            official: "Ukraine",
            nativeName: {
              ukr: { official: "Україна", common: "Україна" },
            },
          },
          flags: {
            png: "ua.png",
            svg: "ua.svg",
            alt: "Flag of Ukraine",
          },
        },
        {
          name: {
            common: "Poland",
            official: "Republic of Poland",
            nativeName: {
              pol: { official: "Rzeczpospolita Polska", common: "Polska" },
            },
          },
          flags: {
            png: "pl.png",
            svg: "pl.svg",
            alt: "Flag of Poland",
          },
        },
      ];

      apiService = createMockApiService(
        vi.fn().mockResolvedValue(mockCountries)
      );

      // Easily inject any APIService into HomeRepository
      const repo = new HomeRepository(apiService);
      const result = await repo.findCountries();

      expect(result).toEqual(mockCountries);
    });

    it("should return empty array", async () => {
      apiService = createMockApiService(vi.fn().mockResolvedValue([]));

      const repo = new HomeRepository(apiService);
      const result = await repo.findCountries();

      expect(result).toEqual([]);
    });

    it("should fail when API throws", async () => {
      apiService = createMockApiService(
        vi.fn().mockRejectedValue(new Error("API fail"))
      );
      const repo = new HomeRepository(apiService);
      await expect(repo.findCountries()).rejects.toThrow("API fail");
    });
  });
});

describe("homeRepositoryFactory", () => {
  it("should return HomeRepository instance with working apiService", () => {
    const repo = homeRepositoryFactory();

    expect(repo).toBeDefined();
    expect(typeof repo.findCountries).toBe("function");
  });
});

Notice how straightforward it is to test the repository since we made it “dumb” earlier:

it("should return empty array", async () => {
  apiService = createMockApiService(vi.fn().mockResolvedValue([]));

  const repo = new HomeRepository(apiService);
  const result = await repo.findCountries();

  expect(result).toEqual([]);
});

We can inject any specimen of the APIService into the HomeRepository. This shows Dependency Inversion in action. The repository just needs an object that fits the APIService interface, which makes mocking and testing a piece of cake.

Here’s how we can test historySlice:

import { beforeEach, describe, expect, it } from "vitest";
import { historySlice } from "../history.slice";

// Mock localStorage for Zustand persist
const localStorageMock = (() => {
  let store: Record<string, string> = {};

  return {
    getItem: (key: string) => store[key] || null,
    setItem: (key: string, value: string) => {
      store[key] = value;
    },
    removeItem: (key: string) => {
      delete store[key];
    },
    clear: () => {
      store = {};
    },
  };
})();

Object.defineProperty(window, "localStorage", { value: localStorageMock });

describe("historySlice", () => {
  let slice: typeof historySlice;

  const sample = {
    flagImage: "flag.png",
    countryName: "Ukraine",
    userAnswer: "Ukraine",
  };

  // Start from scratch each test case - clear the history
  beforeEach(() => {
    window.localStorage.clear();

    slice = historySlice;
    slice.getState().clearHistory();
  });

  it("should initialize with empty history", () => {
    expect(slice.getState().history).toEqual([]);
  });

  it("should save an answer to history", () => {
    slice.getState().saveAnswer(sample);

    expect(slice.getState().history[0]).toEqual(sample);
  });

  it("should save multiple answers in correct order", () => {
    const answer = {
      flagImage: "b.png",
      countryName: "Poland",
      userAnswer: "Poland",
    };

    // sample is inserted first, but should appear last in the final array
    slice.getState().saveAnswer(sample);

    // answer is inserted last, but should appear first in the final array
    slice.getState().saveAnswer(answer);

    expect(slice.getState().history[0]).toEqual(answer);

    // sample is second, because Zustand append new value at the start of the array
    expect(slice.getState().history[1]).toEqual(sample);
  });

  it("should clear history", () => {
    slice.getState().saveAnswer(sample);
    slice.getState().clearHistory();

    expect(slice.getState().history).toEqual([]);
  });
});

Because Zustand persists in the localStorage, we need to mock it in test environments that lack browsers’ API:

const localStorageMock = (() => {
  let store: Record<string, string> = {};

  return {
    getItem: (key: string) => store[key] || null,
    setItem: (key: string, value: string) => {
      store[key] = value;
    },
    removeItem: (key: string) => {
      delete store[key];
    },
    clear: () => {
      store = {};
    },
  };
})();

Object.defineProperty(window, "localStorage", { value: localStorageMock });

As you can see, test cases use regular Zustand syntax to assert the expected results:

it("should save an answer to history", () => {
  slice.getState().saveAnswer(sample);

  expect(slice.getState().history[0]).toEqual(sample);
});

As a little practice task, try to write unit tests for HistoryRepository on your own. Find my implementation of tests for the history repository on GitHub.

Summary

You made it! 🔥

Now you know:

What a repository is and how to use it.
Why the dependency inversion principle is important and how the repository allows you to fulfill it.

Additionally, you’ve learned how to utilize modern libraries like TanStack Query and Zustand to make your repositories more powerful than ever.

As icing on the cake, we discussed how to test different kinds of repositories. You saw how effortless it is to write unit tests when the repo follows clean architecture*.*

What’s next?

Deep dive into the series to grasp the whole picture about modern MVVM architecture in React:

Creating content like this is not an easy ride, so I hope you’ll hit that like button and drop a comment. As usual, constructive feedback is always welcome!

🔗 Follow me on LinkedIn

📰 Read me on the platform of your choice: Substack, DEV.to

Till next time 👋

React MVVM Architecture with TanStack Router: An Introduction

Olexandr — Thu, 21 Aug 2025 11:30:04 +0000

If you’re reading this article, you’ve probably already understood the importance of having clean architecture within your app. And if you’ve tried applying those clean architecture principles to your React front-end, you’ve likely hit a wall (I know, I’ve been there too).

In this blog post, I don’t want in a million time explain why clean architecture matters, like so many great authors did before me. I want to focus on rather how to implement it, specifically on the front-end using React and TanStack Router.

I’ve been carefully crafting and experimenting with the approach I’m about to show you for years on dozens of production and side projects. My goal now is to help you implement the same approach in your own projects.

TIP: If you want to understand the fundamentals of software architecture, I recommend choosing the book called “Clean Architecture: A Craftsman's Guide to Software Structure and Design” by R. Martin as a starting point.

First things first: Why TanStack Router?

While it comes with some great features like a file-based routing system and router-related code generation, regarding the architectural aspects, the official documentation doesn’t provide you with any information. But that’s exactly what I like about TanStack Router: it’s a robust yet highly adaptable client-side framework. You can build any architecture with it, including the hero of today’s article.

Ladies and gents, meet MVVM

MVVM is a common design pattern that you can use to:

Have a clear separation of concerns between UI, business logic, data accessing, and interfaces or types.
Integrate tools like plop.js to automate the creation of the new modules within your app with all the required concerns.
Simplify unit tests writing by focusing on one piece of functionality at a time. It simply means that with MVVM, you can test business logic without worrying about UI and vice versa.

NOTE: When I say “modules within your app”, I mean Authentication, Shopping Cart, Home, About, and other pages in your app. You might also know them as features.

How can MVVM gift me all these sweets?

By breaking all the modules in your app into:

Models - a place where data access and business logic handling are happening.
Views - UI (widgets or components).
ViewModels - serve as an orchestrator between models and views.

More practical approach

Above, I’ve described the theory of MVVM with three core parts. In practice, I break MVVM into five more granular layers:

Data, Application, and Model correspond to the Model layer in the original MVVM.
View stays the same in both the original and the implementation I’m about to show you.
Orchestrating component used as a ViewModel.

This way, each concern stays isolated, making things easier to test and maintain. Each layer handles its specific task, and there's a clear way in which they interact with one another.

NOTE: Naming of the layers is totally up to you. I just recommend keeping it consistent to ensure clarity and speed up onboarding.

Here’s the preview:

Now let’s take a closer look at each layer.👇

NOTE: Because there's a lot to explain, this article focuses on a broad, high-level look at the layers. You can find links below to individual articles that dive deeper into each layer with code examples. I recommend following the order of layers beneath when exploring each one individually. Thus, you don’t miss anything and understand all the details.

Data Layer

This layer communicates with the external source(-s). For example, it can perform API calls, make requests to localStorage, and read or write data into a file. Think of the Data Layer as “raw” access: it only knows how to fetch.

The layer contains a well-known class(-es) called the repository pattern, which is used to access the external data. The repository has methods, each representing one operation.

Suppose we need to fetch a list of all products. We’d create a method inside the repository called findAllProducts which:

Makes a GET request to an external source.
Defines a type for the raw JSON response.
Returns type-safe data to the consumer who called the method.

Learn more about the Data layer and repositories.

Model Layer

Now that we’ve fetched the data, let’s add some types for it.

The Model layer defines types, interfaces, and classes, including:

Payloads

TypeScript interfaces or types that define a structure for the untyped data (like JSON) we receive from the external source. Suppose findAllProducts receives the next JSON from the API:

[
  {
    "id": "prod_12345",
    "name": "Wireless Headphones",
    "description": "Noise-cancelling over-ear Bluetooth headphones",
    "price": 149.99,
    "currency": "USD",
    "//other": "properties...."
  }
]

So the payload type is the following:

export type ProductPayload = {
  id: string;
  name: string;
  description: string;
  price: number;
  currency: string;
  // other properties...
};

Of course, it should be an array in our case: ProductPayload[]

Data Transfer Objects (DTOs)

TypeScript interfaces or types that describe the structure for the untyped data (like JSON) sent to the external source.

Following the example from the previous section, we can specify a DTO type for the query parameters of the findAllProducts method and call it FindAllProductsDTO. We’ll assume it contains one parameter called category, so the whole DTO type will look like:

type FindAllProductsDTO = {
  category: string
}

TIP: Find out more about DTOs in this amazing article by Miłosz Piechocki.

Module Type

The main type of our module. It holds all the properties that will be displayed on the UI or used for business logic within the module.

Let’s say we need to display the data that findAllProducts returns to us. For that, we may want to merge the price and currency of ProductPayload into a single price property. So the Product module type will look like this:

type Product = {
  id: string;
  name: string;
  description: string;
  price: string;
  // other properties...
}

With this structure, we can conveniently display all the product info on the UI.

Prop types

Simple type objects for React components (widgets and orchestrating component in our case) that we all know.

TIP: Follow the next sections to learn what widgets and orchestrating component are.

Learn more about the Model layer.

View layer

This layer displays the data and serves as a primary point of user interactions. The layer is divided into widgets - individual components that render the UI and respond to events. In most cases, all the widgets must be pure React components without any business logic inside and with a single return of JSX.

Assume we want to display our list of products on the Home page. We’d create a widget called ProductsList.tsx, and one of the props for it would be an array of products - Product[]. Later, we can iterate through the array and display the products like a list of cards.

Learn more about the View layer.

Application Layer

Now that we can receive and display typed data, it’s time to handle business logic (use cases, if you prefer), and that’s where the Application layer comes in.

Some of the common tasks for this layer may include:

Map the data before sending it to the View layer
Make conditional requests to the Data layer - decide when and why to fetch the data.
Initialize functions that will handle user interactions: clicks on buttons, filling a form, scrolling, etc.

In React, I prefer to implement the Application layer as a group of hooks. Usually, each hook corresponds to a specific widget from the View layer, although sometimes we can pass the data from a single hook to multiple widgets. For example, for ProductsList.tsx, we would create a hook called useProductsList.tsx. This hook would handle all the business logic for the widget.

Learn more about the Application layer.

Orchestrating component

Once our business logic is isolated, it’s time to glue everything together. This is exactly the role of the Orchestrator.

You can probably guess from the name that the Orchestrating component connects all four layers and makes them work together. We need the Orchestrator since we can’t simply call hooks from the Application layer into View widgets, because then widgets won’t be clean components anymore.

If we had a Home page that should show a list of products, the Orchestrator would first call hooks from the Application layer. Then, it would pass the data returned from each hook to the appropriate widget in the View layer, and finally return those widgets as JSX.

import { useProductsList } from './application/useProductsList';
import { ProductsList } from './view/ProductsList';
import { Loading } from '~/components/Loading';
import { Error } from '~/components/Error';

export const Home = () => {
  const { products, isLoading, error } = useProductsList();

  // You can handle loading and error state in the Orchestrator or in each widget individually 
  if (isLoading) return <Loading />;
  if (error) return <Error />;

  return <ProductsList products={products} />;
};

Learn more about Orchestrator.

Disadvantages

As with everything in the world, this architecture is not perfect either. Here are some downsides that I’ve spotted while I was implementing it on a variety of projects:

Adoption - when you try to implement this architecture on the existing project, you may face rejection from your colleagues, claiming that it’ll bring complexity and unnecessary boilerplate to the codebase. In this situation, don’t rush refactoring the whole project. Start slow, implement new or refactor existing small module using MVVM. Document the real benefits and show them to the doubters.
More boilerplate - yes, MVVM will bring more boilerplate, but you can automate its creation using tools like plop.js and stop wasting time. Eventually, you will even win from having a standardized structure that you can bootstrap automatically, as it will bring order to the project.

Conclusion

Congratulations! 🎉

You’ve learned the fundamentals of MVVM and its practical five-layer implementation. We’ve discussed how to CRUD the data, type it, apply the business logic, and present it on the UI.

Want to go deeper? Use the links at the end of each section, or start experimenting right away using this high-level overview I’ve provided in the article.

Creating content like this is not an easy ride, so I hope you’ll hit that like button and drop a comment. As usual, constructive feedback is always welcome!

🔗 Follow me on LinkedIn

📰 Read me on the platform of your choice: Substack, DEV.to

Till next time! 👋

DEV Community: Olexandr

I asked successful entrepreneurs about their transition from employee to founder

How did you cope with the switch from employee to founder?

Did you take a sabbatical or a long break to launch a company?

Who did you consult with when making the decision?

How did you manage your personal priorities?

How and when did you tell your colleagues about your decision to leave and start a company?

Conclusion

Continue reading

10 mistakes I made as a first-time solo founder

1. Didn’t find a co-founder

Why it’s a problem

What to do

2. Became a CEO instead of CTO

Why it’s a problem

What to do

3. Extended the team too early

Why it’s a problem

What to do

4. Scrum is your enemy in the early stages

Why it’s a problem

What to do

5. Customer development is a 1-to-1 interview, not a Google Form

Why it’s a problem

What to do

6. Conducted pre-sale too late

Why it’s a problem

What to do

7. Overbuilt the MVP

Why it’s a problem

What to do

8. Selected the wrong revenue model

Why it’s a problem

What to do

9. Operated from personal accounts

Why it’s a problem

What to do

10. I wasn’t the customer of my own product

Why it’s a problem

What to do

Conclusion

Summary

Want more?

Three React MUI commandments

Rule number uno - theme it or leave it

Rule number two - styled component is what you do

Why not to use sx?

Style can’t solve? React component's the resolve

Conclusion

Want more? 🔥

React MVVM Architecture with TanStack Router: Orchestrator

The glue of a module

Creation of the orchestrator

Split into sub-orchestrators when needed

Test the orchestrator

Homework

MVVM brainteaser is done!

What’s next?

React MVVM Architecture with TanStack Router: Application Layer

Random country to guess

Wrong data shall not pass

Form submission

Triggering the form submission

Testing

Homework

Conclusion

Further reading

Want more?

React MVVM Architecture with TanStack Router: View Layer

Shape of the whole app

Let the users guess the country

Answering form

Right or wrong?

Visual Recap

Folders organization

Previewing the Quiz

Testing

Test start of the quiz

Test the answering form

Test results

Why not to use `sx`?