Deco To Tanstack Migration

What Belongs Where

@decocms/start (framework)
├── src/cms/          # Block loading, page resolution, section registry
│   └── loader.ts     # loadBlocks, setBlocks, AsyncLocalStorage for per-request overrides
├── src/admin/        # Admin protocol: meta, decofile, invoke, render, schema composition
│   ├── meta.ts       # setMetaData() calls composeMeta() at startup; /deco/meta handler
│   ├── schema.ts     # MetaResponse type, composeMeta(), framework block schemas (pages)
│   ├── render.ts     # /live/previews/* for section + page preview (HTML shell)
│   ├── setup.ts      # Client-safe setup (setMetaData, setInvokeLoaders, setRenderShell)
│   ├── decofile.ts   # /.decofile read/reload
│   ├── invoke.ts     # /deco/invoke for loader/action calls
│   ├── cors.ts       # CORS + admin origin validation
│   └── liveControls.ts # Admin iframe bridge postMessage script
├── src/sdk/
│   ├── workerEntry.ts # createDecoWorkerEntry: outermost Cloudflare Worker wrapper
│   ├── useScript.ts, signal.ts, clx.ts, cachedLoader.ts, instrumentedFetch.ts
│   └── ...
├── src/hooks/        # DecoPageRenderer (uses registry, NOT hardcoded map), LiveControls
├── src/types/        # FnContext, App, AppContext, Section, SectionProps, Resolved
└── scripts/          # generate-blocks.ts, generate-schema.ts

@decocms/apps (commerce)
├── commerce/types/   # Product, AnalyticsItem, BreadcrumbList, Filter, etc.
├── commerce/utils/   # mapProductToAnalyticsItem, parseRange, formatRange
├── commerce/sdk/     # useOffer, useVariantPossibilities, formatPrice, relative, analytics
├── vtex/             # Client, loaders (actual VTEX API calls)
└── shopify/          # Client, loaders (actual Shopify API calls)

site repo (UI + business logic)
├── src/components/   # All UI components (Image, Picture, Seo, Theme, etc.)
├── src/hooks/        # useCart (real VTEX implementation), useUser, useWishlist
├── src/types/        # widgets.ts (string aliases), vtex.ts (OrderFormItem, etc.)
├── src/sdk/          # Site-specific contexts, usePlatform, useUI, useSuggestions
├── src/sections/     # All CMS-renderable sections
├── src/routes/       # TanStack Router routes
└── src/server/       # Server functions (invoke.ts — createServerFn wrappers for @decocms/apps)

Architecture Map

Migration Phases

Each phase has entry/exit criteria. Follow in order. Automation % indicates how much can be done with bulk sed/grep.

Phase 0 — Scaffold

Entry: Source site accessible, @decocms/start + @decocms/apps published

Actions:

1. Create TanStack Start project
2. Copy src/components/, src/sections/, src/islands/, src/hooks/, src/sdk/, src/loaders/ from source
3. Copy .deco/blocks/ (CMS content)
4. Copy static/ assets
5. Create package.json — see templates/package-json.md
6. Create vite.config.ts — see templates/vite-config.md
7. npm install

Exit: Empty project builds with npm run build

Phase 1 — Imports & JSX

Entry: Source files copied to src/

Actions (bulk sed — see references/codemod-commands.md):

1. Preact → React: from "preact/hooks" → from "react", etc.
2. ComponentChildren → ReactNode
3. class= → className= in JSX
4. SVG attrs: stroke-width → strokeWidth, fill-rule → fillRule, etc.
5. HTML attrs: for= → htmlFor=, fetchpriority → fetchPriority, autocomplete → autoComplete
6. Remove /** @jsxRuntime automatic */ pragma comments

Verification: grep -r 'from "preact' src/ | wc -l → 0

Exit: Zero preact imports, zero class= in JSX

See: references/imports/README.md

Phase 2 — Signals & State

Entry: Phase 1 complete

Actions:

1. Bulk: from "@preact/signals" → from "@decocms/start/sdk/signal" (module-level signals)
2. Manual: useSignal(val) → useState(val) (component hooks)
3. Manual: useComputed(() => expr) → useMemo(() => expr, [deps]) (component hooks)
4. For global reactive state: use signal() from @decocms/start/sdk/signal + useStore() from @tanstack/react-store

Verification: grep -r '@preact/signals' src/ | wc -l → 0

Exit: Zero @preact/signals imports

See: references/signals/README.md

