Instalação
Um comando, as duas linhas de CSS e o Provider.
O @rivocode/ui é privado e mora no GitHub Packages (npm.pkg.github.com), e
não no npmjs.com. Instalar pede um token do GitHub com acesso de leitura aos
pacotes da organização RivoCode.
O caminho curto: um projeto novo
Antes do primeiro npx, aponte o escopo @rivocode para o GitHub Packages na
sua pasta pessoal (~/.npmrc). Sem isso o npx procura o pacote no npmjs.com
e responde 404:
npm config set @rivocode:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken '${RIVOCODE_NPM_TOKEN}'
A segunda linha grava o nome da variável, e não o token: as aspas simples
impedem o shell de expandir, e o npm lê o RIVOCODE_NPM_TOKEN do ambiente na
hora de instalar. O token é o mesmo do passo 0, abaixo. Com isso, um comando cria
o projeto já ligado à biblioteca:
npx -p @rivocode/ui rivocode-ui create
Ele pergunta o nome, com a validação na hora (pasta que já existe, caractere que o npm recusa) e um nome sugerido, e depois a base (Vite, Next ou Expo), o roteador, no Vite (TanStack Router, React Router ou nenhum), e o gerenciador de pacote (npm, pnpm, yarn ou bun), cada um numa lista que se escolhe com as setas e o Enter. Os três extras vêm numa lista só, todos marcados, e o espaço desmarca:
- A camada de dados (
--dados): instala o@tanstack/react-querye monta oQueryClientProviderdentro doRivoProvider, nomain.tsxdo Vite e noproviders.tsxdo Next. No Expo ele vai noproviders.tsxao lado da pasta de rotas, junto doRivoProvider, que o comando monta com a pergunta emsimou emnao. - O formulário (
--formulario): instala oreact-hook-form, ozode o@hookform/resolvers, que o@rivocode/ui/forme o@rivocode/ui-native/formpedem. - A skill e o MCP (
--skill): roda orivocode-ui skill --mcpno projeto novo, pelo bin instalado, e o seu agente já abre o projeto sabendo a biblioteca. No Expo o bin é o do@rivocode/ui-native, que traz a skill da versão dele. A skill é instalada para o Claude Code; para outra ferramenta, rode de novo com--para.
A biblioteca não escolhe a pilha por você: diga nao para o que o seu projeto
resolve de outro jeito. Sem perguntar:
npx -p @rivocode/ui rivocode-ui create meu-app --base vite --roteador react-router --gerenciador pnpm
npx -p @rivocode/ui rivocode-ui create meu-app --sim --dados nao --skill nao
Antes de escrever, ele mostra o resumo do que vai criar e pede confirmação, e cada instalação roda com um indicador de progresso. O Ctrl+C sai sem deixar projeto pela metade: a pasta que o comando criou é apagada, e uma pasta que já existia nunca é tocada.
O --sim aceita o padrão do que não veio na linha, e o --dry-run mostra o
que ele escreveria e instalaria, sem fazer nada. Fora de um terminal, como na
CI, ou com todas as respostas na linha, ele não pergunta nada. Para um projeto que já existe,
siga os passos abaixo.
No Expo, depois do create-expo, o comando roda o rivocode-ui-native-init, gera
o generated.css e embrulha o _layout.tsx do template (src/app/_layout.tsx
no template atual, app/_layout.tsx no anterior): o generated.css entra no
topo e o layout que o template trazia, com o splash e as abas, passa a ser
montado dentro do Providers. Layout que ele não reconhece não é reescrito: o
comando avisa e o resto segue. Para conferir o app de celular, o doctor é o do
pacote nativo, npx rivocode-ui-native-doctor; o deste pacote, rodado num app
do Expo, diz isso e para.
0. Apontar o escopo para o GitHub Packages
Crie um .npmrc na raiz do projeto:
@rivocode:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${RIVOCODE_NPM_TOKEN}
O RIVOCODE_NPM_TOKEN é um token pessoal do GitHub (clássico, com o escopo
read:packages), exportado no ambiente: na sua máquina, na CI e no deploy. O
.npmrc pode ir para o git, porque só carrega o nome da variável. Na CI do
GitHub Actions de um repositório da organização, o secrets.GITHUB_TOKEN com
permissions: packages: read serve, passado no env como RIVOCODE_NPM_TOKEN,
desde que o pacote dê acesso de leitura àquele repositório. O nome não é GITHUB_TOKEN de propósito: o gh dá preferência a essa variável sobre o próprio login, e um token que só lê pacote o deixaria sem acesso aos repositórios.
1. Instalar
O lucide-react vai junto na mesma linha, e não é enfeite: os componentes
importam ícone direto dele. O npm instala esse par sozinho, mas o pnpm e o
yarn não, e sem ele a Sidebar, a Pagination e o DatePicker quebram em
tempo de execução.
npm install @rivocode/ui lucide-react
pnpm add @rivocode/ui lucide-react
yarn add @rivocode/ui lucide-react
bun add @rivocode/ui lucide-react
E o Tailwind, como dependência de desenvolvimento:
npm install -D tailwindcss @tailwindcss/vite
React 19, React DOM 19 e Tailwind 4 são dependências de par: quem manda na versão é o seu projeto, não a biblioteca. Isso evita a duplicação de React, que quebra contexto e hooks de formas difíceis de diagnosticar.
Estes são opcionais, e só quem usa carrega o peso:
| Se você for usar | Instale junto |
|---|---|
@rivocode/ui/form |
react-hook-form, zod, @hookform/resolvers |
@rivocode/ui/chart |
recharts |
@rivocode/ui/dnd |
@dnd-kit/core, @dnd-kit/sortable |
@rivocode/ui/editor |
@tiptap/react, @tiptap/pm, @tiptap/core, @tiptap/starter-kit, @tiptap/extensions |
2. Ligar o Tailwind no build
Instalar o @tailwindcss/vite não basta: ele precisa entrar na lista de
plugins. Sem isso o build passa sem erro nenhum e gera um CSS sem uma
única classe da biblioteca, então a tela aparece crua e nada na saída explica
por quê.
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [react(), tailwindcss()],
})
Em Next.js o caminho é o plugin do PostCSS, e não este.
3. As duas linhas de CSS
No arquivo de CSS do projeto:
@import "tailwindcss";
@import "@rivocode/ui/preset";
@import "@rivocode/ui/fonts.css";
@source '../node_modules/@rivocode/ui/dist';
A linha @source não é opcional, e é a que mais quebra. O Tailwind 4 só
gera a classe que encontra ao varrer arquivos. Sem essa linha ele não varre os
componentes da biblioteca, não gera as classes que eles usam, e a tela aparece
sem estilo nenhum, sem erro, sem aviso, sem pista. Ajuste o caminho
relativo conforme a pasta onde o seu CSS mora.
O preset traz as três camadas de token e os dois temas. As faces da marca
(Manrope, Poppins e JetBrains Mono) vêm à parte, no fonts.css: sem ele a tela
inteira cai em system-ui, de novo sem erro. Se o seu projeto tem tipografia
própria, deixe o fonts.css de fora e aponte os tokens de fonte, como em
Temas e personalização.
4. O Provider, uma vez
import { RivoProvider } from '@rivocode/ui'
import './styles.css'
export function App() {
return (
<RivoProvider theme="rivocode-dark" density="comfortable">
<SuaAplicacao />
</RivoProvider>
)
}
Sem ele nada tem estilo, e Dialog, Menu, Select, Tooltip e os avisos
lançam erro, todos leem o contexto dele. O Provider já monta por dentro o
provedor de dica, a fiação de aviso e um container de portal que leva o tema
junto. Não monte nenhum deles à mão.
5. Ensinar o seu agente
Se você programa com Claude Code, Codex, Copilot, Gemini CLI, Cursor ou outro agente que leia skills, um comando instala a que ensina esta biblioteca (o contrato, a escolha entre peças parecidas e o vocabulário de ícones):
npx rivocode-ui skill # Claude Code
npx rivocode-ui skill --para codex # ou copilot, gemini, cursor, todos
Ela entra em .claude/skills/rivocode-ui (ou em .agents/skills/rivocode-ui,
nas outras ferramentas), com a rivocode-ui-audit e a rivocode-ui-teste ao
lado, e a equipe recebe junto pelo Git.
Detalhes e alternativas em Skill.
Next.js
Os componentes são interativos e trazem "use client" na origem. O Provider
precisa viver num arquivo de cliente, normalmente um providers.tsx importado
pelo layout raiz:
'use client'
import { RivoProvider } from '@rivocode/ui'
export function Providers({ children }: { children: React.ReactNode }) {
return <RivoProvider theme="rivocode-dark">{children}</RivoProvider>
}
Quando algo não aparece
Um comando confere o setup inteiro pelos arquivos do projeto (as dependências,
o .npmrc, o plugin do Tailwind, o CSS, a linha @source, as fontes, o
Provider e a versão da skill do agente) e diz o que falta em cada um:
npx rivocode-ui doctor
O plugin do Tailwind vale em qualquer uma das formas: tailwindcss() no
vite.config, @tailwindcss/postcss no postcss.config, o
@tailwindcss/turbopack no package.json de um projeto Next 16 (ou o loader
@tailwindcss/webpack no next.config) e o bun-plugin-tailwind em
[serve.static] plugins do bunfig.toml. O CSS é lido a partir da entrada: o
.css que o código importa (import "./styles.css" no main.tsx, no
layout.tsx ou no _layout.tsx), o que um .html liga por <link rel="stylesheet"> ou o app/globals.css do Next, e daí cada @import
relativo. Um .css que o app não importa não conta, nem para o preset, nem para
o @source, nem para as fontes. Fonte faltando é falha, porque a tela inteira
muda de família.
Em desenvolvimento, o RivoProvider também avisa no console quando o preset
não chegou à página, quando as classes das peças não foram geradas (o
@source) e quando a fonte do tema não tem @font-face carregado. Em produção
ele não confere nada.
| Sintoma | Causa quase certa |
|---|---|
| Tudo estilizado, e o texto na fonte do sistema | falta o @import "@rivocode/ui/fonts.css", ou a sua fonte no tema |
| Tela sem estilo nenhum, nem a sua | o plugin do Tailwind não está na lista de plugins do vite.config.ts |
| Suas classes pegam, as da biblioteca não | falta a linha @source, ou o caminho relativo dela está errado |
ChevronRight is not defined ou similar |
falta o lucide-react: o pnpm e o yarn não instalam par sozinhos |
| Erro de contexto ao abrir diálogo ou menu | árvore fora do RivoProvider |
| Dois Reacts na página | React como dependência direta da biblioteca em vez de par, verifique o lockfile |
| Flutuante sem tema, solto no fim da página | scope="local" sem o container de portal do Provider |
| Tudo estilizado, e a página inteira na fonte do sistema | tema de cliente sem --rc-font-sans: rode npx rivocode-ui check-theme no CSS do seu tema |
O último não dá erro em lugar nenhum, e por isso tem comando próprio. O
rivocode-ui check-theme lê os arquivos de tema do seu projeto e cobra papel
faltando, dizendo o que acontece na tela sem cada um. Detalhes em
Temas e personalização.