Modular React architecture

On modular architecture

What's modular architecture? Let's go through an example of what it isn't, and
we'll work towards transforming it. By the end you may be convinced of its
merits or that it's a colossal waste of time.

This is a real scenario I growth-mindsetted through at work. Names and details
anonymized, but a real-world example of a common concept should be fun to walk
through, if nothing else.

Requirements, and how to find them

Our site has a button that lives in the site header. It displays how many
V-Bucks the user has left, but also has some business logic baked into it:

• If this is their first time visiting the site, open a popover to welcome them & show something they can do with their V-Bucks
• If they have < 5 V-Bucks remaining, show a popover upselling more
• If they are a Basic user, show one style of button; if SuperDuper user, show another, fancier button

And so on. There are many such cases our product managers and project managers
and design managers and Group V-Bucks Directors have dreamed up that we need to
handle.

Jimbo the intern has been tasked with implementing this because it's just a
button!

He sifts through fifteen conflicting iterations of Figma designs. He finds
requirements in as many separate Word docs as there are PMs. He organizes and
endures seven knowledge transfer sessions with seven teams to uncover the
ancient, proprietary knowledge of which services will provide the data he needs
for user type and V-Bucks count. The content team has reassured him that the
final version of all the strings will be approved by legal and marketing by end
of week, and with that, he's ready to build this button.

The hacker approach

Here's the first iteration of his V-Bucks button, popovers, and relevant
business logic.

Jimbo is pleased with the simple directory structure he's come up with:

/v-bucks-button
├── button.tsx
├── index.ts
└── /v-bucks-popover
│ ├── popover.tsx

So he starts building this button, and it begins innocently enough.

export const VBucksButton: React.FC<VBBProps> = ({ ... }) => {
  // Set up state
  const authConfig    = { ... }
  const { user }      = useAuth({ ...authConfig })
  const { vBucks }    = useGetVBucks({ user })
  const { telemetry } = useTelemetry()
  const { t }         = useTranslation('vBucksButton.content')
  const styles        = useButtonStyles()

  // Derive some state via business logic
  const handleClick = () => { ... }
  const buttonText  = vBucks === ERROR ? '--' : vBucks.toString();
  // About 25 more lines of various button state, error handling,
  // conditional rendering, with comments throughout explaining
  // why we're showing or hiding something or other

  const popoverProps = {
    // About 200 lines of typical popover handling,
    // telemetry, business logic, content to display, etc
  }

  const tooltipProps = {
    // Another 100 lines of the same for tooltip
  }

  return (
    <VBucksPopover
      {...popoverProps}
      trigger={
        <Tooltip {...tooltipProps}>
          <button
            ariaLabel={t('ariaLabel')}
            className={`
              about seven-hundred classnames for responsive design,
              accessibility, conditional premium styles, et cetera`}
            onClick={handleClick}>
            {buttonText}
          </button>
        </Tooltip>
      }
    />
  )
}

He's implemented a first go at it. The VBucksPopover has similarly complex
business logic, error handling, state management, styling, and comments excusing
tech debt in the name of shipping.

At just under 400 lines, this button is trivially simple. Even if the popover is
another 500 lines of spaghetti. Does "cleaning" it up or splitting it up really
benefit us, or our users, in any way? It depends. If this is all we'll need for
this button, who cares. Let's move on!

But two months have passed and a PM and designer from another product team love
your button and want it in their app's header. They have a simple list, no
pressure from their end, of some changes they'd like you to accommodate and if
you could please give an ETA by end of day for LT that'd be great, thanks:

• Update the button's styling and display text based on the app it's shown in
• Show a completely different set of popovers, per app
• Open a new company-wide, standard upsell modal when the user's out of V-Bucks, but only in some regions, and only to users age 16+, and only if they're in experiment group A

Can Jimbo cram all of this new functionality into the same components?

Yes. Will splitting or refactoring benefit the users or impress your managers?

No. But refactoring has some strong arguments at this level of complexity:

• Dev sanity
• The sanity of the dev who replaces Jimbo when he's PIPed for not refactoring
• More reps, so you do better from the start next time
• Something to blog about later

The modular architecture approach

The morals of the Clean Code initiates, and other anal types who know enough to
answer on Stack Overflow regularly, and even your grandparents, look something
like this:

• KISS, DRY, & other acronym blankets
• Separation of concerns
• Atomicity! Decoupling! Onomatopoeia!

These are great, and help inform Jimbo's next attempt. He didn't get PIPed after
all, and actually got a promo for delivering ahead of schedule and for sharing
so many meetings and documents.

But he's wiser now and learned a cool way to implement those adages. It looks
something like this:

