Arquitetura recomendada
O roteiro para um projeto novo: pastas por funcionalidade, a casca, os dados e o agente, no Vite ou no Next.
Um roteiro para começar um projeto com o @rivocode/ui e fazê-lo crescer sem
virar uma pasta de componentes soltos. Não é molde obrigatório: é a organização
que a casa recomenda, e cada projeto adapta o que precisar. A pilha não entra na
recomendação: roteador, camada de dados e gerenciador de pacote são escolha do
projeto, e a biblioteca funciona com qualquer um.
O roteiro vale para os dois jeitos de montar a aplicação:
| Base | Quando usar |
|---|---|
| Vite, com o roteador que você preferir | sistema logado, que roda no navegador: painel, gestão, área do cliente |
| Next.js com App Router | quando a página precisa de SEO ou de servidor: site público, loja, página aberta |
Os formulários vêm do @rivocode/ui/form. Nos exemplos, os dados vêm do
TanStack Query, mas qualquer camada que entregue data, isLoading e isError
serve. Autenticação fica de fora: cada projeto liga a sua.
Começar pelo comando
npm config set @rivocode:registry https://npm.pkg.github.com
npx -p @rivocode/ui rivocode-ui create
A primeira linha vai uma vez por máquina: sem ela o npx procura o pacote no
npmjs.com e responde 404. O token vem junto, como está na
instalação.
Ele pergunta 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), e
entrega o projeto já com o .npmrc, o Tailwind, o CSS da biblioteca, o
Provider e a casca abaixo. Depois pergunta o resto desta página, com sim de
padrão: a camada de dados (--dados, o TanStack Query, com o
QueryClientProvider já montado como na casca abaixo), o formulário
(--formulario, o react-hook-form, o zod e o @hookform/resolvers) e a
skill com o MCP (--skill), para o agente abrir o projeto sabendo a
biblioteca. Quem usa outra camada de dados responde nao. O passo a passo à
mão está na Instalação.
As pastas: uma por funcionalidade
src/
app/ a casca: rotas, providers, AppShell
features/
pedidos/
schema.ts o Zod, que é a fonte do tipo
api.ts as chamadas ao servidor
queries.ts os hooks do TanStack Query
pedidos-page.tsx a tela
order-form.tsx o formulário
schema.test.ts o teste
painel/
shared/ o que mais de uma funcionalidade usa
Funcionalidade nova é uma pasta nova em features/, e tudo dela mora ali: o
schema, a API, a tela e o teste. Uma funcionalidade não importa de dentro da
outra: o que as duas precisam sobe para shared/. É o que deixa apagar,
mover ou entregar uma funcionalidade sem caçar referência pelo projeto, e o que
faz o projeto de trinta telas ter a mesma cara do de três.
app/ só monta: rota, provider e casca. Regra de negócio não mora lá.
O que instalar
O @rivocode/ui mora no GitHub Packages: antes, o .npmrc do escopo
@rivocode, como na Instalação.
npm install @rivocode/ui lucide-react @tanstack/react-query react-hook-form zod @hookform/resolvers
npm install -D tailwindcss
No Vite, mais o roteador escolhido e o @tailwindcss/vite. No Next, mais
@tailwindcss/postcss. O CSS e o plugin do Tailwind seguem a
Instalação.
A casca
O RivoProvider fica uma vez só, por fora de tudo, e o AppShell monta o
cabeçalho, a barra lateral e o conteúdo. O item da barra lateral recebe o link
do router pelo render: sem ele, cada clique recarrega a página inteira.
No Vite, o RouterProvider é o do roteador escolhido:
// src/main.tsx
createRoot(document.getElementById('root')!).render(
<RivoProvider theme="system">
<QueryClientProvider client={queryClient}>
<RouterProvider router={router} />
</QueryClientProvider>
</RivoProvider>,
)
A casca, aqui com o React Router. No TanStack Router muda só a importação, e o
caminho atual vem do useRouterState, como em Roteador e dados:
// src/app/shell.tsx
import { Link as RouterLink, Outlet, useLocation } from 'react-router'
export function Shell() {
const { pathname } = useLocation()
return (
<AppShell
container
sidebar={
<SidebarContent>
<SidebarMenu>
<SidebarMenuItem render={<RouterLink to="/pedidos" />} active={pathname === '/pedidos'}>
Pedidos
</SidebarMenuItem>
</SidebarMenu>
</SidebarContent>
}
>
<Outlet />
</AppShell>
)
}
Cada tela entra na rota por import dinâmico, e só é baixada quando alguém a
abre: o lazy no React Router, o lazyRouteComponent no TanStack Router. Os
dois estão em Roteador e dados.
No Next, os providers vão num arquivo de cliente, e a casca usa o Link de
next/link e o usePathname:
// src/app/providers.tsx
'use client'
export function Providers({ children }: { children: ReactNode }) {
const [queryClient] = useState(() => new QueryClient())
return (
<RivoProvider theme="system">
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
</RivoProvider>
)
}
// src/app/shell.tsx
'use client'
<SidebarMenuItem render={<Link href="/pedidos" />} active={pathname === '/pedidos'}>
Pedidos
</SidebarMenuItem>
O layout.tsx da raiz embrulha tudo em <Providers><Shell>{children}</Shell></Providers>,
e cada page.tsx só renderiza a tela da funcionalidade.
Uma funcionalidade inteira
O schema é a fonte da verdade. Ele valida o formulário e dá o tipo, e o campo brasileiro leva o validador da biblioteca:
// src/features/pedidos/schema.ts
export const orderSchema = z.object({
customer: z.string().trim().min(2, 'Informe o nome do cliente'),
document: z.string().refine(isValidCpf, 'CPF inválido: confira os dígitos'),
amount: z.number().int().positive('O valor precisa ser maior que zero'),
})
A consulta mora num hook, e a tela não sabe de onde o dado vem:
// src/features/pedidos/queries.ts
export function useOrders() {
return useQuery({ queryKey: ['pedidos'], queryFn: listOrders })
}
export function useCreateOrder() {
const client = useQueryClient()
return useMutation({
mutationFn: createOrder,
onSuccess: () => client.invalidateQueries({ queryKey: ['pedidos'] }),
})
}
A tela desenha os quatro finais, e não só o caminho feliz:
<DataTable
data={orders.data}
isLoading={orders.isLoading}
isError={orders.isError}
onRetry={() => orders.refetch()}
rowKey={(row) => row.id}
columns={columns}
empty={{
title: 'Nenhum pedido por aqui',
description: 'Quando a loja vender pela primeira vez, o pedido aparece nesta lista.',
action: <Button onClick={() => setCreating(true)}>Registrar o primeiro pedido</Button>,
}}
/>
O formulário usa a peça certa para cada dado: máscara e validador no CPF, centavos inteiros no dinheiro.
<Form form={form} onSubmit={onSubmit}>
<FormField name="customer" label="Cliente">
{(field) => <Input {...field} autoComplete="name" />}
</FormField>
<FormField name="document" label="CPF do cliente">
{(field) => <MaskedInput {...forValue(field)} mask="cpf" />}
</FormField>
<FormField name="amount" label="Valor">
{(field) => <CurrencyInput {...forValue(field)} />}
</FormField>
<Button type="submit" loading={form.formState.isSubmitting}>
Registrar pedido
</Button>
</Form>
Excluir oferece desfazer, em vez de pedir confirmação:
const { mutateAsync: removeOrder } = useMutation({ mutationFn: deleteOrder })
const { mutate: undoRemove } = useMutation({ mutationFn: restoreOrder })
async function removeWithUndo(order: Order) {
await removeOrder(order.id)
const id = toast.add({
title: `Pedido ${order.number} excluído`,
timeout: 8000,
actionProps: {
children: 'Desfazer',
onClick: () => {
undoRemove(order)
toast.close(id)
},
},
})
}
Criar e editar abrem numa Sheet ao lado da lista, que mantém o contexto de
trás. O motivo de cada uma dessas escolhas está no guia de fluxo da
Skill.
O agente trabalhando do jeito da casa
Três arquivos na raiz do projeto fazem o Claude Code, o Cursor ou outro agente seguir este roteiro sozinho:
- A skill, com
npx rivocode-ui skill(e--para codex,copilot,gemini,cursoroutodosfora do Claude Code): o contrato da biblioteca, a escolha de peça e as regras de fluxo. - O MCP, em
.mcp.jsonno Claude Code (cada ferramenta tem o seu arquivo, listado em Para agents):
{
"mcpServers": {
"rivocode-ui": {
"command": "npx",
"args": ["-y", "@rivocode/ui-mcp"],
"env": { "RIVOCODE_NPM_TOKEN": "${RIVOCODE_NPM_TOKEN}" }
}
}
}
O pacote é privado: o .npmrc do projeto, o mesmo da instalação, manda o
escopo @rivocode para o GitHub Packages, e basta no Claude Code, que sobe o
servidor na pasta do projeto. Os outros casos estão em Para agents. O
${RIVOCODE_NPM_TOKEN} lê a variável do seu ambiente, e o token não entra no
repositório junto com o .mcp.json.
- Um
CLAUDE.md, ou umAGENTS.mdpara as outras ferramentas, que diga a arquitetura: onde mora cada coisa, que funcionalidade não importa de outra, e as regras de interface (a peça do catálogo antes do<div>, o campo que sai do dado, os quatro finais e o desfazer). A auditoria de tela do MCP, oaudit_screen, dá nota a uma tela pronta.
Testes e CI
Um teste por funcionalidade, começando pelo schema, que é onde mora a regra:
test('recusa o CPF com dígito errado', () => {
const result = orderSchema.safeParse({
customer: 'Marina Souza',
document: '123.456.789-00',
amount: 128_000,
})
expect(result.success).toBe(false)
})
E a CI roda tipos, testes e build em todo push, para a main nunca receber o
que não compila.