Visão geral da migração

Fresh e o antigo admin da deco.cx foram descontinuados. Esta é a entrada para migrar um site Fresh/Deno existente para Blocks 7.x publicado; migrar o editor para o Studio é uma etapa separada. O playbook completo está espalhado nesta seção; esta página diz o que ler em qual ordem.

Leia nesta ordem

1. Visão geral da migração — você está aqui.
2. Playbook — passo a passo manual, fase por fase.
3. Script de migração — o que npx -p @decocms/blocks-cli deco-migrate faz.
4. Agent skills — usar IA de coding para a cauda longa.
5. Checklist — validação antes do merge.

Matriz de decisão

Use a documentação Fresh apenas para interpretar uma instalação antiga durante a migração; ela não oferece um compromisso de manutenção contínua.

Compatibilidade de versões

O destino da migração é Blocks 7.x, com os pacotes separados @decocms/blocks, @decocms/blocks-admin, @decocms/tanstack e @decocms/blocks-cli. Instale individualmente versões 7.x compatíveis dos provedores e registre as versões resolvidas no lockfile. Blocks Next tem outra API e não é o destino desta migração.

Use a configuração de dependências do quickstart 7.x e da referência de migração Fresh. Não use exemplos antigos de pacotes 2.x/1.x nem uma dependência literal @decocms/apps-*.

O que sobrevive à migração

• Conteúdo do repositório — preserve o JSON e reconcilie chaves renomeadas, apps instalados e funções registradas com o relatório da migração.
• Todas as interfaces Props de section — sem reescrita de schema.
• Configuração de matchers — porte as funções e confira requisições reais, atribuição de variantes e cache pelo contrato 7.x.
• SEO do site — configureWebsite({ seo }) de @decocms/apps-website espelha o config do v1.
• Configuração de commerce — preserve as opções necessárias e valide assinaturas de loaders/actions, cookies e registro no runtime atual.

O que você vai ter que refazer

• Tudo em src/islands/ — islands não existem em React. A maior parte vira componentes "use client", alguns viram parte da section pai, outros viram helpers.
• Padrões useScript(fn) — o pattern do v1 não sobrevive. Use inlineScript, mova para o client ou reestruture.
• Rotas Fresh customizadas — porte para file routes do TanStack Router.
• Leituras Deno.env — use o acesso ao ambiente Worker ou o mecanismo de ambiente do servidor suportado pelo setup 7.x; RequestContext.current não tem propriedade env.
• Steps de build customizados em deno.json — traduza para scripts em package.json.

Orçamento de tempo (aproximado)

Para uma loja média (50-100 sections):

Ou seja: mais ou menos 1-2 semanas para um engenheiro só, mais rápido em par, mais lento se houver muita lógica custom.

O que NÃO fazer

• Separe os imports de runtime. Migre a aplicação em uma branch ou worktree própria. Um monorepo pode conter aplicações Fresh e 7.x isoladas; não misture imports de runtimes incompatíveis na mesma aplicação.
• Revise os shims da migração. Substitua imports antigos e remova shims específicos do site apenas depois de validar seus substitutos; a compatibilidade fornecida pelo framework está no guia 7.x.
• Não corrija manualmente imports que o script vai resolver. Rode o script primeiro; ele cobre 70+ regras de reescrita.
• Não pule o checklist. Type-clean, lint-clean e build-clean não são o mesmo que correto em runtime — verifique carrinho, PDP, PLP e busca de ponta a ponta.

Veja também

• Playbook de migração
• Script de migração
• Agent skills
• Checklist de migração