Overview

A note before we start

Many developers who encounter Phlex for the first time bounce off it.

Not because it’s poorly designed — quite the opposite. They bounce off it because the early examples don’t look like an improvement. You see explicit initialize methods with four lines of variable assignment. You see plain calls where ERB would let you just type inline. You see Ruby methods where you expected HTML tags. And you think: this is more work, not less.

That was this tutorial author’s experience. Phlex was evaluated briefly, judged as too verbose compared to ERB partials, and set aside. Then ViewComponent was tried — better interfaces, but two files per component and ERB still doing the heavy lifting. Eventually it was back to partials, with all their familiar problems. It was only after watching a video that showed Phlex being used to build something genuinely complex — a full component library, real-time UI, composable layouts — that the picture finally came together.

The early friction is real. But it’s the friction of learning a new mental model, not the friction of a poorly designed tool. Once the model clicks, Phlex becomes one of the most productive ways to build Rails UI — and the code you were writing before starts to look surprisingly messy by comparison.

This tutorial is designed to get you to that moment faster than we did.

What you’ll build

By the end of this series you will have built two things:

Phlex::UI — a portable component library of 20+ components with typed props, Tailwind token theming, dark mode, three colour themes, and a full Lookbook component browser. It’s genuinely reusable — the Bonus Module packages it as a Ruby gem you can bundle add into any Rails project.

KanbanFlow — a production-ready, real-time, multi-user Kanban board built entirely in Phlex on Rails 8. Sign up, create boards, invite collaborators, drag cards between columns, and watch changes appear instantly in every connected browser.

The journey

Modules 1–7 — The foundations

The first seven modules feel like infrastructure. You’ll build a component library, a theming system, form primitives, a token-based design system with dark mode and multiple colour themes. The app will be sparse — a boards index, a create form, some polished navigation.

This is intentional.

Every decision made in these modules exists to serve what comes later. The typed props mean your components are self-documenting and impossible to misuse. The token system means changing the entire app’s colour scheme is one line of CSS. The form primitives mean every form in the app looks and behaves consistently. The Lookbook component browser means you can see and interact with every component in every state, across every theme, without navigating the app.

By the end of Module 7, KanbanFlow looks polished and professional — but it doesn’t do much yet. The component library in Lookbook, however, is genuinely impressive. Three colour themes, dark mode, 20+ components each with multiple variants and states. That’s a real deliverable.

Module 8 — Stimulus

The component library comes alive. Modals open and close with focus trapping. Dropdowns respond to keyboard navigation. Toasts appear and auto-dismiss. The board gets a working “Board actions” dropdown. It’s still not a real Kanban board — but it’s interactive and accessible.

This module also establishes patterns that pay off in Module 9: Stimulus controllers, the StimulusComponent base class, cross-controller communication. The infrastructure continues — but now you can see it moving.

Module 9 — The payoff

This is where KanbanFlow becomes a real application, almost overnight.

Everything built in Modules 3–8 falls into place. Columns render horizontally. Cards stack within them. You can drag cards between columns and watch positions persist. Click “+ Add card” and a form appears inline — submit it and the card appears without a page reload. Click a card title to edit it in place. Add columns, reorder them.

None of this required rewriting or rethinking what came before. The components snapped together. The Turbo patterns were clean because the DOM was well-structured. The drag-and-drop controller was reusable because StimulusComponent was already in place.

By the end of Module 9, KanbanFlow feels like Trello.

Module 10 - Authentication

Users sign up, sign in, reset passwords. Each user sees only their boards.

Module 11 — Membership, Policy and Prsence

Admins can manage members and delete boards. Members can create and move cards.

The presence bar now shows real user avatars. current_user flows through the entire app — every component that needed it has been waiting since Module 4.

The finished application

✓ Sign up / sign in / password reset
✓ Create, edit, delete boards
✓ Invite team members by email
✓ Role-based access — admin and member roles
✓ Columns with drag-to-reorder
✓ Cards with drag between columns
✓ Inline card creation and editing
✓ Card detail — description, labels, due dates, assignees
✓ Real-time updates across all connected users
✓ Presence bar showing who's viewing the board
✓ Search across boards and cards
✓ Three colour themes × dark/light mode
✓ Full Phlex::UI component library with Lookbook browser (Bonus 1)
✓ Deployed to production with Kamal (Bonus 2)

A note on pacing

The modules are not equal in size or payoff. Modules 3–7 are dense and the visible results are modest. Module 9 is when everything clicks and the app becomes something you’d actually want to use.

If you find yourself in Module 5 wondering whether all this component architecture is worth it — it is. The moment in Module 9 when you wire up drag-and-drop in 20 minutes because every piece was already in place is the moment the investment pays off.

Stay with it.

Prerequisites

• Comfortable with Ruby and Rails — you’ve built Rails apps before
• Familiar with Tailwind CSS basics — utility classes, responsive prefixes
• No prior Phlex experience required — that’s what this series is for
• No Node.js or build tools — Rails 8 with importmaps throughout

Series structure