docs(skills): autoconfigApps fails in prod build + validate on prod not dev

[hugo-ccabral]

Second batch of storefront-tanstack findings for the decocms-v6-to-v7-upgrade skill (follow-up to #336), from debugging why the migrated PDP rendered "Page not found" only in production.

The finding

autoconfigApps configures each app via its registry entry's module — for @decocms/apps-shopify that's () => import("./mod"). That dynamic import resolves under vite dev but NOT in the vite/workerd production bundle, and autoconfig's catch {} swallows the error — so the app is skipped, its commerce loaders never register, and (deferred) PDP/shelves resolve to null. Invisible in dev, in curl'd SSR HTML, and even in a direct resolveValue. Fix: pass the module statically (import * as shopifyMod from "@decocms/apps-shopify/mod"; [{ ...SHOPIFY_REGISTRY_ENTRY, module: async () => shopifyMod }]).

Also

• New verification gate: bun run dev is not a pass — validate the production build (bun run preview) + a client-deferred page (PDP) in a headless browser (Playwright / deco-e2e-testing), since deferred /_serverFn/ loads + prod-only failures don't show in dev/curl. Includes how to read the deferred request/response + x-cache.
• Corrected the .ts-fix version reference to 7.11.2 (it shipped as a patch, not 7.12.0).

Docs-only.

🤖 Generated with Claude Code

---

Summary by cubic

Documented a production-only autoconfigApps failure and how to fix it, and added a gate to validate the production build + deferred PDP/PLP pages. Also corrected the .ts suffix fallback fix version to @decocms/blocks 7.11.2.

• Bug Fixes

  • autoconfigApps uses dynamic () => import("./mod") in each registry entry, which works in vite dev but fails in the vite/workerd production bundle. The silent catch {} skips the app, so its loaders never register and PDPs render "Page not found". Fix: pass the module statically, e.g. import * as shopifyMod from "@decocms/apps-shopify/mod"; [{ ...SHOPIFY_REGISTRY_ENTRY, module: async () => shopifyMod }].
  • Corrected docs to reflect the .ts/.tsx resolveType fallback shipped in @decocms/blocks 7.11.2 (not 7.12.0).

• Migration

  • New verification gate: do not rely on bun run dev. Validate the production bundle with bun run preview and load a real deferred PDP/PLP in a headless browser, ensuring product data renders (and inspecting the /_serverFn/ call and x-cache).

^{Written for commit 0830b3d. Summary will update on new commits.}