Skip to content
Abhijeet Maharana, home
All posts

Building an Internal React Component Library That Teams Actually Use

What made a shared React library stick across 5+ apps: small typed APIs, accessibility inside the components, tests that check behaviour, versioned releases, and code splitting that cut load time by 40%.

Abhijeet Maharana · 7 min read

  • React
  • TypeScript
  • Accessibility
  • Performance

Short version: in my current role I built and maintain a shared React and TypeScript component library that 5+ internal apps use. It cut frontend development time by about 30%. What made teams adopt it was boring on purpose: small typed APIs, accessibility built into each component, tests that check what users see, and versioned releases so nobody is forced to upgrade on someone else's schedule. Separately, route-level code splitting and lazy loading cut core app load time by 40%.

Why teams rebuild the same button

When several apps grow in parallel, each team builds its own buttons, forms, tables, dialogs and navigation. Nobody decides to do this. It is just faster, that week, than waiting for a shared version.

A year later you have:

  • The same component five times, each a little different, for the same users.
  • The same bugs fixed five times, or fixed in one app and still broken in the others.
  • Uneven accessibility. One team handled keyboard focus in its dialog. Another did not.

A shared library fixes this only if teams choose to use it. Here is what made that happen.

Make the common case one line

If using the shared component takes more code than writing your own, teams will write their own. So the API should make the usual case short and still leave room for the odd one.

type ButtonProps = React.ComponentProps<"button"> & {
  variant?: "primary" | "secondary" | "danger";
  size?: "sm" | "md";
  loading?: boolean;
};

// cx joins class names and skips empty ones (clsx works too).
export function Button({ variant = "secondary", size = "md", loading, disabled, children, ...rest }: ButtonProps) {
  return (
    <button
      {...rest}
      disabled={disabled || loading}
      aria-busy={loading || undefined}
      className={cx("btn", `btn-${variant}`, `btn-${size}`, rest.className)}
    >
      {loading ? <Spinner aria-hidden /> : null}
      {children}
    </button>
  );
}

A few rules that help:

  • Extend the native element's props. onClick, type, form, aria-* and data-* all work without the library listing them.
  • Use unions for variants, not free strings. TypeScript then shows the options in the editor, which is most of the documentation people read.
  • Compose instead of adding props. A Dialog with Dialog.Title, Dialog.Body and Dialog.Actions stays readable. A Dialog with 25 props does not.

Put accessibility inside the component

Accessibility was a property of the library, so every app inherited it without doing anything:

  • Semantic HTML first. A <button> is focusable, works with Enter and Space and is announced correctly. ARIA only fills the gaps native elements leave.
  • Keyboard support and visible focus on every interactive component.
  • Focus management for dialogs and menus: focus moves in when they open, stays inside while open, and returns to the trigger when they close.
  • Colour contrast in the design tokens, so a team cannot pick a text colour that fails WCAG without going around the library.

For dialogs, the native <dialog> element now does much of this. showModal() makes the rest of the page inert and Escape closes it. Wrapping it is less code than building a focus trap yourself.

Test what users see

The library's tests use Jest and React Testing Library, and they test behaviour, not implementation. A test finds a button by its role and name, clicks it, and checks what the user would see. It never reaches into state or class names.

test("loading button is disabled and announced as busy", async () => {
  render(<Button loading>Save</Button>);
  const button = screen.getByRole("button", { name: "Save" });
  expect(button).toBeDisabled();
  expect(button).toHaveAttribute("aria-busy", "true");
});

Querying by role does double duty. If a test cannot find the element by role and accessible name, a screen reader user probably cannot either.

Version it, so nobody is forced to upgrade

Teams worry that a shared dependency will break their app at a bad moment. Versioned releases answer that. Each app pins a version and upgrades when it is ready. With semantic versioning, breaking changes only come in a major version, so a team knows when to read the upgrade notes.

It also lowers the cost of trying the library. A team can try the library on one screen, keep its own components elsewhere, and move over at its own pace.

How code splitting cut load time by 40%

The core apps shipped code for every screen on first load, including screens most users never opened. I changed that so each screen loads only what it needs.

Split by route. Each page becomes its own bundle with React.lazy and a dynamic import():

import { lazy, Suspense } from "react";

const Reports = lazy(() => import("./pages/Reports"));
const Settings = lazy(() => import("./pages/Settings"));

<Suspense fallback={<PageSkeleton />}>
  <Routes>
    <Route path="/reports" element={<Reports />} />
    <Route path="/settings" element={<Settings />} />
  </Routes>
</Suspense>;

Lazy load heavy components. Charts and complex editors load only when they are opened or scroll into view, not with the page around them.

Load feature state when the feature is used. State and logic for a feature were set up at startup whether or not the user went near it. Moving that to first use took more work off the startup path.

Together these cut core application load time by 40%. If you do one thing, start with route splitting. It is usually a few lines per route and it gives the biggest drop.

What a startup can take from this

A startup with two or three product surfaces (an app, an admin panel, a marketing site) hits the same problem early, just smaller. A small library of well-typed components with accessibility built in keeps the product consistent as the team grows, and saves rebuilding the same dialog on every new screen. You do not need 50 components. Ten good ones that people actually use is a better start.

The case study has the results in one place.