DEV Community: Jackson Pires

🇺🇸 How I built my Proxmox homelab by talking to Claude

Jackson Pires — Wed, 07 Oct 2026 13:59:52 +0000

One week, a server forgotten in a corner, and not a single line of configuration typed by hand.

I had a mini PC running Proxmox VE. In practice, it was one of those projects you start full of excitement and abandon halfway: installed on an old network, with a 4 TB NVMe full of experiment volumes I no longer remembered, a 1.4 TB USB drive holding an abandoned Bitcoin VM, and a Windows VM I used now and then without really knowing how it was set up.

This time I tried something different. Instead of spending weekends reading forums, mounting disks and editing config files, I decided to do everything by talking to Claude Code. I described what I wanted in plain Portuguese, and it did the rest over SSH: it inspected, planned, executed, tested and documented.

This post is the story of how that went.

Chapter 1: first, understand the house

The first thing Claude did was not change anything. It looked. It logged into the server over SSH and took a full inventory: hardware, Proxmox version, disks, network, VMs and containers. And it stored everything in a place that became the backbone of the project: a knowledge bundle in markdown using the OKF (Open Knowledge Format), one file per topic, versioned alongside everything else. To manage these documents we used the OKF gem, a gem that helps you create, validate and maintain OKF documents. I recommend it to anyone who wants documentation that humans and AI agents read from the same source.

Right away it found six problems I didn't even know I had:

The server couldn't resolve names. DNS still pointed to the old network's router (10.0.0.1), which is why apt update hung.
/etc/hosts claimed the server had an IP address that no longer existed.
The Pi-hole container had a gateway outside its subnet.
Proxmox's enterprise repositories were enabled without a subscription.
And ~3.6 TB of disk sat outside Proxmox, in orphaned volumes.

In one afternoon, DNS and /etc/hosts were fixed, the repositories were switched to the free ones and the system was upgraded (182 packages and a reboot). Every fix was verified and recorded in the bundle, with a dated log.

What struck me: Claude doesn't guess. Before wiping the NVMe, it showed me what was inside each volume (old Docker and Transmission containers, an entire Umbrel VM) and waited for me to say it could all go.

Chapter 2: the disks

With my approval, the 4 TB Kingston NVMe was wiped and turned into a 3.57 TB lvmthin storage called vmdata. All VMs and containers were migrated to it.

The Windows VM put up a fight. After the migration its disk ended up 100% allocated, because discard wasn't enabled. Claude turned it on and tried the normal route (a Windows retrim), which didn't work with that version of the VirtIO driver. Instead of giving up, it did an offline round-trip copy through the other storage, and the disk dropped from 100% to 28.65% usage.

I just watched.

Chapter 3: an Ubuntu VM I could actually use

I had created an Ubuntu 26.04 VM and asked for two things: a static IP and remote desktop access.

The static IP seemed trivial. Claude configured NetworkManager and, while testing, noticed the VM now had two IPs: the installer's config file was still keeping DHCP on underneath. Once fixed, the VM answered only on 192.168.0.103. I picked the 103 ending because that's its ID in Proxmox, which makes it easy to remember.

RDP turned into a little saga:

Claude enabled GNOME's Remote Login. From my Mac, Microsoft's Windows App got stuck on "Securing connection".
Reading the server logs, it found that authentication worked, but during the hand-off to the session, Microsoft's Mac client re-sent the wrong credentials. It's a known bug.
We switched to FreeRDP, which also failed, this time before even leaving the Mac. macOS blocks non-Apple binaries from reaching the local network, and they don't even show up in the permissions list.
The fix was an SSH tunnel: FreeRDP connects to localhost, and the tunnel carries it to the VM.
So I wouldn't have to remember commands, Claude wrote an rdp-ubuntu script (opens the tunnel, pulls the password from the macOS Keychain, connects, and tears everything down on exit) and then an app with an icon in the Applications folder.

Today I click an icon and I'm in Ubuntu.

Chapter 4: the USB drive becomes a torrent server

I asked for the 1.4 TB USB drive to be used only for torrent downloads, with a web interface. The first thing Claude noticed: the drive was plugged into a USB 2.0 port. I moved it, Claude measured the read speed (117 MB/s at the start of the disk), and we moved on.

Here something came up that I wouldn't have planned for on my own: the drive can be unplugged. So the whole design was built around that:

The drive is passed through to the VM as a USB device, not as a disk, so the VM boots even without it.
qBittorrent only runs while the drive is mounted. If the drive goes away, it stops on its own, and nothing is ever written to the system disk.
An ejetar-torrents ("eject torrents") command stops everything safely before you pull the cable.
When the drive is plugged back in, it mounts and qBittorrent comes back by itself.

We tested all of it: a real download with a verified checksum, a simulated unplug, a replug, and booting with and without the drive.

Chapter 5: getting to the files from anywhere

I wanted to upload, download and delete files from the web, and also see the folders directly in the Finder.

For the web, the plan was File Browser. Claude installed it and, when the service started, read the warning the program itself printed: the project had been archived a month earlier, with unpatched security flaws. One of them deleted folders when an upload failed. Claude stopped, explained the risk and offered me three actively maintained alternatives. I chose copyparty, which was validated with a 6 GB upload and download, checksum verified, resume-after-interruption and all.

For the Finder, in came Samba. The server shows up on its own in the Mac's sidebar. And then came the tensest moment of the week: in the middle of the 6 GB copy test, the entire server dropped off the network. I had to power-cycle it with the button.

When it came back, Claude read the logs and found the cause within minutes: the mini PC's Intel I219 network card had hung (Detected Hardware Unit Hang), a known bug in that chip under heavy traffic. The fix was to turn off two of the card's offloads (TSO/GSO). For good measure, it set up a watchdog that resets the card automatically if it ever hangs again. The same 6 GB test then passed without a single hang.

The same day it found another subtle problem: ejetar-torrents sometimes re-mounted the drive on its own right after unmounting it. The cause was an interaction between systemd and fstab, triggered by a timer that runs every 10 minutes. One option (noauto) fixed it for good.

Chapter 6: one dashboard to see it all

To wrap up the server side, I asked for a dashboard. Claude installed Glance at http://192.168.0.103, no port needed:

icons and status for every service;
disk usage, CPU and RAM for the VM;
torrent speeds;
a summary of the Proxmox host, with CPU, RAM and the state of each VM, read through a read-only token. It tested that the token can't shut anything down.

In the test with the drive ejected, the dashboard showed "13 GB of 128 GB" for the USB drive. It was reading the empty folder on the system disk. Claude didn't accept the wrong number: it wrote a small collector that reports the real state, and now the dashboard shows "● HD desconectado" ("drive disconnected") when that's the case.

The method behind the magic

Looking back, what made this work wasn't Claude "knowing Linux". It was the way of working:

Plan before executing. Every larger task started with a plan saved in plan/yyyy-mm-dd.md, with decisions, reasons and a checkbox for each phase. I approved it and followed progress there.
Test everything, for real. Nothing was called done without a test: checksums on 6 GB files, simulated unplugs, reboots with and without the drive.
Documentation as code. The knowledge bundle (configuration/), in OKF format, is updated with every change and validated automatically with the OKF gem, which checks the documents' structure and flags broken links and stale indexes. Any future session starts out knowing what has already been done.
Ask before anything irreversible. Wiping a disk, formatting the drive, deleting files: always with the exact list of what would be affected and my confirmation. When a request of mine was ambiguous and matched more than one thing, it asked which one before deleting.
Secrets stay out of the chat. Passwords were generated and stored in the Mac's Keychain, and handed to services without ever appearing on screen.

What went wrong (and why it gave me more confidence)

It wasn't all perfect, and I think this is the most important part of the post:

The server outage was caused by one of Claude's own tests. The difference is that it diagnosed, fixed and hardened against the problem right after.
It got dates wrong in the documentation once and corrected them when it noticed.
A hasty conclusion: the first time the drive re-mounted itself right after being ejected, Claude put it down to a side effect of the previous test, because it couldn't reproduce it. When it happened again, it went back to it on its own, admitted the explanation had been wrong, cross-checked the timestamps against the logs and found the real cause (the 10-minute timer and fstab). Its first method for simulating a drive unplug also didn't actually work; it noticed and switched to one that did.
Early on, I pasted a password into the chat. Claude used it, but recommended I change it. I did, and since then everything goes through the Keychain.

An assistant that never makes mistakes is one I'd have no way to evaluate. One that finds its own mistakes, explains them and documents how to avoid them is one I'll let touch my server.

By the numbers

