Migrar do Fresh

Fresh e o antigo admin da deco.cx foram descontinuados. Para um site Fresh existente, migre o runtime para Blocks 7.x publicado e conecte o Site Editor separadamente. O script automatiza transformações mecânicas. Um agente pode ajudar a revisar o relatório e adaptar o código específico do site; sua equipe ainda valida comportamento, integrações e deploy.

Esta página é a árvore de decisão — o playbook de verdade vive em Migração →.

Quando migrar?

Migre agora se…	Espere se…
Você está investindo em novas features e quer React + ecossistema mais amplo	Você está em feature freeze antes de uma data de pico
Está esbarrando em limites de concorrência ou cold-start no Deno Deploy	Depende de islands ou padrões específicos do Preact ainda não portados
Quer cache de borda first-class no Cloudflare	Seu time está no meio de um redesign e não absorve mudança de stack
Seu time já escreve React no dia a dia e a fricção do Preact é real	Você está bem no v1 e não tem motivo forte

A documentação Fresh é um arquivo para instalações existentes, não uma promessa de manutenção contínua.

O que é automático vs manual

Automatizado pelo deco-migrate:

Reescrita de imports (Preact → React, $fresh/* → TanStack, @deco/deco/* → @decocms/blocks/*).
Scaffolding de Vite + Wrangler.
Geração do worker entry e do setup file.
Correções Tailwind v3 → v4.
Remoção de islands/, rotas Fresh antigas, deno.json, static/ (movido para public/).

Ajustes manuais (o script sinaliza):

Implementações de hooks de plataforma (overrides customizados de useCart, useUser, useWishlist).
Padrões useScript(fn) que não hidratam mais limpo — troque por inlineScript ou mova para "use client".
Scripts de terceiros no <head> que causam CLS.
Quaisquer shims em compat/ que seu time tenha criado.
Lógica de worker específica do site (proxies custom, harness de A/B).

Os três caminhos

Caminho A — Rodar o script direto

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

Roda a migração em 7 fases no próprio lugar e gera um MIGRATION_REPORT.md com os TODOs manuais. Veja Referência do script de migração.

Caminho B — Usar o Agent Skill

Se você usa Claude Code, Cursor ou Codex, instale o skill de migração e deixe o agente conduzir:

npx skills add decocms/blocks

No editor: "migre este projeto para TanStack Start". O skill sabe o que é automático e o que não é, e percorre os ajustes manuais junto com você. Veja Agent skills.

Caminho C — Port manual

Para lojas pequenas (< 30 sections) ou times que querem controle total, siga a receita de Começar do zero para criar à mão o esqueleto mínimo do projeto e leve suas sections, components e conteúdo de .deco/blocks/ para lá.

Como saber que terminou

Use o checklist pós-migração para validar:

tsc --noEmit limpo.
vite build sem warnings de import faltando.
wrangler deploy --dry-run passando.
Site renderiza a home local sem erros no console.
Todas as sections aparecem no admin via /live/_meta.