@decocms/start 0.31.1 → 0.32.0

package/scripts/migrate/templates/package-json.ts

@@ -0,0 +1,59 @@
+import type { MigrationContext } from "../types.ts";
+
+export function generatePackageJson(ctx: MigrationContext): string {
+  const pkg = {
+    name: ctx.siteName,
+    version: "0.1.0",
+    type: "module",
+    description: `${ctx.siteName} storefront powered by TanStack Start`,
+    scripts: {
+      dev: "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 ${ctx.siteName}`,
+      build:
+        "npm run generate:blocks && npm run generate:schema && 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",
+    },
+    author: "deco.cx",
+    license: "MIT",
+    dependencies: {
+      "@decocms/apps": "^0.25.2",
+      "@decocms/start": "^0.31.1",
+      "@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",
+      "colorjs.io": "^0.6.1",
+      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",
+      tsx: "^4.19.4",
+      typescript: "^5.9.3",
+      vite: "^7.3.1",
+      wrangler: "^4.72.0",
+    },
+  };
+
+  return JSON.stringify(pkg, null, 2) + "\n";
+}

package/scripts/migrate/templates/routes.ts

@@ -0,0 +1,280 @@
+import type { MigrationContext } from "../types.ts";
+
+export function generateRoutes(
+  ctx: MigrationContext,
+): Record<string, string> {
+  const siteName = ctx.siteName;
+  const siteTitle = siteName.charAt(0).toUpperCase() + siteName.slice(1);
+
+  return {
+    "src/routes/__root.tsx": generateRoot(ctx, siteTitle),
+    "src/routes/index.tsx": generateIndex(siteTitle),
+    "src/routes/$.tsx": generateCatchAll(siteTitle),
+    "src/routes/deco/meta.ts": generateDecoMeta(),
+    "src/routes/deco/invoke.$.ts": generateDecoInvoke(),
+    "src/routes/deco/render.ts": generateDecoRender(),
+  };
+}
+
+function generateRoot(ctx: MigrationContext, siteTitle: string): string {
+  const gtmScript = ctx.gtmId
+    ? `
+  // Google Tag Manager
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const script = document.createElement("script");
+    script.async = true;
+    script.src = "https://www.googletagmanager.com/gtm.js?id=${ctx.gtmId}";
+    document.head.appendChild(script);
+    window.dataLayer = window.dataLayer || [];
+    window.dataLayer.push({ "gtm.start": Date.now(), event: "gtm.js" });
+  }, []);`
+    : "";
+
+  return `import { useState, useEffect, useRef } 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";
+
+declare global {
+  interface Window {
+    __deco_ready?: boolean;
+    dataLayer: unknown[];
+  }
+}
+
+const PROGRESS_CSS = \`
+@keyframes progressSlide { from { transform: translateX(-100%); } to { transform: translateX(100%); } }
+.nav-progress-bar { animation: progressSlide 1s ease-in-out infinite; }
+\`;
+
+function NavigationProgress() {
+  const isLoading = useRouterState({ select: (s) => s.isLoading });
+  if (!isLoading) return null;
+  return (
+    <div className="fixed top-0 left-0 right-0 z-[9999] h-1 bg-primary/20 overflow-hidden">
+      <style dangerouslySetInnerHTML={{ __html: PROGRESS_CSS }} />
+      <div className="nav-progress-bar h-full w-1/3 bg-primary rounded-full" />
+    </div>
+  );
+}
+
+function StableOutlet() {
+  const isLoading = useRouterState({ select: (s) => s.isLoading });
+  const ref = useRef<HTMLDivElement>(null);
+  const savedHeight = useRef<number | undefined>();
+
+  useEffect(() => {
+    if (isLoading && ref.current) {
+      savedHeight.current = ref.current.offsetHeight;
+    }
+    if (!isLoading) {
+      savedHeight.current = undefined;
+    }
+  }, [isLoading]);
+
+  return (
+    <div ref={ref} style={savedHeight.current ? { minHeight: savedHeight.current } : undefined}>
+      <Outlet />
+    </div>
+  );
+}
+
+const DECO_EVENTS_BOOTSTRAP = \`
+window.DECO = window.DECO || {};
+window.DECO.events = window.DECO.events || {
+  _q: [],
+  _subs: [],
+  dispatch: function(e) {
+    this._q.push(e);
+    for (var i = 0; i < this._subs.length; i++) {
+      try { this._subs[i](e); } catch(err) { console.error('[DECO.events]', err); }
+    }
+  },
+  subscribe: function(fn) {
+    this._subs.push(fn);
+    for (var i = 0; i < this._q.length; i++) {
+      try { fn(this._q[i]); } catch(err) {}
+    }
+  }
+};
+window.dataLayer = window.dataLayer || [];
+\`;
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      { title: "${siteTitle}" },
+    ],
+    links: [
+      { rel: "stylesheet", href: appCss },
+      { rel: "icon", href: "/favicon.ico" },
+    ],
+  }),
+  component: RootLayout,
+});
+
+function RootLayout() {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: { staleTime: 30_000 },
+        },
+      }),
+  );
+${gtmScript}
+
+  useEffect(() => {
+    const id = setTimeout(() => {
+      window.__deco_ready = true;
+      document.dispatchEvent(new Event("deco:ready"));
+    }, 500);
+    return () => clearTimeout(id);
+  }, []);
+
+  return (
+    <html lang="pt-BR" data-theme="light" suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body className="bg-base-200 text-base-content" suppressHydrationWarning>
+        <script dangerouslySetInnerHTML={{ __html: DECO_EVENTS_BOOTSTRAP }} />
+        <QueryClientProvider client={queryClient}>
+          <NavigationProgress />
+          <main>
+            <StableOutlet />
+          </main>
+        </QueryClientProvider>
+        <LiveControls site="${ctx.siteName}" />
+        <script type="module" dangerouslySetInnerHTML={{ __html: ANALYTICS_SCRIPT }} />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+`;
+}
+
+function generateIndex(siteTitle: string): string {
+  return `import { createFileRoute } from "@tanstack/react-router";
+import { cmsHomeRouteConfig, deferredSectionLoader } from "@decocms/start/routes";
+import { DecoPageRenderer } from "@decocms/start/hooks";
+
+export const Route = createFileRoute("/")({
+  ...cmsHomeRouteConfig({
+    defaultTitle: "${siteTitle}",
+    siteName: "${siteTitle}",
+  }),
+  component: HomePage,
+});
+
+function HomePage() {
+  const data = Route.useLoaderData() as Record<string, any> | null;
+
+  if (!data) {
+    return (
+      <div className="min-h-screen flex items-center justify-center">
+        <div className="text-center">
+          <h1 className="text-4xl font-bold mb-4">${siteTitle}</h1>
+          <p className="text-sm text-base-content/40 mt-2">Nenhuma pagina CMS encontrada para /</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <DecoPageRenderer
+      sections={data.resolvedSections ?? []}
+      deferredSections={data.deferredSections ?? []}
+      deferredPromises={data.deferredPromises}
+      pagePath={data.pagePath}
+      pageUrl={data.pageUrl}
+      loadDeferredSectionFn={deferredSectionLoader}
+    />
+  );
+}
+`;
+}
+
+function generateCatchAll(siteTitle: string): string {
+  return `import { createFileRoute } from "@tanstack/react-router";
+import { cmsRouteConfig, deferredSectionLoader } from "@decocms/start/routes";
+import { DecoPageRenderer } from "@decocms/start/hooks";
+
+const routeConfig = cmsRouteConfig({
+  siteName: "${siteTitle}",
+  defaultTitle: "${siteTitle}",
+});
+
+export const Route = createFileRoute("/$")({
+  ...routeConfig,
+  component: CmsPage,
+  notFoundComponent: NotFoundPage,
+  staleTime: 30_000,
+});
+
+function CmsPage() {
+  const data = Route.useLoaderData() as Record<string, any> | null;
+  if (!data) return <NotFoundPage />;
+
+  return (
+    <DecoPageRenderer
+      sections={data.resolvedSections ?? []}
+      deferredSections={data.deferredSections ?? []}
+      deferredPromises={data.deferredPromises}
+      pagePath={data.pagePath}
+      pageUrl={data.pageUrl}
+      loadDeferredSectionFn={deferredSectionLoader}
+    />
+  );
+}
+
+function NotFoundPage() {
+  return (
+    <div className="min-h-screen flex items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-6xl font-bold text-base-content/20 mb-4">404</h1>
+        <h2 className="text-2xl font-bold mb-2">Pagina nao encontrada</h2>
+        <a href="/" className="btn btn-primary">Voltar para Home</a>
+      </div>
+    </div>
+  );
+}
+`;
+}
+
+function generateDecoMeta(): string {
+  return `import { createFileRoute } from "@tanstack/react-router";
+import { decoMetaRoute } from "@decocms/start/routes";
+
+export const Route = createFileRoute("/deco/meta")(decoMetaRoute);
+`;
+}
+
+function generateDecoInvoke(): string {
+  return `import { createFileRoute } from "@tanstack/react-router";
+import { decoInvokeRoute } from "@decocms/start/routes";
+
+export const Route = createFileRoute("/deco/invoke/$")(decoInvokeRoute);
+`;
+}
+
+function generateDecoRender(): string {
+  return `import { createFileRoute } from "@tanstack/react-router";
+import { decoRenderRoute } from "@decocms/start/routes";
+
+export const Route = createFileRoute("/deco/render")(decoRenderRoute);
+`;
+}

