npm - @decocms/start - Versions diffs - 0.38.0 → 0.40.0 - Mend

@decocms/start 0.38.0 → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/.agents/skills/deco-to-tanstack-migration/templates/root-route.md ADDED Viewed

@@ -0,0 +1,110 @@
+# __root.tsx Template
+```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";
+import appCss from "../styles/app.css?url";
+// Deco analytics event dispatcher — must be in <head> before any section renders
+const DECO_EVENTS_BOOTSTRAP = `
+window.DECO = window.DECO || {};
+window.DECO.events = window.DECO.events || {
+  _q: [],
+  dispatch: function(e) {
+    if (window.dataLayer) { window.dataLayer.push({ event: e.name, ecommerce: e.params }); }
+    this._q.push(e);
+  }
+};
+window.dataLayer = window.dataLayer || [];
+`;
+// Navigation progress bar CSS
+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)}
+@keyframes decoFadeIn{from{opacity:0}to{opacity:1}}
+.deco-nav-overlay{position:fixed;inset:0;z-index:9998;pointer-events:none;background:rgba(255,255,255,0.15);animation:decoFadeIn .2s ease-out}
+`;
+function NavigationProgress() {
+  const isLoading = useRouterState({ select: (s) => s.isLoading });
+  if (!isLoading) return null;
+  return (
+    <>
+      <style dangerouslySetInnerHTML={{ __html: PROGRESS_CSS }} />
+      <div className="deco-nav-progress" />
+      <div className="deco-nav-overlay" />
+    </>
+  );
+}
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      { title: "My Store" },
+    ],
+    links: [
+      { rel: "preconnect", href: "https://fonts.googleapis.com" },
+      { rel: "preconnect", href: "https://fonts.gstatic.com", crossOrigin: "anonymous" },
+      // Add your font stylesheet here:
+      // { rel: "stylesheet", href: "https://fonts.googleapis.com/css2?family=..." },
+      { 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>
+        <script dangerouslySetInnerHTML={{ __html: DECO_EVENTS_BOOTSTRAP }} />
+        <HeadContent />
+      </head>
+      <body className="bg-base-100 text-base-content" suppressHydrationWarning>
+        <NavigationProgress />
+        <QueryClientProvider client={queryClient}>
+          <Outlet />
+        </QueryClientProvider>
+        <LiveControls site={process.env.DECO_SITE_NAME} />
+        <script type="module" dangerouslySetInnerHTML={{ __html: ANALYTICS_SCRIPT }} />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
+## Key Points
+1. **QueryClientProvider** — Required even if not using React Query directly. @decocms/apps hooks may use it.
+2. **LiveControls** — Admin iframe bridge. `site` prop must match CMS site name.
+3. **DECO_EVENTS_BOOTSTRAP** — Must be in `<head>` before sections. Sections dispatch analytics events on render.
+4. **NavigationProgress** — Visual feedback during client-side navigation.
+5. **suppressHydrationWarning** — On `<html>` and `<body>` to avoid mismatches from browser extensions.
+6. **data-theme="light"** — Required for DaisyUI v4/v5 CSS variables to activate.

package/.agents/skills/deco-to-tanstack-migration/templates/router.md ADDED Viewed

@@ -0,0 +1,96 @@
+# 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/.agents/skills/deco-to-tanstack-migration/templates/setup-ts.md ADDED Viewed

@@ -0,0 +1,167 @@
+# setup.ts Template
+Annotated template based on espacosmart-storefront (100+ sections, VTEX, async rendering).
+```typescript
+// ==========================================================================
+// 1. CMS BLOCKS & META
+// ==========================================================================
+import blocksJson from "./server/cms/blocks.gen.ts";
+import metaData from "./server/admin/meta.gen.json";
+import { setBlocks } from "@decocms/start/cms/loader";
+import { setMetaData, setInvokeLoaders, setRenderShell } from "@decocms/start/admin";
+import { registerSections, registerSectionsSync, setResolvedComponent } from "@decocms/start/cms/registry";
+import { registerSectionLoaders, registerLayoutSections } from "@decocms/start/cms/sectionLoaders";
+import { registerCommerceLoaders, setAsyncRenderingConfig, onBeforeResolve } from "@decocms/start/cms/resolve";
+import { createCachedLoader } from "@decocms/start/sdk/cachedLoader";
+import appCss from "./styles/app.css?url";
+// Load CMS blocks (pages, sections, configs) from generated JSON
+setBlocks(blocksJson);
+// Set admin schema for /live/_meta endpoint
+setMetaData(metaData);
+// Configure admin preview HTML shell
+setRenderShell({
+  css: appCss,
+  fonts: ["https://fonts.googleapis.com/css2?family=YourFont:wght@400;500;600;700&display=swap"],
+  theme: "light",       // data-theme="light" on <html> for DaisyUI
+  bodyClass: "bg-base-100 text-base-content",
+  lang: "pt-BR",
+});
+// ==========================================================================
+// 2. SECTION REGISTRATION
+// ==========================================================================
+// Critical sections — above-the-fold, bundled synchronously
+import HeaderSection from "./components/header/Header";
+import FooterSection from "./sections/Footer/Footer";
+const criticalSections: Record<string, any> = {
+  "site/sections/Header/Header.tsx": HeaderSection,
+  "site/sections/Footer/Footer.tsx": FooterSection,
+};
+// Register sync components for instant SSR (no Suspense boundary)
+for (const [key, mod] of Object.entries(criticalSections)) {
+  setResolvedComponent(key, mod.default || mod);
+}
+registerSectionsSync(criticalSections);
+// All sections — lazy-loaded via dynamic import
+registerSections({
+  "site/sections/Header/Header.tsx": () => import("./sections/Header/Header"),
+  "site/sections/Footer/Footer.tsx": () => import("./sections/Footer/Footer"),
+  "site/sections/Theme/Theme.tsx": () => import("./sections/Theme/Theme"),
+  // ... register ALL sections from src/sections/ here
+  // Pattern: "site/sections/Path/Name.tsx": () => import("./sections/Path/Name")
+});
+// ==========================================================================
+// 3. LAYOUT SECTIONS
+// ==========================================================================
+// Layout sections are always rendered eagerly (never lazy/deferred),
+// even if wrapped in Lazy.tsx in the CMS.
+registerLayoutSections([
+  "site/sections/Header/Header.tsx",
+  "site/sections/Footer/Footer.tsx",
+  "site/sections/Theme/Theme.tsx",
+  "site/sections/Social/WhatsApp.tsx",
+]);
+// ==========================================================================
+// 4. SECTION LOADERS
+// ==========================================================================
+// Section loaders enrich CMS props with server-side data (e.g., VTEX API calls).
+// Only needed for sections that export `const loader`.
+registerSectionLoaders({
+  "site/sections/Product/ProductShelf.tsx": (props: any, req: Request) =>
+    import("./components/product/ProductShelf").then((m) => m.loader(props, req)),
+  "site/sections/Product/SearchResult.tsx": (props: any, req: Request) =>
+    import("./components/search/SearchResult").then((m) => m.loader(props, req)),
+  // ... add for each section that has `export const loader`
+});
+// ==========================================================================
+// 5. COMMERCE LOADERS (VTEX)
+// ==========================================================================
+import { vtexProductList } from "@decocms/apps/vtex/loaders/productList";
+import { vtexProductDetailsPage } from "@decocms/apps/vtex/loaders/productDetailsPage";
+import { vtexProductListingPage } from "@decocms/apps/vtex/loaders/productListingPage";
+import { vtexSuggestions } from "@decocms/apps/vtex/loaders/suggestions";
+import { initVtexFromBlocks } from "@decocms/apps/vtex/setup";
+// SWR-cached commerce loaders — avoids re-fetching on every page navigation
+const cachedProductList = createCachedLoader("vtex/productList", vtexProductList, {
+  policy: "stale-while-revalidate", maxAge: 60_000,
+});
+const cachedPDP = createCachedLoader("vtex/pdp", vtexProductDetailsPage, {
+  policy: "stale-while-revalidate", maxAge: 30_000,
+});
+const cachedPLP = createCachedLoader("vtex/plp", vtexProductListingPage, {
+  policy: "stale-while-revalidate", maxAge: 60_000,
+});
+const cachedSuggestions = createCachedLoader("vtex/suggestions", vtexSuggestions, {
+  policy: "stale-while-revalidate", maxAge: 120_000,
+});
+// Map CMS __resolveType strings to actual loader functions
+registerCommerceLoaders({
+  "vtex/loaders/intelligentSearch/productList.ts": cachedProductList,
+  "vtex/loaders/intelligentSearch/productListingPage.ts": cachedPLP,
+  "vtex/loaders/intelligentSearch/productDetailsPage.ts": cachedPDP,
+  "vtex/loaders/intelligentSearch/suggestions.ts": cachedSuggestions,
+  // Add passthrough loaders for types that don't need caching:
+  // "vtex/loaders/config.ts": (props) => props,
+});
+// ==========================================================================
+// 6. VTEX INITIALIZATION
+// ==========================================================================
+// onBeforeResolve runs once before the first CMS page resolution.
+// initVtexFromBlocks reads VTEX config (account, publicUrl) from CMS blocks.
+onBeforeResolve(() => {
+  initVtexFromBlocks();
+});
+// ==========================================================================
+// 7. ASYNC RENDERING
+// ==========================================================================
+// Enable deferred section loading (scroll-triggered).
+// Respects CMS Lazy wrappers. Layout sections and alwaysEager are never deferred.
+setAsyncRenderingConfig({
+  alwaysEager: [
+    "site/sections/Header/Header.tsx",
+    "site/sections/Footer/Footer.tsx",
+    "site/sections/Theme/Theme.tsx",
+    "site/sections/Images/Carousel.tsx",
+    // Add above-the-fold sections here
+  ],
+});
+// ==========================================================================
+// 8. INVOKE LOADERS (for /deco/invoke endpoint)
+// ==========================================================================
+setInvokeLoaders({
+  "vtex/loaders/intelligentSearch/productList.ts": cachedProductList,
+  "vtex/loaders/intelligentSearch/suggestions.ts": cachedSuggestions,
+  // Used by the admin to preview loader results
+});
+```
+## Key Patterns
+1. **Order matters**: blocks → meta → sections → loaders → commerce → async config
+2. **Critical sections**: Import synchronously for instant SSR, also register as lazy for client code-splitting
+3. **SWR caching**: `createCachedLoader` wraps commerce loaders with stale-while-revalidate
+4. **onBeforeResolve**: Deferred initialization — VTEX config is read from CMS blocks at first request
+5. **alwaysEager**: Sections that must render on first paint (no deferred loading)

package/.agents/skills/deco-to-tanstack-migration/templates/vite-config.md ADDED Viewed

@@ -0,0 +1,122 @@
+# vite.config.ts Template
+Battle-tested configuration from espacosmart-storefront.
+```typescript
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { tanstackStart } from "@tanstack/react-start/plugin/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(),
+    // CRITICAL: Stubs for client bundles that transitively import server modules.
+    // Without this, client build crashes on node:async_hooks, react-dom/server, etc.
+    {
+      name: "deco-server-only-stubs",
+      enforce: "pre" as const,
+      resolveId(id, _importer, options) {
+        if (options?.ssr) return undefined;
+        const CLIENT_STUBS: Record<string, string> = {
+          "react-dom/server": "\0stub:react-dom-server",
+          "react-dom/server.browser": "\0stub:react-dom-server",
+          "node:stream": "\0stub:node-stream",
+          "node:stream/web": "\0stub:node-stream-web",
+          "node:async_hooks": "\0stub:node-async-hooks",
+          "tanstack-start-injected-head-scripts:v": "\0stub:tanstack-head-scripts",
+        };
+        return CLIENT_STUBS[id];
+      },
+      configEnvironment(name: string, env: any) {
+        if (name === "ssr" || name === "client") {
+          env.optimizeDeps = env.optimizeDeps || {};
+          env.optimizeDeps.esbuildOptions = env.optimizeDeps.esbuildOptions || {};
+          env.optimizeDeps.esbuildOptions.jsx = "automatic";
+          env.optimizeDeps.esbuildOptions.jsxImportSource = "react";
+        }
+      },
+      load(id) {
+        if (id === "\0stub:react-dom-server") {
+          return [
+            "const noop = () => '';",
+            "export const renderToString = noop;",
+            "export const renderToStaticMarkup = noop;",
+            "export const renderToReadableStream = noop;",
+            "export const resume = noop;",
+            "export const version = '19.0.0';",
+            "export default { renderToString: noop, renderToStaticMarkup: noop, renderToReadableStream: noop, resume: noop, version: '19.0.0' };",
+          ].join("\n");
+        }
+        if (id === "\0stub:node-stream") {
+          return "export class PassThrough {}; export class Readable {}; export class Writable {}; export default { PassThrough, Readable, Writable };";
+        }
+        if (id === "\0stub:node-stream-web") {
+          return "export const ReadableStream = globalThis.ReadableStream; export const WritableStream = globalThis.WritableStream; export const TransformStream = globalThis.TransformStream; export default { ReadableStream, WritableStream, TransformStream };";
+        }
+        if (id === "\0stub:node-async-hooks") {
+          return [
+            "class _ALS { getStore() { return undefined; } run(_store, fn, ...args) { return fn(...args); } enterWith() {} disable() {} }",
+            "export const AsyncLocalStorage = _ALS;",
+            "export const AsyncResource = class {};",
+            "export function executionAsyncId() { return 0; }",
+            "export function createHook() { return { enable() {}, disable() {} }; }",
+            "export default { AsyncLocalStorage: _ALS, AsyncResource, executionAsyncId, createHook };",
+          ].join("\n");
+        }
+        if (id === "\0stub:tanstack-head-scripts") {
+          return "export const injectedHeadScripts = undefined;";
+        }
+      },
+    },
+  ],
+  // Inject site name at build time (not runtime)
+  define: {
+    "process.env.DECO_SITE_NAME": JSON.stringify(
+      process.env.DECO_SITE_NAME || "my-store"
+    ),
+  },
+  esbuild: {
+    jsx: "automatic",
+    jsxImportSource: "react",
+  },
+  resolve: {
+    // CRITICAL: Without dedupe, multiple React/TanStack instances cause hook errors
+    dedupe: [
+      "@tanstack/react-start",
+      "@tanstack/react-router",
+      "@tanstack/react-start-server",
+      "@tanstack/start-server-core",
+      "@tanstack/start-client-core",
+      "@tanstack/start-plugin-core",
+      "@tanstack/start-storage-context",
+      "react",
+      "react-dom",
+    ],
+    alias: {
+      "~": srcDir,
+    },
+  },
+});
+```
+## Key Points
+1. **deco-server-only-stubs plugin** — Required. Client bundles transitively import `node:async_hooks`, `react-dom/server`, etc. Without stubs, build crashes.
+2. **resolve.dedupe** — Required. Without it, multiple React instances cause "Invalid hook call" errors.
+3. **process.env.DECO_SITE_NAME via define** — Must be injected at build time, not read at runtime.
+4. **React Compiler** — `babel-plugin-react-compiler` with target 19 for automatic memoization.
+5. **esbuild.jsx** — Must be `"automatic"` with `jsxImportSource: "react"` for proper JSX transform.

package/.agents/skills/deco-to-tanstack-migration/templates/worker-entry.md ADDED Viewed

@@ -0,0 +1,67 @@
+# Worker Entry Templates
+## src/server.ts
+```typescript
+// CRITICAL: import "./setup" MUST be the first import.
+// Without it, server functions in Vite split modules have empty state
+// (blocks, registry, commerce loaders) causing 404 on client-side navigation.
+import "./setup";
+import { createStartHandler, defaultStreamHandler } from "@tanstack/react-start/server";
+export default createStartHandler(defaultStreamHandler);
+```
+## src/worker-entry.ts
+```typescript
+// CRITICAL: import "./setup" MUST be the first import.
+import "./setup";
+import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
+import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+import {
+  handleMeta,
+  handleDecofileRead,
+  handleDecofileReload,
+  handleRender,
+  corsHeaders,
+} from "@decocms/start/admin";
+// Only if using VTEX:
+import { shouldProxyToVtex, proxyToVtex } from "@decocms/apps/vtex/utils/proxy";
+const serverEntry = createServerEntry({
+  async fetch(request) {
+    return await handler.fetch(request);
+  },
+});
+export default createDecoWorkerEntry(serverEntry, {
+  admin: {
+    handleMeta,
+    handleDecofileRead,
+    handleDecofileReload,
+    handleRender,
+    corsHeaders,
+  },
+  // VTEX proxy — routes like /api/*, /checkout/*, /arquivos/* go to VTEX
+  proxyHandler: (request, url) => {
+    if (shouldProxyToVtex(url.pathname)) {
+      return proxyToVtex(request);
+    }
+    return null;
+  },
+});
+```
+## Key Rules
+1. **`import "./setup"` is ALWAYS the first line** — both files. This registers sections, loaders, blocks, and commerce config before any server function executes.
+2. **Admin handlers go in `createDecoWorkerEntry`** — NOT inside `createServerEntry`. TanStack Start's build strips custom fetch logic from `createServerEntry` in production.
+3. **Proxy handler** — Optional. Only needed for platforms (VTEX, Shopify) that require server-side proxying.
+4. **Request flow**: `createDecoWorkerEntry` → admin routes (first) → cache check → proxy check → `serverEntry.fetch()` (TanStack Start).
+## Why `import "./setup"` Must Be First
+TanStack Start compiles `createServerFn()` calls into "split modules" — separate Vite module instances. Module-level state (blockData, commerceLoaders, sectionRegistry) initialized in `setup.ts` only exists in the original module instance. Without importing setup first, these split modules execute with empty state.
+The fix in `@decocms/start` uses `globalThis.__deco` to share state across all module instances. But `setup.ts` must run BEFORE any server function is called — which means it must be imported before `createStartHandler` or `createServerEntry`.

package/README.md CHANGED Viewed

@@ -62,6 +62,51 @@ Request → createDecoWorkerEntry()
 | `/cart`, `/checkout` | private | none |
 | Everything else | listing | 2 min |
+## Migrating from Fresh/Preact/Deno
+`@decocms/start` includes an Agent Skill that handles migration for you. It works with Claude Code, Cursor, Codex, and other AI coding tools. Install the skill, open your Fresh storefront, and tell the AI to migrate:
+```bash
+npx skills add decocms/deco-start
+```
+Then open your project in any supported tool and say:
+> migrate this project to TanStack Start
+The skill handles compatibility checking, import rewrites, config generation, section registry setup, and worker entry creation. It knows what `@decocms/start` supports and will flag anything that needs manual attention.
+### Or run the script manually
+```bash
+# From a new TanStack Start project with @decocms/start installed:
+npx tsx node_modules/@decocms/start/scripts/migrate.ts --source /path/to/fresh-site
+# Preview first without writing:
+npx tsx node_modules/@decocms/start/scripts/migrate.ts --source /path/to/fresh-site --dry-run --verbose
+```
+The script runs 7 phases automatically:
+1. **Analyze** — scan source, detect Preact/Fresh/Deco patterns
+2. **Scaffold** — generate `vite.config.ts`, `wrangler.jsonc`, routes, `setup.ts`, worker entry
+3. **Transform** — rewrite imports (70+ rules), JSX attrs, Fresh APIs, Deno-isms, Tailwind v3→v4
+4. **Cleanup** — delete `islands/`, old routes, `deno.json`, move `static/` → `public/`
+5. **Report** — generate `MIGRATION_REPORT.md` with manual review items
+6. **Verify** — 18+ smoke tests (zero old imports, scaffolded files exist)
+7. **Bootstrap** — `npm install`, generate CMS blocks, generate routes
+Your existing `src/sections/`, `src/components/`, and `.deco/blocks/` work as-is. The script gets you to "builds clean with zero old imports" — manual work starts at platform hooks (`useCart`) and runtime tuning.
+### Agent Skills
+Skills live in [`.agents/skills/`](.agents/skills/) and provide deep context to AI coding tools:
+| Skill | What it covers |
+|-------|---------------|
+| `deco-to-tanstack-migration` | Full 12-phase migration playbook with 22 reference docs and 6 templates |
+| `deco-migrate-script` | How the automated `scripts/migrate.ts` works, how to extend it |
 ## Peer Dependencies
 - `@tanstack/react-start` >= 1.0.0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -42,6 +42,7 @@
     "./sdk/createInvoke": "./src/sdk/createInvoke.ts",
     "./matchers/posthog": "./src/matchers/posthog.ts",
     "./apps/autoconfig": "./src/apps/autoconfig.ts",
+    "./sdk/setupApps": "./src/sdk/setupApps.ts",
     "./matchers/builtins": "./src/matchers/builtins.ts",
     "./types/widgets": "./src/types/widgets.ts",
     "./routes": "./src/routes/index.ts",

package/src/admin/index.ts CHANGED Viewed

@@ -1,9 +1,11 @@
 export { corsHeaders, isAdminOrLocalhost, registerAdminOrigin, registerAdminOrigins } from "./cors";
 export { handleDecofileRead, handleDecofileReload } from "./decofile";
 export {
+  clearInvokeHandlers,
   handleInvoke,
   type InvokeAction,
   type InvokeLoader,
+  registerInvokeHandlers,
   setInvokeActions,
   setInvokeLoaders,
 } from "./invoke";