1 server cleaned up: DNS, repositories, upgrade, and 4 TB of NVMe reclaimed.
6 new services on the Ubuntu VM (RDP, qBittorrent, copyparty, Samba, Glance and the dashboard's status collector), plus the network-card watchdog on the host.
3 hardware and software problems I didn't know about: the USB 2.0 port, the network card that hung, and the drive's phantom re-mount.
1 documentation bundle, 4 execution plans, and zero config files edited by me.

Conclusion

I didn't stop understanding my server. Quite the opposite: today it's better documented than anything I've ever set up on my own. The difference is that I spent the week deciding what I wanted, not fighting over how to do it.

If you have a homelab gathering dust for lack of time, my advice is: open a terminal, connect Claude to your server, and start by asking it to look and document before changing anything. The rest comes from the conversation.

🇧🇷 Como montei meu homelab Proxmox conversando com o Claude

Jackson Pires — Wed, 07 Oct 2026 13:56:19 +0000

Uma semana, um servidor esquecido num canto e nenhuma linha de configuração digitada à mão.

Eu tinha um mini PC rodando Proxmox VE. Na prática, ele era um daqueles projetos que a gente começa empolgado e larga pela metade: instalado numa rede antiga, com um NVMe de 4 TB cheio de volumes de experimentos que eu nem lembrava mais, um HD USB de 1,4 TB guardando uma VM de Bitcoin abandonada e uma VM do Windows que eu usava de vez em quando, sem saber direito como estava configurada.

A ideia desta vez foi diferente. Em vez de passar fins de semana lendo fóruns, montando discos e editando arquivos de configuração, resolvi fazer tudo conversando com o Claude Code. Eu descrevia o que queria em português, e ele fazia o resto por SSH: inspecionava, planejava, executava, testava e documentava.

Este post conta como foi.

Capítulo 1: primeiro, entender a casa

A primeira coisa que o Claude fez não foi mudar nada. Foi olhar. Entrou no servidor por SSH e fez um inventário completo: hardware, versão do Proxmox, discos, rede, VMs e containers. E guardou tudo num lugar que virou a espinha dorsal do projeto: um bundle de conhecimento em markdown no formato OKF (Open Knowledge Format), com um arquivo por assunto, versionado junto com o resto. Para gerenciar esses documentos usamos a OKF gem, uma gem que ajuda a criar, validar e manter documentos OKF. Recomendo o uso para quem quer uma documentação que humanos e agentes de IA leiam da mesma fonte.

Logo de cara ele achou seis problemas que eu nem sabia que tinha:

O servidor não resolvia nomes. O DNS ainda apontava para o roteador da rede antiga (10.0.0.1), e por isso o apt update travava.
O /etc/hosts dizia que o servidor tinha um IP que não existia mais.
O container do Pi-hole tinha um gateway fora da sub-rede.
Os repositórios enterprise do Proxmox estavam ativos sem assinatura.
E ~3,6 TB de disco estavam fora do Proxmox, em volumes órfãos.

Em uma tarde, o DNS e o /etc/hosts foram corrigidos, os repositórios trocados pelos gratuitos e o sistema atualizado (182 pacotes e um reboot). Cada correção foi conferida e registrada no bundle, com um log datado.

O que me chamou atenção: o Claude não "chuta". Antes de apagar o NVMe, ele me mostrou o que havia dentro de cada volume (containers antigos de Docker e Transmission, uma VM Umbrel inteira) e esperou eu dizer que podia descartar.

Capítulo 2: os discos

Com a minha autorização, o NVMe Kingston de 4 TB foi apagado e virou um storage lvmthin de 3,57 TB chamado vmdata. Todas as VMs e containers foram migrados para ele.

A VM do Windows deu trabalho. Depois da migração, o disco dela ficou 100% alocado, porque não tinha discard habilitado. O Claude ativou o recurso e tentou o caminho normal (o retrim do Windows), que não funcionou com aquela versão do driver VirtIO. Em vez de desistir, ele fez uma cópia offline de ida e volta pelo outro storage, e o disco caiu de 100% para 28,65% de ocupação.

Eu só acompanhei.

Capítulo 3: uma VM Ubuntu que eu pudesse usar de verdade

Eu tinha criado uma VM com Ubuntu 26.04 e pedi duas coisas: IP fixo e acesso remoto pela área de trabalho.

O IP fixo parecia trivial. O Claude configurou o NetworkManager e, ao testar, percebeu que a VM tinha ficado com dois IPs: o arquivo do instalador mantinha o DHCP ligado por baixo. Corrigido, a VM passou a responder só no 192.168.0.103. Escolhi o final 103 porque é o ID dela no Proxmox, e assim fica fácil lembrar.

O RDP foi uma pequena saga:

O Claude ativou o Login Remoto do GNOME. Do meu Mac, o Windows App da Microsoft ficava travado em "Securing connection".
Lendo os logs do servidor, ele descobriu que a autenticação funcionava, mas, no redirecionamento para a sessão, o cliente da Microsoft no Mac reenviava as credenciais erradas. É um bug conhecido.
Trocamos para o FreeRDP, que também falhou, desta vez antes de sair do Mac. O macOS bloqueia binários fora da Apple de acessar a rede local, e eles nem aparecem na lista de permissões.
A solução foi um túnel SSH: o FreeRDP conecta em localhost, e o túnel leva até a VM.
Para não depender de comando, o Claude criou um script rdp-ubuntu (abre o túnel, busca a senha no Chaveiro do macOS, conecta e fecha tudo ao sair) e depois um app com ícone na pasta Aplicativos.

Hoje eu clico num ícone e estou no Ubuntu.

Capítulo 4: o HD USB vira servidor de torrents

Pedi que o HD USB de 1,4 TB fosse usado só para downloads de torrent, com interface web. A primeira coisa que o Claude notou: o HD estava numa porta USB 2.0. Troquei de porta, ele mediu a leitura (117 MB/s no início do disco) e seguimos.

Aqui apareceu algo que eu não teria planejado sozinho: o HD pode ser desplugado. Então o desenho inteiro foi pensado para isso:

O HD é repassado para a VM como dispositivo USB, e não como disco. Assim a VM liga mesmo sem ele.
O qBittorrent só roda com o HD montado. Se o HD sai, ele para sozinho, e nada é gravado no disco do sistema.
Um comando ejetar-torrents para tudo com segurança antes de tirar o cabo.
Ao replugar, o HD monta e o qBittorrent volta sozinho.

Testamos tudo: download real com checksum conferido, desplugue simulado, replugue e boot com e sem o HD.

Capítulo 5: acessar os arquivos de qualquer jeito

Eu queria enviar, baixar e apagar arquivos pela web e também ver as pastas direto no Finder.

Pela web, o plano era o File Browser. O Claude instalou e, ao subir o serviço, leu o aviso que o próprio programa imprimia: o projeto tinha sido arquivado um mês antes, com falhas de segurança sem correção. Uma delas apagava pastas quando um upload falhava. Ele parou, me explicou o risco e me deu três alternativas ativas. Escolhi o copyparty, que foi validado com um upload e um download de 6 GB, checksum conferido, retomada no meio e tudo.

No Finder, entrou o Samba. O servidor aparece sozinho na barra lateral do Mac. E aí veio o momento mais tenso da semana: no meio do teste de cópia de 6 GB, o servidor inteiro sumiu da rede. Tive que desligar e ligar no botão.

Quando ele voltou, o Claude leu os logs e achou a causa em minutos: a placa de rede Intel I219 do mini PC tinha travado (Detected Hardware Unit Hang), um bug conhecido desse chip sob tráfego pesado. A correção foi desligar duas otimizações da placa (TSO/GSO). Para garantir, ele criou um vigia que reseta a placa sozinho se ela travar de novo. O mesmo teste de 6 GB passou depois sem nenhum travamento.

No mesmo dia ele achou mais um problema sutil: o ejetar-torrents às vezes remontava o HD sozinho logo depois de desmontar. A causa era uma interação do systemd com o fstab, disparada por um timer que roda a cada 10 minutos. Uma opção (noauto) resolveu de vez.

Capítulo 6: um painel para ver tudo

Para fechar a parte do servidor, pedi um dashboard. O Claude instalou o Glance em http://192.168.0.103, sem porta:

ícones e status de cada serviço;
ocupação dos discos, CPU e RAM da VM;
velocidade dos torrents;
um resumo do host Proxmox, com CPU, RAM e estado de cada VM, lido por um token só de leitura. Ele testou que o token não consegue desligar nada.

No teste com o HD ejetado, o painel mostrou "13 GB de 128 GB" no lugar do HD. Estava lendo a pasta vazia no disco do sistema. O Claude não aceitou o número errado: criou um pequeno coletor que informa o estado real, e agora o painel mostra "● HD desconectado" quando é o caso.

O método por trás da mágica

Olhando para trás, o que fez isso funcionar não foi o Claude "saber Linux". Foi o jeito de trabalhar:

Planejar antes de executar. Toda tarefa maior começava com um plano gravado em plan/aaaa-mm-dd.md, com decisões, motivos e caixinhas de cada fase. Eu aprovava e acompanhava o andamento ali.
Testar tudo, de verdade. Nada era dado como pronto sem teste: checksums de arquivos de 6 GB, desplugues simulados, reinícios com e sem o HD.
Documentar como código. O bundle de conhecimento (configuration/), no formato OKF, é atualizado a cada mudança e validado automaticamente com a OKF gem, que confere a estrutura dos documentos e aponta links quebrados e índices desatualizados. Qualquer sessão futura começa sabendo o que já foi feito.
Perguntar antes do irreversível. Apagar um disco, formatar o HD, remover arquivos: sempre com a lista exata do que seria afetado e a minha confirmação. Quando um pedido meu era ambíguo e casava com mais de uma coisa, ele perguntava qual antes de apagar.
Segredos fora da conversa. Senhas geradas e guardadas no Chaveiro do Mac, passadas aos serviços sem aparecer na tela.

O que deu errado (e por que isso me deu mais confiança)

Não foi tudo perfeito, e eu acho que essa é a parte mais importante deste post:

A queda do servidor foi provocada por um teste do próprio Claude. A diferença é que ele diagnosticou, corrigiu e blindou o problema em seguida.
Ele errou datas na documentação uma vez e corrigiu ao perceber.
Uma conclusão apressada: a primeira vez que o HD remontou sozinho logo depois de ejetar, o Claude atribuiu o caso a um efeito colateral do teste anterior, porque não conseguiu reproduzir. Quando aconteceu de novo, ele mesmo voltou ao assunto, admitiu que a explicação estava errada, cruzou os horários com os logs e achou a causa real (o timer de 10 minutos e o fstab). O primeiro método dele para simular o desplugue do HD também não funcionava, e ele percebeu e trocou por um que funcionava.
No começo eu colei uma senha na conversa. O Claude usou, mas recomendou trocá-la. Troquei, e desde então tudo passa pelo Chaveiro.

Um assistente que nunca erra eu não teria como avaliar. Um que encontra os próprios erros, explica e documenta como evitar é um que eu deixo mexer no meu servidor.

Em números

1 servidor saneado: DNS, repositórios, atualização e 4 TB de NVMe recuperados.
6 serviços novos na VM Ubuntu (RDP, qBittorrent, copyparty, Samba, Glance e o coletor de status do painel), mais o vigia da placa de rede no host.
3 problemas de hardware e software que eu não conhecia: a porta USB 2.0, a placa de rede que travava e a remontagem fantasma do HD.
1 bundle de documentação, 4 planos de execução e zero arquivos de configuração editados por mim.

Conclusão

Eu não deixei de entender o meu servidor. Pelo contrário: hoje ele está mais bem documentado do que qualquer coisa que eu já montei sozinho. A diferença é que eu passei a semana decidindo o que queria, e não brigando com como fazer.

Se você tem um homelab parado por falta de tempo, a minha dica é: abra um terminal, conecte o Claude ao seu servidor e comece pedindo para ele olhar e documentar antes de mudar qualquer coisa. O resto vem conversando.

🇺🇸 Why You Should Adopt RubyUI in Your Rails Projects (and How Three Gems Can Accelerate Your Journey)

Jackson Pires — Sat, 25 Jul 2026 23:31:11 +0000

Over the past few years, the Ruby on Rails ecosystem has seen a resurgence of server-side UI development. Thanks to projects like Phlex, Hotwire, and RubyUI, it's now possible to build modern, responsive, and highly productive applications without relying on large JavaScript frameworks.

RubyUI provides a beautiful collection of components built on top of Phlex and Tailwind CSS, offering an experience similar to what shadcn/ui brought to the React ecosystem—but fully embracing the Rails way.

Like any relatively new technology, however, adopting RubyUI comes with a learning curve. You need to understand how components work, learn their APIs, and discover the best patterns for building real-world applications.

That's exactly why I created three open-source gems:

ruby_ui_converter
ruby_ui_scaffold
ruby_ui_admin

Each one solves a different problem, and together they make adopting RubyUI significantly easier.

Why Choose RubyUI?

There are many reasons to adopt RubyUI in your next Rails project.

Ruby-first Components

Instead of maintaining large ERB templates filled with HTML, you build your UI using Ruby components, making your codebase cleaner, easier to maintain, and more reusable.

Better Organization

Each component has a single responsibility, making your application easier to understand, test, and evolve over time.

Seamless Hotwire Integration

RubyUI was designed to work naturally with Hotwire and Stimulus, allowing you to build highly interactive interfaces while keeping rendering on the server.

Modern Design

RubyUI ships with a polished set of components, so you can create professional-looking applications without reinventing common UI elements.

Faster Development

Once you're familiar with the ecosystem, building new screens becomes dramatically faster than writing everything manually.

The Real Challenge Isn't Installing RubyUI

Installing RubyUI only takes a few minutes.

The real challenge starts when you begin building an actual application.

Questions like these quickly appear:

How do I migrate my existing views?
What's the best way to structure components?
How do I build a complete CRUD interface?
How can I create an admin panel?

These three gems were built to answer exactly those questions.

ruby_ui_converter

GitHub:

https://github.com/jacksonpires/ruby_ui_converter

One of the biggest obstacles when adopting RubyUI is migrating an existing Rails application.

Most projects already contain hundreds—or even thousands—of .erb templates.

Rewriting every view manually would be incredibly time-consuming.

That's where ruby_ui_converter comes in.

Instead of converting HTML, the gem converts existing ERB templates into RubyUI components, dramatically reducing the amount of repetitive work involved in migrating a project.

If you're modernizing an existing Rails application, this tool can save you countless hours.

ruby_ui_scaffold

GitHub:

https://github.com/jacksonpires/ruby_ui_scaffold

Once you've learned the basics of RubyUI, another question naturally arises:

How do I build a complete application with it?

Most examples available online showcase individual components.

Real-world applications, however, need much more:

resource listings;
forms;
pagination;
filters;
navigation;
full CRUD operations.

That's exactly what ruby_ui_scaffold provides.

It generates complete CRUD interfaces using RubyUI, giving you both a solid starting point for new projects and practical examples of how components work together.

Whether you're learning RubyUI or bootstrapping a new application, it can significantly increase your productivity.

ruby_ui_admin

GitHub:

https://github.com/jacksonpires/ruby_ui_admin

After generating a few CRUDs, another need usually emerges:

What if there were an admin interface built entirely on top of RubyUI?

That question led to the creation of ruby_ui_admin.

The goal is simple: provide a modern administrative foundation built with RubyUI.

Instead of recreating the same infrastructure for every project, you get a ready-to-use admin layout that includes elements such as:

admin layout;
sidebar;
header;
navigation;
common pages;
reusable UI components.

This allows you to focus on your application's business logic instead of rebuilding the same administrative interface over and over again.

Three Gems, One Ecosystem

Although each gem addresses a different challenge, they complement one another perfectly.

A typical workflow might look like this:

Use ruby_ui_converter to migrate existing ERB templates.
Generate new CRUD interfaces with ruby_ui_scaffold.
Organize everything inside an admin dashboard powered by ruby_ui_admin.

Together, they dramatically reduce the time required to start and scale a RubyUI-based Rails application.

Spend Less Time Learning, More Time Building

Every new library comes with a learning curve.

You have to read documentation, understand component APIs, and experiment with different patterns before becoming productive.

These gems shorten that journey.

Instead of starting from a blank page every time, you work with practical examples, reusable structures, and tools that automate repetitive tasks.

The result is a much smoother adoption of RubyUI and a far more enjoyable development experience.

Final Thoughts

RubyUI is quickly becoming one of the most exciting options for building modern user interfaces in Ruby on Rails with Phlex and Hotwire.

The ruby_ui_converter, ruby_ui_scaffold, and ruby_ui_admin gems were created to make that journey even easier.

Each one solves a specific challenge:

ruby_ui_converter helps migrate existing ERB templates into RubyUI components.
ruby_ui_scaffold accelerates CRUD development while serving as a learning tool.
ruby_ui_admin provides a ready-made foundation for modern administrative interfaces.

If you're planning to adopt RubyUI in your next Rails project, these three gems can save you many hours of repetitive work and help you unlock the full potential of the RubyUI ecosystem from day one.

GitHub Repositories

ruby_ui_converter — https://github.com/jacksonpires/ruby_ui_converter
ruby_ui_scaffold — https://github.com/jacksonpires/ruby_ui_scaffold
ruby_ui_admin — https://github.com/jacksonpires/ruby_ui_admin

🇧🇷 Por que adotar RubyUI em seus projetos Rails (e como três gems podem acelerar essa jornada)

Jackson Pires — Sat, 25 Jul 2026 23:30:06 +0000

Nos últimos anos, o ecossistema Ruby on Rails voltou a mostrar toda a sua força no desenvolvimento de interfaces server-side. Com ferramentas como Phlex, Hotwire e RubyUI, tornou-se possível criar aplicações modernas, reativas e altamente produtivas sem depender de frameworks JavaScript complexos.

O RubyUI oferece uma biblioteca de componentes construída sobre Phlex e Tailwind CSS, proporcionando uma experiência semelhante ao que o shadcn/ui representa para o ecossistema React, mas totalmente integrada à filosofia do Rails.

Entretanto, como toda tecnologia relativamente nova, existe uma curva de aprendizado. É preciso entender como os componentes funcionam, aprender sua API e descobrir boas práticas para estruturar aplicações reais.

Foi justamente pensando nesses desafios que nasceram três gems open source:

ruby_ui_converter
ruby_ui_scaffold
ruby_ui_admin

Cada uma resolve um problema específico e, juntas, tornam a adoção do RubyUI muito mais simples.

Por que escolher RubyUI?

Existem vários motivos para adotar RubyUI em uma aplicação Rails.

Componentes escritos em Ruby

Ao invés de misturar grandes blocos de HTML e ERB, você passa a construir interfaces utilizando componentes Ruby, tornando o código muito mais organizado e reutilizável.

Melhor organização

Cada componente possui sua própria responsabilidade, facilitando manutenção, testes e evolução da aplicação.

Excelente integração com Hotwire

RubyUI foi pensado para trabalhar em conjunto com Hotwire e Stimulus, permitindo criar interfaces extremamente responsivas sem abrir mão da renderização server-side.

Interface moderna

Você obtém componentes com aparência moderna e consistente sem precisar construir tudo do zero.

Produtividade

Depois que você domina o ecossistema, criar novas telas passa a ser significativamente mais rápido do que construir toda a interface manualmente.

O verdadeiro desafio não é usar RubyUI

Na prática, instalar RubyUI leva apenas alguns minutos.

O desafio aparece quando você começa a desenvolver uma aplicação real.

Perguntas como estas são bastante comuns:

Como converter telas existentes?
Como escrever componentes corretamente?
Como montar um CRUD completo?
Como construir um painel administrativo?

Foi exatamente para responder essas perguntas que essas três gems foram criadas.

ruby_ui_converter

GitHub:

https://github.com/jacksonpires/ruby_ui_converter

Uma das maiores dificuldades ao adotar RubyUI é migrar aplicações Rails já existentes.

Normalmente elas possuem centenas (ou milhares) de templates .erb.

Reescrever tudo manualmente seria um trabalho enorme.

O ruby_ui_converter nasceu justamente para reduzir esse esforço.

A gem converte templates ERB em componentes RubyUI, acelerando o processo de migração e eliminando boa parte do trabalho repetitivo.

Isso é especialmente útil quando você deseja modernizar uma aplicação sem precisar reescrever cada tela manualmente.

ruby_ui_scaffold

GitHub:

https://github.com/jacksonpires/ruby_ui_scaffold

Depois de aprender alguns componentes, surge uma nova necessidade:

Como construir uma aplicação inteira utilizando RubyUI?

A maioria dos exemplos disponíveis mostra apenas componentes isolados.

Na prática, aplicações possuem:

listagens;
formulários;
paginação;
filtros;
navegação;
ações CRUD.

O ruby_ui_scaffold gera exatamente esse tipo de estrutura.

Em poucos minutos você possui um CRUD completo utilizando RubyUI, seguindo boas práticas e servindo como excelente material de estudo.

Além de acelerar novos projetos, ele também ajuda quem está aprendendo a entender como os componentes trabalham em conjunto.

ruby_ui_admin

GitHub:

https://github.com/jacksonpires/ruby_ui_admin

Depois de criar alguns CRUDs, normalmente surge outra necessidade:

E se existisse um painel administrativo inteiro baseado em RubyUI?

Foi dessa ideia que nasceu o ruby_ui_admin.

A proposta é fornecer uma base moderna para aplicações administrativas utilizando RubyUI.

Em vez de começar cada projeto do zero, você passa a contar com uma estrutura pronta contendo elementos como:

layout administrativo;
sidebar;
header;
navegação;
páginas padrão;
componentes reutilizáveis.

Assim, você pode concentrar seus esforços na regra de negócio da aplicação, em vez de gastar tempo recriando a infraestrutura visual de cada projeto.

Um ecossistema pensado para trabalhar em conjunto

Embora cada gem resolva um problema diferente, elas se complementam perfeitamente.

Um fluxo bastante natural seria:

Utilizar o ruby_ui_converter para migrar templates ERB existentes.
Gerar novos CRUDs utilizando o ruby_ui_scaffold.
Organizar toda a aplicação dentro de um painel administrativo criado com o ruby_ui_admin.

Esse fluxo reduz significativamente o tempo necessário para iniciar um novo projeto utilizando RubyUI.

Menos tempo aprendendo, mais tempo construindo

Aprender uma nova biblioteca sempre exige investimento.

Você precisa entender a documentação, conhecer os componentes e descobrir quais padrões funcionam melhor.

Essas três gems reduzem bastante essa curva de aprendizado.

Em vez de começar sempre do zero, você passa a trabalhar com exemplos reais, estruturas prontas e ferramentas que automatizam tarefas repetitivas.

O resultado é uma adoção muito mais rápida do RubyUI e uma experiência de desenvolvimento muito mais produtiva.

Conclusão

RubyUI vem se consolidando como uma excelente opção para quem deseja construir interfaces modernas utilizando Ruby on Rails, Phlex e Hotwire.

As gems ruby_ui_converter, ruby_ui_scaffold e ruby_ui_admin surgiram para facilitar ainda mais essa jornada.

Cada uma resolve um problema específico:

ruby_ui_converter ajuda na migração de templates ERB para componentes RubyUI.
ruby_ui_scaffold acelera a criação de CRUDs completos e serve como ferramenta de aprendizado.
ruby_ui_admin oferece uma base pronta para construção de painéis administrativos modernos.

Se você pretende adotar RubyUI em seus próximos projetos, essas três gems podem economizar muitas horas de trabalho e permitir que você aproveite todo o potencial desse ecossistema desde o primeiro dia.

Repositórios

ruby_ui_converter — https://github.com/jacksonpires/ruby_ui_converter
ruby_ui_scaffold — https://github.com/jacksonpires/ruby_ui_scaffold
ruby_ui_admin — https://github.com/jacksonpires/ruby_ui_admin

🇺🇸 What if there was an admin interface built on top of RubyUI? That's how RubyUI Admin was born.

Jackson Pires — Fri, 17 Jul 2026 23:53:27 +0000

We're living in an exciting time for software development.

With AI, generating code, exploring ideas, and building new projects has never been easier. The old excuse of "that would take too much time" doesn't really hold anymore.

If there's a tool you've always wanted but it doesn't exist yet, this is probably the best time to build it.

That's exactly how RubyUI Admin came to life.

https://github.com/jacksonpires/ruby_ui_admin/

For quite some time I've admired projects like Avo and the developer experience they provide for building Rails admin interfaces. At the same time, I was using RubyUI, powered by Phlex, more and more in my own applications.

Eventually a simple question came to mind:

What if there was an admin dashboard entirely built with RubyUI?

Instead of waiting for someone else to build it, I decided to create it myself.

What is RubyUI Admin?

RubyUI Admin is a Rails engine that turns your Active Record models into a complete administration panel.

With very little configuration, you get:

Complete CRUD
Pagination
Filters
Named scopes
Dashboards
Custom actions
Bulk actions
Authorization
Built-in i18n (English and Brazilian Portuguese)

Everything is rendered server-side using RubyUI + Phlex, with progressive enhancements powered by Hotwire (Turbo + Stimulus).

Your admin becomes part of your application

One of the project's main architectural decisions was to avoid creating yet another isolated UI framework.

Instead, RubyUI Admin renders your application's own RubyUI components.

That means:

the admin follows your application's design system;
changes to your components are immediately reflected in the admin;
there's no duplicated UI library to maintain.

The result is an administration panel that truly feels like part of your application.

Server-rendered by default

Following the philosophy that has always made Rails productive, RubyUI Admin embraces server-side rendering.

JavaScript is only there to enhance the experience.

Everything continues to work even without JavaScript.

Turbo and Stimulus simply improve interactions like:

dialogs
notifications
tabs
clickable rows
small interface enhancements

Documentation inside your application

One feature I'm particularly proud of is the built-in documentation.

After mounting the engine, simply visit:

/admin/docs

The gem serves its own documentation as HTML directly inside your application.

No need to leave your admin panel or search through external documentation while you're developing.

It's enabled by default during development and can also be exposed in production behind your application's authentication.

Current features

RubyUI Admin already includes:

Full CRUD
Configurable resources
Rich field catalog
Pagination
Filters
Named scopes
Dashboards
Metric cards
Custom actions
Bulk actions
Authorization with Action Policy
Internationalization
Multiple generators
Ruby-based customization

And it's still growing.

Future versions are expected to include advanced association management and additional index view types.

Project philosophy

A few principles guided the project from day one.

Everything is Ruby

Resources, policies, filters, dashboards, and actions are just Ruby classes.

Nothing is hidden behind magic.

Whenever you need to customize something, you simply extend or override it.

Progressive enhancement

The primary goal is to deliver a fully functional application before adding JavaScript.

This keeps the project robust, maintainable, and closely aligned with modern Rails philosophy.

One Design System

Since the admin uses your own RubyUI components, your application maintains a single source of truth for its UI.

Buttons, dialogs, tables, cards, and every other component are shared across both your application and your admin interface.

Getting started

Installing RubyUI Admin is straightforward.

gem "ruby_ui_admin"

Then mount the engine:

mount_ruby_ui_admin at: "/admin"

Configure authentication and authorization, create your resources, and you're ready to go.

Just getting started

RubyUI Admin is already usable today, but this is only the beginning.

My goal is to build a modern admin solution for Rails applications using RubyUI, while staying true to the Rails, Hotwire, and Phlex ecosystem.

If you're already using RubyUI, I'd love for you to give it a try.

Feedback, issues, ideas, and contributions are always welcome.

I hope this is only the beginning.

A special thanks to Ítalo Moura for helping me test the gem.

🇧🇷 E se existisse uma interface admin baseada na RubyUI? Assim nasceu a RubyUI Admin.

Jackson Pires — Fri, 17 Jul 2026 23:51:35 +0000

Vivemos um momento curioso no desenvolvimento de software.

Com IA, gerar código, estruturar projetos e até explorar novas ideias nunca foi tão rápido. Aquela desculpa de "isso daria muito trabalho" simplesmente deixou de existir. Se existe uma ferramenta que você gostaria de usar e ela ainda não existe, talvez este seja o melhor momento para criá-la.

Foi exatamente assim que nasceu a RubyUI Admin.

https://github.com/jacksonpires/ruby_ui_admin/

Durante algum tempo acompanhei projetos como o Avo e sempre gostei da experiência de construir interfaces administrativas modernas para aplicações Rails. Ao mesmo tempo, comecei a utilizar cada vez mais a RubyUI, baseada em Phlex, para desenvolver interfaces server-side utilizando componentes Ruby.

Então surgiu a pergunta:

E se existisse uma interface administrativa totalmente construída sobre a RubyUI?

A resposta foi criar a minha própria.

O que é a RubyUI Admin?

A RubyUI Admin é uma engine para Ruby on Rails que transforma seus modelos Active Record em uma interface administrativa completa.

Com poucos arquivos você já possui:

CRUD completo
Paginação
Filtros
Scopes
Dashboards
Ações customizadas
Ações em lote
Autorização
Internacionalização (EN e PT-BR)

Tudo isso renderizado no servidor utilizando RubyUI + Phlex, com melhorias progressivas através de Hotwire (Turbo + Stimulus).

A interface faz parte da sua aplicação

Uma das decisões de arquitetura mais importantes do projeto foi não criar mais um framework visual isolado.

Em vez disso, a RubyUI Admin utiliza os próprios componentes RubyUI da aplicação hospedeira.

Isso significa que:

o admin acompanha o mesmo Design System da aplicação;
qualquer customização feita em um componente é refletida automaticamente no admin;
não existe uma cópia dos componentes para manter sincronizada.

Na prática, o painel administrativo deixa de parecer um produto separado e passa a fazer parte da aplicação.

Server-side first

Assim como Rails sempre incentivou, a RubyUI Admin aposta em renderização no servidor.

JavaScript existe apenas para melhorar a experiência.

Sem JavaScript a aplicação continua funcionando normalmente.

Turbo e Stimulus entram apenas para tornar algumas interações mais agradáveis, como:

modais;
notificações;
abas;
linhas clicáveis;
pequenas interações da interface.

Documentação dentro da própria aplicação

Uma funcionalidade que gosto bastante é que a própria gem serve sua documentação.

Depois de montar a engine, basta acessar:

/admin/docs

Toda a documentação é renderizada como HTML dentro da própria aplicação.

Isso significa que você pode consultar exemplos sem precisar abrir outra aba do navegador.

Durante o desenvolvimento ela já vem habilitada e, se desejar, também pode ser disponibilizada em produção protegida pela autenticação da aplicação.

Recursos disponíveis

Hoje a RubyUI Admin já oferece:

CRUD completo
Recursos configuráveis
Catálogo completo de campos
Paginação
Filtros
Scopes
Dashboards
Cards de métricas
Ações customizadas
Ações em lote
Policies utilizando Action Policy
Internacionalização
Diversos generators
Customização através de classes Ruby

E o projeto continua evoluindo.

Algumas funcionalidades planejadas para versões futuras incluem gerenciamento avançado de associações e novos formatos de visualização.

Filosofia do projeto

Desde o início alguns princípios guiaram o desenvolvimento.

Tudo é Ruby

Recursos, policies, filtros, dashboards e ações são apenas classes Ruby.

Nada fica escondido.

Quando você precisar personalizar algum comportamento, basta sobrescrever ou estender o que desejar.

Progressivamente aprimorado

O foco sempre foi entregar uma aplicação funcional antes de adicionar JavaScript.

Essa abordagem deixa a aplicação mais robusta, simples de manter e muito alinhada com a filosofia atual do Rails.

Sem reinventar seu Design System

Ao utilizar RubyUI, a aplicação inteira compartilha os mesmos componentes.

Você mantém apenas uma implementação de botões, tabelas, diálogos, cards e demais elementos visuais.

Instalação

Adicionar a gem é bastante simples.

gem "ruby_ui_admin"

Depois monte a engine:

mount_ruby_ui_admin at: "/admin"

Configure a autenticação e autorização e você já pode começar a criar seus recursos.

Ainda está no começo

Apesar de já ser perfeitamente utilizável, a RubyUI Admin ainda está em evolução.

Meu objetivo é construir uma alternativa moderna para aplicações Rails que utilizam RubyUI, mantendo toda a experiência alinhada ao ecossistema Rails, Hotwire e Phlex.

Se você utiliza RubyUI, acredito que vale a pena experimentar.

Toda contribuição, feedback e sugestões são muito bem-vindos.

Espero que esse seja apenas o começo.

Um agradecimento especial a Ítalo Moura que me ajudou com os testes da gem.

🇧🇷 Continuando a jornada com RubyUI: apresentando o ruby_ui_converter

Jackson Pires — Sun, 14 Jun 2026 19:09:05 +0000

Recentemente publiquei uma gem chamada ruby_ui_scaffold, um gerador de scaffolds para Rails pensado para quem quer construir aplicações modernas utilizando Phlex e RubyUI desde o início do projeto.

A proposta dela era bastante simples:

Em vez de usar o scaffold tradicional do Rails gerando views em .erb, a ideia era criar aplicações já preparadas para uma arquitetura baseada em componentes Ruby, utilizando Phlex e os componentes do RubyUI.

Mas logo percebi uma questão importante.

E quem já possui uma aplicação Rails existente?

O problema das aplicações legadas

O ruby_ui_scaffold resolve muito bem o cenário de novos projetos.

Com ele, você consegue gerar CRUDs completos com controllers, formulários, tabelas, componentes visuais e toda a estrutura baseada em Phlex desde o primeiro dia.

Mas a realidade é que grande parte da comunidade Rails trabalha em aplicações já existentes.

Aplicações que possuem anos de evolução e centenas de arquivos como estes:

app/views/products/index.html.erb
app/views/users/show.html.erb
app/views/orders/_form.html.erb

E nesse cenário surge uma pergunta natural:

Como migrar uma aplicação já existente para Phlex + RubyUI sem precisar reescrever manualmente toda a camada de views?

Foi exatamente essa pergunta que me levou a criar a próxima gem dessa jornada.

Apresentando o ruby_ui_converter

https://github.com/jacksonpires/ruby_ui_converter

Se o ruby_ui_scaffold foi criado para ajudar no desenvolvimento de novas aplicações Rails, o ruby_ui_converter nasce como sua continuação natural.

A proposta é simples:

Permitir que aplicações Rails já existentes possam migrar gradualmente seus templates .erb para componentes baseados em Phlex e RubyUI.

Em outras palavras:

ruby_ui_scaffold → cria aplicações novas já utilizando a stack moderna
ruby_ui_converter → ajuda aplicações existentes a fazer essa transição

Transformando ERB em componentes Ruby automaticamente

A gem percorre uma pasta de views Rails e converte automaticamente arquivos .erb em componentes Ruby.

Exemplo:

bundle exec ruby_ui_converter convert app/views/users

Resultado:

app/views/users/index.html.erb → app/views/users/index.rb
app/views/users/_user.html.erb → app/views/users/user.rb

A ideia é eliminar o trabalho repetitivo que normalmente existiria nesse processo de migração.

Conversão inteligente para Phlex e RubyUI

O objetivo não era simplesmente transformar HTML em Ruby.

A gem entende padrões comuns do Rails e gera código compatível com Phlex e com componentes RubyUI.

Por exemplo:

Um template tradicional:

<%= link_to "Dashboard", dashboard_path %>

vira automaticamente:

Link(href: dashboard_path) { "Dashboard" }

Partials como:

<%= render "form", product: @product %>

são convertidos para componentes Ruby:

render Views::Products::Form.new(product: @product)

E até estruturas mais complexas como:

form_with
collection_select
checkboxes
condicionais (if, unless)
loops (each)
helpers Rails (dom_id, button_to, content_for)

são analisadas e convertidas automaticamente.

Migração gradual, sem reescrever tudo

Esse era um requisito importante para mim durante o desenvolvimento.

A gem não modifica os arquivos ERB originais.

Ela gera os novos arquivos Ruby lado a lado.

Isso permite um processo de migração incremental:

converter apenas uma pasta por vez
revisar o código gerado
testar cada tela individualmente
manter partes da aplicação ainda usando ERB

Sem precisar fazer uma migração radical.

Construindo um ecossistema em torno de RubyUI

Minha ideia com essas gems nunca foi lançar ferramentas isoladas.

O objetivo é construir ferramentas que ajudem a tornar o uso de Phlex e RubyUI cada vez mais acessível dentro do ecossistema Rails.

Hoje essa jornada começa com duas peças complementares:

ruby_ui_scaffold

Para novos projetos.

Cria CRUDs completos utilizando Phlex + RubyUI desde o início.

ruby_ui_converter

Para aplicações existentes.

Ajuda a migrar views tradicionais em ERB para componentes Ruby.

O objetivo final

Tenho explorado bastante a ideia de trazer uma experiência mais moderna de desenvolvimento frontend para aplicações Rails, mas sem abandonar aquilo que sempre gostei no ecossistema Ruby:

Escrever código simples.

Manter produtividade alta.

Continuar trabalhando majoritariamente em Ruby.

Essas gems fazem parte exatamente dessa visão.

Acredito que nos próximos anos veremos cada vez mais aplicações Rails adotando abordagens baseadas em componentes, e quero contribuir para tornar essa transição mais simples.

Se você trabalha com Rails e tem curiosidade em explorar o mundo do Phlex e RubyUI, talvez essas ferramentas possam ajudar nessa jornada.

E isso é só o começo :)

