iGRPIGRP 3.0Documentation

Migrações do template

Atualizar uma app Next.js iGRP às novas versões do template com igrp migrate (ou @igrp/template-migrator) — estado, plano, aplicação, rollback e CI.

Quando sai uma nova versão do iGRP Framework, o @igrp/template-migrator aplica à tua app as alterações do template — novos ficheiros, middleware atualizado, bumps de dependências e novas chaves .env.example — como migrações numeradas e registadas em .igrp-migrations-lock.json.

O teu .env real nunca é tocado — ver Variáveis de ambiente para o único passo manual.

Correr o migrator

Corre o comando igrp migrate (CLI 1.7.7 ou superior; recomendada a mais recente) na pasta da app:

cd minha-app
igrp migrate status            # o que falta
igrp migrate plan              # o que vai mudar (não escreve nada)
igrp migrate apply             # aplica, com confirmação por migração
pnpm install                   # se alguma migração mudou dependências
git add -A && git commit -m "chore: aplica migrações do template"
A usar @igrp/template-migrator 0.2.0-beta.16

Template: demo-v1  CLI: 0.2.0-beta.16

  ✓ applied  01-preview-mode-not-found
  …
  ✓ applied  72-home-overview-title-size (→ 0.2.0-beta.13)
  • pending  73-session-first-switcher-rollback-docs (→ 0.2.0-beta.13)
  • pending  74-framework-next-beta14-i18n-deps (→ 0.2.0-beta.14)
  • pending  75-multi-app-auth-sessions
  • pending  76-resync-framework-next-beta15 (→ 0.2.0-beta.15)

73 applied, 4 pending

Antes de correr, o CLI pergunta ao registry qual é a versão exata do migrator e mostra-a (A usar @igrp/template-migrator …), por isso latest é sempre a última publicada, mesmo com uma cópia antiga em cache. Para fixar uma versão:

igrp migrate@0.2.0-beta.16 status
igrp migrate --use 0.2.0-beta.16 status   # forma equivalente

Tudo o que vem depois do comando é passado ao migrator. O registry por defeito é https://sonatype.nosi.cv/repository/igrp/ (variável IGRP_REGISTRY). Uma nova versão do migrator não exige nova versão do CLI.

Sem o CLI

O mesmo migrator corre diretamente com pnpm dlx (ou npx): pnpm dlx @igrp/template-migrator@latest status. No Studio, o bundle Template Migrator (separador Bundles do projeto) aplica tudo de uma vez — equivale a apply --yes --force, por isso sobrepõe alterações locais aos ficheiros geridos.

Projetos novos

Uma app criada pelo Studio já traz o .igrp-migrations-lock.json. O Studio descarrega sempre o template Next.js mais recente publicado, mas cada migração nova só chega aos projetos novos quando o template é republicado. Corre igrp migrate status depois de criar o projeto: se aparecerem pendentes, aplica-as como em qualquer outra app.

Comandos

status — ver o estado atual

igrp migrate status

Lista as migrações aplicadas (✓ applied, ignoradas no próximo apply) e as pendentes (• pending), com o total no fim — ver o exemplo em Correr o migrator.

plan — pré-visualizar sem escrever

igrp migrate plan

Imprime cada operação de ficheiro que cada migração pendente irá executar. Nenhum ficheiro é escrito — seguro de correr a qualquer momento.

Pending migrations (1):

── 07-data-access-layer ─────────────────────────────────────
  file.create src/lib/dal.ts
  file.write  src/lib/auth.ts  (replace)
  deps.bump   package.json

No files were written.

apply — correr as migrações

igrp migrate apply

O CLI percorre cada migração pendente por ordem. Para cada passo mostra o que vai fazer e pede confirmação antes de escrever. Após cada migração concluída regista uma entrada em .igrp-migrations-lock.json.

Se alguma package.json foi atualizada, o CLI imprime:

Next steps:
  pnpm install

Corre sempre pnpm install quando essa mensagem aparecer.

Opções úteis

# Sem prompts — CI / scripts
igrp migrate apply --yes

# Aplicar só até uma migração específica
igrp migrate apply --to 04-multi-auth-provider

Se um ficheiro gerido pelo template foi alterado por ti, o apply pára nessa migração. Revê a alteração; para a sobrepor, repete com --force.