package/scripts/migrate/templates/server-entry.ts

@@ -0,0 +1,148 @@
+import type { MigrationContext } from "../types.ts";
+
+export function generateServerEntry(
+  ctx: MigrationContext,
+): Record<string, string> {
+  return {
+    "src/server.ts": generateServer(),
+    "src/worker-entry.ts": generateWorkerEntry(ctx),
+    "src/router.tsx": generateRouter(),
+    "src/runtime.ts": generateRuntime(),
+    "src/context.ts": generateContext(ctx),
+  };
+}
+
+function generateServer(): string {
+  return `import {
+  createStartHandler,
+  defaultStreamHandler,
+} from "@tanstack/react-start/server";
+
+export default createStartHandler(defaultStreamHandler);
+`;
+}
+
+function generateWorkerEntry(ctx: MigrationContext): string {
+  return `/**
+ * Cloudflare Worker entry point.
+ *
+ * For a simple site without VTEX proxy or A/B testing, this is a thin wrapper
+ * around the TanStack Start handler. Add proxy logic, security headers, or
+ * A/B testing as needed.
+ */
+import { createDecoWorkerEntry } from "@decocms/start/worker";
+
+const handler = createDecoWorkerEntry({
+  siteName: "${ctx.siteName}",
+});
+
+export default handler;
+`;
+}
+
+function generateRouter(): string {
+  return `import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+import type { SearchSerializer, SearchParser } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+import "./setup";
+
+const parseSearch: SearchParser = (searchStr) => {
+  const str = searchStr.startsWith("?") ? searchStr.slice(1) : searchStr;
+  if (!str) return {};
+  const params = new URLSearchParams(str);
+  const result: Record<string, string | string[]> = {};
+  for (const key of new Set(params.keys())) {
+    const values = params.getAll(key);
+    result[key] = values.length === 1 ? values[0] : values;
+  }
+  return result;
+};
+
+const stringifySearch: SearchSerializer = (search) => {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(search)) {
+    if (value === undefined || value === null || value === "") continue;
+    if (Array.isArray(value)) {
+      for (const v of value) params.append(key, String(v));
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  const str = params.toString();
+  return str ? \`?\${str}\` : "";
+};
+
+export function getRouter() {
+  const router = createTanStackRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreload: "intent",
+    parseSearch,
+    stringifySearch,
+  });
+  return router;
+}
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: ReturnType<typeof getRouter>;
+  }
+}
+`;
+}
+
+function generateRuntime(): string {
+  return `/**
+ * Runtime invoke proxy — turns nested property access into typed RPC calls.
+ *
+ *   invoke.vtex.loaders.productList(props)
+ *   → POST /deco/invoke/vtex/loaders/productList
+ */
+function createNestedInvokeProxy(path: string[] = []): any {
+  return new Proxy(
+    Object.assign(async (props: any) => {
+      const key = path.join("/");
+      for (const k of [key, \`\${key}.ts\`]) {
+        const response = await fetch(\`/deco/invoke/\${k}\`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(props ?? {}),
+        });
+        if (response.status === 404) continue;
+        if (!response.ok) {
+          throw new Error(\`invoke(\${k}) failed: \${response.status}\`);
+        }
+        return response.json();
+      }
+      throw new Error(\`invoke(\${key}) failed: handler not found\`);
+    }, {}),
+    {
+      get(_target: any, prop: string) {
+        if (prop === "then" || prop === "catch" || prop === "finally") {
+          return undefined;
+        }
+        return createNestedInvokeProxy([...path, prop]);
+      },
+    },
+  );
+}
+
+export const invoke = createNestedInvokeProxy() as any;
+export const Runtime = { invoke };
+`;
+}
+
+function generateContext(ctx: MigrationContext): string {
+  return `import { createContext } from "react";
+
+export interface AccountContextValue {
+  name: string;
+}
+
+const Account = createContext<AccountContextValue>({
+  name: "${ctx.siteName}",
+});
+
+export default Account;
+`;
+}

