@decocms/start 0.21.0 → 0.21.1

package/.cursor/skills/deco-to-tanstack-migration/SKILL.md

@@ -15,6 +15,46 @@ Phase-based playbook for converting `deco-sites/*` storefronts from Fresh/Preact
 | **@decocms/apps** | `@decocms/apps` | VTEX/Shopify loaders, commerce types, commerce sdk (useOffer, formatPrice, analytics) | Passthrough HTML components, Preact/Fresh refs |
 | **Site repo** | (not published) | All UI: components, hooks, types, routes, styles | No compat/ layer, no aliases beyond `~` |
 
+### 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
 
 | Old Stack | New Stack |
@@ -278,6 +318,24 @@ npm run dev
 # 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
@@ -492,6 +550,7 @@ The conductor approach that worked (836 errors → 0 across 213 files) treated e
 | Vite configuration | `references/vite-config/` |
 | Automation commands | `references/codemod-commands.md` |
 | Admin schema composition | `src/admin/schema.ts` in `@decocms/start` |
+| Server functions (`createServerFn`) | `references/server-functions/` |
 | Common gotchas (45 items) | `references/gotchas.md` |
 | setup.ts template | `templates/setup-ts.md` |
 | vite.config.ts template | `templates/vite-config.md` |

package/.cursor/skills/deco-to-tanstack-migration/references/deco-framework/README.md

@@ -126,3 +126,49 @@ grep -r '@deco/deco' src/ --include='*.ts' --include='*.tsx'
 grep -r '\$fresh/' src/ --include='*.ts' --include='*.tsx'
 # Both should return ZERO matches
 ```
+
+## Deferred Sections and CLS Prevention
+
+When a CMS page wraps a section in `website/sections/Rendering/Lazy.tsx`, it becomes a `DeferredSection`. The `DeferredSectionWrapper` renders a skeleton via `getSectionOptions(key).loadingFallback`.
+
+**Problem**: `getSectionOptions` returns `undefined` if the section module hasn't loaded yet. The module is loaded async in a `useEffect` (`preloadSectionModule`), so on first paint `skeleton = null` — the space is blank and the footer jumps down as sections load (CLS).
+
+**Fix**: Use `registerSection` with `loadingFallback` pre-populated in `setup.ts` instead of including the section in the bulk `registerSections` call:
+
+```typescript
+import { registerSection, registerSections } from "@decocms/start/cms";
+import PDPSkeleton from "./components/product/PDPSkeleton";
+
+registerSections({
+  // ... all other sections (NOT the lazy-wrapped one)
+});
+
+// Pre-populate sectionOptions synchronously so DeferredSectionWrapper
+// has loadingFallback on the very first render — no null flash.
+registerSection(
+  "site/sections/Product/NotFoundChallenge.tsx",
+  () => import("./sections/Product/NotFoundChallenge") as any,
+  { loadingFallback: PDPSkeleton },
+);
+```
+
+**Why `as any`**: `registerSection` expects `Promise<SectionModule>` but the actual module export is wider (includes `LoadingFallback`, `loader`, etc.). The cast is safe.
+
+**Composite skeleton**: Create a `PDPSkeleton` that combines all `LoadingFallback` exports from the section's sub-components:
+
+```tsx
+// src/components/product/PDPSkeleton.tsx
+import { LoadingFallback as MountedPDPSkeleton } from "~/components/product/MountedPDP";
+import { LoadingFallback as ProductDescriptionSkeleton } from "~/components/product/MountedPDP/ProductDescription";
+import { LoadingFallback as ProductFAQSkeleton } from "~/components/product/MountedPDP/ProductFAQ";
+
+export default function PDPSkeleton() {
+  return (
+    <div>
+      <MountedPDPSkeleton />
+      <ProductDescriptionSkeleton />
+      <ProductFAQSkeleton />
+    </div>
+  );
+}
+```

package/.cursor/skills/deco-to-tanstack-migration/references/gotchas.md

@@ -1,6 +1,6 @@
 # Migration Gotchas
 
-45 pitfalls discovered during real migrations (espacosmart-storefront, osklen).
+46 pitfalls discovered during real migrations (espacosmart-storefront, osklen).
 
 ## 1. Section Loaders Don't Execute
 
@@ -717,3 +717,20 @@ Or in project `.npmrc` with an env var (for CI):
 ```
 
 **Tradeoff with `github:` syntax**: No semver resolution — `npm update` is meaningless. Pin to a tag for stability: `github:decocms/deco-start#v0.14.2`. Without a tag, you get HEAD of the default branch.