Phase 3 — Deco Framework

Entry: Phase 2 complete

Actions (mostly bulk sed):

1. Remove $fresh/runtime.ts imports (asset() → identity, IS_BROWSER → typeof window !== "undefined")
2. from "deco-sites/SITENAME/" → from "~/"
3. from "$store/" → from "~/"
4. from "site/" → from "~/"
5. SectionProps → inline type or import { SectionProps } from "~/types/section"
6. useScript → from "@decocms/start/sdk/useScript"
7. clx → from "@decocms/start/sdk/clx"

Verification: grep -rE 'from "(@deco/deco|\$fresh|deco-sites/)' src/ | wc -l → 0

Exit: Zero @deco/deco, $fresh, deco-sites/ imports

See: references/deco-framework/README.md

Phase 4 — Commerce & Types

Entry: Phase 3 complete

Actions:

1. from "apps/commerce/types.ts" → from "@decocms/apps/commerce/types"
2. from "apps/admin/widgets.ts" → from "~/types/widgets" (create local file with string aliases)
3. from "apps/website/components/Image.tsx" → from "~/components/ui/Image" (create local components)
4. SDK utilities: ~/sdk/useOffer → @decocms/apps/commerce/sdk/useOffer, ~/sdk/format → @decocms/apps/commerce/sdk/formatPrice, etc.

Verification: grep -r 'from "apps/' src/ | wc -l → 0

Exit: Zero apps/ imports

See: references/commerce/README.md

Phase 5 — Platform Hooks

Entry: Phase 4 complete

Actions (manual implementation):

1. Create src/hooks/useCart.ts — module-level singleton + listener pattern
2. Create src/hooks/useUser.ts, src/hooks/useWishlist.ts (stubs or real)
3. Wire VTEX API calls via @decocms/apps invoke functions

Pattern: Closure state + _listeners Set + useState for re-renders. See espacosmart's useCart.ts as template.

Exit: Cart add/remove works, no apps/{platform}/hooks imports

See: references/platform-hooks/README.md, skill deco-apps-vtex-porting

Phase 6 — Islands Elimination

Entry: Phase 5 complete

Actions:

1. Audit src/islands/ — categorize each file:
   • Wrapper: just re-exports from components/ → delete, repoint imports
   • Standalone: has real logic → move to src/components/
2. Update all imports pointing to islands/ to point to components/
3. Delete src/islands/ directory

Verification: ls src/islands/ 2>/dev/null → directory not found

Exit: No islands/ directory

See: skill deco-islands-migration

Phase 7 — Section Registry

Entry: Phase 6 complete

Actions (critical — build src/setup.ts):

1. Register all sections via registerSections() with dynamic imports
2. Register critical sections (Header, Footer) via registerSectionsSync() + setResolvedComponent()
3. Register section loaders via registerSectionLoaders() for sections with export const loader
4. Register layout sections via registerLayoutSections()
5. Register commerce loaders via registerCommerceLoaders() with SWR caching
6. Wire onBeforeResolve() → initVtexFromBlocks() for VTEX config
7. Configure setAsyncRenderingConfig() with alwaysEager for critical sections
8. Configure admin: setMetaData(), setRenderShell(), setInvokeLoaders()
9. Register SEO sections via registerSeoSections() — identify sections that produce title/description/canonical (typically SEOPDP, SEOPLP). Register their loaders in registerSectionLoaders too.

Template: templates/setup-ts.md

Exit: setup.ts compiles, all sections registered

See: skill deco-async-rendering-site-guide

Phase 8 — Routes & CMS

Entry: Phase 7 complete

Actions:

1. Create src/router.tsx with scroll restoration
2. Create src/routes/__root.tsx with QueryClient, LiveControls, NavigationProgress, analytics. Include fallback description, og:site_name, og:locale in root head(). Do NOT include a hardcoded Device.Provider.
3. Create src/routes/index.tsx using cmsHomeRouteConfig({ defaultTitle, defaultDescription, siteName })
4. Create src/routes/$.tsx using cmsRouteConfig({ siteName, defaultTitle, defaultDescription }) — spread the full config, do NOT cherry-pick fields. The framework handles SEO head, cache headers, and staleTime/gcTime.
5. Create/port Seo.tsx component — must render JSON-LD structured data (NOT return null). Meta tags are handled by the framework's head().
6. Port device detection — use useSyncExternalStore + matchMedia for client-side. Use registerSectionLoaders for server-side UA detection. Do NOT use a hardcoded Device.Provider.

