Module 02 — Phlex Fundamentals

6 lessons · Phlex core · Standalone sandbox
Pure Phlex. No Rails, no Tailwind, no magic. Just Ruby producing HTML.
Every lesson is a single file you run with ruby filename.rb.

Before we start

This module is about building understanding, not showing off. The code you write here will sometimes feel more verbose than the ERB equivalent — and occasionally it genuinely is. You’ll write plain "By " where ERB would let you just type “By " inline. You’ll write explicit initialize methods with four lines of assignment that a framework might handle in one. You’ll run scripts in a terminal and read raw HTML output instead of seeing a rendered page.

Bear with it.

The reason we start here — with pure Phlex, no Rails, no Tailwind, no shortcuts — is that every shortcut we introduce later only makes sense if you understand what it’s shortcutting. The Components::Base class in Module 3 will eliminate most of the initialize boilerplate. The component library we build in Modules 3–5 will make the “By <strong>Alice</strong>” problem disappear into a well-named helper. The Tailwind theming in Module 7 will make styling feel like a design system rather than a pile of class strings. Module 9 will show you real-time collaborative UI that would take weeks to build any other way.

None of that lands if you haven’t felt the shape of the thing first.

The goal of this module is simple: by the end of it, you should feel comfortable reading and writing Phlex components, and you should understand why they work the way they do. The reward comes later — and it’s worth it.

Setup

You need one thing: the phlex gem.

1
2
3

mkdir phlex-sandbox && cd phlex-sandbox
bundle init
bundle add phlex

That’s it. No Rails. No database. No asset pipeline. Every lesson file starts with:

1
2

require "phlex"
require "date"

Note: the second line here require "date" is only needed in some circumstances. At this stage of our understanding, it’s simplest to always require it. (Needless to say, if you’re using Rails you can ignore both of these require statements).

To see the output of any component, we’ll use a tiny helper at the bottom of each file:

1

puts MyComponent.new.call

call renders the component and returns an HTML string. puts prints it to the terminal.

Note: the .call is not something we’d normally use, but is added here just to allow us to see the output from the terminal.

You can pipe it through a formatter if you like:

1

ruby lesson.rb | tidy -indent -quiet

“If you want to pretty-print the output for easier reading, xmllint --format - works on most systems, or tidy -indent -quiet if you have it installed. Honestly though, for the short fragments in these lessons, the raw output is readable enough.”

tidy — the classic HTML-specific formatter. More forgiving than xmllint because it actually understands HTML5. Install with brew install tidy-html5 on macOS or sudo apt install tidy on Linux:

Or just read the raw output — it’s valid HTML either way.