+
+## 46. `export type { X } from "..."` Does Not Scope `X` for Parameter Annotations
+
+Re-exporting a type makes it available to importers but does NOT bring it into scope in the same file:
+
+```typescript
+// BROKEN — Props is not in scope
+export type { Props } from "~/components/ui/Foo";
+export default function Foo({ bar }: Props) { } // Error: Cannot find name 'Props'
+
+// CORRECT — import separately, then re-export
+import type { Props } from "~/components/ui/Foo";
+export type { Props };
+export default function Foo({ bar }: Props) { }
+```
+
+This is a common pattern in section wrapper files (e.g. `src/sections/CountDownApp/CountDownApp.tsx`).

package/.cursor/skills/deco-to-tanstack-migration/references/platform-hooks/README.md

@@ -18,60 +18,27 @@ The storefront domain (e.g., `my-store.deco.site`) differs from the VTEX checkou
 
 Use TanStack Start `createServerFn` to create server-side proxy functions that the client hook calls transparently.
 
-### Server Functions (~/lib/vtex-cart-server.ts)
+> See `references/server-functions/README.md` for the full pattern and all TypeScript pitfalls.
 
-```typescript
-import { createServerFn } from "@tanstack/react-start";
+### Server Functions (`src/server/invoke.ts`)
 
-const ACCOUNT = "myaccount";
-const API_KEY = process.env.VTEX_APP_KEY!;
-const API_TOKEN = process.env.VTEX_APP_TOKEN!;
-
-export const getOrCreateCart = createServerFn({ method: "GET" })
-  .validator((orderFormId: string) => orderFormId)
-  .handler(async ({ data: orderFormId }) => {
-    const url = orderFormId
-      ? `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${orderFormId}`
-      : `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm`;
-    const res = await fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-VTEX-API-AppKey": API_KEY,
-        "X-VTEX-API-AppToken": API_TOKEN,
-      },
-      body: JSON.stringify({ expectedOrderFormSections: ["items", "totalizers", "shippingData", "clientPreferencesData", "storePreferencesData", "marketingData"] }),
-    });
-    return res.json();
-  });
+Wrap `@decocms/apps` VTEX actions in `createServerFn`. Always use `.inputValidator()` (not `.validator()`) and return `Promise<any>` to bypass `ValidateSerializable`:
 
-export const addItemsToCart = createServerFn({ method: "POST" })
-  .validator((data: { orderFormId: string; items: any[] }) => data)
-  .handler(async ({ data }) => {
-    const res = await fetch(
-      `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${data.orderFormId}/items`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "X-VTEX-API-AppKey": API_KEY, "X-VTEX-API-AppToken": API_TOKEN },
-        body: JSON.stringify({ orderItems: data.items }),
-      },
-    );
-    return res.json();
+```typescript
+import { createServerFn } from "@tanstack/react-start";
+import { getOrCreateCart } from "@decocms/apps/vtex/actions/checkout";
+
+// Preferred: wrap @decocms/apps actions (handles auth + API details internally)
+const _getOrCreateCart = createServerFn({ method: "POST" })
+  .inputValidator((data: { orderFormId?: string }) => data)
+  .handler(async ({ data }): Promise<any> => {
+    const result = await getOrCreateCart(data.orderFormId);
+    return (result as any).data;
   });
 
