Ir para o conteúdo
decodecodeveloper docs
Storefront → Templates → Migração

Script de migração

O que npx -p @decocms/blocks-cli deco-migrate faz de fato.

@decocms/blocks-cli fornece deco-migrate para migrar um site Fresh/Deno descontinuado para o binding TanStack de Blocks 7.x publicado. Esta página documenta o que ele faz, quais flags aceita e o que não faz.

Início rápido

# de dentro do diretório da loja v1
npx -p @decocms/blocks-cli deco-migrate

Pronto. O script analisa o layout, gera arquivos Blocks 7.x, transforma imports/JSX/APIs, limpa código morto, gera relatório, verifica e instala dependências.

Flags

FlagFunção
--source <dir>Diretório de origem (default: cwd)
--dry-runMostra o que aconteceria, sem escrever
--verboseSaída detalhada por transformação
--no-compilePula o tsc --noEmit + vite build pós-transformação
--no-cleanup-auditPula a auditoria pós-migração (read-only)
--strictFail no run em qualquer warning de auditoria
--with-buildRoda vite build completo (default só typecheck)
--help, -hMostra ajuda

As sete fases

Vindo de scripts/migrate.ts:

1. Análise     — escaneia origem, detecta padrões Preact/Fresh/Deco
2. Scaffold    — gera vite.config.ts, wrangler.jsonc, rotas, setup.ts, worker-entry
3. Transform   — reescreve imports (70+ regras), atributos JSX, APIs Fresh, Deno-isms, Tailwind v3→v4
4. Cleanup     — apaga islands/, rotas antigas, deno.json, move static/ → public/
5. Report      — gera MIGRATION_REPORT.md com itens manuais
6. Verify      — 18+ smoke tests (zero imports antigos, arquivos scaffolded existem)
7. Bootstrap   — instala com Bun, gera blocks do CMS, gera rotas

Depois da fase 7, opcionalmente:

  • Compila (--no-compile para pular): roda tsc --noEmit e (com --with-build) vite build. Falhas são reportadas, mas não fazem o run falhar a menos que --strict.
  • Auditoria de cleanup (--no-cleanup-audit para pular): auditoria read-only de padrões Fresh remanescentes. Aponta coisas como pastas compat/ esquecidas ou useScript(fn) perdidos.

Detecção de layout

A fase 0 aceita projetos Fresh clássicos, com sections/, islands/ e diretórios relacionados na raiz, e modernos, com esses diretórios em src/. Os dois layouts são analisados nativamente.

Um layout misto (diretórios populados na raiz e em src/) ou vazio interrompe o processo antes de escrever a migração. Confira o caminho da origem ou restaure um checkout limpo, sem reorganizar um layout src/ suportado. O dry run usa o mesmo preflight.

O que MIGRATION_REPORT.md contém

Após um run real:

  • Modo do run (DRY_RUN ou EXECUTED) e timestamp.
  • Contagem de arquivos — scaffolded, transformados, deletados.
  • Listas completas de arquivos por categoria.
  • Inventário de loaders — todo loaders/*.ts e actions/*.ts encontrado, com status de port.
  • Pegadinhas Tailwind v3 → v4 — z-index negativo, migrações de opacidade, reescritas de @apply.
  • Boilerplate duplicado de @decocms/blocks — lugares onde o código migrado se sobrepõe a helpers do framework (candidatos a limpeza).
  • Próximos passos concretos — comandos exatos para rodar.

O relatório é escrito na raiz do site. Revise-o e faça o commit junto com a migração para que os reviewers possam conferir as mudanças.

Arquivo de configuração

Você pode fixar comportamento via .deco-migrate.config.json na raiz do projeto:

{
  "sectionConventions": {
    "extend": {
      "eagerSync": ["Header"],
      "sync": ["Hero"],
      "listingCache": ["ProductShelf"],
      "staticCache": ["Footer"]
    }
  }
}

extend adiciona nomes de arquivos de section aos padrões; replace usa apenas suas listas. Esse arquivo não implementa exclude, skipPhases ou verbose; use as flags documentadas e revise o diff. Veja convenções de section.

Scripts companheiros

deco-post-cleanup

Rode após a migração para limpar boilerplate que o framework já absorveu:

npx -p @decocms/blocks-cli deco-post-cleanup

É read + write — revise o diff antes de commitar.

deco-htmx-analyze

Para sites que usavam HTMX no v1. Reporta uso para você planejar a conversão para padrões React. HTMX não vem em @decocms/blocks — sites que dependiam precisam reescrever para React.

npx -p @decocms/blocks-cli deco-htmx-analyze

O que o script NÃO faz

  • Não migra overrides de useCart / useUser / useWishlist. Se sua loja v1 sobrescreveu, porte manualmente usando as factories v2. Veja Hooks VTEX.
  • Não migra lógica custom de worker. Proxies, harness AB, transforms de borda — o script gera um worker-entry.ts baunilha e deixa você camadear lógica custom em cima usando createDecoWorkerEntry.
  • Não corrige correção em runtime. Migração bem-sucedida produz código que compila; problemas em runtime (carrinho não carrega, PDP errado, mismatches de hidratação) precisam de atenção humana.
  • Não traduz sites não-loja. Tunado para o arquétipo de loja deco.cx. Sites de marketing com setups Fresh muito custom devem esperar mais trabalho manual.

Troubleshooting

"Layout não clássico — abortando"

O migrador atual aceita layouts na raiz e em src/. Para origem mista ou vazia, confira --source e restaure um checkout completo; leia o diagnóstico da CLI antes de mover diretórios.

tsc --noEmit falha após a migração

Leia MIGRATION_REPORT.md. Causas comuns:

  • Hook de plataforma (useCart etc.) que precisa de implementação específica do site.
  • useScript(fn) que o script transformou mas o chamador não aceita.
  • Matcher ou loader custom usando APIs Deno-only.

vite build falha

Rode com --with-build para ver durante a migração. Depois leia o erro — a maioria são imports faltando causados por uma island que foi deletada mas ainda é referenciada.

Deploy de produção funciona mas preview do admin está quebrado

Provavelmente moveu handlers de admin para o server entry do TanStack em vez do worker entry. Veja Referência do worker entry.

Veja também