Migration overview

Fresh and the former deco.cx admin are retired. This is the entry point for moving an existing Fresh/Deno website to released Blocks 7.x; editor migration to Studio is a separate step. The full playbook lives across this section; this page tells you which to read in what order.

Read this in order

1. Migration overview — you are here.
2. Playbook — the manual walkthrough, phase by phase.
3. Migrate script — what npx -p @decocms/blocks-cli deco-migrate does.
4. Agent skills — using AI coding tools to handle the long tail.
5. Checklist — verification steps before merging.

Decision matrix

Version compatibility

The migration target is Blocks 7.x, using the split @decocms/blocks, @decocms/blocks-admin, @decocms/tanstack, and @decocms/blocks-cli packages. Install compatible 7.x provider packages individually; record the resolved versions in your lockfile. Blocks Next has a separate API and is not this migration target.

Use the tested dependency setup from the 7.x quickstart and Fresh migration reference. Do not use retired 2.x/1.x package examples or a literal @decocms/apps-* dependency.

What survives migration

• Repository content — preserve the saved JSON, then reconcile renamed keys, installed apps, and registered functions against the migration report.
• All section Props interfaces — no schema rewrites.
• Matcher configuration — port its functions and verify real requests, assignment, and caching against the 7.x contract.
• Site SEO — configureWebsite({ seo }) from @decocms/apps-website mirrors v1 SEO config.
• Commerce configuration — preserve required provider settings and validate the current loader/action signatures, cookies, and runtime registration.

What you'll have to redo

• Anything in src/islands/ — islands don't exist in React. Most become "use client" components, some merge into their parent section, some become helpers.
• useScript(fn) patterns — the v1 script extraction pattern doesn't survive. Use inlineScript, move to the client, or restructure.
• Custom Fresh routes — port to TanStack Router file routes.
• Deno.env reads — use the supported Worker environment access or server environment mechanism in your 7.x setup; RequestContext.current has no env property.
• Custom build steps in deno.json — translate to npm scripts in package.json.

Time budget (rough)

For a typical mid-sized storefront (50-100 sections):

So: roughly 1-2 weeks for a single engineer, faster with a pair, slower if the site has heavy custom logic.

What NOT to do

• Keep runtime imports separate. Port the application on its own branch or worktree. A monorepo can contain isolated Fresh and 7.x applications; do not mix their incompatible runtime imports in one application.
• Review migration shims. Replace obsolete imports and remove site-specific shims only after verifying their replacements; framework-provided compatibility behavior is documented in the 7.x migration guide.
• Don't manually fix imports the script will handle. Run the script first; it covers 70+ rewrite rules.
• Don't skip the checklist. Type-clean, lint-clean, and build-clean isn't the same as runtime-correct — verify the cart, the PDP, the PLP, and search end-to-end.

See also

• Migration playbook
• Migrate script
• Agent skills
• Migration checklist