Pular para o conteúdo

Arquitetura recomendada

O roteiro para um projeto novo: pastas por funcionalidade, a casca, os dados e o agente, no Vite ou no Next.

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

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, cursor ou todos fora do Claude Code): o contrato da biblioteca, a escolha de peça e as regras de fluxo.
  • O MCP, em .mcp.json no 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 um AGENTS.md para 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, o audit_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.

@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.