🇺🇸 Continuing the RubyUI Journey: Introducing ruby_ui_converter

Jackson Pires — Sun, 14 Jun 2026 19:07:39 +0000

Recently, I released a gem called ruby_ui_scaffold, a Rails scaffold generator designed for developers who want to build modern applications using Phlex and RubyUI from day one.

The idea behind it was simple:

Instead of relying on the traditional Rails scaffold that generates .erb templates, the goal was to create applications already structured around a Ruby component-based architecture powered by Phlex and RubyUI.

But shortly after releasing it, I realized an important question remained unanswered.

What about existing Rails applications?

The challenge of legacy applications

ruby_ui_scaffold works extremely well for new projects.

It allows developers to generate complete CRUD interfaces with controllers, forms, tables, and UI components entirely built with Phlex and RubyUI.

But the reality is that a huge part of the Rails community works on existing applications.

Applications that have evolved for years and contain hundreds of files like these:

app/views/products/index.html.erb
app/views/users/show.html.erb
app/views/orders/_form.html.erb

And naturally, this leads to an important question:

How do you migrate an existing Rails application to Phlex + RubyUI without manually rewriting the entire view layer?

That question led me to build the next step in this journey.

Introducing ruby_ui_converter

https://github.com/jacksonpires/ruby_ui_converter

