DEV Community: Vídeos de Ti

🇺🇸 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.

🇺🇸 I Got Tired of Stale API Documentation in Rails — So I Built `rails-api-docs`

Jackson Pires — Wed, 03 Jun 2026 12:25:33 +0000

API documentation always starts with good intentions.

At the beginning of a project, everything is in sync.

Routes match reality.

Examples are accurate.

Parameters make sense.

Responses reflect exactly what the API returns.

But as the system evolves, documentation starts falling behind.

A new route gets added.

A parameter changes.

An endpoint gains authentication.

A response receives new fields.

And before you realize it, the documentation no longer represents reality.

If you've worked with Rails APIs for long enough, you've probably experienced this.

I certainly have.

And it was exactly that frustration that led me to create rails-api-docs.

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

The idea started with a simple question

Your Rails application already knows a lot.

It knows:

your routes
your controllers
your parameters
your models
your database schema
your HTTP verbs

So why should documentation always start from scratch?

Why do we need to manually rewrite information that already exists inside the application?

The idea behind rails-api-docs was to leverage the knowledge Rails already has to generate the first draft of the documentation automatically.

The workflow I wanted didn't exist

I didn't want another tool where the workflow looked like this:

edit documentation
→ generate artifacts
→ rebuild
→ restart server
→ validate changes

I wanted something closer to the typical Rails development experience:

edit
→ refresh browser
→ keep working

That's where the core concept of the gem came from:

A single editable YAML file that powers both development-time documentation and production-ready documentation.

A single source of truth

The entire workflow revolves around a single file:

config/rails-api-docs.yml

This file becomes the source of truth for your documentation.

From it, the gem generates:

live documentation during development
request examples
response examples
documented schemas
static HTML documentation for production

You update one file.

Everything else updates automatically.

How it works

First, generate the initial YAML file:

rails g rails-api-docs:init

The gem automatically inspects:

Rails.application.routes
controllers (via Prism AST analysis)
ActiveRecord schema

And creates an initial documentation structure.

Then start your application:

rails server

And visit:

http://localhost:3000/rails/api-docs

Whenever you modify the YAML file, simply refresh the page.

No build step.

No frontend tooling.

No intermediate process.

Let the code write the first draft

One of the most interesting parts of this project was using Prism to analyze controllers.

For example:

params.require(:user).permit(
  :email,
  :password,
  :role
)

The gem can automatically identify these fields and use them to build the initial documentation structure.

Combined with ActiveRecord schema information, it can also infer:

field types
required attributes
initial examples
schema metadata

The goal was never to replace developers.

The goal was to eliminate repetitive work.

Let the machine handle what it can already discover.

And let humans focus on the important part: explaining the API.

Documentation updates shouldn't destroy your work

This is probably the feature that frustrated me most in existing approaches.

You generate documentation.

Spend time writing descriptions.

Add examples.

Organize sections.

Customize schemas.

Then you run the generator again.

And hope nothing gets overwritten.

rails-api-docs follows an append-only strategy.

When you add new routes to your application, simply run:

rails g rails-api-docs:update

The gem appends only new endpoints.

Everything you've written remains untouched.

That includes:

descriptions
examples
tags
authentication details
schemas
section organization

In practice, the documentation becomes a living document rather than a disposable artifact.

Organizing larger APIs with tags

As APIs grow, navigation becomes increasingly important.

That's why the gem supports tags:

tags:
  - auth
  - public

These tags aren't just labels.

They also become interactive filters in the generated documentation.

Clicking a tag instantly filters the navigation to show only endpoints associated with that category.

This makes large APIs significantly easier to explore.

Production should be simple

Another important goal was making deployment boring.

When you're ready to publish the documentation, simply run:

rake rails-api-docs:build

The result is:

public/api-docs.html

A single HTML file.

Everything embedded.

Inline CSS.

Inline JavaScript.

No external dependencies.

No CDN.

No Asset Pipeline.

No JavaScript runtime.

Just a static file that can be hosted almost anywhere.

I'm not trying to replace OpenAPI

There are excellent OpenAPI and Swagger-based tools available today.

They solve many problems extremely well.

The goal of rails-api-docs is not to replace that ecosystem.

The idea is different.

I wanted a solution that allows developers to:

generate documentation from an existing Rails application
edit everything in YAML
preview changes instantly
export a static HTML file
keep documentation synchronized with minimal effort

That's the workflow I was looking for.

And since I couldn't find exactly what I wanted, I decided to build it.

Final thoughts

API documentation should be easy to create and easy to maintain.

In my experience, generating the first version isn't the hard part.

Keeping it updated over time is.

rails-api-docs was created to reduce that friction.

By inspecting the application to generate a starting point.

By preserving your customizations over time.

And by providing an extremely fast feedback loop during development.

If you'd like to try it out:

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

Feedback, suggestions, and contributions are always welcome.

🇧🇷 Eu Cansei de Documentação de API Desatualizada no Rails — Então Criei a Gem `rails-api-docs`

Jackson Pires — Wed, 03 Jun 2026 12:24:43 +0000

Documentação de API sempre começa com boas intenções.

No início do projeto, tudo está sincronizado.

As rotas batem com a aplicação.

Os exemplos estão corretos.

Os parâmetros fazem sentido.

As respostas refletem exatamente o que a API retorna.

Mas conforme o sistema evolui, a documentação começa a ficar para trás.

Uma nova rota é criada.

Um parâmetro muda.

Um endpoint ganha autenticação.

Uma resposta recebe novos campos.

E, sem perceber, a documentação deixa de representar a realidade.

Se você trabalha com APIs em Rails há algum tempo, provavelmente já passou por isso.