rollback — desfazer uma migração

igrp migrate rollback 04-multi-auth-provider

Restaura os ficheiros que a migração escreveu e remove a entrada do lock file. Os passos de desfazer correm em ordem inversa.

Rollback pode recusar-se

Se uma migração sobrescreveu ou apagou um ficheiro e o lock entry não tem cópia do conteúdo anterior (entradas escritas por versões mais antigas do CLI), o rollback lista esses paths e para. Usa --force para ignorar esses ficheiros e reverter o resto:

igrp migrate rollback 04-multi-auth-provider --force

Migrações que vieram com a app não podem ser revertidas

Se a tua app foi criada a partir do template zip, as migrações já estão registadas mas o CLI nunca as correu aqui — não há nada para reverter. Usa git para desfazer manualmente esses ficheiros.

list — listar todas as migrações disponíveis

igrp migrate list

Mostra todas as migrações incluídas nesta versão do CLI.

check — gate de CI

igrp migrate check

Sai com código 1 se houver migrações pendentes, 0 se tudo estiver atualizado. Adiciona ao teu pipeline:

- name: Check for pending IGRP migrations
  run: pnpm dlx @igrp/template-migrator@latest check

convert — migrar lock file legado

Versões antigas guardavam o estado em .igrpmigrations/lock.json. Se tens um, os outros comandos param e apontam para aqui:

igrp migrate convert

Move o estado para .igrp-migrations-lock.json na raiz do projeto e remove o diretório antigo. Commit o resultado e re-executa o que estavas a fazer.

Variáveis de ambiente

As migrações só escrevem no .env.example. O teu .env real nunca é lido nem modificado.

Isso significa que uma migração que introduz uma nova configuração deixa a tua app sem ela. Após um apply que reporte novas chaves, compara os dois ficheiros e copia o que precisas:

git diff .env.example
Tipo de chaveUrgência
Com default sensato (IGRP_SYNC_ACCESS=false)Podes deixar até precisares
Sem default (AUTENTIKA_CLIENT_ID, etc.)Preenche antes de arrancar

O lock file

Após cada migração bem-sucedida o CLI escreve .igrp-migrations-lock.json na raiz do projeto.

Faz commit deste ficheiro

É a fonte de verdade de quais migrações a tua app já aplicou. Re-correr apply salta sempre as entradas completas.

Resolução de problemas

Migração parcialmente aplicada — Re-corre apply. Se a execução foi interrompida (Ctrl-C, timeout de CI, crash), o CLI deixa um .igrp-migration-journal.json na raiz a registar o que já correu. O próximo apply reverte esses passos e re-aplica a migração desde a base limpa:

Recovering from an interrupted run of 29-permissions-catalog-sync...
  reverted 3 step(s) from the interrupted migration
  ✓ recovered

Build falha após aplicar — Reverte, verifica o guia em prosa daquela migração para passos manuais, e re-aplica:

igrp migrate rollback <id>
# ajustes manuais
igrp migrate apply --to <id>

Lock file em falta mas migrações já aplicadas — Re-corre apply. As sobrescritas são idempotentes e as entradas ficam registadas corretamente.

Que migrações existem

igrp migrate list

Lista todas as migrações da versão do migrator em uso, com a data e a versão do framework a que levam (→ 0.2.0-beta.15). Na 0.2.0-beta.16 são 76, de 01-preview-mode-not-found a 76-resync-framework-next-beta15; funciona também fora de uma app. Para o que cada uma muda, usa igrp migrate plan na tua app.

Códigos de saída de igrp migrate

CódigoSignificado
0Sucesso.
1Validação — versão inválida, pasta que não é uma app iGRP, nem pnpm nem npx no PATH.
2Registry — versão não encontrada, registry inalcançável.
outroCódigo de saída do próprio migrator, passado tal e qual (check sai com 1 se houver migrações pendentes ou alteradas).
How is this guide?

Última atualização:

On this page

Correr o migratorComandosstatus — ver o estado atualplan — pré-visualizar sem escreverapply — correr as migraçõesOpções úteisrollback — desfazer uma migraçãolist — listar todas as migrações disponíveischeck — gate de CIconvert — migrar lock file legadoVariáveis de ambienteO lock fileResolução de problemasQue migrações existemCódigos de saída de igrp migrate