If ruby_ui_scaffold was created to help developers build new Rails applications using a modern stack, ruby_ui_converter is its natural continuation.

The goal is simple:

Allow existing Rails applications to gradually migrate their .erb templates into Phlex and RubyUI components.

In other words:

ruby_ui_scaffold → helps build new applications with the modern stack from the beginning
ruby_ui_converter → helps existing applications transition to that stack

Automatically converting ERB into Ruby components

The gem recursively scans Rails view folders and automatically converts .erb templates into Ruby component files.

Example:

bundle exec ruby_ui_converter convert app/views/users

Output:

app/views/users/index.html.erb → app/views/users/index.rb
app/views/users/_user.html.erb → app/views/users/user.rb

The entire idea is to eliminate the repetitive work that usually comes with large migrations.

Intelligent conversion for Phlex and RubyUI

The goal was never to simply transform HTML into Ruby syntax.

The gem understands common Rails patterns and generates code compatible with both Phlex and RubyUI.

For example:

A traditional Rails template:

<%= link_to "Dashboard", dashboard_path %>

gets automatically converted into:

Link(href: dashboard_path) { "Dashboard" }

Partials like:

<%= render "form", product: @product %>

become Ruby components:

render Views::Products::Form.new(product: @product)

It also understands more complex structures like:

form_with
collection_select
checkboxes
conditionals (if, unless)
loops (each)
Rails helpers (dom_id, button_to, content_for)

and converts them automatically.

Gradual migration without rewriting everything

This was one of the most important requirements during development.

The gem does not modify the original ERB files.

Instead, it generates Ruby files alongside them.

This makes incremental migration possible:

convert one folder at a time
review generated code
test each screen individually
keep parts of the application running on ERB

There is no need for a risky “big bang” migration.

Building an ecosystem around RubyUI

My goal with these gems has never been to release isolated tools.

The bigger idea is to create tools that make adopting Phlex and RubyUI easier inside the Rails ecosystem.

Right now, that journey starts with two complementary pieces.

ruby_ui_scaffold

Built for new projects.

Generate complete CRUD applications using Phlex + RubyUI from the very beginning.

ruby_ui_converter

Built for existing applications.

Help legacy Rails apps migrate traditional ERB views into Ruby components.

The bigger vision

I’ve been spending a lot of time exploring ways to bring a more modern frontend development experience into Rails applications without losing what I have always loved about the Ruby ecosystem.

Writing simple code.

Maintaining high productivity.

Continuing to work primarily in Ruby.

These gems are part of that vision.

I believe that over the next few years, we’ll see more Rails applications adopting component-based architectures, and I want to help make that transition easier.

