@decocms/start 1.0.0 → 1.1.0

package/package.json

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

package/scripts/generate-loaders.ts

@@ -0,0 +1,133 @@
+#!/usr/bin/env tsx
+/**
+ * Scans site loader and action files and generates a registry map
+ * for COMMERCE_LOADERS pass-through entries.
+ *
+ * Each loader/action file that exports a default function gets a generated
+ * entry like:
+ *   "site/loaders/SAP/getUser": async (props) => {
+ *     const mod = await import("../../loaders/SAP/getUser");
+ *     return mod.default(props);
+ *   },
+ *
+ * Both keyed with and without `.ts` suffix for CMS block compatibility.
+ *
+ * Files listed in --exclude are skipped (they need custom wiring in setup.ts).
+ *
+ * Usage (from site root):
+ *   npx tsx node_modules/@decocms/start/scripts/generate-loaders.ts
+ *
+ * CLI:
+ *   --loaders-dir  override loaders input  (default: src/loaders)
+ *   --actions-dir  override actions input  (default: src/actions)
+ *   --out-file     override output         (default: src/server/cms/loaders.gen.ts)
+ *   --exclude      comma-separated list of loader keys to skip (they have custom wiring)
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+function arg(name: string, fallback: string): string {
+  const idx = args.indexOf(`--${name}`);
+  return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
+}
+
+const loadersDir = path.resolve(process.cwd(), arg("loaders-dir", "src/loaders"));
+const actionsDir = path.resolve(process.cwd(), arg("actions-dir", "src/actions"));
+const outFile = path.resolve(process.cwd(), arg("out-file", "src/server/cms/loaders.gen.ts"));
+const excludeRaw = arg("exclude", "");
+const excludeSet = new Set(excludeRaw.split(",").map((s) => s.trim()).filter(Boolean));
+
+function walkDir(dir: string): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(fullPath));
+    } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function fileToKey(filePath: string, baseDir: string, prefix: string): string {
+  const rel = path.relative(baseDir, filePath).replace(/\\/g, "/").replace(/\.tsx?$/, "");
+  return `${prefix}/${rel}`;
+}
+
+function relativeImportPath(from: string, to: string): string {
+  let rel = path.relative(path.dirname(from), to).replace(/\\/g, "/");
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return rel.replace(/\.tsx?$/, "");
+}
+
+function hasDefaultExport(content: string): boolean {
+  return /export\s+default\b/.test(content) || /export\s*\{[^}]*\bdefault\b/.test(content);
+}
+
+// ---------------------------------------------------------------------------
+
+interface LoaderEntry {
+  key: string;
+  importPath: string;
+}
+
+const entries: LoaderEntry[] = [];
+
+for (const filePath of walkDir(loadersDir)) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  if (!hasDefaultExport(content)) continue;
+  const key = fileToKey(filePath, loadersDir, "site/loaders");
+  if (excludeSet.has(key) || excludeSet.has(`${key}.ts`)) continue;
+  entries.push({
+    key,
+    importPath: relativeImportPath(outFile, filePath),
+  });
+}
+
+for (const filePath of walkDir(actionsDir)) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  if (!hasDefaultExport(content)) continue;
+  const key = fileToKey(filePath, actionsDir, "site/actions");
+  if (excludeSet.has(key) || excludeSet.has(`${key}.ts`)) continue;
+  entries.push({
+    key,
+    importPath: relativeImportPath(outFile, filePath),
+  });
+}
+
+entries.sort((a, b) => a.key.localeCompare(b.key));
+
+const lines: string[] = [
+  "// Auto-generated by @decocms/start/scripts/generate-loaders.ts",
+  "// Do not edit manually. Run `npm run generate:loaders` to update.",
+  "//",
+  "// Pass-through loader/action entries for COMMERCE_LOADERS.",
+  "// Custom-wired entries should be excluded via --exclude and added manually in setup.ts.",
+  "",
+  "export const siteLoaders: Record<string, (props: any) => Promise<any>> = {",
+];
+
+for (const entry of entries) {
+  lines.push(`  "${entry.key}": async (props: any) => {`);
+  lines.push(`    const mod = await import("${entry.importPath}");`);
+  lines.push("    return mod.default(props);");
+  lines.push("  },");
+  lines.push(`  "${entry.key}.ts": async (props: any) => {`);
+  lines.push(`    const mod = await import("${entry.importPath}");`);
+  lines.push("    return mod.default(props);");
+  lines.push("  },");
+}
+
+lines.push("};");
+lines.push("");
+
+fs.mkdirSync(path.dirname(outFile), { recursive: true });
+fs.writeFileSync(outFile, lines.join("\n"));
+
+console.log(
+  `Generated ${entries.length} loader entries (${entries.length * 2} with .ts aliases) → ${path.relative(process.cwd(), outFile)}`,
+);

package/scripts/generate-sections.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env tsx
+/**
+ * Scans site section files and extracts convention-based metadata:
+ *   - export const eager = true       → alwaysEager
+ *   - export const cache = "listing"  → registerCacheableSections
+ *   - export const layout = true      → registerLayoutSections
+ *   - export const sync = true        → registerSectionsSync (bundled, not lazy)
+ *   - export const clientOnly = true  → registerSection with clientOnly
+ *   - export const seo = true         → registerSeoSections
+ *   - export function LoadingFallback → registerSection with loadingFallback
+ *
+ * Emits sections.gen.ts with metadata + sync imports for sections marked sync=true.
+ *
+ * Usage (from site root):
+ *   npx tsx node_modules/@decocms/start/scripts/generate-sections.ts
+ *
+ * CLI:
+ *   --sections-dir  override input  (default: src/sections)
+ *   --out-file      override output (default: src/server/cms/sections.gen.ts)
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+function arg(name: string, fallback: string): string {
+  const idx = args.indexOf(`--${name}`);
+  return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
+}
+
+const sectionsDir = path.resolve(process.cwd(), arg("sections-dir", "src/sections"));
+const outFile = path.resolve(process.cwd(), arg("out-file", "src/server/cms/sections.gen.ts"));
+
+interface SectionMeta {
+  eager?: boolean;
+  cache?: string;
+  layout?: boolean;
+  sync?: boolean;
+  clientOnly?: boolean;
+  seo?: boolean;
+  hasLoadingFallback?: boolean;
+}
+
+const EXPORT_CONST_RE = /export\s+const\s+(eager|cache|layout|sync|clientOnly|seo)\s*=\s*(.+?)(?:;|\n)/g;
+const LOADING_FALLBACK_RE = /export\s+(?:function|const)\s+LoadingFallback\b/;
+
+function extractMeta(content: string): SectionMeta | null {
+  const meta: SectionMeta = {};
+  let found = false;
+
+  for (const match of content.matchAll(EXPORT_CONST_RE)) {
+    const key = match[1] as keyof SectionMeta;
+    const rawValue = match[2].trim().replace(/['"]/g, "");
+    found = true;
+
+    if (key === "cache") {
+      meta.cache = rawValue;
+    } else if (rawValue === "true") {
+      (meta as any)[key] = true;
+    }
+  }
+
+  if (LOADING_FALLBACK_RE.test(content)) {
+    meta.hasLoadingFallback = true;
+    found = true;
+  }
+
+  return found ? meta : null;
+}
+
+function walkDir(dir: string, base: string = dir): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(fullPath, base));
+    } else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function fileToSectionKey(filePath: string, _sectionsDir: string): string {
+  const rel = path.relative(_sectionsDir, filePath).replace(/\\/g, "/");
+  return `site/sections/${rel}`;
+}
+
+function relativeImportPath(from: string, to: string): string {
+  let rel = path.relative(path.dirname(from), to).replace(/\\/g, "/");
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return rel.replace(/\.tsx?$/, "");
+}
+
+// ---------------------------------------------------------------------------
+
+if (!fs.existsSync(sectionsDir)) {
+  console.warn(`Sections directory not found: ${sectionsDir} — generating empty output.`);
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  fs.writeFileSync(outFile, [
+    "// Auto-generated — no sections found.",
+    "export const sectionMeta = {};",
+    "",
+  ].join("\n"));
+  process.exit(0);
+}
+
+const sectionFiles = walkDir(sectionsDir);
+const entries: Array<{ key: string; meta: SectionMeta; filePath: string }> = [];
+
+for (const filePath of sectionFiles) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const meta = extractMeta(content);
+  if (!meta) continue;
+  const key = fileToSectionKey(filePath, sectionsDir);
+  entries.push({ key, meta, filePath });
+}
+
+const syncEntries = entries.filter((e) => e.meta.sync);
+const fallbackEntries = entries.filter((e) => e.meta.hasLoadingFallback);
+
+const lines: string[] = [
+  "// Auto-generated by @decocms/start/scripts/generate-sections.ts",
+  "// Do not edit manually. Add convention exports to your section files instead.",
+  "//",
+  "// Supported conventions:",
+  "//   export const eager = true       → always SSR'd (never deferred)",
+  "//   export const cache = \"listing\"  → SWR-cached section loader results",
+  "//   export const layout = true      → cached as layout (Header, Footer, Theme)",
+  "//   export const sync = true        → bundled synchronously (not lazy-loaded)",
+  "//   export const clientOnly = true  → skip SSR (client-only rendering)",
+  "//   export const seo = true         → SEO section (provides page head data)",
+  "//   export function LoadingFallback → skeleton shown while section loads",
+  "",
+];
+
+// Sync imports — sections marked sync=true get static imports for registerSectionsSync
+for (let i = 0; i < syncEntries.length; i++) {
+  const e = syncEntries[i];
+  const importPath = relativeImportPath(outFile, e.filePath);
+  const varName = `_sync${i}`;
+  lines.push(`import * as ${varName} from "${importPath}";`);
+}
+
+// LoadingFallback imports — sections with LoadingFallback that aren't sync-imported
+const nonSyncFallbacks = fallbackEntries.filter((e) => !e.meta.sync);
+for (let i = 0; i < nonSyncFallbacks.length; i++) {
+  const e = nonSyncFallbacks[i];
+  const importPath = relativeImportPath(outFile, e.filePath);
+  lines.push(`import { LoadingFallback as _fb${i} } from "${importPath}";`);
+}
+
+lines.push("");
+
+// Metadata map
+lines.push("export interface SectionMetaEntry {");
+lines.push("  eager?: boolean;");
+lines.push("  cache?: string;");
+lines.push("  layout?: boolean;");
+lines.push("  sync?: boolean;");
+lines.push("  clientOnly?: boolean;");
+lines.push("  seo?: boolean;");
+lines.push("  hasLoadingFallback?: boolean;");
+lines.push("}");
+lines.push("");
+lines.push("export const sectionMeta: Record<string, SectionMetaEntry> = {");
+for (const e of entries) {
+  const props = Object.entries(e.meta)
+    .map(([k, v]) => `${k}: ${typeof v === "string" ? `"${v}"` : v}`)
+    .join(", ");
+  lines.push(`  "${e.key}": { ${props} },`);
+}
+lines.push("};");
+lines.push("");
+
+// Sync components map
+if (syncEntries.length > 0) {
+  lines.push("export const syncComponents: Record<string, any> = {");
+  for (let i = 0; i < syncEntries.length; i++) {
+    lines.push(`  "${syncEntries[i].key}": _sync${i},`);
+  }
+  lines.push("};");
+} else {
+  lines.push("export const syncComponents: Record<string, any> = {};");
+}
+lines.push("");
+
+// LoadingFallback components map
+const allFallbacks = entries.filter((e) => e.meta.hasLoadingFallback);
+if (allFallbacks.length > 0) {
+  lines.push("export const loadingFallbacks: Record<string, React.ComponentType<any>> = {");
+  for (const e of allFallbacks) {
+    if (e.meta.sync) {
+      const syncIdx = syncEntries.indexOf(e);
+      lines.push(`  "${e.key}": _sync${syncIdx}.LoadingFallback,`);
+    } else {
+      const fbIdx = nonSyncFallbacks.indexOf(e);
+      lines.push(`  "${e.key}": _fb${fbIdx},`);
+    }
+  }
+  lines.push("};");
+} else {
+  lines.push("export const loadingFallbacks: Record<string, React.ComponentType<any>> = {};");
+}
+lines.push("");
+
+fs.mkdirSync(path.dirname(outFile), { recursive: true });
+fs.writeFileSync(outFile, lines.join("\n"));
+
+console.log(
+  `Generated section metadata for ${entries.length} sections → ${path.relative(process.cwd(), outFile)}`,
+);
+console.log(
+  `  ${syncEntries.length} sync, ${allFallbacks.length} with LoadingFallback, ` +
+  `${entries.filter((e) => e.meta.eager).length} eager, ` +
+  `${entries.filter((e) => e.meta.layout).length} layout, ` +
+  `${entries.filter((e) => e.meta.cache).length} cached`,
+);

package/src/cms/applySectionConventions.ts

@@ -0,0 +1,109 @@
+/**
+ * Applies convention-based section metadata generated by generate-sections.ts.
+ *
+ * Reads the generated sectionMeta/syncComponents/loadingFallbacks and calls
+ * the appropriate registration functions — replacing manual calls to
+ * registerSectionsSync, setAsyncRenderingConfig, registerCacheableSections,
+ * registerLayoutSections, registerSeoSections, and registerSection.
+ */
+import {
+  registerSection,
+  registerSectionsSync,
+} from "./registry";
+import {
+  registerCacheableSections,
+  registerLayoutSections,
+} from "./sectionLoaders";
+import {
+  registerSeoSections,
+  setAsyncRenderingConfig,
+  getAsyncRenderingConfig,
+} from "./resolve";
+
+export interface SectionMetaEntry {
+  eager?: boolean;
+  cache?: string;
+  layout?: boolean;
+  sync?: boolean;
+  clientOnly?: boolean;
+  seo?: boolean;
+  hasLoadingFallback?: boolean;
+}
+
+export interface ApplySectionConventionsInput {
+  /** Section metadata map from sections.gen.ts */
+  meta: Record<string, SectionMetaEntry>;
+  /** Sync-imported section modules from sections.gen.ts */
+  syncComponents?: Record<string, any>;
+  /** LoadingFallback components from sections.gen.ts */
+  loadingFallbacks?: Record<string, React.ComponentType<any>>;
+  /** Lazy section loaders from import.meta.glob (used for clientOnly/loadingFallback registration) */
+  sectionGlob?: Record<string, () => Promise<any>>;
+}
+
+export function applySectionConventions(input: ApplySectionConventionsInput): void {
+  const { meta, syncComponents, loadingFallbacks, sectionGlob } = input;
+
+  const eagerSections: string[] = [];
+  const layoutSections: string[] = [];
+  const seoSections: string[] = [];
+  const cacheableSections: Record<string, string> = {};
+
+  for (const [key, entry] of Object.entries(meta)) {
+    if (entry.eager) eagerSections.push(key);
+    if (entry.layout) layoutSections.push(key);
+    if (entry.seo) seoSections.push(key);
+    if (entry.cache) cacheableSections[key] = entry.cache;
+
+    if (entry.clientOnly && sectionGlob) {
+      const globKey = sectionGlobKey(key, sectionGlob);
+      if (globKey) {
+        registerSection(key, sectionGlob[globKey] as any, { clientOnly: true });
+      }
+    }
+
+    if (entry.hasLoadingFallback && loadingFallbacks?.[key] && sectionGlob) {
+      const globKey = sectionGlobKey(key, sectionGlob);
+      if (globKey) {
+        registerSection(key, sectionGlob[globKey] as any, {
+          loadingFallback: loadingFallbacks[key],
+        });
+      }
+    }
+  }
+
+  if (syncComponents && Object.keys(syncComponents).length > 0) {
+    registerSectionsSync(syncComponents);
+  }
+
+  if (eagerSections.length > 0) {
+    const existing = getAsyncRenderingConfig();
+    setAsyncRenderingConfig({
+      ...existing,
+      alwaysEager: [...(existing.alwaysEager ?? []), ...eagerSections],
+    });
+  }
+
+  if (layoutSections.length > 0) {
+    registerLayoutSections(layoutSections);
+  }
+
+  if (seoSections.length > 0) {
+    registerSeoSections(seoSections);
+  }
+
+  if (Object.keys(cacheableSections).length > 0) {
+    registerCacheableSections(cacheableSections);
+  }
+}
+
+function sectionGlobKey(
+  sectionKey: string,
+  glob: Record<string, () => Promise<any>>,
+): string | null {
+  const relative = sectionKey.replace("site/sections/", "./sections/");
+  if (glob[relative]) return relative;
+  const withDot = sectionKey.replace("site/", "./");
+  if (glob[withDot]) return withDot;
+  return null;
+}

