@decocms/start 2.12.0 → 2.14.0

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

@@ -1,103 +0,0 @@
-# Vite Configuration
-
-For the canonical battle-tested template (with VTEX dev proxy, CSP headers,
-React Compiler, dedupe, framework plugin, and rollup chunk strategy) see
-[`../../templates/vite-config.md`](../../templates/vite-config.md).
-
-This page covers the post-migration **minimum viable config** if you've
-stripped everything optional. Real sites should use the full template.
-
-## Minimum Viable Config
-
-```typescript
-import { cloudflare } from "@cloudflare/vite-plugin";
-import { tanstackStart } from "@tanstack/react-start/plugin/vite";
-import { decoVitePlugin } from "@decocms/start/vite";
-import react from "@vitejs/plugin-react";
-import tailwindcss from "@tailwindcss/vite";
-import { defineConfig } from "vite";
-import path from "path";
-
-const srcDir = path.resolve(__dirname, "src");
-
-export default defineConfig({
-  plugins: [
-    cloudflare({ viteEnvironment: { name: "ssr" } }),
-    tanstackStart({ server: { entry: "server" } }),
-    react({
-      babel: {
-        plugins: [["babel-plugin-react-compiler", { target: "19" }]],
-      },
-    }),
-    tailwindcss(),
-    // Required — server-only stubs, blocks.gen.ts fast-path, meta.gen
-    // client stub, daemon/tunnel for dev mode. Without this, client
-    // bundle crashes on node:async_hooks / react-dom/server transitively
-    // imported by @decocms/start.
-    decoVitePlugin(),
-  ],
-  resolve: {
-    // Required — dedupe React/TanStack/Deco packages so there's only one
-    // instance of each. Without this you get "Invalid hook call" errors.
-    dedupe: [
-      "@decocms/start",
-      "@decocms/apps",
-      "@tanstack/react-start",
-      "@tanstack/react-router",
-      "react",
-      "react-dom",
-    ],
-    alias: {
-      "~": srcDir,
-    },
-  },
-});
-```
-
-**One alias only**: `~` -> `src/`. Nothing else.
-
-The `decoVitePlugin()` call is **mandatory** — the older skill examples
-that omitted it (or inlined the stub logic) reflect the pre-2.x state of
-`@decocms/start` and will produce build/runtime failures on current versions.
-
-## tsconfig.json
-
-Must mirror the Vite alias:
-
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "moduleResolution": "bundler",
-    "module": "ESNext",
-    "target": "ES2022",
-    "skipLibCheck": true,
-    "strictNullChecks": true,
-    "baseUrl": ".",
-    "paths": {
-      "~/*": ["./src/*"]
-    }
-  },
-  "include": ["src/**/*", "vite.config.ts"]
-}
-```
-
-No `$store/*`, `site/*`, `apps/*`, `preact`, `@preact/signals`, `@deco/deco` paths. Those are all dead.
-
-## React Compiler
-
-The `babel-plugin-react-compiler` with `target: "19"` enables automatic memoization. Requires `@vitejs/plugin-react` instead of the default SWC plugin.
-
-Install: `npm install -D @vitejs/plugin-react babel-plugin-react-compiler`
-
-## Environment Variables
-
-For VTEX API keys, use Cloudflare Workers secrets or `.dev.vars`:
-
-```
-VTEX_ACCOUNT=mystore
-VTEX_APP_KEY=...
-VTEX_APP_TOKEN=...
-```
-
-Accessed via `process.env.*` in `createServerFn` handlers.

package/.cursor/skills/deco-to-tanstack-migration/templates/package-json.md

@@ -1,75 +0,0 @@
-# package.json Template
-
-Current as of `@decocms/start@1.6.2` and `@decocms/apps@1.4.1+`.
-
-```json
-{
-  "name": "my-tanstack-store",
-  "version": "0.1.0",
-  "type": "module",
-  "description": "storefront powered by TanStack Start",
-  "scripts": {
-    "dev": "vite dev",
-    "dev:clean": "rm -rf node_modules/.vite .wrangler/state .tanstack && vite dev",
-    "generate:blocks":   "tsx node_modules/@decocms/start/scripts/generate-blocks.ts",
-    "generate:routes":   "tsr generate",
-    "generate:schema":   "tsx node_modules/@decocms/start/scripts/generate-schema.ts --site <SITE>",
-    "generate:invoke":   "tsx node_modules/@decocms/start/scripts/generate-invoke.ts",
-    "generate:sections": "tsx node_modules/@decocms/start/scripts/generate-sections.ts",
-    "generate:loaders":  "tsx node_modules/@decocms/start/scripts/generate-loaders.ts --exclude shopify/loaders,shopify/actions",
-    "build": "npm run generate:blocks && npm run generate:schema && npm run generate:sections && npm run generate:loaders && tsr generate && vite build",
-    "preview": "vite preview",
-    "deploy": "npm run build && wrangler deploy",
-    "types": "wrangler types",
-    "typecheck": "tsc --noEmit",
-    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
-    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
-    "knip": "knip",
-    "tailwind:lint": "tsx scripts/tailwind-lint.ts",
-    "tailwind:fix": "tsx scripts/tailwind-lint.ts --fix"
-  },
-  "dependencies": {
-    "@decocms/apps": "^1.4.1",
-    "@decocms/start": "^1.6.2",
-    "@tanstack/react-query": "5.90.21",
-    "@tanstack/react-router": "1.166.7",
-    "@tanstack/react-start": "1.166.8",
-    "@tanstack/react-store": "0.9.2",
-    "@tanstack/store": "0.9.2",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4"
-  },
-  "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.27.0",
-    "@tailwindcss/vite": "^4.2.1",
-    "@tanstack/router-cli": "1.166.7",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.4",
-    "babel-plugin-react-compiler": "^1.0.0",
-    "daisyui": "^5.5.19",
-    "knip": "^5.61.2",
-    "prettier": "^3.5.3",
-    "tailwindcss": "^4.2.1",
-    "ts-morph": "^27.0.2",
-    "tsx": "^4.19.4",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.1",
-    "wrangler": "^4.72.0"
-  }
-}
-```
-
-## Notes
-
-- **Minimum `@decocms/start` version is `1.6.2`** — earlier versions have a bug where deferred sections (`Lazy`-wrapped) lose `routeParams`, causing PDP loaders with `:slug` to return null. See gotcha #47.
-- **`generate` scripts** run as part of `build`. In dev, Vite HMR picks up changes without re-running them — you only need to re-run `generate:blocks` / `generate:sections` after editing `.deco/blocks/` or a section's metadata exports.
-- **`generate:loaders --exclude shopify/loaders,shopify/actions`** — the Shopify app ships its own loaders/actions, registered by `autoconfigApps`. Exclude to avoid double-registering site-local invoke entries for them.
-- **`tsr generate`** produces `src/routeTree.gen.ts` from file-based routes.
-- **GitHub Packages**: add an `.npmrc` in the repo root (git-ignore is optional):
-  ```
-  @decocms:registry=https://npm.pkg.github.com
-  //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
-  ```
-  Then set `NODE_AUTH_TOKEN` in `.env` for local installs and as a CI secret. Alternatively, pin by Git tag via `github:` URL syntax — see gotcha #45.
-- **React Compiler** is enabled via `babel-plugin-react-compiler` in `vite.config.ts`. Most sections benefit without annotation.

package/.cursor/skills/deco-to-tanstack-migration/templates/root-route.md

@@ -1,127 +0,0 @@
-# __root.tsx Template
-
-Two options — pick the one that matches the site's needs.
-
-## Option A — Minimal (recommended default)
-
-`DecoRootLayout` from `@decocms/start/hooks` wraps the `<html>` shell with all the pieces the framework expects (DaisyUI theme, LiveControls, HeadContent, Scripts, analytics bootstrap). Use this for every new site unless you need custom providers at the root.
-
-```typescript
-import { createRootRoute } from "@tanstack/react-router";
-import { DecoRootLayout } from "@decocms/start/hooks";
-// @ts-ignore Vite ?url import
-import appCss from "../styles/app.css?url";
-
-export const Route = createRootRoute({
-  head: () => ({
-    meta: [
-      { charSet: "utf-8" },
-      { name: "viewport", content: "width=device-width, initial-scale=1" },
-      { title: "My Store" },
-    ],
-    links: [
-      { rel: "stylesheet", href: appCss },
-      { rel: "icon", href: "/favicon.ico" },
-    ],
-  }),
-  component: RootLayout,
-});
-
-function RootLayout() {
-  return <DecoRootLayout lang="pt-BR" siteName="my-store" />;
-}
-```
-
-## Option B — Custom providers (cart/React Query at root)
-
-Only reach for this when you need providers wrapping the CMS outlet — a root-mounted cart store that must hydrate before any section, global React Query client, etc. Everything else stays in sections.
-
-```typescript
-import { useState } from "react";
-import {
-  createRootRoute,
-  HeadContent,
-  Outlet,
-  Scripts,
-  useRouterState,
-} from "@tanstack/react-router";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { LiveControls } from "@decocms/start/hooks";
-import { ANALYTICS_SCRIPT } from "@decocms/start/sdk/analytics";
-// @ts-ignore Vite ?url import
-import appCss from "../styles/app.css?url";
-
-const PROGRESS_CSS = `
-@keyframes decoProgress{0%{width:0}30%{width:50%}60%{width:80%}100%{width:98%}}
-.deco-nav-progress{position:fixed;top:0;left:0;height:3px;background:var(--color-primary,#e53e3e);z-index:9999;animation:decoProgress 4s cubic-bezier(.4,0,.2,1) forwards;pointer-events:none;box-shadow:0 0 8px var(--color-primary,#e53e3e)}
-`;
-
-function NavigationProgress() {
-  const isLoading = useRouterState({ select: (s) => s.isLoading });
-  if (!isLoading) return null;
-  return (
-    <>
-      <style dangerouslySetInnerHTML={{ __html: PROGRESS_CSS }} />
-      <div className="deco-nav-progress" />
-    </>
-  );
-}
-
-export const Route = createRootRoute({
-  head: () => ({
-    meta: [
-      { charSet: "utf-8" },
-      { name: "viewport", content: "width=device-width, initial-scale=1" },
-      { title: "My Store" },
-    ],
-    links: [
-      { rel: "stylesheet", href: appCss },
-      { rel: "icon", href: "/favicon.ico" },
-    ],
-  }),
-  component: RootLayout,
-});
-
-function RootLayout() {
-  const [queryClient] = useState(
-    () => new QueryClient({
-      defaultOptions: {
-        queries: {
-          staleTime: import.meta.env.DEV ? 0 : 30_000,
-          gcTime: import.meta.env.DEV ? 0 : 5 * 60_000,
-          refetchOnWindowFocus: import.meta.env.DEV,
-        },
-      },
-    }),
-  );
-
-  return (
-    <html lang="pt-BR" data-theme="light" suppressHydrationWarning>
-      <head>
-        <HeadContent />
-      </head>
-      <body className="bg-base-100 text-base-content" suppressHydrationWarning>
-        <NavigationProgress />
-        <QueryClientProvider client={queryClient}>
-          <Outlet />
-        </QueryClientProvider>
-        <LiveControls site="my-store" />
-        <script type="module" dangerouslySetInnerHTML={{ __html: ANALYTICS_SCRIPT }} />
-        <Scripts />
-      </body>
-    </html>
-  );
-}
-```
-
-## Key points (applies to both)
-
-1. **`data-theme="light"`** on `<html>` — required for DaisyUI v4/v5 CSS variables to activate in production AND in the admin preview shell. Option A sets this for you.
-2. **`suppressHydrationWarning`** on `<html>` and `<body>` — browser extensions mutate these elements; React would warn on mismatch.
-3. **`LiveControls site={...}`** — admin iframe bridge. `site` MUST match the CMS site name used in `@decocms/apps/registry` entries and `.deco/blocks/`.
-4. **No `Device.Provider`** — do NOT hardcode `<Device.Provider value={{ isMobile: true }}>` in the root. Device detection belongs in each page route's `createServerFn` loader (see gotcha #29).
-5. **Keep the root thin** — sections own their own data. Avoid cross-section state at the root unless it's truly global (cart, theme). Every provider at the root ships to every page, even ones that don't need it.
-
-## Cart/platform state
-
-If you add a cart store at the root (Option B), wire it AFTER `QueryClientProvider` so section-local hooks can use both. The cart store itself should be a module-level `@tanstack/store` `Store`, and a `useCart()` hook reads via `useStore(cartStore)`. SSR hydration: the page loader fetches the initial cart (via the minicart loader or Shopify `getCart`) and the root passes the initial state to `cartStore.setState()` before hydration.

package/.cursor/skills/deco-to-tanstack-migration/templates/router.md

@@ -1,96 +0,0 @@
-# router.tsx Template
-
-```typescript
-import { createRouter as createTanStackRouter } from "@tanstack/react-router";
-import { routeTree } from "./routeTree.gen";
-
-export function createRouter() {
-  const router = createTanStackRouter({
-    routeTree,
-    scrollRestoration: true,
-  });
-
-  // Scroll to top on forward navigation (PUSH/REPLACE), skip on back/forward (GO)
-  router.subscribe("onResolved", (evt) => {
-    if (evt.type === "GO") return;
-    window.scrollTo({ top: 0 });
-  });
-
-  return router;
-}
-
-declare module "@tanstack/react-router" {
-  interface Register {
-    router: ReturnType<typeof createRouter>;
-  }
-}
-```
-
-## Route Files
-
-### src/routes/index.tsx (Homepage)
-
-```typescript
-import { createFileRoute } from "@tanstack/react-router";
-import { cmsHomeRouteConfig } from "@decocms/start/routes";
-import { DecoPageRenderer } from "@decocms/start/hooks";
-import { loadDeferredSection } from "@decocms/start/routes/cmsRoute";
-
-const { loader, head } = cmsHomeRouteConfig({
-  defaultTitle: "My Store",
-});
-
-export const Route = createFileRoute("/")({
-  loader,
-  head,
-  component: HomePage,
-});
-
-function HomePage() {
-  const { resolvedSections, deferredSections, pagePath } = Route.useLoaderData();
-  return (
-    <DecoPageRenderer
-      sections={resolvedSections}
-      deferredSections={deferredSections}
-      pagePath={pagePath}
-      loadDeferredSectionFn={loadDeferredSection}
-    />
-  );
-}
-```
-
-### src/routes/$.tsx (Catch-All CMS Route)
-
-```typescript
-import { createFileRoute, notFound } from "@tanstack/react-router";
-import { cmsRouteConfig } from "@decocms/start/routes";
-import { DecoPageRenderer } from "@decocms/start/hooks";
-import { loadDeferredSection } from "@decocms/start/routes/cmsRoute";
-
-const { loader, head } = cmsRouteConfig({
-  siteName: "My Store",
-  ignoreSearchParams: ["skuId"],
-});
-
-export const Route = createFileRoute("/$")({
-  loader: async (ctx) => {
-    const data = await loader(ctx);
-    if (!data) throw notFound();
-    return data;
-  },
-  head,
-  component: CmsPage,
-});
-
-function CmsPage() {
-  const { resolvedSections, deferredSections, pagePath } = Route.useLoaderData();
-  return (
-    <DecoPageRenderer
-      sections={resolvedSections}
-      deferredSections={deferredSections}
-      pagePath={pagePath}
-      loadDeferredSectionFn={loadDeferredSection}
-    />
-  );
-}
-```

package/.cursor/skills/deco-to-tanstack-migration/templates/setup-ts.md

@@ -1,148 +0,0 @@
-# setup.ts Template
-
-Minimal, convention-driven setup. Matches `@decocms/start >= 1.6.2`. Based on the storefront-tanstack Shopify port.
-
-Three framework composers do the work — the site file is short by design:
-
-- `createSiteSetup(options)` — CMS engine + admin protocol + matcher registration
-- `applySectionConventions(gen)` — reads `sections.gen.ts` and wires eager/layout/seo/cache/sync sections
-- `autoconfigApps(blocks, APP_REGISTRY)` — dual-registers every app's loaders + actions from `@decocms/apps/registry`
-
-```typescript
-/**
- * Site setup — orchestrator that wires framework, apps, and sections.
- *
- * App-installed loaders + actions (Shopify, VTEX, Resend, …) are wired via
- * `autoconfigApps(blocks, APP_REGISTRY)` — adding a new app is a one-line
- * entry in `@decocms/apps/registry.ts`, no change needed here.
- *
- * Section-specific prop enrichment lives in `setup/section-loaders.ts`.
- * Section metadata (eager, sync, layout, cache, LoadingFallback) is declared
- * in each section file and auto-extracted by generate-sections.ts.
- */
-
-import "./cache-config";
-
-import {
-  registerCommerceLoaders,
-  applySectionConventions,
-} from "@decocms/start/cms";
-import { createSiteSetup } from "@decocms/start/setup";
-import { autoconfigApps } from "@decocms/start/apps";
-import { createInstrumentedFetch } from "@decocms/start/sdk/instrumentedFetch";
-import { initShopifyFromBlocks, setShopifyFetch } from "@decocms/apps/shopify";
-import { APP_REGISTRY } from "@decocms/apps/registry";
-import { blocks as generatedBlocks } from "./server/cms/blocks.gen";
-import {
-  sectionMeta,
-  syncComponents,
-  loadingFallbacks,
-} from "./server/cms/sections.gen";
-import { PreviewProviders } from "@decocms/start/hooks";
-// @ts-ignore Vite ?url import
-import appCss from "./styles/app.css?url";
-
-import "./setup/section-loaders";
-
-// -- Framework setup --
-createSiteSetup({
-  sections: import.meta.glob("./sections/**/*.tsx") as Record<string, () => Promise<any>>,
-  blocks: generatedBlocks,
-  meta: () => import("./server/admin/meta.gen.json").then((m) => m.default),
-  css: appCss,
-  fonts: [],
-  productionOrigins: [
-    "https://www.<SITE>.com.br",
-    "https://<SITE>.com.br",
-  ],
-  previewWrapper: PreviewProviders,
-  initPlatform: (blocks) => initShopifyFromBlocks(blocks),  // or initVtexFromBlocks
-  onResolveError: (error, resolveType, context) => {
-    console.error(`[CMS-DEBUG] ${context} "${resolveType}" failed:`, error);
-  },
-  onDanglingReference: (resolveType) => {
-    console.warn(`[CMS-DEBUG] Dangling reference: ${resolveType}`);
-    return null;
-  },
-});
-
-// -- Platform fetch instrumentation (optional, for observability) --
-setShopifyFetch(createInstrumentedFetch("shopify"));
-
-// -- Convention-driven section registration --
-applySectionConventions({
-  meta: sectionMeta,
-  syncComponents,
-  loadingFallbacks,
-  sectionGlob: import.meta.glob("./sections/**/*.tsx") as Record<string, () => Promise<any>>,
-});
-
-// -- Apps: auto-configure from decofile against the @decocms/apps registry --
-// Dual-registers into commerce loaders (CMS resolve) + invoke handlers (admin)
-// for every configured app. Adding a new app = add an entry in
-// @decocms/apps/registry.ts. No change here per app.
-await autoconfigApps(generatedBlocks, APP_REGISTRY);
-
-// -- Site-local loaders (not shipped by an app) --
-// Register .ts and bare variants — CMS resolver may query either.
-registerCommerceLoaders({
-  "site/loaders/minicart.ts": async () => (await import("./loaders/minicart")).default(),
-  "site/loaders/minicart":    async () => (await import("./loaders/minicart")).default(),
-  "site/loaders/user.ts":     async () => (await import("./loaders/user")).default(),
-  "site/loaders/user":        async () => (await import("./loaders/user")).default(),
-  "site/loaders/wishlist.ts": async () => (await import("./loaders/wishlist")).default(),
-  "site/loaders/wishlist":    async () => (await import("./loaders/wishlist")).default(),
-});
-```
-
-## Section metadata convention
-
-Declare section behavior in the section file, not in setup.ts. `generate-sections.ts` scans `src/sections/**` and emits `src/server/cms/sections.gen.ts`.
-
-```typescript
-// src/sections/Header/Header.tsx
-export default function Header(props) { /* ... */ }
-
-export const eager = true;    // always render eagerly (bypass Lazy wrappers)
-export const sync = true;     // import bundled, not code-split (for first paint)
-export const layout = true;   // render as a layout section (header/footer/theme)
-```
-
-```typescript
-// src/sections/Product/SearchResult.tsx
-export const cache = "listing";  // SWR cache profile
-
-export function LoadingFallback() {
-  return <div className="animate-pulse h-96 bg-base-200" />;
-}
-```
-
-```typescript
-// src/sections/SEO/SeoPDP.tsx
-export const seo = true;  // extract page SEO from this section's output
-```
-
-After changes to any `export const <flag>` or `LoadingFallback`, re-run `npm run generate:sections` (or `npm run build`).
-
-## What NOT to put here
-
-- **Section imports** — lazy via Vite glob, sync via `sectionMeta.sync` + `syncComponents`. Zero manual imports needed.
-- **App loaders/actions** — `autoconfigApps` registers every entry in `APP_REGISTRY`. Adding Shopify/VTEX/Resend loaders by hand is a bug.
-- **alwaysEager arrays** — driven by `export const eager = true` in section files.
-- **SEO registration** — driven by `export const seo = true`.
-- **Cache profile arrays** — driven by `export const cache = "..."`.
-- **`setMetaData` / `setRenderShell` / `setInvokeLoaders` calls** — `createSiteSetup` handles them. Only reach for the low-level APIs if composing a non-standard pipeline.
-
-## Adding a new app (e.g., 4th commerce integration)
-
-1. `@decocms/apps/registry.ts` gets one new entry: `{ blockKey, module, displayName, category, description }`
-2. Bump `@decocms/apps` minor version; site installs the bump
-3. Add the block in `.deco/blocks/<blockKey>.json` with platform config
-4. Nothing else changes — `autoconfigApps` picks it up on next boot
-
-## See also
-
-- `applySectionConventions` source: `@decocms/start/src/cms/applySectionConventions.ts`
-- `autoconfigApps` source: `@decocms/start/src/apps/autoconfig.ts`
-- Registry source: `@decocms/apps/registry.ts`
-- Generate scripts: `@decocms/start/scripts/generate-{blocks,schema,sections,loaders,invoke}.ts`