If you work with Rails and are curious about exploring the world of Phlex and RubyUI, I hope these tools can help you on that journey.

And this is only the beginning :)

🇺🇸 Learning RubyUI Through Real Applications with `ruby_ui_scaffold`

Jackson Pires — Wed, 10 Jun 2026 13:01:57 +0000

Building CRUD applications in Ruby on Rails has never been difficult. The challenge begins when we want to create modern, reusable, component-based interfaces without ending up with a mix of ERB templates, helpers, partials, and presentation logic spread across the application.

Over the past few years, tools like Phlex and RubyUI have introduced a compelling alternative for Rails developers who want a cleaner and more maintainable view layer. However, one challenge remains: getting started.

How should you structure your views? Which components should you use? How do you build complete CRUD flows with RubyUI?

To make that journey easier, I built ruby_ui_scaffold.

https://github.com/jacksonpires/ruby_ui_scaffold

What is ruby_ui_scaffold?

ruby_ui_scaffold is a Rails scaffold generator that creates complete CRUD applications using:

Ruby on Rails
Phlex
RubyUI
Tailwind CSS

Instead of generating traditional ERB templates, it produces fully functional Phlex views built with RubyUI components from day one.

Think of it as a modern alternative to:

rails g scaffold

but designed specifically for component-based Rails applications.

