feat: the v7-to-v8 migrator and skill use @decocms/tanstack and @decocms/nextjs

TL
3h ago
+2878-174

Stacked on #699 (P6). P7 of the v8 framework packages: the v7-to-v8 migration script and the deco-v7-to-v8-migration skill use @decocms/tanstack and @decocms/nextjs, so sites stop copying v7's worker, draft, Studio-bridge and image code into their own tree.

After the product owner's review (2026-10-14), this branch follows the stack below it: @decocms/blocks exports no draft names or Studio origins (they are in each binding's root), @decocms/blocks/image is platform-neutral, and VTEX's and Shopify's image URL helpers live in @decocms/apps-vtex/image and @decocms/apps-shopify/image.

@decocms/tanstack/react: Image, Picture, Source

  • They take v7's props and render v7's markup, so a call site only changes its import.
  • The URLs come from ImageUrlProvider (an ImageUrl the site builds with createImageUrl) instead of v7's registerImageCdnDomain/registerImageQuality module state. A site puts the provider around its pages with createDecoRouter's Wrap option.
  • No platform knowledge. @decocms/tanstack depends on no @decocms/apps-* package. A site that shows VTEX or Shopify images lists the platform's helper first: 
    createImageUrl({ providers: [vtexCatalog(), shopifyCdn(), decoCdn({ sources: "all", ...byRelease })] })
    That gives v7's URLs byte for byte, except PO-approved fix 2 (#694): an already-resized Deco CDN URL in content is re-resized from its src. byRelease depends on the @decocms/blocks 7.x release the site ran, because v7's Image changed across releases (e.g. stripAssetHosts: "leading" from 7.71.4); the skill has the table and the script reports the line for the site's version. Keep both helpers whatever the platform: v7 resized VTEX and Shopify images on every site. Without a provider, every source goes through the Deco image CDN (DECO_IMAGE_URL, which replaces the earlier V7_IMAGE_URL).
  • Golden markup: tests/tanstack-image-markup.golden.test.ts renders the 160 cases recorded from v7's own components (v7's defaults, and a site with another CDN host and quality) with the helpers supplied as a site would. Zero cases changed. It sits outside the package because the package can't depend on apps-*, not even for tests. With no provider, the non-VTEX/Shopify cases also match.
  • More golden markup (review pass): tests/__fixtures__/tanstack-v7-image-markup-nowidth-nuvemshop.jsonl, 90 more cases from v7's own components (7.x latest): Image/Source without a width (v7's width=NaN … NaNw candidates, which blocks' srcSet now reproduces, #694) and Nuvemshop product images (v7 from 7.77.1 picks one of the CDN's fixed sizes). No @decocms/apps-* package covers Nuvemshop, so the test holds a store's own provider (the one framework-code.md gives) to v7's markup. Zero changed; dropping that provider, or the srcSet fix, makes it fail.
  • Differences from v7: no "Missing height" warning on every render, and PO-approved fix 2 (#694, in decoCdn, not in the component): an already-resized Deco CDN URL that v7 turned into src=image is re-resized from its src. The component itself has no image-URL rule of its own.

The migration script

  • Imports (imports.ts):

    • It moves the v7 names the bindings keep: createDecoRouter and the search functions go to /router, NavigationProgress/StableOutlet to /react, decoServerFnFetch to /start, and on a TanStack site Image/Picture/Source to /react.
    • DRAFT_PARAM, DRAFT_COOKIE, DRAFT_HEADER, draftResponseHeaders, STUDIO_ORIGINS, STUDIO_FRAME_ANCESTORS and isStudioOrigin imported from @decocms/blocks move to the site's binding root (@decocms/tanstack or @decocms/nextjs). A site with neither binding gets a report line instead.
    • An import that mixes moved and other names is split.
    • Every other binding import is reported name by name with its replacement.
    • The image hints (registerImageCdnDomain, getOptimizedMediaUrl, …) and the Image note spell out v7's URLs as v8 code: createImageUrl and decoCdn from @decocms/blocks/image, vtexCatalog from @decocms/apps-vtex/image, shopifyCdn from @decocms/apps-shopify/image, with the decoCdn options of the site's 7.x release (siteBlocksVersion: the installed copy, else the package.json range). Rows: before 7.71.0 legacyHosts: [] with decoims.com as the default domain; 7.71.0 to 7.71.3 legacyHosts: []; 7.71.4 legacyHosts: ["decoims.com"]; 7.71.5 on nothing more, plus a Nuvemshop provider from 7.77.1. stripAssetHosts is left at decoCdn's default, "leading", on every row (see the PO decisions below). Each row was checked against that release's hooks/Image.tsx over every golden source, six widths, three heights, two fits and three CDN configs (Cloudflare, decoims.com + quality, an Azion host): no changed case.
    • Left alone as v8: the platform-neutral names of @decocms/blocks/image (now a list, not *, so a stale name is reported), @decocms/apps-vtex/image, @decocms/apps-shopify/image, the @decocms/tanstack root, and the @decocms/nextjs root with its draft names and Studio origins.

  • Settings (siteSettings.ts):

    • <site>.deco.site and <site>.deco-cx.workers.dev are no longer written into CMS.json, because the bindings allow them from their site option.
    • The report says which site to pass.
    • DECO_ALLOWED_PREVIEW_HOSTS maps to previewHosts.

  • Dependencies note: @decocms/blocks ^8.3.0 plus the matching binding ^8.3.0.

  • A site's own copy of v7's image helper (f80cf1ab). A site that kept a copy of hooks/Image.tsx under src/ (a file that defines getOptimizedMediaUrl) serves the copy's URLs, not its release's. One storefront's copy was 7.20.7, edited to 7.77.1's CDN domain and decoims.com rule. The 7.20.7 row would have given it legacyHosts: [] on decoims.com. The script (scripts/imageCopy.ts) now reads these rules from the copy:

    • the initial domain and quality;
    • asset-host stripping (anywhere or leading);
    • the decoims.com rule (none, Cloudflare-only or always);
    • the VTEX, Shopify and Nuvemshop rules.

    It also reads the site's registerImageCdnDomain/registerImageQuality literals through the TypeScript AST, so a comment doesn't count. The copy gets its own report line with the createImageUrl call, and the Image note uses that line too. A copy whose rules the script can't read is reported for comparison by hand. Fuzz check: the options read from each 7.x release's Image.tsx (7.2.0, 7.51.0, 7.71.0, 7.71.4, 7.71.5, 7.77.1) and from both storefronts' pre-migration copies, each with four registered domains, give 0 differing URLs (1,944 cases each) besides fix 2's. On those two storefronts' trees, the script prints exactly the imageUrl they ship. The demo storefront's copy (7.64.3) and its release row agree.

The skill

  • framework-code.md covers the TanStack image setup with the platform helpers. It now says that options come from a site's own copy when it has one, and names fix 2 (an already-resized Deco CDN URL is re-resized from its src). For next/image it names fix 1 (via: "thumbor"). script-steps.md and import-map.md say the same.
  • framework-code.md and nextjs.md cover the Next.js loader: vtexCatalogWebp() + vtexFileManager({ via }) + decoCdn({ quality: "high", fit: "contain", layout: "quality-last" }). The earlier line about file-manager images moving to Thumbor is gone: URLs match the site's current loader.
  • framework-code.md also gives the draft names and Studio origins per binding.
  • import-map.md: moved-name rows, the left-alone list, and the image row.
  • Also updated: manual-steps.md, script-steps.md and SKILL.md (10,236 bytes, under the 10 KB budget).
  • Outside the skill: packages/tanstack/README.md, CLAUDE.md and knip.json.

PO decisions of 2026-10-15 (merged up from #693–#699, then here)

  • Image rule (decision 5). decoCdn strips only a leading asset host by default now (#694), so the script writes no stripAssetHosts for any site. A site whose v7 code stripped the asset hosts anywhere (7.x before 7.71.4, or a copy of v7's image helper that did) moves to "leading" too, as approved, and never gets stripAssetHosts: "anywhere". The report's new "image URLs" line counts and lists the URLs in .deco/blocks and src/ whose image URL changes: a URL that merely contains an asset URL (https://other.host/https://assets.decocache.com/…). changedByLeadingStrip is tested against decoCdn itself (both settings, eight sources). On a fresh copy of the demo storefront (7.64.3), the line says no URL changes.
  • Dev mode (decision 1). The skill no longer tells Next.js sites to pass dev: isNextDev(...): createCMS reads NODE_ENV, and isNextDev is gone from @decocms/nextjs (#697). The script never wrote a dev flag. telemetry.md (merge conflict resolved) says to leave dev out.
  • Schema check in CI (decision 2). New scripts/ciSchemaCheck.ts, run as part of the scripts step. It adds deco schema --check right after the install step of the site's pull-request workflows, or of every workflow when none runs on pull requests, and never to v7's regen-blocks. It uses the lockfile's runner (bunx, pnpm exec, yarn, npx) and the install's working directory (the site's folder in a monorepo). Comments and layout are kept, a second run changes nothing, and a workflow it can't edit (none, or a multi-line install) gets a report line. On the demo storefront, whose only workflow posts preview links, the script reports that line.
  • Tests: ciSchemaCheck.test.ts (5) and 4 new imageCopy.test.ts tests. Mutations that widen the install match, drop the working directory, skip the report, misread 7.71.0–7.71.3 or stop comparing against the leading strip each fail them. The skill's scripts pass 90/90.
  • Gates at aedc30b7: bun run check, bun run build, skills:check and skills:readme:check pass. Plain Node imports all 38 built exports, @decocms/nextjs has no isNextDev, and deco --help lists --check. bun run test (2 GB): 2,482 passed, 4 failed, 95 skipped. The failures are DS-2 (known; the fix is on its own PR against main) and three timeouts under full-suite load (two in schema.test.ts, plus tr-13). Those three files run alone: 102 passed, 1 failed (DS-2).

Tests

  • steps.test.ts:

    • The draft names move per binding and are reported without one.
    • The image hint names the apps-*/image helpers.
    • Every move target exports the name.
    • The runtime exports of the @decocms/tanstack root, the @decocms/nextjs root, /preview and @decocms/blocks/image are all listed.
    • @decocms/blocks exports none of the moved names.
    • @decocms/blocks/image's list names no platform.

  • bindings.test.ts: a v7 TanStack Start fixture goes through migrate, then the rewritten files type-check against this repo's sources. That includes a prerelease DRAFT_COOKIE/STUDIO_ORIGINS import (moved to @decocms/tanstack) and the imageUrl + ImageUrlProvider module the report asks for, built on @decocms/apps-vtex/image and @decocms/apps-shopify/image. Feeding it an old helper signature makes it fail.

  • steps.test.ts also checks the per-release table and how the version is read.

  • imageCopy.test.ts (7 tests) uses verbatim excerpts of each release form and of an edited copy. It covers:

    • telling a copy apart from code that only uses the helper;
    • the options for each release form, the registered domain and quality, and an edited copy's own rules;
    • an unreadable copy;
    • the report line taking priority over the release's.

    A mutation that ignores the copy makes it fail.

  • Results (adversarial pass, 2026-10-14, at db44e19b): fix 2 narrowed in #694 (6b7e7001: decoCdn's default match is back to the pre-fix sources, so a Deco CDN URL that used to pass through, e.g. deco-assets.edgedeco.com under sources: "deco", is unchanged again) and merged up. bun run check, bun run build, skills:check and skills:readme:check pass. bun run test: 2,455 passed, 3 failed under full-suite load: DS-2 (known), a schema.test.ts timeout and a syntax.cli.test.ts timeout (saved-01); those three files alone: 89 passed, 1 failed (DS-2). Copy-reading fuzz rerun with a strict fix-2 rule (a difference counts as fix 2 only when v7 wrote src=image or src=<cdn>/image): 7 releases' Image.tsx + 2 storefront copies x 4 registrations, 1,944 cases each, 0 other differences.

  • Results (fix 2 + copy reading, 2026-10-14, at f80cf1ab):

    • bun run check, bun run build, skills:check and skills:readme:check pass.
    • bun run test: 2,453 passed, 4 failed under full-suite load: DS-2 (known), two schema.test.ts timeouts and an HRI-3 timing assertion. Run alone, schema.test.ts passes 58/58 and delivery.test.ts passes 94/94 (twice); delivery.cli.test.ts fails only DS-2.
    • The fix-2 golden cases pass: blocks 160 and next/image 60, all marked approved. The TanStack markup goldens (250 cases) have no already-resized CDN source, and all of them still match.

  • Results (review pass, 2026-10-14, at 73c0a225):

    • bun run check, bun run build, skills:check and skills:readme:check pass; plain Node imports all 14 built @decocms/blocks exports and none exports a draft name, a Studio origin or a platform name.
    • bun run test (at 2755ef95): 2,434 passed, 8 failed: DS-2 (known) plus load timeouts in schema, serve, cli (cli-01, cli-02) and migrate. Those five files run alone: 274 passed, 1 failed (DS-2). The skill's scripts pass 74/74 at 73c0a225.

  • Earlier results:

    • bun run check, bun run build, skills:check and skills:readme:check pass.
    • bun run test: 2,433 passed, 7 failed. The failures are DS-2 (known) and six tests that timed out under full-suite load, in check, schema, cli cp-51, HRI-3 and HRI-4. Those five files pass when run alone (338/339, the only failure being DS-2).

For the PO

  • The image components are in @decocms/tanstack, not in blocks, and know no platform. PageBlocks and pageRoute from the plan are still not shipped.
  • blocks-cli templates live only on 7.x, so nothing changed for them here.
  • On Next.js, passing site lets <site>.deco.site preview, which v7's Next binding didn't allow. The report and nextjs.md say so, and say to leave site out to keep v7's hosts.
  • No release or npm action in this PR.
  • Decided (PO, 2026-10-14): Nuvemshop's image rule stays in the store's own code. There is no @decocms/apps-nuvemshop. A Nuvemshop store keeps v7's URLs with a provider in its own imageUrl.ts; the skill gives that provider, and the golden test holds it to v7.
  • Approved (PO, 2026-10-14): fixes 1 and 2 from #694. Fix 2 is merged here and documented in the skill. Fix 1 is a site change.

https://claude.ai/code/session_01WNwbSEePYNcY5YCgqZURig

Review round (2026-10-15)

  • a771f6cf: migrate() itself is now tested to add deco schema --check to the site's pull-request CI. Before, only addSchemaCheck was tested, so dropping its call from migrate() failed nothing; now it fails the new test.

Studio's "." and outlines in the skill (2026-10-16, 19393a99)

  • framework-code.md and the import map: a TanStack page loader returns pathTemplate; a site with its own document renders DecoPreview (bridge, badge and draft) rather than StudioBridge alone; a Next.js page renders StudioPage; page sections keep v7's <section id data-manifest-key> wrapper, which Studio's editor outlines, selects and scrolls to. A Next site whose own section list drops it (v7 Next storefronts did) makes that wrapper a <section>.
  • The import check accepts StudioPage and StudioPageInfo; the import test covers them and DecoPreview.

Main refresh (2026-10-17, ced92e19)

  • Merged P6 6ce49dcf into this branch (normal merge, no conflicts), then merged up the stack to M2 #707.
  • Gates at the top of the stack (M2 5131a3c1): bun run check, bun run build, skills:check, skills:readme:check pass. bun run test (2 GB memory cap): 122 files pass, 1 skipped; 2,745 tests pass, 95 skipped, 0 fail. DS-2 now passes (fixed on main by #709); no timeouts this run.
  • CI on this PR's new head: all checks pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_016ZsmzpZ2zahRBoATBb2tBu