Skip to main content

​
Requirements

Before installing Phlex, ensure your environment meets these requirements:

Ruby Version: 3.2 or higher requiredCheck your Ruby version:
ruby -v

​
Installation Methods

Add Phlex to your Gemfile:
Gemfile
gem "phlex", "~> 2.4"
Then install:
bundle install
Using a version constraint like "~> 2.4" ensures you get patch updates while avoiding breaking changes.

​
Framework Integration

​
Ruby on Rails

1

Add to Gemfile

Gemfile
gem "phlex", "~> 2.4"
gem "phlex-rails" # Optional: Rails-specific helpers
2

Install dependencies

bundle install
3

Create components directory

mkdir -p app/views/components
4

Configure autoloading

Rails will automatically autoload components from app/views/components in Rails 7+.For earlier versions, add to config/application.rb:
config.autoload_paths << Rails.root.join("app/views/components")
Consider using phlex-rails for Rails-specific features like automatic layout rendering and helper method integration.

​
Sinatra

1

Add to Gemfile

Gemfile
gem "phlex", "~> 2.4"
2

Install

bundle install
3

Require in your app

app.rb
require "sinatra"
require "phlex"

class Layout < Phlex::HTML
  def view_template(&block)
    html do
      head { title { "My Sinatra App" } }
      body(&block)
    end
  end
end

get "/" do
  Layout.new.call do
    h1 { "Hello from Phlex!" }
  end
end

​
Hanami

1

Add to Gemfile

Gemfile
gem "phlex", "~> 2.4"
2

Install

bundle install
3

Create views in slices

slices/main/views/home/index.rb
module Main
  module Views
    module Home
      class Index < Phlex::HTML
        def view_template
          h1 { "Welcome to Hanami with Phlex" }
        end
      end
    end
  end
end

​
Verify Installation

Create a simple test file to verify Phlex is working:
test_phlex.rb
require "phlex"

class HelloWorld < Phlex::HTML
  def view_template
    html do
      head { title { "Test" } }
      body do
        h1 { "Phlex is working!" }
      end
    end
  end
end

puts HelloWorld.call
Run it: 
ruby test_phlex.rb
You should see: 
<html><head><title>Test</title></head><body><h1>Phlex is working!</h1></body></html>
Installation successful! Phlex is ready to use.

​
Dependencies

Phlex automatically installs these dependencies:
Provides efficient autoloading for Phlex’s internal modules and your component classes.Learn more about Zeitwerk
Enables efficient rendering and buffer management for optimal performance.

​
Troubleshooting

Error: required_ruby_version (>= 3.2) not satisfiedSolution: Upgrade Ruby to version 3.2 or higher:
# Using rbenv
rbenv install 3.2.0
rbenv local 3.2.0

# Using rvm
rvm install 3.2.0
rvm use 3.2.0
Error: LoadError: cannot load such file -- phlexSolution: Make sure you’ve run bundle install or the gem is in your load path:
bundle install
# or
gem install phlex
Problem: Components not found or not reloading in developmentSolution: Ensure your components directory is in the autoload path:
config/application.rb
config.autoload_paths << Rails.root.join("app/views/components")

​
Next Steps

Build Your First Component

Now that Phlex is installed, create your first component and learn the core concepts.

Build docs developers (and LLMs) love

Get started for freeTalk to us