Migrate from Fresh

Fresh and the former deco.cx admin are retired. For an existing Fresh site, migrate the runtime to released Blocks 7.x and connect the Site Editor separately. The migration script automates mechanical transformations. An agent can help review its report and make site-specific changes; your team still validates behavior, integrations, and deployment.

This page is the decision tree — the actual playbook lives under Migration →.

When should I migrate?

You should migrate now if…	You should wait if…
You're investing in new features and want React + the broader ecosystem	You're in a feature freeze before a major sales event
You're hitting Deno Deploy concurrency limits or cold-start issues	You depend on islands or Preact-specific patterns that aren't yet ported
You want first-class edge caching on Cloudflare	Your team is mid-redesign and can't absorb a stack change
Your team already writes React day-to-day and Preact friction is real	You're happy on v1 and don't have a forcing function

Fresh documentation is retained as an archive for existing installations, not an ongoing maintenance promise.

What's automatic vs. manual

Automated by deco-migrate:

Import rewrites (Preact → React, $fresh/* → TanStack, @deco/deco/* → @decocms/blocks/*).
Vite + Wrangler scaffolding.
Worker entry + setup file generation.
Tailwind v3 → v4 token fixes.
Deletion of islands/, old Fresh routes, deno.json, static/ (moved to public/).

Manual fixes (the script flags these):

Platform hook implementations (custom useCart, useUser, useWishlist overrides).
useScript(fn) patterns that no longer hydrate cleanly — switch to inlineScript or move to "use client".
Third-party <head> scripts that cause CLS.
Any compat/ shims your team built.
Site-specific worker logic (custom proxies, AB harnesses).

The three paths

Path A — Run the script directly

# from your v1 site directory
npx -p @decocms/blocks-cli deco-migrate

This runs the 7-phase migration in-place and produces a MIGRATION_REPORT.md with the manual TODOs. See Migration script reference.

Path B — Use the Agent Skill

If you use Claude Code, Cursor, or Codex, install the migration skill and let the agent drive:

npx skills add decocms/blocks

Then in your editor: "migrate this project to TanStack Start." The skill knows what's automated and what isn't, and walks the manual fixes interactively. See Agent skills.

Path C — Manual port

For small storefronts (< 30 sections) or for teams who want full control, follow the Start fresh recipe to hand-create the minimum project layout, then copy your sections, components, and .deco/blocks/ content over.

What "done" looks like

Use the post-migration checklist to verify:

tsc --noEmit is clean.
vite build produces a bundle without warnings about missing imports.
wrangler deploy --dry-run succeeds.
The site renders the home page locally with no console errors.
Registered sections appear in Studio after the site connection is configured; verify /live/_meta metadata separately.