package/src/cms/index.ts

@@ -70,3 +70,6 @@ export {
   runSectionLoaders,
   runSingleSectionLoader,
 } from "./sectionLoaders";
+export { compose, withDevice, withMobile, withSearchParam } from "./sectionMixins";
+export type { ApplySectionConventionsInput, SectionMetaEntry } from "./applySectionConventions";
+export { applySectionConventions } from "./applySectionConventions";

package/src/cms/sectionMixins.ts

@@ -0,0 +1,76 @@
+/**
+ * Section Loader Mixins
+ *
+ * Reusable section loader factories for common patterns like device detection,
+ * mobile flag injection, and search param extraction. Eliminates repetitive
+ * `(props, req) => ({ ...props, device: detectDevice(...) })` boilerplate.
+ *
+ * @example
+ * ```ts
+ * import { withDevice, withMobile, compose } from "@decocms/start/cms";
+ *
+ * registerSectionLoaders({
+ *   "site/sections/Product/ProductShelf.tsx": withDevice(),
+ *   "site/sections/Images/Carousel.tsx": withMobile(),
+ *   "site/sections/Header/Header.tsx": compose(withDevice(), withSearchParam()),
+ * });
+ * ```
+ */
+import { detectDevice } from "../sdk/useDevice";
+import type { SectionLoaderFn } from "./sectionLoaders";
+
+/**
+ * Injects `device: "mobile" | "desktop" | "tablet"` from the request User-Agent.
+ */
+export function withDevice(): SectionLoaderFn {
+  return (props, req) => ({
+    ...props,
+    device: detectDevice(req.headers.get("user-agent") ?? ""),
+  });
+}
+
+/**
+ * Injects `isMobile: boolean` (true for mobile and tablet) from the request User-Agent.
+ */
+export function withMobile(): SectionLoaderFn {
+  return (props, req) => {
+    const d = detectDevice(req.headers.get("user-agent") ?? "");
+    return { ...props, isMobile: d === "mobile" || d === "tablet" };
+  };
+}
+
+const REGEX_QUERY_VALUE = /[?&]q=([^&]*)/;
+
+/**
+ * Injects `currentSearchParam: string | undefined` extracted from the `?q=` URL parameter.
+ */
+export function withSearchParam(): SectionLoaderFn {
+  return (props, req) => {
+    const match = req.url.match(REGEX_QUERY_VALUE);
+    return {
+      ...props,
+      currentSearchParam: match ? decodeURIComponent(match[1]) : undefined,
+    };
+  };
+}
+
+/**
+ * Composes multiple section loader mixins into a single loader.
+ * Each mixin's result is merged left-to-right (later mixins override earlier ones).
+ *
+ * @example
+ * ```ts
+ * compose(withDevice(), withSearchParam())
+ * // Equivalent to: (props, req) => ({ ...props, device: ..., currentSearchParam: ... })
+ * ```
+ */
+export function compose(...mixins: SectionLoaderFn[]): SectionLoaderFn {
+  return async (props, req) => {
+    let result = { ...props };
+    for (const mixin of mixins) {
+      const partial = await mixin(result, req);
+      result = { ...result, ...partial };
+    }
+    return result;
+  };
+}