-export const updateCartItems = createServerFn({ method: "POST" })
-  .validator((data: { orderFormId: string; items: any[] }) => data)
-  .handler(async ({ data }) => {
-    const res = await fetch(
-      `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${data.orderFormId}/items/update`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "X-VTEX-API-AppKey": API_KEY, "X-VTEX-API-AppToken": API_TOKEN },
-        body: JSON.stringify({ orderItems: data.items }),
-      },
-    );
-    return res.json();
-  });
+export const invoke = {
+  vtex: { actions: { getOrCreateCart: _getOrCreateCart } },
+} as const;
 ```
 
 ### Hook (~/hooks/useCart.ts)

package/.cursor/skills/deco-to-tanstack-migration/references/server-functions/README.md

@@ -0,0 +1,120 @@
+# Server Functions (`createServerFn`)
+
+All VTEX API calls that need credentials (cart, MasterData, session, newsletter, shipping simulation) must run on the Worker — not on the client — to avoid CORS errors and keep secrets server-side.
+
+## Pattern: `src/server/invoke.ts`
+
+Create a single file that wraps `@decocms/apps` invoke functions in `createServerFn`. This keeps VTEX credentials inside the Worker and gives type-safe RPC from the browser.
+
+```typescript
+import { createServerFn } from "@tanstack/react-start";
+import {
+  getOrCreateCart,
+  addItemsToCart,
+  updateCartItems,
+  addCouponToCart,
+  updateOrderFormAttachment,
+  simulateCart,
+} from "@decocms/apps/vtex/actions/checkout";
+
+// CRITICAL: always chain .inputValidator() before .handler()
+// Without it, ctx.data is typed as `undefined` and every access fails.
+const _getOrCreateCart = createServerFn({ method: "POST" })
+  .inputValidator((data: { orderFormId?: string }) => data)
+  .handler(async ({ data }): Promise<any> => {
+    // Promise<any> bypasses ValidateSerializable on OrderForm.storeId: unknown
+    const result = await getOrCreateCart(data.orderFormId);
+    return (result as any).data;
+  });
+
+const _addItemsToCart = createServerFn({ method: "POST" })
+  .inputValidator((data: {
+    orderFormId: string;
+    orderItems: Array<{ id: string; seller: string; quantity: number }>;
+  }) => data)
+  .handler(async ({ data }): Promise<any> => {
+    const result = await addItemsToCart(data.orderFormId, data.orderItems);
+    return (result as any).data;
+  });
+
+// ... repeat for updateCartItems, addCouponToCart, simulateCart, etc.
+
+export const invoke = {
+  vtex: {
+    actions: {
+      getOrCreateCart: _getOrCreateCart,
+      addItemsToCart: _addItemsToCart,
+      // ...
+    },
+  },
+} as const;
+```
+
+## Required: `.inputValidator()`
+
+Without `.inputValidator()`, TanStack Start types `ctx.data` as `undefined`:
+
+```typescript
+// BROKEN — ctx.data is typed as undefined
+createServerFn({ method: "POST" })
+  .handler(async (ctx) => {
+    ctx.data.orderFormId; // TS Error: ctx.data is undefined
+  });
+
+// CORRECT
+createServerFn({ method: "POST" })
+  .inputValidator((data: { orderFormId: string }) => data)
+  .handler(async ({ data }) => {
+    data.orderFormId; // typed correctly
+  });
+```
+
+## Required: `Promise<any>` Return Type
+
+TanStack Start validates that return types are serializable via `ValidateSerializable`. Types with `unknown` fields (e.g. `OrderForm.storeId: unknown`) fail this check at compile time:
+
+```
+Type 'OrderForm' does not satisfy the constraint 'Serializable'.
+  Types of property 'storeId' are incompatible.
+    Type 'unknown' is not assignable to type 'Serializable'
+```
+
+**Fix**: Annotate the handler return as `Promise<any>`:
+
+```typescript
+.handler(async ({ data }): Promise<any> => {
+  return await doSomething(data);
+});
+```
+
+## Stripping Non-Serializable Properties
+
+Loader results that include function properties must have those functions removed before being returned — Seroval (TanStack's hydration serializer) cannot serialize functions.
+
+```typescript
+.handler(async ({ data }): Promise<any> => {
+  const result = await productReviewsLoader(data);
+  // Strip functions before serialization
+  const { getProductReview: _r, reviewLikeAction: _l, ...serializable } = result as any;
+  return serializable;
+});
+```
+
+## Invoke from `useCart`
+
+```typescript
+// ~/hooks/useCart.ts
+import { invoke } from "~/server/invoke";
+
+const updated = await invoke.vtex.actions.addItemsToCart({
+  data: { orderFormId, orderItems },
+});
+```
+
+## Verification
+
+```bash
+# No direct VTEX API calls from client components
+rg 'vtexcommercestable\.com\.br' src/ --include='*.tsx'
+# Should return ZERO (all calls go through invoke)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/cms/registry.ts

@@ -160,7 +160,24 @@ export type SyncSectionEntry =
  */
 export function registerSectionsSync(sections: Record<string, SyncSectionEntry>): void {
   for (const [key, entry] of Object.entries(sections)) {
-    const component = typeof entry === "function" ? entry : entry.default;
+    const raw = typeof entry === "function" ? entry : (entry as any).default;
+    // Accept functions and React wrapper objects (React.memo, forwardRef, lazy)
+    const REACT_WRAPPERS = [
+      Symbol.for("react.memo"),
+      Symbol.for("react.forward_ref"),
+      Symbol.for("react.lazy"),
+    ];
+    const component =
+      typeof raw === "function" ||
+      (raw != null &&
+        typeof raw === "object" &&
+        REACT_WRAPPERS.includes((raw as any).$$typeof))
+        ? raw
+        : undefined;
+    if (!component) {
+      console.warn(`[registerSectionsSync] "${key}" has no callable default export — skipping`);
+      continue;
+    }
     syncComponents[key] = component;
     resolvedComponents[key] = component;