@decocms/start 2.21.0 → 2.23.0

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

@@ -43,7 +43,7 @@ Each phase has entry/exit criteria. Follow in order. Automation % indicates how
 | [2](#phase-2--signals--state) | Signals & State | ~50% | `references/signals/` |
 | [3](#phase-3--deco-framework) | Deco Framework Elimination | ~80% | `references/deco-framework/` |
 | [4](#phase-4--commerce--types) | Commerce Types & UI | ~70% | `references/commerce/` |
-| [5](#phase-5--platform-hooks) | Platform Hooks | 0% | `references/platform-hooks/` |
+| [5](#phase-5--platform-hooks) | Platform Hooks (factories, W12+) | template | `references/platform-hooks-factories.md` |
 | [6](#phase-6--islands-elimination) | Islands Elimination | ~60% | `references/islands.md` |
 | [7](#phase-7--section-registry) | Section Registry & Setup | 0% | `references/async-rendering.md` |
 | [8](#phase-8--routes--cms) | Routes & CMS | template | `references/navigation.md` |
@@ -152,14 +152,18 @@ See: `references/commerce/README.md`, `references/vtex-commerce.md`
 
 **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
+**Actions (Wave 12+ factory-based — current)**:
+1. `src/hooks/useCart.ts` — 5-line shim around `createUseCart` from `@decocms/apps/vtex/hooks/createUseCart`
+2. `src/hooks/useUser.ts` — 5-line shim around `createUseUser`
+3. `src/hooks/useWishlist.ts` — 5-line shim around `createUseWishlist`
+4. The migration template (`scripts/migrate/templates/hooks.ts`) emits all three for VTEX sites automatically.
+
+For non-VTEX platforms, scaffold no-op stubs using `@decocms/start/sdk/signal` (see factories doc § "Non-VTEX platforms").
 
 **Exit**: Cart add/remove works, no `apps/{platform}/hooks` imports
 
-See: `references/platform-hooks/README.md`
+See: `references/platform-hooks-factories.md` (canonical, Wave 12+).
+Pre-W12 manual approach is preserved at `references/platform-hooks/README.md` for sites that haven't migrated to factories yet.
 
 ---
 
@@ -356,7 +360,8 @@ For sites with 100+ sections:
 | Signals → TanStack Store | `references/signals/` |
 | Deco framework elimination | `references/deco-framework/` |
 | Commerce & widget types | `references/commerce/` |
-| Platform hooks (VTEX) | `references/platform-hooks/` |
+| Platform hooks (VTEX, factories — Wave 12+) | `references/platform-hooks-factories.md` |
+| Platform hooks (manual, legacy pre-W12) | `references/platform-hooks/README.md` |
 | Vite configuration | `references/vite-config/` |
 | Automation commands | `references/codemod-commands.md` |
 | Islands elimination | `references/islands.md` |

package/.agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md

@@ -62,6 +62,27 @@ Both rewrite to the same React `onClick` / `onChange` etc.
 The biggest bucket. Almost always a `useScript`-wrapped function
 attached as an event handler, with no fetch involved.
 
+> **Codemod available** (since `@decocms/start >= 2.21.0`). The
+> migration script's `transforms` pipeline now runs
+> `htmx-on-event-rename`, which mechanically rewrites
+> `hx-on:click={…}` → `onClick={…}` (and every other standard DOM
+> event in the [STANDARD_EVENT_MAP](https://github.com/decocms/deco-start/blob/main/scripts/migrate/transforms/htmx-on-events.ts)
+> table) for both colon and dash variants. Handler bodies are
+> preserved verbatim; if the body references Fresh-only globals
+> (`useScript(…)`, `globalThis.window.STOREFRONT`, `STOREFRONT.…`),
+> the codemod injects a single MIGRATION TODO comment at the top
+> of the file pointing back here. **htmx lifecycle events**
+> (`hx-on:htmx-config-request`, `hx-on-htmx-before-request`, etc.)
+> and unknown custom events (`hx-on:my-custom-thing`) are left
+> alone — those need manual rewrite, and the `htmx-residue` audit
+> rule catches them.
+>
+> Smoke result on als-storefront (754 files): codemod renames 98
+> `hx-on:*` attributes across 71 files; 67 of those files (94 %)
+> get the body-TODO. Engineers still own the body rewrite below;
+> the codemod just removes the dead `hx-*` attribute name so the
+> file compiles in React.
+
 ### Before
 
 ```tsx

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

@@ -1,16 +1,29 @@
-# Platform Hooks Migration
+# Platform Hooks Migration (legacy reference)
 
-Platform hooks (useCart, useUser, useWishlist) are the most complex migration target because they have real business logic.
+> **This document describes the pre-Wave-12 manual approach.** New
+> migrations should follow
+> [`platform-hooks-factories.md`](../platform-hooks-factories.md), which
+> covers the `createUseCart` / `createUseUser` / `createUseWishlist`
+> factories from `@decocms/apps/vtex/hooks`. The factories collapse
+> everything below into a 5-line site shim per hook.
+>
+> This file is kept for sites that scaffolded before the factories
+> existed — typically sites with `src/lib/vtex-cart-server.ts` or
+> hand-rolled `createServerFn` calls to VTEX endpoints inside
+> `src/hooks/useCart.ts`. See the **"Migrating off the manual approach"**
+> section in the new doc for the cleanup playbook.
 
-## Strategy
+---
+
+## Strategy (legacy)
 
 All hooks are **site-local**. No Vite alias tricks. No compat layers.
 
-- Active platform hooks (VTEX for this store) -> `~/hooks/useCart.ts` with real implementation
-- Inactive platform hooks (Wake, Shopify, etc.) -> `~/hooks/platform/{name}.ts` with no-op stubs
-- Auth hooks -> `~/hooks/useUser.ts`, `~/hooks/useWishlist.ts`
+- Active platform hooks (VTEX for this store) → `~/hooks/useCart.ts` with real implementation
+- Inactive platform hooks (Wake, Shopify, etc.) → `~/hooks/platform/{name}.ts` with no-op stubs
+- Auth hooks → `~/hooks/useUser.ts`, `~/hooks/useWishlist.ts`
 
-## VTEX useCart (Real Implementation)
+## VTEX useCart (Manual Implementation)
 
 ### Why Server Functions Are Required
 
@@ -18,7 +31,7 @@ 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)
+### Server Functions (`~/lib/vtex-cart-server.ts`)
 
 ```typescript
 import { createServerFn } from "@tanstack/react-start";
@@ -40,50 +53,46 @@ export const getOrCreateCart = createServerFn({ method: "GET" })
         "X-VTEX-API-AppKey": API_KEY,
         "X-VTEX-API-AppToken": API_TOKEN,
       },
-      body: JSON.stringify({ expectedOrderFormSections: ["items", "totalizers", "shippingData", "clientPreferencesData", "storePreferencesData", "marketingData"] }),
+      body: JSON.stringify({
+        expectedOrderFormSections: [
+          "items",
+          "totalizers",
+          "shippingData",
+          "clientPreferencesData",
+          "storePreferencesData",
+          "marketingData",
+        ],
+      }),
     });
     return res.json();
   });
-
-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();
-  });
-
-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();
-  });
 ```
 
-### Hook (~/hooks/useCart.ts)
+> **Don't write code like this in new sites.** The factories already wrap
+> all canonical VTEX action endpoints (cart, session, masterdata,
+> newsletter, checkout) in `@decocms/apps/vtex/actions/*`. The migration
+> template scaffolds `src/server/invoke.gen.ts` which exposes them as
+> typed server functions; `~/server/invoke.ts` then re-exports them
+> under `invoke.vtex.actions.*`. The factory consumes that surface and
+> returns the legacy hook shape.
 
-Key design decisions:
+### Hook (`~/hooks/useCart.ts`)
+
+Key design decisions of the legacy manual hook:
 - **Module-level singleton state** shared across all component instances
 - **Pub/sub pattern** (`_listeners` Set) for notifying React components of changes
-- **Cookie-based session**: reads/writes `checkout.vtex.com__orderFormId` on the **client** side (not VTEX's domain cookie)
+- **Cookie-based session**: reads/writes `checkout.vtex.com__orderFormId` on the **client** side
 - Returns `cart` and `loading` with `.value` getter/setter for backward compat with Preact-era components
 - Lazy initialization: cart is fetched on first component mount, not on module load
 - Exports `itemToAnalyticsItem` for cart-specific analytics mapping
 
+The factory in `@decocms/apps/vtex/hooks/createUseCart` ships *exactly*
+these semantics — that's the implementation behind the new shim. If your
+site needs to extend behaviour (e.g. extra analytics events, custom
+post-add hooks), prefer wrapping the factory's exports rather than
+forking back to a manual hook; the factory leaves space for that
+without giving up the upgrade path.
+
 ### Cross-Domain Checkout
 
 The minicart's "Finalizar Compra" button must link to the VTEX checkout domain with the `orderFormId` as a query parameter — the VTEX domain can't read the storefront's cookies:
@@ -92,10 +101,8 @@ The minicart's "Finalizar Compra" button must link to the VTEX checkout domain w
 const checkoutUrl = `https://secure.${STORE_DOMAIN}/checkout/?orderFormId=${orderFormId}`;
 ```
 
-### VTEX Types (~/types/vtex.ts)
-
-Site-local types for VTEX-specific structures:
-- `OrderFormItem`, `SimulationOrderForm`, `Sla`, `SKU`, `VtexProduct`
+This pattern is unchanged by the factory — it's a UI concern, not a hook
+concern. Implement it in your minicart component as before.
 
 ## Inactive Platform Stubs
 
@@ -130,9 +137,13 @@ export function useWishlist() {
 }
 ```
 
-Create similar stubs for: `shopify.ts`, `linx.ts`, `vnda.ts`, `nuvemshop.ts`.
+Create similar stubs for: `shopify.ts`, `linx.ts`, `vnda.ts`, `nuvemshop.ts`. Match the return shape to what each platform's AddToCartButton expects (some use `addItem`, others `addItems`).
 
-Match the return shape to what each platform's AddToCartButton expects (some use `addItem`, others `addItems`).
+The factory equivalent for non-VTEX sites is documented in
+[`platform-hooks-factories.md` § "Non-VTEX platforms"](../platform-hooks-factories.md#non-vtex-platforms).
+Until each platform has its own factory in `@decocms/apps`, the stub
+shape above is still correct — but use `@decocms/start/sdk/signal`
+instead of hand-rolled `{ value: ... }` objects.
 
 ## Import Rewrites
 
@@ -143,7 +154,6 @@ sed -i '' 's|from "apps/vtex/hooks/useWishlist.ts"|from "~/hooks/useWishlist"|g'
 sed -i '' 's|from "apps/vtex/utils/types.ts"|from "~/types/vtex"|g'
 sed -i '' 's|from "apps/shopify/hooks/useCart.ts"|from "~/hooks/platform/shopify"|g'
 sed -i '' 's|from "apps/wake/hooks/useCart.ts"|from "~/hooks/platform/wake"|g'
-# etc. for all platforms
 ```
 
 ## Verification

package/.agents/skills/deco-to-tanstack-migration/references/platform-hooks-factories.md

@@ -0,0 +1,186 @@
+# Platform Hooks — Factory Pattern
+
+> **Canonical reference for `createUseCart` / `createUseUser` /
+> `createUseWishlist` from `@decocms/apps/vtex/hooks`.** These factories
+> ship the legacy invoke-based hook semantics that migrated Fresh sites
+> depend on — module-level singleton state, listener-based re-render,
+> awaitable async actions, signal-shaped accessors. Sites consume them
+> as 5-line shims.
+
+This doc replaces the pre-W12 "manual `createServerFn` per VTEX endpoint"
+approach in
+[`platform-hooks/README.md`](./platform-hooks/README.md). If you scaffolded
+a site before Wave 12 (≤ `@decocms/apps@2.x` / `@decocms/start@2.18`), see
+"Migrating off the manual approach" at the bottom.
+
+---
+
+## What the factories own
+
+| Concern | Where it lives |
+|---|---|
+| Module-level singleton state (`cart`, `user`, `wishlist`) | Inside the factory closure |
+| `useEffect` + `forceRender(c => c + 1)` re-render pattern | Factory |
+| Signal-shaped accessors (`cart.value`, `user.value`) | Factory |
+| Awaitable mutations (`await addItem(...)`) | Factory |
+| `itemToAnalyticsItem` helper (cart) | Factory |
+| Wishlist arg swap (`productId` ↔ `productGroupId`) | Factory |
+| **VTEX HTTP calls** | NOT in the factory — provided by the `invoke` proxy you pass in |
+
+The factory only wires state + listeners. The site provides an `invoke`
+object whose shape is structurally typed against
+`CreateUseCartInvoke` / `CreateUseUserInvoke` / `CreateUseWishlistInvoke`
+(exported next to each factory). The migration template generates an
+`invoke` proxy in `src/server/invoke.ts` that meets all three shapes
+without any extra wiring.
+
+---
+
+## Site-local shim (the entire file)
+
+### `src/hooks/useCart.ts`
+
+```ts
+import { createUseCart } from "@decocms/apps/vtex/hooks/createUseCart";
+import { invoke } from "~/server/invoke";
+
+export type { OrderForm, OrderFormItem } from "@decocms/apps/vtex/types";
+
+export const { useCart, resetCart, itemToAnalyticsItem } = createUseCart({
+  invoke,
+});
+```
+
+### `src/hooks/useUser.ts`
+
+```ts
+import { createUseUser } from "@decocms/apps/vtex/hooks/createUseUser";
+import { invoke } from "~/server/invoke";
+
+export type { Person } from "@decocms/apps/vtex/loaders/user";
+
+export const { useUser, resetUser } = createUseUser({ invoke });
+```
+
+### `src/hooks/useWishlist.ts`
+
+```ts
+import { createUseWishlist } from "@decocms/apps/vtex/hooks/createUseWishlist";
+import { invoke } from "~/server/invoke";
+
+export type { WishlistItem } from "@decocms/apps/vtex/loaders/wishlist";
+
+export const { useWishlist, resetWishlist } = createUseWishlist({ invoke });
+```
+
+That's the whole hook — no `createServerFn`, no VTEX URLs, no `AppKey`
+plumbing. `npm run migrate` scaffolds these three files automatically
+when `--platform vtex` is set; if you regenerate, the migration template
+in `scripts/migrate/templates/hooks.ts` is the source of truth.
+
+---
+
+## Why a factory and not a single hook?
+
+> Two reasons that come up repeatedly when reviewing migration PRs.
+
+1. **`useCart` already exists in apps.** The canonical `vtex/hooks/useCart.ts`
+   is built on TanStack Query and exposes the `Minicart` shape — that is
+   the shape new code should target. The factory exists strictly so
+   already-migrated UIs keep working without a rewrite. Both can coexist
+   in one site.
+2. **Singletons can't live in a shared package without leaking across
+   sites.** The factory call instantiates a fresh module-level state per
+   site. Importing `useCart` directly from apps would share state across
+   any sites that ran in the same Worker (matters less in practice, but
+   it's the architectural reason the factory exists).
+
+The factory boundary is also the seam where we'd later wire
+`@tanstack/store` if we wanted to — the API shape is signal-compatible
+already.
+
+---
+
+## Non-VTEX platforms
+
+Sites that target Wake / Shopify / VNDA / Linx / Nuvemshop still need a
+hook surface that AddToCartButtons can consume. Until each platform has
+its own factory in `@decocms/apps`, scaffold a no-op shim:
+
+```ts
+// src/hooks/useCart.ts (custom platform)
+import { signal } from "@decocms/start/sdk/signal";
+
+const cart = signal<unknown>(null);
+const loading = signal(false);
+
+export function useCart() {
+  return {
+    cart,
+    loading,
+    async getCart() {
+      // TODO: call your platform's cart API via ~/server/invoke
+      return null;
+    },
+    async addItems(_items: unknown[]) {
+      // TODO
+    },
+    async updateItems(_items: unknown[]) {
+      // TODO
+    },
+    setCart(next: unknown) {
+      cart.value = next;
+    },
+  };
+}
+
+export default useCart;
+```
+
+`@decocms/start/sdk/signal` (re-exported via `~/sdk/signal` after
+migration) gives you the same `.value` getter/setter the factory uses,
+so AddToCart UI components don't need to know which platform is wired.
+
+The migration template's `generateGenericUseCart()` emits this stub when
+`--platform` is `custom` (or any non-VTEX value).
+
+---
+
+## Migrating off the manual approach (pre-W12 sites)
+
+If your site contains files like `src/lib/vtex-cart-server.ts` or hand-rolled `createServerFn` blocks for VTEX endpoints in `src/hooks/useCart.ts`, the post-cleanup audit will not auto-fix them — the manual code accumulated 6+ months of site-specific edits and the per-site judgment call about "what's still needed?" is real. The mechanical part:
+
+1. Replace the entire body of `src/hooks/useCart.ts` with the 5-line factory shim above.
+2. Delete `src/lib/vtex-cart-server.ts` (the migration template's `src/server/invoke.gen.ts` provides equivalent server functions wrapping `@decocms/apps/vtex/actions/checkout`).
+3. Verify `src/server/invoke.ts` exports the proxy shape the factory needs (cart actions under `invoke.vtex.actions`). The migration template scaffolds this; older sites may need to add the missing entries by hand.
+4. Run `npm run typecheck` — TypeScript will surface any callsites that referenced removed helpers (e.g. local `getOrCreateCart` shims).
+5. Repeat for `useUser` / `useWishlist`.
+
+For `useUser`, the analog of step 2 is removing any local `currentUser` /
+`getUser` server functions in favor of `@decocms/apps/vtex/loaders/user`
+exposed via `invoke.vtex.loaders.user()`. For `useWishlist`, the
+canonical surface is `@decocms/apps/vtex/{actions,loaders}/wishlist`.
+
+If you find yourself wanting to add behaviour to a factory (extra cart
+actions, custom analytics events) rather than ripping out the factory and going back to a manual hook:
+
+- **Extra read paths** → expose a new loader from
+  `@decocms/apps/vtex/loaders/*`, register it in `~/server/invoke.ts`,
+  call from your component (the factory doesn't need to know).
+- **Extra write paths** → ditto for `@decocms/apps/vtex/actions/*`.
+- **Cross-cutting business logic** (e.g. PIX-specific offer pricing) →
+  this is the kind of seam that justifies a parallel `useOffer` factory.
+  Talk to the apps maintainers; opening up a factory's plugin slots is a
+  one-PR change in apps, not a per-site rewrite.
+
+---
+
+## Related
+
+- `scripts/migrate/templates/hooks.ts` — the template that emits the
+  shims above.
+- `apps-start/vtex/hooks/createUseCart.ts` /
+  `createUseUser.ts` / `createUseWishlist.ts` — the factories
+  themselves; each docstring is the authoritative API reference.
+- `references/platform-hooks/README.md` — historical reference for the
+  pre-W12 manual approach (kept for sites that haven't migrated yet).