Rails Toastify

Sobre o projeto

O Rails Toastify é uma gem de código aberto para exibir notificações em aplicações Rails, inspirada na experiência do React Toastify. Transforma mensagens de flash em notificações com temas, animações, barra de progresso e fechamento por arraste.

A integração utiliza helpers de view e um arquivo de configuração, sem exigir JavaScript adicional na aplicação para exibir as mensagens de flash.

Problema

Aplicações Rails precisam informar ao usuário quando uma ação foi concluída ou quando ocorreu um erro. O framework oferece o mecanismo de flash, mas a apresentação visual das mensagens fica a cargo de cada projeto.

Criar essa apresentação envolve definir o componente, o estilo, o tempo de exibição e o comportamento durante a navegação. Quando cada aplicação implementa sua própria solução, o mesmo trabalho se repete e gera mais código para manter.

Bibliotecas como React Toastify mostram o valor de uma solução reutilizável para notificações. Meu objetivo foi oferecer uma experiência semelhante integrada às convenções do Rails, com configuração simples e sem adicionar um framework JavaScript apenas para essa funcionalidade.

Solução

A gem utiliza um Rails Engine para distribuir CSS e JavaScript prontos para o asset pipeline. Dois helpers de view conectam esses recursos às mensagens da aplicação.

Após instalar a gem e adicionar os helpers ao layout, a aplicação continua utilizando flash[:notice] e flash[:alert].

gem "rails_toastify"

<%= rails_toastify_container %>
<%= rails_toastify_messages %>

Temas, tipos de mensagem e comportamento podem ser ajustados no arquivo de configuração ou em chamadas específicas.

Minha atuação

Criei e mantenho a gem. Desenvolvi a arquitetura do engine, as animações e os temas em CSS, a camada JavaScript sem dependências e a API de configuração. Também sou responsável pela documentação, pela matriz de testes de compatibilidade e pela publicação no RubyGems.

Principais funcionalidades

• Notificações automáticas a partir do flash do Rails
• Seis posições de exibição na tela
• Quatro animações de entrada: bounce, slide, flip e zoom
• Três temas: claro, escuro e colorido
• Cinco tipos de mensagem: padrão, sucesso, aviso, erro e informação
• Cor da barra de progresso configurável por aplicação, tipo de mensagem ou notificação
• Fechamento por arraste com distância configurável
• API JavaScript para exibir notificações programaticamente
• Configuração independente de tema, tipo e duração para notice e alert

Arquitetura e decisões técnicas

O Rails Engine fornece CSS e JavaScript prontos para uso no navegador, sem etapa adicional de compilação ou dependência de Node.js. Isso permite integrar a gem a projetos que utilizam Propshaft ou Sprockets.

O helper serializa as mensagens de flash como JSON com escape, sem inserir scripts inline. O JavaScript da gem lê esse conteúdo nos eventos DOMContentLoaded e turbo:load, além de tratar o caso em que a página já foi carregada. Essa abordagem atende à navegação tradicional e à navegação com Turbo.

As configurações seguem uma ordem de prioridade: opções da chamada, opções do tipo de mensagem, configuração global e valores padrão do tema. A aplicação pode definir um comportamento geral e ajustar notificações individuais quando necessário.

O fechamento por arraste utiliza Pointer Events, compartilhando a implementação entre mouse, toque e caneta.

A compatibilidade declarada abrange Ruby 3.2 ou superior e Rails de 7.1 a 8. Essas combinações são verificadas em uma matriz de testes antes de cada publicação. Valores de configuração de versões anteriores são aceitos e normalizados para preservar a compatibilidade nas atualizações.

Resultado

Gem publicada no RubyGems sob licença MIT, com mais de 6 mil downloads e uso em produção. Entre os projetos que a utilizam estão o site de uma prefeitura no Pará, o Meus Compromissos e o Medicare.

Tecnologias

Ruby, Ruby on Rails, JavaScript, CSS, Turbo e RubyGems.