package/scripts/migrate/templates/setup.ts

@@ -0,0 +1,32 @@
+import type { MigrationContext } from "../types.ts";
+
+export function generateSetup(_ctx: MigrationContext): string {
+  return `/**
+ * Site setup — registers all sections, loaders and matchers with the CMS.
+ *
+ * This file is imported by router.tsx at startup.
+ * It uses import.meta.glob to lazily discover all section components.
+ */
+import { registerSections } from "@decocms/start/cms";
+import { registerMatcher } from "@decocms/start/matchers";
+
+// -- Section Registry --
+// Discovers all .tsx files under src/sections/ and registers them as CMS blocks.
+const sectionModules = import.meta.glob("./sections/**/*.tsx");
+registerSections(sectionModules);
+
+// -- Matchers --
+// Register any custom matchers here.
+// Example: registerMatcher("device", deviceMatcher);
+
+// -- Loader Cache --
+// Register cached loaders here if needed.
+// Example:
+// import { createCachedLoader } from "@decocms/start/loaders";
+// registerLoader("productList", createCachedLoader(vtexProductList, { ttl: 60_000 }));
+
+// -- CMS Blocks --
+// Load generated blocks at module level so they're available for resolution.
+import "./server/cms/blocks.gen";
+`;
+}

package/scripts/migrate/templates/tsconfig.ts

