Pular para o conteúdo

Instalação

Um comando, as duas linhas de CSS e o Provider.

/instalacao.mdmarkdown cru, para quem lê com agent em vez de olho

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-query e monta o QueryClientProvider dentro do RivoProvider, no main.tsx do Vite e no providers.tsx do Next. No Expo ele vai no providers.tsx ao lado da pasta de rotas, junto do RivoProvider, que o comando monta com a pergunta em sim ou em nao.
  • O formulário (--formulario): instala o react-hook-form, o zod e o @hookform/resolvers, que o @rivocode/ui/form e o @rivocode/ui-native/form pedem.
  • A skill e o MCP (--skill): roda o rivocode-ui skill --mcp no 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.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.