Templates: templates/root-route.md, templates/router.md

Exit: Routes compile, CMS pages resolve, PDPs have JSON-LD + meta description in <head>

See: skills deco-tanstack-navigation, deco-cms-route-config

Phase 9 — Worker Entry

Entry: Phase 8 complete

Actions:

1. Create src/server.ts — CRITICAL: import "./setup" MUST be the first line
2. Create src/worker-entry.ts — same: import "./setup" first
3. Wire admin handlers (handleMeta, handleDecofileRead, handleRender)
4. Wire VTEX proxy if needed

Template: templates/worker-entry.md

CRITICAL: Without import "./setup" as the first import, server functions in Vite split modules will have empty state (blocks, registry, commerce loaders). This causes 404 on client-side navigation.

Exit: npm run dev serves pages, admin endpoints work

See: skill deco-edge-caching

Phase 10 — Async Rendering

Entry: Phase 9 complete (site builds and serves pages)

Actions:

1. Identify lazy sections from CMS Lazy wrappers
2. Add export function LoadingFallback() to lazy sections
3. Configure registerCacheableSections() for SWR on heavy sections
4. Test deferred section loading on scroll

Exit: Above-the-fold renders instantly, below-fold loads on scroll

See: skill deco-async-rendering-site-guide

Post-Migration Verification

# 1. Build
npm run build

# 2. Zero old imports
grep -rE 'from "(preact|@preact|@deco/deco|\$fresh|deco-sites/|apps/)' src/ | wc -l
# Expected: 0

# 3. Dev server
npm run dev

# 4. SSR test — load homepage via F5
# 5. Client nav — click links, verify no 404
# 6. Console — no hydration warnings, no missing keys
# 7. Deferred — scroll down, sections load on scroll
# 8. Admin — /deco/meta returns JSON, /live/previews works

Quick Start (Full Migration)

1. Scaffold: npm create @tanstack/app@latest -- --template cloudflare-workers
2. Copy source: Move src/ from deco-site
3. Configure Vite: See references/vite-config/
4. Install deps: npm install @decocms/start @decocms/apps @tanstack/store @tanstack/react-store
5. Link local libs (if not published): cd apps-start && npm link && cd ../deco-start && npm link && cd ../my-store && npm link @decocms/apps @decocms/start
6. Rewrite imports (parallelizable):
   • Preact -> React: references/imports/
   • Signals -> TanStack Store: references/signals/
   • Deco framework -> inline: references/deco-framework/
   • Commerce/widget types -> @decocms/apps + local: references/commerce/
   • SDK utilities -> packages: ~/sdk/useOffer -> @decocms/apps/commerce/sdk/useOffer, ~/sdk/useScript -> @decocms/start/sdk/useScript, etc.
7. Create local UI components: Image.tsx, Picture.tsx, Seo.tsx, Theme.tsx in ~/components/ui/
8. Implement platform hooks: references/platform-hooks/
9. Build & verify: npm run build
10. Final audit: Zero from "apps/", from "$store/", from "preact", from "@preact", from "@deco/deco", from "~/sdk/useOffer", from "~/sdk/format" etc. -- all sdk utilities should come from packages

Key Principles