More than a Scaffold Generator

While the primary goal is to speed up CRUD development, ruby_ui_scaffold also serves as a practical learning tool.

Every generated resource includes real-world examples of RubyUI components such as:

Table
DataTable
Form
Input
Textarea
Checkbox
Badge
Select
Combobox
DropdownMenu
AlertDialog
DatePicker

Instead of reading documentation and trying to figure out how components fit together, you can study complete working implementations inside your own application.

Learning RubyUI Through Real Code

One of the biggest challenges when learning any component library is moving beyond isolated examples.

For example, generating:

bin/rails g ruby_ui_scaffold Buddy \
  name:string \
  email:string \
  admin:boolean \
  birthday:date

automatically creates:

Forms
Index pages
Show pages
Create and update flows
Delete confirmations

All powered by RubyUI components.

This provides practical examples that developers can inspect, modify, and learn from immediately.

Exploring Relationships

The generator also supports belongs_to relationships out of the box.

For example:

bin/rails g ruby_ui_scaffold Book \
  title:string \
  author:references

automatically generates:

Select inputs for small datasets
Searchable Comboboxes for larger datasets
Human-friendly relationship rendering
Eager loading to prevent N+1 queries

These generated examples demonstrate how advanced RubyUI components can be used in real applications.

Discovering the DataTable Component

Developers looking to explore more advanced UI patterns can enable:

--datatable

This generates fully featured tables with:

Search
Sorting
Pagination
Per-page controls

All built around RubyUI's DataTable component.

For many developers, this becomes one of the easiest ways to understand how to integrate advanced RubyUI features into production applications.

Generate Data and Experiment

The included seed command makes experimentation easy:

bin/rails ruby_ui_scaffold:seed Buddy --count 100

Using Faker, the generator populates your database with realistic sample data.

This allows you to test:

Tables
Forms
Search experiences
Pagination
Selection components

under realistic conditions.

A Playground for Phlex and RubyUI

Although ruby_ui_scaffold is highly productive, I believe its greatest value lies in education.

Every generated scaffold becomes a living collection of RubyUI examples that developers can inspect and learn from.

Rather than starting from a blank page, developers start from a complete application and gradually understand how RubyUI and Phlex work together.

For teams evaluating RubyUI, this can dramatically shorten the learning curve.

Conclusion

ruby_ui_scaffold was not created to replace learning RubyUI.

It was created to make that learning process easier.

By generating real code for real scenarios using real components, the gem helps bridge the gap between documentation and practical application.

If your goal is to accelerate CRUD development, ruby_ui_scaffold can help.

If your goal is to learn RubyUI and Phlex through hands-on examples, it may be one of the fastest ways to get started.

🇧🇷 Aprendendo RubyUI na Prática com `ruby_ui_scaffold`

Jackson Pires — Wed, 10 Jun 2026 13:00:43 +0000

Quem trabalha com Ruby on Rails sabe que gerar um CRUD é fácil. O desafio começa quando queremos construir interfaces modernas, consistentes e reutilizáveis sem cair em uma mistura de ERB, helpers, partials e componentes espalhados pela aplicação.

Nos últimos anos, o ecossistema Rails ganhou ferramentas extremamente interessantes como Phlex e RubyUI, que trazem uma experiência mais orientada a componentes para a camada de apresentação. Porém, para quem está começando, existe uma barreira inicial: como estruturar tudo isso? Quais componentes utilizar? Como conectar formulários, tabelas e ações CRUD usando RubyUI?

Foi exatamente para reduzir essa curva de aprendizado que desenvolvi a gem ruby_ui_scaffold.

https://github.com/jacksonpires/ruby_ui_scaffold

O que é o ruby_ui_scaffold?

O ruby_ui_scaffold é um gerador de scaffold para Rails que cria aplicações CRUD completas utilizando:

Ruby on Rails
Phlex
RubyUI
Tailwind CSS

Em vez de gerar views ERB tradicionais, ele produz views escritas em Phlex utilizando componentes RubyUI desde o primeiro momento.

Na prática, ele funciona como uma alternativa moderna ao tradicional:

rails g scaffold

mas gerando uma interface visual pronta para uso e alinhada com as boas práticas do ecossistema RubyUI.

Mais do que um gerador

Embora o objetivo inicial seja acelerar a criação de CRUDs, o ruby_ui_scaffold acaba se tornando uma excelente ferramenta educacional.

Ao gerar um recurso, você recebe exemplos reais de utilização de componentes como:

Table
DataTable
Form
Input
Textarea
Checkbox
Badge
Select
Combobox
DropdownMenu
AlertDialog
DatePicker

Em vez de consultar a documentação e tentar imaginar como cada componente deve ser utilizado, você passa a ter exemplos completos funcionando dentro da sua própria aplicação.

Aprendendo RubyUI através de código real

Uma das maiores dificuldades ao aprender qualquer biblioteca de componentes é sair dos exemplos isolados e entender como ela funciona em um sistema real.

Por exemplo, ao gerar:

bin/rails g ruby_ui_scaffold Buddy \
  name:string \
  email:string \
  admin:boolean \
  birthday:date

o scaffold cria automaticamente:

Formulários completos
Listagens
Páginas de detalhes
Fluxo de criação e edição
Exclusão com confirmação visual

Tudo utilizando componentes RubyUI.

Isso permite estudar padrões reais de implementação, em vez de exemplos artificiais.

Explorando relacionamentos

Outro aspecto interessante é o suporte automático a associações belongs_to.

Ao gerar um relacionamento:

bin/rails g ruby_ui_scaffold Book \
  title:string \
  author:references

o scaffold cria automaticamente:

Selects para pequenas listas
Comboboxes pesquisáveis para grandes volumes
Exibição amigável do relacionamento
Eager loading para evitar N+1 queries

Além de acelerar o desenvolvimento, isso mostra na prática como utilizar componentes avançados do RubyUI em cenários reais.

Conhecendo o DataTable

Quem deseja explorar componentes mais sofisticados pode utilizar a opção:

--datatable

Com ela, o scaffold gera páginas com:

Busca
Ordenação
Paginação
Controle de quantidade de registros por página

Tudo baseado no componente DataTable do RubyUI.

Essa funcionalidade é particularmente útil para quem deseja aprender como implementar tabelas avançadas utilizando RubyUI sem precisar construir tudo do zero.

Gerando dados para experimentar

Outro recurso interessante é o comando de seed:

bin/rails ruby_ui_scaffold:seed Buddy --count 100

Ele gera dados fictícios utilizando Faker, permitindo que você teste rapidamente:

Tabelas
Formulários
Paginação
Componentes de busca
Componentes de seleção

Quanto mais dados você gera, mais fácil fica entender o comportamento dos componentes RubyUI em situações reais.

Um laboratório para aprender Phlex e RubyUI

Embora a gem seja extremamente útil para acelerar o desenvolvimento, acredito que seu maior valor esteja na capacidade de servir como um laboratório de aprendizado.

Cada scaffold gerado se transforma em uma coleção de exemplos reais que podem ser estudados, adaptados e reutilizados.

Se você está começando com RubyUI ou deseja entender como estruturar aplicações Rails utilizando Phlex, o ruby_ui_scaffold pode funcionar como um excelente ponto de partida.

Em vez de começar com uma página em branco, você começa com uma aplicação funcional e pode evoluir a partir dela, aprendendo os componentes e padrões aos poucos.

Conclusão

O ruby_ui_scaffold não pretende substituir o aprendizado do RubyUI. Pelo contrário: ele foi criado para facilitar esse processo.

Ao gerar código real, utilizando componentes reais e cenários reais, a gem reduz a distância entre a documentação e a aplicação prática.

Se você quer acelerar seus CRUDs, ótimo.

Mas se também quer aprender RubyUI e Phlex de forma prática, provavelmente esse é um dos caminhos mais rápidos para começar.

🇺🇸 3 Essential Gems to Eliminate Friction in Your Rails Workflow

