Skip to content
← Back to writing

August 31, 2025

We migrated the entire frontend to React in one sprint

A full Bootstrap-to-React 19 rewrite of the HomelabARR frontend in one sprint, and the Tailwind plus shadcn/ui PostCSS gotcha that ate half a day.

The Bootstrap problem

The real postcss.config.js and AppCard.tsx as committed in August 2025: the two-plugin Tailwind config, and the AppCard component at the center of the catalog.

HomelabARR's frontend started on Bootstrap because Bootstrap is what you reach for when you don't yet know React. Templates, a predictable grid, jQuery-shaped patterns. It got the MVP out the door, and it looked like every other Bootstrap admin panel from 2019.

I was building something meant to sit next to Unraid, TrueNAS, and the newer crowd. HexOS shipped a clean React interface. ZimaOS had a PWA that felt native. My backend was production-ready and my frontend was a sidebar that didn't collapse right on mobile. The mismatch was the whole problem. Nobody trusts a NAS UI that looks like a weekend project.

So the sprint was a full rewrite. Every page, React, no gradual adoption.

One sprint, three surfaces

The work split into three chunks, tracked as through .

The container catalog was the centerpiece. An app card grid over the template library, status badges pulled from Docker metadata, and a deploy flow that walks you through ports, environment, and restart policy instead of making you hand-write a compose file. That card component is still the spine of the UI today:

// src/components/AppCard.tsx
export function AppCard({ app, onDeploy, starred = false, onToggleStar }: AppCardProps) {
  const { theme } = useTheme();
  const cliApp = (app as AppTemplate & { _cliApp?: CLIApplication })._cliApp;
  const showDescription = app.description && !isJunkDescription(app.description);

  return (
    <Card className="group relative overflow-hidden transition-colors duration-200 flex flex-col h-full hover:border-muted-foreground/30">

The other two chunks were the deploy/progress surface and the auth and settings screens. Container controls, live deployment progress over an event stream, login, user settings. None of it glamorous, all of it the difference between a demo and a thing people log into every day.

The stack

React 19 with TypeScript in strict mode. shadcn/ui for components, so I owned the source instead of fighting a black-box library. Tailwind for styling, Vite for the build. Custom hooks for the API polling and the container stats stream.

I want to be honest about what this rewrite was. The structure and the specs were mine. A lot of the component scaffolding was written with an AI in the loop, and then tested and corrected by hand. That is how the whole project gets built, and pretending otherwise would be a lie.

The PostCSS gotcha that ate half a day

The one that cost me real time was Tailwind plus shadcn/ui through PostCSS. shadcn is fussy about its build pipeline, and if the PostCSS plugin setup drifts, the components break quietly. No error, just styles that don't land. The config that actually worked was small and load-bearing:

// postcss.config.js  (Tailwind 3 era)
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

Two plugins, in that order. That is the whole thing, and the project runs on exactly that. I left a note to myself not to touch it, because I knew I would forget why it mattered and break it on some unrelated cleanup.

Build config like this is the kind of thing that is invisible until it silently eats your styling, so write down why it is the way it is.

What changed

Before the sprint, the frontend looked like a side project. After it, it looked like a product. Same backend, same Docker integration, same templates underneath. The interface was the part that had been holding the rest of it back, and fixing it changed how the whole thing read to anyone seeing it for the first time.

That is most of the argument for a modern component library when you are one person. shadcn gave me a coherent design language I was never going to hand-build, React gave me composition Bootstrap couldn't, and TypeScript caught a pile of mistakes before they shipped. The sprint didn't close perfectly clean, but it closed, and it was the week I stopped being embarrassed to show people the thing.

homelabarr.com · mjashley.com