Instalação

O @rivocode/ui é público no npm, sob licença MIT. Não precisa de token, nem de .npmrc, nem de acesso à organização.

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:

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";

@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, os dois temas e as fontes da marca. Se o seu projeto já tem tipografia própria, veja Temas e personalização para importar só os tokens.

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, 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

Ela entra em .claude/skills/rivocode-ui 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

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.