Jackson Pires — Thu, 04 Jun 2026 21:48:37 +0000

Anyone who works with Ruby on Rails knows that, despite the framework being incredible for productivity, there are some classic workflow deficiencies that haunt almost every project.

You are focused on writing code, but suddenly you need to open an external tool like Postman to test a route. Then, you run a complex script to generate a static database diagram. And at the end of the day, you still need to manually update the API documentation, which will inevitably become outdated in the next sprint.

This constant context switching and manual maintenance generates enormous friction. To cover these deficiencies, I developed three gems that bring these tools inside your application. They are so practical that they quickly become indispensable in any Rails project. Meet each one of them:

1. `rails-api-docs`: The End of Outdated Documentation]

https://github.com/jacksonpires/rails-api-docs

The deficiency: API documentation always starts with good intentions, but as the system evolves—new routes, parameters, and response fields—it quickly stops representing reality. Keeping this updated manually is repetitive and frustrating work.

The solution: The rails-api-docs gem solves this by leveraging what Rails already knows. It inspects your routes, controllers (via AST analysis using Prism), and the ActiveRecord schema to automatically generate the first draft of your documentation. Everything is saved in a single YAML file (config/rails-api-docs.yml), which serves as the single source of truth.

Why it is indispensable:

Append-only strategy: When adding new routes and running the generator, the gem only appends what's new. Your descriptions, custom examples, and tags are never modified or deleted, making the documentation a living document.
Zero development friction: You edit the YAML in one window and view the updated documentation in the browser at localhost:3000/rails/api-docs instantly, with no build step required. For production, it exports a single static HTML file without any external dependencies.

2. `rails-http-lab`: Your HTTP Client Right in the App

https://github.com/jacksonpires/rails-http-lab

The deficiency: Testing HTTP endpoints usually requires switching to external tools (like Postman or Insomnia) or creating temporary scripts. Besides the loss of focus, these tools live outside your repository and frequently suffer from CORS issues when trying to access internal services.

The solution: The rails-http-lab is a Rails Engine that couples an HTTP request lab inside your own application. By accessing /rails/http-lab, you have a lightweight interface to test methods, headers, and payloads while visualizing the responses directly in the browser.

Why it is indispensable:

Stays in the Repository: Your requests are saved in .bru format (interchangeable with the Bruno desktop app) inside the project's docs/http-lab/ folder. This means your API tests are version-controlled in Git and can be easily reviewed in Pull Requests.
No CORS limits: Since the requests are executed by the Rails server itself, you don't have CORS problems and can reach internal services transparently.

3. `rails-realtime-erd`: Database Diagrams Always in Sync

https://github.com/jacksonpires/rails-realtime-erd

The deficiency: Understanding database relationships in a growing project is difficult. Traditional tools generate static diagrams (ERD) that require manual tasks and quickly become outdated as soon as a new migration is executed.

The solution: The rails-realtime-erd gem mounts a route at /rails/erd that renders your schema diagram in real-time using Mermaid, all processed by Hotwire (Stimulus), without relying on complex JavaScript frameworks.

Why it is indispensable:
You will never again need to run a rake step to generate a static image file. The introspection is done on the fly: if you run a migration, just refresh the page to see the new tables and relationships reflected in the diagram immediately. It is excellent for onboarding new developers and keeping a live documentation of your architecture.

Conclusion

These three tools share the same philosophy: your code already has the necessary knowledge, and the support tools should live as close to it as possible.

Adopting rails-api-docs, rails-http-lab, and rails-realtime-erd drastically reduces daily friction, eliminating external dependencies and manual rework. With simple installation steps, your development environment will become much more productive, robust, and integrated.

🇧🇷 3 Gems Indispensáveis para Eliminar as Deficiências do seu Fluxo de Trabalho no Rails

Jackson Pires — Thu, 04 Jun 2026 21:47:50 +0000

Quem trabalha com Ruby on Rails sabe que, embora o framework seja incrível para a produtividade, existem algumas deficiências clássicas no fluxo de desenvolvimento que assombram quase todo projeto.

Você está focado escrevendo código, mas de repente precisa abrir uma ferramenta externa como o Postman para testar uma rota. Depois, roda um script complexo para gerar um diagrama estático do banco de dados. E, no fim do dia, ainda precisa atualizar manualmente a documentação da API, que fatalmente ficará defasada na próxima sprint.

Essa constante alternância de contexto e manutenção manual geram um enorme atrito. Para cobrir essas deficiências, eu desenvolvi três gems que trazem essas ferramentas para dentro da sua aplicação. Elas são tão práticas que rapidamente se tornam indispensáveis em qualquer projeto Rails. Conheça cada uma delas:

1. `rails-api-docs`: O Fim da Documentação Desatualizada

https://github.com/jacksonpires/rails-api-docs

A deficiência: A documentação de API sempre começa com boas intenções, mas conforme o sistema evolui — novas rotas, parâmetros e campos na resposta —, ela rapidamente deixa de representar a realidade. Manter isso atualizado manualmente é um trabalho repetitivo e frustrante.

A solução: A gem rails-api-docs resolve isso aproveitando o que o Rails já sabe. Ela inspeciona suas rotas, controllers (via análise AST usando Prism) e o schema do ActiveRecord para gerar automaticamente o primeiro rascunho da sua documentação. Tudo é salvo em um único arquivo YAML (config/rails-api-docs.yml), que serve como fonte da verdade.

Por que é indispensável:

Estratégia Append-only: Ao adicionar novas rotas e rodar o gerador, a gem apenas adiciona o que é novo. Suas descrições, exemplos customizados e tags não são apagados, tornando a documentação um documento vivo.
Zero atrito no desenvolvimento: Você edita o YAML de um lado e visualiza a documentação atualizada no navegador em localhost:3000/rails/api-docs instantaneamente, sem etapa de build. Para produção, ela exporta um único arquivo HTML estático, sem dependências externas.

2. `rails-http-lab`: Seu Client HTTP Direto na Aplicação

https://github.com/jacksonpires/rails-http-lab

A deficiência: Testar endpoints HTTP geralmente exige alternar para ferramentas externas (como Postman ou Insomnia) ou criar scripts temporários. Além da perda de foco, essas ferramentas vivem fora do seu repositório e frequentemente sofrem com problemas de CORS ao tentar acessar serviços internos.

A solução: O rails-http-lab é uma Rails Engine que acopla um laboratório de requisições HTTP dentro da sua própria aplicação. Ao acessar /rails/http-lab, você tem uma interface leve para testar métodos, headers e payloads visualizando as respostas diretamente no navegador.

Por que é indispensável:

Fica no Repositório: As suas requisições são salvas no formato .bru (compatível com o aplicativo desktop Bruno) dentro da pasta docs/http-lab/ do projeto. Isso significa que os testes da sua API são versionados no Git e podem ser revisados nos Pull Requests.
Sem limites de CORS: Como as requisições são executadas pelo próprio servidor Rails, você não tem problemas de CORS e pode alcançar serviços internos de forma transparente.

3. `rails-realtime-erd`: Diagramas de Banco de Dados Sempre Sincronizados

https://github.com/jacksonpires/rails-realtime-erd

A deficiência: Entender os relacionamentos do banco de dados em um projeto que está crescendo é difícil. As ferramentas tradicionais geram diagramas estáticos (ERD) que exigem tarefas manuais e rapidamente ficam defasados assim que uma nova migration é executada.

A solução: A gem rails-realtime-erd monta uma rota em /rails/erd que renderiza o diagrama do seu schema em tempo real usando o Mermaid, tudo processado pelo Hotwire (Stimulus), sem depender de frameworks JavaScript complexos.

Por que é indispensável:
Você nunca mais precisará rodar um passo de rake para gerar um arquivo de imagem estático. A introspecção é feita sob demanda: se você rodar uma migration, basta atualizar a página para ver as tabelas e relacionamentos novos refletidos no diagrama imediatamente. É excelente para o onboarding de novos desenvolvedores e documentação viva da arquitetura.

Conclusão

Essas três ferramentas compartilham a mesma filosofia: o seu código já possui o conhecimento necessário, e as ferramentas de apoio devem viver o mais próximo possível dele.

Adotar o rails-api-docs, o rails-http-lab e o rails-realtime-erd reduz drasticamente o atrito no dia a dia, eliminando dependências externas e o retrabalho manual. Com passos simples de instalação (basta adicionar ao Gemfile e rodar um comando), seu ambiente de desenvolvimento se tornará muito mais produtivo, robusto e integrado.