Eu certamente já passei.

E foi justamente essa frustração que me levou a criar o rails-api-docs.

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

A ideia surgiu de uma pergunta simples

Sua aplicação Rails já sabe muita coisa.

Ela conhece:

suas rotas
seus controllers
seus parâmetros
seus modelos
seu schema do banco
seus verbos HTTP

Então por que a documentação precisa começar sempre do zero?

Por que precisamos reescrever manualmente informações que já existem dentro da aplicação?

A ideia por trás do rails-api-docs foi justamente aproveitar esse conhecimento que o Rails já possui para gerar um primeiro rascunho da documentação automaticamente.

O workflow que eu queria não existia

Eu não queria mais uma ferramenta onde o fluxo fosse:

editar documentação
→ gerar artefatos
→ rebuild
→ reiniciar servidor
→ validar alterações

Eu queria algo mais próximo do desenvolvimento Rails tradicional:

editar
→ atualizar navegador
→ continuar trabalhando

Foi daí que surgiu o conceito central da gem:

Um único arquivo YAML editável que gera tanto a documentação em desenvolvimento quanto a documentação de produção.

Uma única fonte da verdade

O fluxo da gem gira em torno de apenas um arquivo:

config/rails-api-docs.yml

Esse arquivo é a fonte da verdade para toda a documentação.

A partir dele a gem gera:

visualização em tempo real durante o desenvolvimento
exemplos de requisição
exemplos de resposta
schemas documentados
documentação HTML estática para produção

Você altera um único lugar.

Todo o resto é atualizado automaticamente.

Como funciona

Primeiro você gera o YAML inicial:

rails g rails-api-docs:init

A gem inspeciona automaticamente:

Rails.application.routes
controllers (via análise AST usando Prism)
schema do ActiveRecord

E cria uma estrutura inicial de documentação.

Depois basta subir a aplicação:

rails server

E acessar:

http://localhost:3000/rails/api-docs

Sempre que você alterar o YAML, basta atualizar a página.

Não existe etapa de build durante o desenvolvimento.

Não existe pipeline frontend.

Não existe processo intermediário.

Deixe o código escrever o primeiro rascunho

Uma das partes mais interessantes do projeto foi utilizar o Prism para analisar controllers.

Por exemplo:

params.require(:user).permit(
  :email,
  :password,
  :role
)

A gem consegue identificar automaticamente esses campos e utilizá-los para montar a estrutura inicial da documentação.

Quando combinamos isso com as informações do ActiveRecord, também é possível inferir:

tipos dos campos
obrigatoriedade
exemplos iniciais
informações do schema

O objetivo nunca foi substituir o trabalho do desenvolvedor.

O objetivo foi eliminar tarefas repetitivas.

Deixar a máquina fazer aquilo que ela consegue descobrir sozinha.

E deixar os humanos cuidarem da parte importante: explicar a API.

Atualizações não deveriam apagar seu trabalho

Essa talvez seja a característica que mais me incomodava em algumas abordagens existentes.

Você gera documentação.

Investe tempo escrevendo descrições.

Adiciona exemplos.

Organiza seções.

Personaliza schemas.

Então roda novamente o gerador.

E precisa rezar para não perder nada.

No rails-api-docs o YAML segue uma estratégia append-only.

Quando você adiciona novas rotas à aplicação basta executar:

rails g rails-api-docs:update

A gem adiciona apenas os endpoints novos.

Todo o conteúdo que você escreveu continua intacto.

Isso inclui:

descrições
exemplos
tags
autenticação
schemas
organização das seções

Na prática, a documentação deixa de ser um artefato descartável e passa a ser um documento vivo.

Organizando APIs maiores com Tags

Conforme uma API cresce, navegar pela documentação pode ficar mais difícil.

Por isso a gem possui suporte a tags:

tags:
  - auth
  - public

Essas tags não são apenas informativas.

Elas também funcionam como filtros interativos na documentação gerada.

Ao clicar em uma tag, a navegação passa a exibir apenas os endpoints relacionados àquela categoria.

Isso facilita bastante a exploração de APIs maiores.

Produção deveria ser simples

Outro objetivo importante era simplificar o deploy da documentação.

Quando chega o momento de publicar, basta executar:

rake rails-api-docs:build

O resultado é:

public/api-docs.html

Um único arquivo HTML.

Tudo embutido.

CSS inline.

JavaScript inline.

Sem dependências externas.

Sem CDN.

Sem Asset Pipeline.

Sem runtime JavaScript.

Apenas um arquivo estático que pode ser hospedado praticamente em qualquer lugar.

Não estou tentando substituir OpenAPI

Existem excelentes ferramentas baseadas em OpenAPI e Swagger.

Elas resolvem muito bem diversos cenários.

O objetivo do rails-api-docs não é substituir esse ecossistema.

A proposta é diferente.

Eu queria uma solução que permitisse:

gerar documentação a partir de uma aplicação Rails existente
editar tudo em YAML
visualizar mudanças instantaneamente
exportar um HTML estático
manter a documentação sincronizada com pouco esforço

Era esse workflow que eu procurava.

E como não encontrei exatamente dessa forma, resolvi construir.

Considerações finais

Documentação de API deveria ser simples de criar e simples de manter.

Na minha experiência, o maior problema não é gerar a primeira versão.

O desafio é mantê-la atualizada ao longo do tempo.

O rails-api-docs nasceu justamente para reduzir esse atrito.

Inspecionando a aplicação para gerar um ponto de partida.

Preservando suas customizações ao longo do tempo.

E oferecendo um ciclo de feedback extremamente rápido durante o desenvolvimento.

Se quiser experimentar:

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

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