1. No compat layer anywhere -- not in @decocms/start, not in @decocms/apps, not in the site repo
2. Replace, don't wrap -- change the import to the real thing, don't create a pass-through
3. Types from the library, UI from the site -- Product type comes from @decocms/apps/commerce/types, but the <Image> component is site-local
4. One Vite alias maximum -- "~" -> "src/" is the only acceptable alias in a finished migration
5. tsconfig.json mirrors vite.config.ts -- only "~/*": ["./src/*"] in paths
6. Signals don't auto-subscribe in React -- reading signal.value in render creates NO subscription; use useStore(signal.store) from @tanstack/react-store
7. Commerce loaders need request context -- resolve.ts must pass URL/path to PLP/PDP loaders for search, categories, sort, and pagination to work
8. wrangler.jsonc main must be a custom worker-entry -- TanStack Start ignores export default in server.ts; create a separate worker-entry.ts and point wrangler to it
9. Copy components faithfully, never rewrite -- cp the original file, then only change: class → className, for → htmlFor, import paths (apps/ → ~/, $store/ → ~/), preact → react. NEVER regenerate, "clean up", or "improve" the component. AI-rewritten components are the #1 source of visual regressions -- the layout, grid classes, responsive variants, and conditional logic must be byte-identical to the original except for the mechanical migration changes
10. Tailwind v4 logical property hazard -- mixed px-* + pl-*/pr-* on the same element breaks the cascade. Replace mixed patterns with consistent longhand (pl-X pr-X instead of px-X) on those elements only
11. oklch CSS variables need triplets, not hex -- sites using oklch(var(--x)) must store variables as oklch triplets (100% 0.00 0deg), not hex values. oklch(#FFF) is invalid CSS

Worker Entry Architecture

The Cloudflare Worker entry point has a strict layering. Admin routes MUST be handled in createDecoWorkerEntry (the outermost wrapper), NOT inside TanStack's createServerEntry. TanStack Start's Vite build strips custom logic from createServerEntry callbacks in production.

Request
  └─> createDecoWorkerEntry(serverEntry, { admin: { ... } })
        ├─> tryAdminRoute()             ← FIRST: /live/_meta, /.decofile, /live/previews/*
        ├─> cache purge check            ← __deco_purge_cache
        ├─> static asset bypass          ← /assets/*, favicon, sprites
        ├─> Cloudflare cache (caches.open)
        └─> serverEntry.fetch()          ← TanStack Start handles everything else

Site worker-entry.ts Pattern

import "./setup";
import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
import {
  handleMeta, handleDecofileRead, handleDecofileReload,
  handleRender, corsHeaders,
} from "@decocms/start/admin";

const serverEntry = createServerEntry({
  async fetch(request) {
    return await handler.fetch(request);
  },
});

export default createDecoWorkerEntry(serverEntry, {
  admin: { handleMeta, handleDecofileRead, handleDecofileReload, handleRender, corsHeaders },
});

Key rules:

• ./setup MUST be imported first (registers sections, loaders, meta, render shell)
• Admin handlers are passed as options, NOT imported inside createDecoWorkerEntry
• /live/ and /.decofile are in DEFAULT_BYPASS_PATHS -- never cached by the edge

Admin Preview HTML Shell

The preview at /live/previews/* renders sections into an HTML shell. This shell MUST match the production <html> attributes for CSS frameworks to work:

// In setup.ts
setRenderShell({
  css: appCss,          // Vite ?url import of app.css
  fonts: ["https://fonts.googleapis.com/css2?family=Montserrat:wght@400;500;600;700&display=swap"],
  theme: "light",       // -> <html data-theme="light"> (required for DaisyUI v4)
  bodyClass: "bg-base-100 text-base-content",
  lang: "pt-BR",
});

Without data-theme="light", DaisyUI v4 theme variables (--color-primary, etc.) won't activate in the preview iframe, causing color mismatches vs production.

Client-Safe vs Server-Only Imports

@decocms/start has two admin entry points:

• @decocms/start/admin -- server-only handlers (handleMeta, handleRender, etc.) -- these may transitively import node:async_hooks
• @decocms/start/admin/setup (re-exported from @decocms/start/admin) -- client-safe setup functions (setMetaData, setInvokeLoaders, setRenderShell) -- NO node: imports

The site's setup.ts can safely import from @decocms/start/admin because it only uses the setup functions. But the barrel export must be structured so Vite tree-shaking doesn't pull server modules into client bundles.

Admin Self-Hosting Architecture

When a site is self-hosted (deployed to its own Cloudflare Worker), the admin communicates with the storefront via the productionUrl:

admin.deco.cx
  └─> createContentSiteSDK (when env.platform === "content" OR devContentUrl is set)
        ├─> fetch(productionUrl + "/live/_meta")     ← schema + manifest
        ├─> fetch(productionUrl + "/.decofile")      ← content blocks
        └─> iframe src = productionUrl + "/live/previews/*"  ← section preview

Content URL Resolution Priority

1. devContentUrl URL param → saved to localStorage[deco::devContentUrl::${site}] → used by Content SDK
2. devContentUrl from localStorage → used by Content SDK
3. site.metadata.selfHosting.productionUrl (Supabase) → used by Content SDK
4. https://${site}.deco.site → fallback

Environment Platform Gate

The admin only uses createContentSiteSDK when:

• devContentUrl is set (localStorage or URL param), OR
• The current environment has platform: "content"

Setting productionUrl in Supabase alone is NOT sufficient. The environment must be "content" platform. This happens when connectSelfHosting is called with a productionUrl -- it deletes/recreates the staging environment as platform: "content".

For local dev, use the URL param shortcut: