Documentação
Migrar da v1
Este guia leva um site feito com o Rubrica v1 para a v2. O comando migrar faz a maior parte do trabalho e não grava em nenhum banco: o que vai para o Convex é você quem importa, primeiro num banco de desenvolvimento novo.
O que muda da v1 para a v2
- O projeto deixa de ser uma cópia do template: passa a depender de
@rubrica/coree de um tema (@rubrica/theme-<nome>). Atualizar vira subir a versão do pacote. - O site público é Astro, em HTML estático (antes, uma SPA em Vite).
- Os 13 layouts viram temas (o seu layout tem um tema equivalente com o mesmo nome; a v2 acrescenta o
padrao). - As páginas fixas viram páginas de blocos, editáveis no painel.
- O
convex/do projeto vira arquivos de uma linha que reexportam o backend do núcleo. - Os idiomas viram uma lista configurável (a v1 tinha português e inglês fixos).
- O script Python da skill
rubricasai; entra o MCP local.
A v1 continua recebendo correções de bug e de segurança por 6 meses depois do lançamento da v2. Enquanto o seu site estiver nela, a documentação certa é a da branch v1 do GitHub: os guias deste site são da v2.
Antes de começar
- O projeto precisa estar na última v1 (1.13.1). Se não estiver:
npx create-rubrica@1 updatee faça o commit. git statussem mudanças pendentes. A migração roda numa branch nova, então a sua branch atual não muda.- Node 22.23 ou mais novo.
- Anote o endereço do site no ar: ele serve para conferir depois.
Passo a passo
1. Veja o que vai acontecer (não grava nada)
npx create-rubrica@latest migrar --relatorio
Mostra o tema equivalente ao seu layout e a lista das personalizações do seu projeto (arquivos que diferem da v1 de referência), cada uma com a sugestão de destino. Se quiser ver também o que os dados viram, passe o export do passo 2 com --export.
2. Exporte os dados da v1
Rode na pasta do projeto. Exporte do banco que tem o conteúdo de verdade, que em geral é a produção (--prod). O --include-file-storage traz as imagens junto:
npx convex export --prod --include-file-storage --path .rubrica/migracao/export-v1.zip
O export é só leitura: não altera o banco da v1. Se o .env.local não aponta para o projeto da v1, use --deployment <nome> (o nome do deployment de produção aparece no painel do Convex) no lugar de --prod.
3. Migre
npx create-rubrica@latest migrar --export .rubrica/migracao/export-v1.zip
O comando mostra o plano e pede confirmação. Depois:
- cria a branch
rubrica-v2; - compara com a v1 de referência e lista as personalizações;
- troca o código: sai o template, entram
@rubrica/coree o tema, oastro.config.ts, oconvex/gerado, oAGENTS.mde o.mcp.json; - converte o export num arquivo de import da v2 (
.rubrica/migracao/import-v2.zip), mais os dados em fixtures; - instala e faz o build sem banco, com os dados convertidos;
- escreve o relatório em
.rubrica/migracao/relatorio.md.
O Convex não é tocado.
4. Leia o relatório
Ele traz, em ordem: o tema escolhido; as páginas montadas e os blocos que ficaram de fora (e por quê); os textos e plugins convertidos; o que ficou pendente (guardado em pendentes-v1.zip); o que foi descartado; tabelas próprias do projeto que não foram convertidas; as personalizações com a sugestão de cada uma; e os próximos passos.
5. Importe no Convex de desenvolvimento NOVO
Nunca importe direto no banco da v1 nem na produção. Crie um banco de desenvolvimento novo e vazio para a v2:
npx convex dev --configure new --once # o .env.local passa a apontar para o novo; o banco da v1 fica intacto
cat .env.local | grep CONVEX_DEPLOYMENT # confira para onde vai
npx convex import .rubrica/migracao/import-v2.zip
npx create-rubrica setup # chaves de login e variáveis (o root e as páginas já vieram no import)
Abra o site (pnpm dev e pnpm dev:convex), entre no painel com o mesmo e-mail e a mesma senha da v1 e confira as páginas.
6. Trate as personalizações
Para cada arquivo da lista do relatório, siga a sugestão:
| Sugestão | Quando | O que fazer |
|---|---|---|
| Tokens | Era só cor, fonte ou espaçamento | Ajuste na tela Aparência do painel; nada de código |
| Bloco próprio | Era uma seção que o catálogo não tem | Crie em src/blocks/ com defineBlock e um componente React puro |
| Ejetar | Era o desenho de um bloco que o catálogo tem | npx create-rubrica ejetar <bloco> e refaça a mudança na cópia |
Siga o menor esforço que resolve. Veja Temas.
7. Confira
pnpm check && pnpm test && pnpm build
npx create-rubrica@latest migrar conferir --v1 https://seusite.com --v2 dist
O migrar conferir compara, nas páginas principais, o título, o h1 e o texto entre o site da v1 no ar (ou uma pasta dist dela) e o build da v2. Diferenças aparecem em lista: nem todas são erros (o tema novo pode mudar a ordem de uma seção), mas título e h1 de SEO devem bater.
8. Analytics, se você usava
O migrar não lê as variáveis da Vercel. Se a v1 tinha Umami, ligue de novo:
npx create-rubrica config --analytics https://cloud.umami.is/script.js --analytics-id <id>
9. Publique, só com o seu ok
A produção só muda quando você publicar. Faça com o mesmo cuidado de sempre: o desenvolvimento conferido primeiro, depois a produção.
- O import em produção apaga o que houver lá. Combine antes com quem cuida do site, e só faça com um "ok" explícito.
- O
publicarprepara o Convex de produção da v2 e a Vercel. Use um banco de produção novo para a v2 e mantenha o da v1 até confirmar que está tudo certo. - Faça o merge da branch
rubrica-v2quando o site da v2 estiver aprovado.
O que é convertido
| Da v1 | Para a v2 |
|---|---|
| Home, sobre, currículo, portfólio, blog, depoimentos | Páginas de blocos, montadas pela receita do tema e preenchidas com o conteúdo da v1 |
| Textos de seção (títulos, chamadas, botões) | Campos dos blocos, com tradução |
| Outros textos do site | Textos de interface |
| Traduções português e inglês | Mapa por idioma: pt-BR (principal) e en, com as mesmas URLs /en |
| Posts, projetos, serviços, depoimentos, FAQ, dia a dia, currículo | As mesmas coleções, com os mesmos ids |
| Configurações do site e plugins | Configurações da v2 (i18n vira translation) |
| Usuários e papéis | Mantidos; ninguém muda de papel |
| Contatos | Mantidos, com o consentimento marcado como "anterior à v2" |
| Propostas, versões e aceites | Mantidos, com hash e prova de aceite intactos |
| Modelos de contrato, checkouts, currículos com IA | Mantidos, com o estado e os ids do Asaas |
| Imagens (biblioteca) | Mantidas |
O que não é convertido
| O que | Por quê |
|---|---|
| Sessões de login | Todo mundo entra de novo |
| Códigos e limites temporários (login, envios) | São zerados |
| Sessões de proposta | Expiram: o cliente digita a senha de novo |
| Contatos na lixeira da v1 | A v2 não tem lixeira de contatos |
| Depoimentos recusados | A v2 apaga o envio ao recusar |
| Depoimentos em vídeo | A v2 só recebe depoimento em texto. Vão como estavam para pendentes-v1.zip |
Plugin playground |
Saiu da v2 |
| Tabelas próprias do projeto | Leve-as para o convex/ da v2 (schema e funções) e importe à parte |
| Personalizações no código | Listadas no relatório, mas você as refaz (bloco próprio, ejetar ou tokens) |
O que não é convertido nunca é apagado: ou fica no pendentes-v1.zip, ou continua no banco da v1.
Se algo der errado
- A migração roda numa branch. Para desistir:
git switch <sua-branch>egit branch -D rubrica-v2. - O banco da v1 nunca é alterado, a menos que você mesmo importe nele (não faça).
- Dúvidas ou casos que o relatório não explica: abra uma issue, sem dados privados.