/vBucksButton
├── /hooks
│ ├── index.ts
│ └── useButtonState.hook.ts
├── /vBucksPopover
│ ├── /app1Popover
│ │ ├── /hooks
│ │ │ ├── index.ts
│ │ │ └── usePopoverState.hook.ts
│ │ ├── ...
│ ├── /app2Popover
│ ├── index.ts
│ ├── popover.renderer.tsx
│ ├── popover.styles.ts
│ ├── popover.tsx
│ └── popover.types.ts
├── /utils
│ ├── experimentation.util.ts
│ ├── store.util.ts
│ ├── telemetry.util.ts
│ └── vBucks.businessLogic.util.ts
├── button.renderer.tsx
├── button.styles.ts
├── button.tsx
├── button.types.ts
└── index.ts

Looks like tons of boilerplate for a button and popover. Why would this be
better?

It depends. Here's Jimbo's brief overview with rationale:

• Split each component into a container and renderer
• Move state and business logic into hooks
• The container uses hooks and passes along any props to the renderer
• The renderer is concerned only with rendering what it's provided
• Common functionality, business logic, or constants can live in utils
• Separate files for types; they tend to be imported in multiple files and become circular deps that you need to extract anyways
• Extracted TailwindCSS -- more on this below

It's infinitely scalable! These building blocks aren't broken down by
arbitrary rules like lines of code or "complexity". They're broken down by
purpose: each conceptual boundary serves a single purpose.

A PM wants you to make 10 new popovers? No problem -- Jimbo's architecture can
handle it.

Leadership wants better metrics on sales in some apps, but other teams don't
have the funding to build out telemetry to support this. Great! We have
telemetry utils that we can horizontally scale to meet various, changing
requirements.

A sweeping redesign means every single popover needs to display different stuff,
based on different conditions. It's typically much simpler now that all of the
stuff we render, and all the logic we use to render it, exist in well-defined
blocks. They're no longer commingled in a giant pile of conflict and logic
chains 20 lines long.

Here's a sample of this container / renderer pattern:

export const VBucksButton: React.FC<ContainerProps> = ({ ... }) => {
  // State comes from hooks
  const buttonProps = useButtonState()

  return (
    <VBucksPopover
      trigger={<VBucksButtonRenderer {...buttonProps} />}
    />
  )
}

export const VBucksButtonRenderer: React.FC<RendererProps> = ({ ... }) => {(
  <Tooltip {...tooltipProps}>
    <button
      ariaLabel{t('ariaLabel')}
      className={styles.vBucksButton}
      onClick={handleClick}>
      {buttonText}
    </button>
  </Tooltip>
)}

/* button.styles.ts */
.vBucksButton {
  @apply all-those same styles-go;
  @apply md:here md:to-make-it-manageable;
  @apply lg:as-these-grow-ever-larger;
}

Aside: The TailwindCSS docs explicitly recommend against using @apply to extract common classes like this. This causes almost zero difference in bundle size, and no other difference than that aside from "you have to come up with class names." Production-grade CSS almost always ends up being dozens of lines long, multiplied by however many elements need styling in a given component. This tradeoff seems worth it 90% of the time.

And the rest of the existing, and new, business logic lives in hooks & utils!

This new architecture satisfies the zealots and makes things easier to scale or
delete or move around.

Writing unit tests becomes less painful because you've got well-defined
boundaries. Your renderer no longer needs to mock ten different services to
validate that it shows some set of shinies given some input. Your hooks can
test, in isolation, that they match your intended business logic.

Did your entire state layer just change? It'd be a shame if the code in your
hook was tightly coupled with the code that uses it, but now it's a simpler
change and your renderer is still just expecting some input.

Final thoughts

This modular architecture adds a lot of boilerplate and can ultimately provide
zero benefit.

I can't practically recommend it if you're working on a passion project or
prioritize shipping & providing value above all. If you've got something that
seems like it might expand in scope over time, or that you may want to
completely overhaul after a POC, it can reduce tech debt... sometimes.

You can use tools like Plop to generate this boilerplate.

So what did I really learn from Jimbo's work & modular architecture?

Clean Code and acronyms we learn in school and the Well Ackshuallys of the world
are one end of a spectrum. Hacking together functional spaghetti code is another
end, and often works quite well, because ultimately all code is tech debt.

The best solution exists in some quantum state or combination of these ends, and
the path we choose will likely be decided based on:

• How much we care about the thing we're building
• How frequently management is asking for updates and ETAs
• Reading something like this and one approach happens to bubble up into your consciousness when you build your next thing
• Frustration, pain
• The spaghetti becomes such a perf bottleneck that you're forced to rewrite it
• The boilerplate becomes so draining that you cut corners