@@ -0,0 +1,21 @@
+export function generateTsconfig(): string {
+  const config = {
+    compilerOptions: {
+      jsx: "react-jsx",
+      moduleResolution: "bundler",
+      module: "ESNext",
+      target: "ES2022",
+      skipLibCheck: true,
+      strictNullChecks: true,
+      forceConsistentCasingInFileNames: true,
+      types: ["vite/client"],
+      baseUrl: ".",
+      paths: {
+        "~/*": ["./src/*"],
+      },
+    },
+    include: ["src/**/*", "vite.config.ts"],
+  };
+
+  return JSON.stringify(config, null, 2) + "\n";
+}

package/scripts/migrate/templates/vite-config.ts

@@ -0,0 +1,108 @@
+import type { MigrationContext } from "../types.ts";
+
+export function generateViteConfig(ctx: MigrationContext): string {
+  return `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({
+  server: {
+    allowedHosts: [".decocdn.com"],
+  },
+  plugins: [
+    cloudflare({ viteEnvironment: { name: "ssr" } }),
+    tanstackStart({ server: { entry: "server" } }),
+    react({
+      babel: {
+        plugins: [
+          ["babel-plugin-react-compiler", { target: "19" }],
+        ],
+      },
+    }),
+    tailwindcss(),
+    decoVitePlugin(),
+    {
+      name: "site-manual-chunks",
+      config(_cfg, { command }) {
+        if (command !== "build") return;
+        return {
+          build: {
+            rollupOptions: {
+              output: {
+                manualChunks(id: string) {
+                  if (id.includes("node_modules/react-dom") || id.includes("node_modules/react/"))
+                    return "vendor-react";
+                  if (id.includes("@tanstack/react-router") || id.includes("@tanstack/start"))
+                    return "vendor-router";
+                  if (id.includes("@tanstack/react-query")) return "vendor-query";
+                },
+              },
+            },
+          },
+        };
+      },
+    },
+    {
+      name: "deco-stub-meta-gen",
+      enforce: "pre" as const,
+      resolveId(id, importer, options) {
+        if (!options?.ssr && importer && id.includes("meta.gen")) {
+          return "\\0stub:meta-gen";
+        }
+      },
+      load(id) {
+        if (id === "\\0stub:meta-gen") {
+          return "export default {};";
+        }
+      },
+    },
+  ],
+  build: {
+    sourcemap: "hidden",
+    rollupOptions: {
+      onLog(level, log, handler) {
+        if (
+          log.code === "PLUGIN_WARNING" &&
+          log.plugin === "vite:reporter" &&
+          log.message?.includes("dynamic import will not move module")
+        ) {
+          return;
+        }
+        handler(level, log);
+      },
+    },
+  },
+  define: {
+    "process.env.DECO_SITE_NAME": JSON.stringify(
+      process.env.DECO_SITE_NAME || "${ctx.siteName}"
+    ),
+  },
+  esbuild: {
+    jsx: "automatic",
+    jsxImportSource: "react",
+  },
+  resolve: {
+    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,
+    },
+  },
+});
+`;
+}

package/scripts/migrate/templates/wrangler.ts

@@ -0,0 +1,25 @@
+import type { MigrationContext } from "../types.ts";
+
+export function generateWrangler(ctx: MigrationContext): string {
+  // Sanitize site name for worker name (lowercase, hyphens only)
+  const workerName = ctx.siteName
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-");
+
+  return `{
+  "name": "${workerName}-tanstack",
+  "compatibility_date": "2026-02-14",
+  "compatibility_flags": ["nodejs_compat", "no_handle_cross_request_promise_resolution"],
+  "main": "./src/worker-entry.ts",
+  "workers_dev": true,
+  "preview_urls": true,
+  "observability": {
+    "logs": {
+      "enabled": true,
+      "invocation_logs": true
+    }
+  }
+}
+`;
+}