Instalação — Shadwire

Requisitos

Os componentes instalados só precisam do que um app Rails normalmente já tem. Estas são as versões mínimas:

Requisito	Versão	Por quê
`ruby`	>= 3.2	Sintaxe usada pelos componentes e pela CLI.
`rails`	>= 7.1	Helpers de view, tag builder e o pipeline de assets.
`view_component`	>= 4.0	Os componentes são classes ViewComponent.
`lucide-rails`	>= 0.7	O port para Rails do Lucide, o conjunto de ícones do shadcn/ui.
Tailwind CSS	v4	Os tokens usam `@theme inline`, que é da v4.

Componentes interativos precisam de Stimulus

29 dos 57 componentes trazem um controller Stimulus. Eles são instalados em app/javascript/controllers/ e se registram pelo eagerLoadControllersFrom padrão do importmap-rails. Se o seu app registra controllers manualmente, registre os novos também. bin/shadwire status --json mostra o que detectou em stack.

Instale a CLI

A CLI só é usada durante o desenvolvimento, nunca em runtime. Você pode instalá-la globalmente ou adicioná-la ao app.

# global
gem install shadwire

# or straight into the app, in the development group
bundle add shadwire --group development

Rode o init

Rode na raiz do app Rails. É o único comando que você roda sem bin/, porque é ele que cria o binstub que os outros comandos usam.

shadwire init                     # gem installed globally
bundle exec shadwire init         # gem in the Gemfile

O que ele faz:

shadwire.json: grava o manifesto na raiz do app: a URL do registry, onde cada tipo de arquivo vai, o entrypoint do Tailwind e o que está instalado.
Arquivos base: instala app/components/ui_component.rb (a superclasse compartilhada) e vendor/shadwire/shadwire.css (os tokens).
Gems base: adiciona view_component e lucide-rails ao Gemfile, se faltarem.
Grupo development: adiciona a própria shadwire ao grupo development do Gemfile.
bin/shadwire: cria o binstub que você passa a usar para rodar a CLI. Ele carrega a CLI pelo bundle do app.
@import do Tailwind: importa o shadwire.css no entrypoint do Tailwind.

Pode rodar de novo sem medo: ele não desfaz nada e não mexe num binstub que já existe. --force recria o shadwire.json e reescreve o binstub.

Por que bin/shadwire

Depois do init, rode todos os comandos por bin/shadwire. O binstub carrega a CLI pelo bundle do app, então todo mundo no projeto usa a mesma versão, independente do que cada um tem instalado globalmente.

Um bundle sem o grupo development não tem a CLI

bundle install --without development, comum em deploy e em alguns jobs de CI, não instala a shadwire, então bin/shadwire não funciona nesse ambiente. Todo job que usa a CLI, como uma checagem de drift, precisa do grupo development.

Adicione o primeiro componente

bin/shadwire add button

Os componentes de que ele depende são instalados junto. Cada componente também instala o próprio módulo de helper (button grava app/helpers/ui/button_helper.rb), e o Rails inclui tudo que está em app/helpers/ nas views, sem include.

<%= ui_button(variant: :outline, size: :sm) { "Save" } %>

<%= render Ui::ButtonComponent.new(variant: :outline, size: :sm) do %>
  Save
<% end %>

As duas formas renderizam a mesma coisa. Nas views, o helper é mais curto.

Confirme que deu certo

bin/shadwire status

O status nunca falha. Fora de um app Rails ele retorna "rails": false, um registry fora do ar aparece como registryError e um shadwire.json ilegível como configError, e o código de saída é sempre 0. A página da CLI lista todos os campos.

Sem a CLI

Dá para copiar os arquivos à mão a partir do registry publicado ou do llms-full.txt, mas aí o shadwire.json não fica sabendo deles, e diff, update e remove dependem dele. Sempre que possível, use a CLI.