@decocms/start 0.19.0

package/src/middleware/liveness.ts

@@ -0,0 +1,21 @@
+/**
+ * Liveness and readiness probe handlers.
+ *
+ * - `/_liveness` — simple 200 OK for load balancers (K8s, Cloudflare)
+ * - `/deco/_health` — detailed JSON health metrics (delegated to healthMetrics)
+ */
+
+import { handleHealthCheck } from "./healthMetrics";
+
+export function handleLiveness(request: Request): Response | null {
+  const url = new URL(request.url);
+
+  if (url.pathname === "/_liveness" || url.pathname === "/deco/_liveness") {
+    return new Response("OK", {
+      status: 200,
+      headers: { "Content-Type": "text/plain", "Cache-Control": "no-store" },
+    });
+  }
+
+  return handleHealthCheck(request);
+}

package/src/middleware/observability.ts

@@ -0,0 +1,205 @@
+/**
+ * Observability utilities for deco middleware.
+ *
+ * Pluggable adapters for tracing (spans) and metrics (counters, gauges,
+ * histograms). Works with any backend: OpenTelemetry, Sentry, Datadog, etc.
+ *
+ * @example
+ * ```ts
+ * import { configureTracer, configureMeter } from "@decocms/start/middleware";
+ * import { trace, metrics } from "@opentelemetry/api";
+ *
+ * configureTracer({
+ *   startSpan: (name, attrs) => {
+ *     const span = trace.getTracer("deco").startSpan(name, { attributes: attrs });
+ *     return {
+ *       end: () => span.end(),
+ *       setError: (e) => span.recordException(e),
+ *       setAttribute: (k, v) => span.setAttribute(k, v),
+ *     };
+ *   },
+ * });
+ *
+ * configureMeter({
+ *   counterInc: (name, value, labels) => metrics.getMeter("deco").createCounter(name).add(value, labels),
+ *   histogramRecord: (name, value, labels) => metrics.getMeter("deco").createHistogram(name).record(value, labels),
+ * });
+ * ```
+ */
+
+// ---------------------------------------------------------------------------
+// Tracer
+// ---------------------------------------------------------------------------
+
+import * as asyncHooks from "node:async_hooks";
+
+export interface Span {
+  end(): void;
+  setError?(error: unknown): void;
+  setAttribute?(key: string, value: string | number | boolean): void;
+}
+
+export interface TracerAdapter {
+  startSpan(name: string, attributes?: Record<string, string | number | boolean>): Span;
+}
+
+let tracer: TracerAdapter | null = null;
+
+// Per-request active span stored in AsyncLocalStorage so concurrent requests
+// cannot overwrite each other's span when `withTracing` awaits async work.
+// The namespace import + runtime guard mirrors loader.ts to stay safe in client builds.
+const ALS = (asyncHooks as any).AsyncLocalStorage as
+  | (new <T>() => { getStore(): T | undefined; run<R>(store: T, fn: () => R): R })
+  | undefined;
+const spanStorage: {
+  getStore(): Span | null | undefined;
+  run<R>(store: Span | null, fn: () => R): R;
+} = ALS ? new ALS<Span | null>() : { getStore: () => undefined, run: (_s: any, fn: any) => fn() };
+
+export function configureTracer(t: TracerAdapter) {
+  tracer = t;
+}
+
+export function getTracer(): TracerAdapter | null {
+  return tracer;
+}
+
+/** Get the currently active span for the current async context, if any. */
+export function getActiveSpan(): Span | null {
+  return spanStorage.getStore() ?? null;
+}
+
+/** Set an attribute on the active span, if one exists. */
+export function setSpanAttribute(key: string, value: string | number | boolean) {
+  getActiveSpan()?.setAttribute?.(key, value);
+}
+
+export async function withTracing<T>(
+  name: string,
+  fn: () => Promise<T>,
+  attributes?: Record<string, string | number | boolean>,
+): Promise<T> {
+  if (!tracer) return fn();
+
+  const span = tracer.startSpan(name, attributes);
+
+  try {
+    const result = await spanStorage.run(span, fn);
+    span.end();
+    return result;
+  } catch (error) {
+    span.setError?.(error);
+    span.end();
+    throw error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Meter
+// ---------------------------------------------------------------------------
+
+type Labels = Record<string, string | number | boolean>;
+
+export interface MeterAdapter {
+  counterInc(name: string, value?: number, labels?: Labels): void;
+  gaugeSet?(name: string, value: number, labels?: Labels): void;
+  histogramRecord?(name: string, value: number, labels?: Labels): void;
+}
+
+let meter: MeterAdapter | null = null;
+
+export function configureMeter(m: MeterAdapter) {
+  meter = m;
+}
+
+export function getMeter(): MeterAdapter | null {
+  return meter;
+}
+
+/** Pre-defined metric names for consistency. */
+export const MetricNames = {
+  HTTP_REQUESTS_TOTAL: "http_requests_total",
+  HTTP_REQUEST_DURATION_MS: "http_request_duration_ms",
+  HTTP_REQUEST_ERRORS: "http_request_errors_total",
+  CACHE_HIT: "cache_hit_total",
+  CACHE_MISS: "cache_miss_total",
+  RESOLVE_DURATION_MS: "resolve_duration_ms",
+  FETCH_DURATION_MS: "fetch_duration_ms",
+} as const;
+
+/**
+ * Record an HTTP request metric.
+ * Call in middleware after the response is produced.
+ */
+export function recordRequestMetric(
+  method: string,
+  path: string,
+  status: number,
+  durationMs: number,
+) {
+  if (!meter) return;
+  const labels: Labels = { method, path: normalizePath(path), status };
+  meter.counterInc(MetricNames.HTTP_REQUESTS_TOTAL, 1, labels);
+  meter.histogramRecord?.(MetricNames.HTTP_REQUEST_DURATION_MS, durationMs, labels);
+  if (status >= 500) {
+    meter.counterInc(MetricNames.HTTP_REQUEST_ERRORS, 1, labels);
+  }
+}
+
+/**
+ * Record a cache hit/miss metric.
+ */
+export function recordCacheMetric(hit: boolean, profile?: string) {
+  if (!meter) return;
+  const labels: Labels = profile ? { profile } : {};
+  meter.counterInc(hit ? MetricNames.CACHE_HIT : MetricNames.CACHE_MISS, 1, labels);
+}
+
+function normalizePath(path: string): string {
+  // Collapse dynamic segments to reduce cardinality
+  return path
+    .replace(/\/[0-9a-f]{8,}/gi, "/:id")
+    .replace(/\/\d+/g, "/:id")
+    .replace(/\/[^/]+\/p$/, "/:slug/p");
+}
+
+// ---------------------------------------------------------------------------
+// Request logging
+// ---------------------------------------------------------------------------
+
+const isDev =
+  typeof globalThis.process !== "undefined" && globalThis.process.env?.NODE_ENV === "development";
+
+/**
+ * Structured request log entry.
+ * JSON in production, colorized in development.
+ * Includes traceId when available.
+ */
+export function logRequest(
+  request: Request,
+  status: number,
+  durationMs: number,
+  extra?: Record<string, unknown>,
+) {
+  const url = new URL(request.url);
+
+  if (isDev) {
+    const color = status >= 500 ? "\x1b[31m" : status >= 400 ? "\x1b[33m" : "\x1b[32m";
+    const extraStr = extra ? ` ${JSON.stringify(extra)}` : "";
+    console.log(
+      `${color}${request.method}\x1b[0m ${url.pathname} ${status} ${durationMs.toFixed(0)}ms${extraStr}`,
+    );
+  } else {
+    console.log(
+      JSON.stringify({
+        level: status >= 500 ? "error" : "info",
+        method: request.method,
+        path: url.pathname,
+        status,
+        durationMs: Math.round(durationMs),
+        timestamp: new Date().toISOString(),
+        ...extra,
+      }),
+    );
+  }
+}

package/src/routes/adminRoutes.ts

@@ -0,0 +1,83 @@
+/**
+ * Admin Route Helpers
+ *
+ * Pre-built server handler configs for the Deco admin protocol routes.
+ * Sites spread these into their `createFileRoute` definitions to avoid
+ * repeating the same CORS + handler boilerplate.
+ *
+ * @example Site's `src/routes/deco/meta.ts`:
+ * ```ts
+ * import { createFileRoute } from "@tanstack/react-router";
+ * import { decoMetaRoute } from "@decocms/start/routes";
+ *
+ * export const Route = createFileRoute("/deco/meta")(decoMetaRoute);
+ * ```
+ */
+import { corsHeaders } from "../admin/cors";
+import { handleInvoke } from "../admin/invoke";
+import { handleMeta } from "../admin/meta";
+import { handleRender } from "../admin/render";
+
+type HandlerFn = (ctx: { request: Request }) => Promise<Response> | Response;
+
+function withCors(handler: HandlerFn): HandlerFn {
+  return async (ctx) => {
+    const response = await handler(ctx);
+    const headers = new Headers(response.headers);
+    for (const [k, v] of Object.entries(corsHeaders(ctx.request))) {
+      headers.set(k, v);
+    }
+    return new Response(response.body, {
+      status: response.status,
+      headers,
+    });
+  };
+}
+
+function optionsHandler(ctx: { request: Request }): Response {
+  return new Response(null, {
+    status: 204,
+    headers: corsHeaders(ctx.request),
+  });
+}
+
+/**
+ * Route config for `/deco/meta` — serves JSON Schema + manifest.
+ * Spread into `createFileRoute("/deco/meta")({...})`.
+ */
+export const decoMetaRoute = {
+  server: {
+    handlers: {
+      GET: withCors(({ request }) => handleMeta(request)),
+      OPTIONS: optionsHandler,
+    },
+  },
+};
+
+/**
+ * Route config for `/deco/render` — section/page preview in iframe.
+ * Spread into `createFileRoute("/deco/render")({...})`.
+ */
+export const decoRenderRoute = {
+  server: {
+    handlers: {
+      GET: withCors(async ({ request }) => handleRender(request)),
+      POST: withCors(async ({ request }) => handleRender(request)),
+      OPTIONS: optionsHandler,
+    },
+  },
+};
+
+/**
+ * Route config for `/deco/invoke/$` — loader/action execution.
+ * Spread into `createFileRoute("/deco/invoke/$")({...})`.
+ */
+export const decoInvokeRoute = {
+  server: {
+    handlers: {
+      GET: withCors(async ({ request }) => handleInvoke(request)),
+      POST: withCors(async ({ request }) => handleInvoke(request)),
+      OPTIONS: optionsHandler,
+    },
+  },
+};

package/src/routes/cmsRoute.ts

@@ -0,0 +1,302 @@
+/**
+ * CMS Route Helpers
+ *
+ * Reusable building blocks for CMS catch-all and homepage routes.
+ * Since TanStack Router requires routes to be file-based in the site repo,
+ * we export helper functions and config that sites use in their route files.
+ *
+ * @example Site's `src/routes/$.tsx`:
+ * ```ts
+ * import { createFileRoute, notFound } from "@tanstack/react-router";
+ * import { loadCmsPage, cmsRouteConfig } from "@decocms/start/routes";
+ * import { DecoPageRenderer } from "@decocms/start/hooks";
+ *
+ * export const Route = createFileRoute("/$")({
+ *   ...cmsRouteConfig({
+ *     siteName: "My Store",
+ *     defaultTitle: "My Store - Best products",
+ *     ignoreSearchParams: ["skuId"],
+ *   }),
+ * });
+ * ```
+ */
+
+import { createServerFn } from "@tanstack/react-start";
+import {
+  getCookies,
+  getRequest,
+  getRequestHeader,
+  getRequestUrl,
+} from "@tanstack/react-start/server";
+import { createElement } from "react";
+import { preloadSectionComponents } from "../cms/registry";
+import type { DeferredSection, MatcherContext, ResolvedSection } from "../cms/resolve";
+import { resolveDecoPage, resolveDeferredSection } from "../cms/resolve";
+import { runSectionLoaders, runSingleSectionLoader } from "../cms/sectionLoaders";
+import {
+  type CacheProfile,
+  cacheHeaders,
+  detectCacheProfile,
+  routeCacheDefaults,
+} from "../sdk/cacheHeaders";
+
+const isServer = typeof document === "undefined";
+
+// ---------------------------------------------------------------------------
+// Server function — loads a CMS page, runs section loaders, detects cache
+// ---------------------------------------------------------------------------
+
+type PageResult = Awaited<ReturnType<typeof loadCmsPageInternal>>;
+const pageInflight = new Map<string, Promise<PageResult>>();
+
+async function loadCmsPageInternal(fullPath: string) {
+  const [basePath] = fullPath.split("?");
+  const serverUrl = getRequestUrl();
+  // Prefer the real server URL when available — it preserves duplicate query
+  // params (e.g. filter.category-1=a&filter.category-1=b) that the TanStack
+  // Router search object (plain Record<string,string>) would collapse.
+  const realUrlPath = serverUrl.pathname + serverUrl.search;
+  const urlWithSearch =
+    realUrlPath.startsWith(basePath) && serverUrl.search
+      ? serverUrl.toString()
+      : fullPath.includes("?")
+        ? new URL(fullPath, serverUrl.origin).toString()
+        : serverUrl.toString();
+
+  const matcherCtx: MatcherContext = {
+    userAgent: getRequestHeader("user-agent") ?? "",
+    url: urlWithSearch,
+    path: basePath,
+    cookies: getCookies(),
+  };
+  const page = await resolveDecoPage(basePath, matcherCtx);
+  if (!page) return null;
+
+  const request = new Request(urlWithSearch, {
+    headers: getRequest().headers,
+  });
+  const enrichedSections = await runSectionLoaders(page.resolvedSections, request);
+
+  // Pre-import eager section modules so their default exports are cached
+  // in resolvedComponents. This ensures SSR renders with direct component
+  // refs, and the client hydration can skip React.lazy/Suspense.
+  const eagerKeys = enrichedSections.map((s) => s.component);
+  await preloadSectionComponents(eagerKeys);
+
+  const cacheProfile = detectCacheProfile(basePath);
+  return {
+    ...page,
+    resolvedSections: enrichedSections,
+    deferredSections: page.deferredSections,
+    cacheProfile,
+  };
+}
+
+export const loadCmsPage = createServerFn({ method: "GET" })
+  .inputValidator((data: unknown) => data as string)
+  .handler(async (ctx) => {
+    const fullPath = ctx.data;
+    const [basePath] = fullPath.split("?");
+
+    const existing = pageInflight.get(basePath);
+    if (existing) return existing;
+
+    const promise = loadCmsPageInternal(fullPath).finally(() => pageInflight.delete(basePath));
+    pageInflight.set(basePath, promise);
+    return promise;
+  });
+
+/**
+ * Same as loadCmsPage but hardcoded to "/" path.
+ * Avoids passing data through the server function for the homepage.
+ */
+export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async () => {
+  const matcherCtx: MatcherContext = {
+    userAgent: getRequestHeader("user-agent") ?? "",
+    url: getRequestUrl().toString(),
+    path: "/",
+    cookies: getCookies(),
+  };
+  const page = await resolveDecoPage("/", matcherCtx);
+  if (!page) return null;
+
+  const request = getRequest();
+  const enrichedSections = await runSectionLoaders(page.resolvedSections, request);
+
+  const eagerKeys = enrichedSections.map((s) => s.component);
+  await preloadSectionComponents(eagerKeys);
+
+  return {
+    ...page,
+    resolvedSections: enrichedSections,
+    deferredSections: page.deferredSections,
+  };
+});
+
+// ---------------------------------------------------------------------------
+// Deferred section loader — resolves + enriches a single section on demand
+// ---------------------------------------------------------------------------
+
+export const loadDeferredSection = createServerFn({ method: "POST" })
+  .inputValidator(
+    (data: unknown) =>
+      data as { component: string; rawProps: Record<string, any>; pagePath: string },
+  )
+  .handler(async (ctx) => {
+    const { component, rawProps, pagePath } = ctx.data;
+
+    const matcherCtx: MatcherContext = {
+      userAgent: getRequestHeader("user-agent") ?? "",
+      url: getRequestUrl().toString(),
+      path: pagePath,
+      cookies: getCookies(),
+    };
+
+    const section = await resolveDeferredSection(component, rawProps, pagePath, matcherCtx);
+    if (!section) return null;
+
+    const request = new Request(getRequestUrl().toString(), {
+      headers: getRequest().headers,
+    });
+    const enriched = await runSingleSectionLoader(section, request);
+    return enriched;
+  });
+
+// ---------------------------------------------------------------------------
+// Default pending component — shown during SPA navigation while loader runs
+// ---------------------------------------------------------------------------
+
+export function CmsPagePendingFallback() {
+  return createElement(
+    "div",
+    { className: "w-full min-h-[60vh] flex flex-col gap-6 py-8" },
+    createElement("div", {
+      className: "skeleton animate-pulse w-full rounded",
+      style: { aspectRatio: "1440/400", minHeight: 200 },
+    }),
+    createElement(
+      "div",
+      { className: "px-4 lg:px-8 flex flex-col gap-4" },
+      createElement("div", { className: "skeleton animate-pulse w-48 h-8 rounded" }),
+      createElement(
+        "div",
+        { className: "grid grid-cols-2 lg:grid-cols-4 gap-4" },
+        ...Array.from({ length: 4 }, (_, i) =>
+          createElement("div", {
+            key: i,
+            className: "skeleton animate-pulse w-full h-48 lg:h-64 rounded",
+          }),
+        ),
+      ),
+    ),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Route configuration factory
+// ---------------------------------------------------------------------------
+
+export interface CmsRouteOptions {
+  /** Site name used in page titles (e.g. "Espaço Smart"). */
+  siteName: string;
+  /** Default page title when CMS page has no name. */
+  defaultTitle: string;
+  /**
+   * Search params to exclude from loader deps.
+   * These params won't trigger a server re-fetch when they change.
+   * Defaults to `["skuId"]` — variant selection is client-side only.
+   */
+  ignoreSearchParams?: string[];
+  /** Custom pending component shown during SPA navigation. */
+  pendingComponent?: () => any;
+}
+
+/**
+ * Returns a TanStack Router route config object for a CMS catch-all route.
+ * Spread the result into your `createFileRoute("/$")({...})` call.
+ *
+ * Includes: loaderDeps, loader, headers, head, staleTime/gcTime.
+ * Does NOT include: component, notFoundComponent (site provides these).
+ */
+export function cmsRouteConfig(options: CmsRouteOptions) {
+  const { siteName, defaultTitle, ignoreSearchParams = ["skuId"], pendingComponent } = options;
+
+  const ignoreSet = new Set(ignoreSearchParams);
+
+  return {
+    loaderDeps: ({ search }: { search: Record<string, string> }) => {
+      const filtered = Object.fromEntries(
+        Object.entries(search ?? {}).filter(([k]) => !ignoreSet.has(k)),
+      );
+      return {
+        search: Object.keys(filtered).length ? filtered : undefined,
+      };
+    },
+
+    loader: async ({
+      params,
+      deps,
+    }: {
+      params: { _splat?: string };
+      deps: { search?: Record<string, string> };
+    }) => {
+      const basePath = "/" + (params._splat || "");
+      const searchStr = deps.search
+        ? "?" + new URLSearchParams(deps.search as Record<string, string>).toString()
+        : "";
+      const page = await loadCmsPage({ data: basePath + searchStr });
+
+      // On the client (SPA navigation or initial hydration), pre-import
+      // eager section modules BEFORE React renders. This ensures
+      // getResolvedComponent() returns a value and we skip React.lazy.
+      if (!isServer && page?.resolvedSections) {
+        const keys = page.resolvedSections.map((s: ResolvedSection) => s.component);
+        await preloadSectionComponents(keys);
+      }
+      return page;
+    },
+
+    ...(pendingComponent ? { pendingComponent } : {}),
+
+    ...routeCacheDefaults("product"),
+
+    headers: ({ loaderData }: { loaderData?: { cacheProfile?: CacheProfile } }) => {
+      const profile = loaderData?.cacheProfile ?? "listing";
+      return cacheHeaders(profile);
+    },
+
+    head: ({ loaderData }: { loaderData?: { name?: string } }) => ({
+      meta: [
+        {
+          title: loaderData?.name ? `${loaderData.name} | ${siteName}` : defaultTitle,
+        },
+      ],
+    }),
+  };
+}
+
+/**
+ * Returns a TanStack Router route config for the CMS homepage route.
+ * Spread into `createFileRoute("/")({...})`.
+ */
+export function cmsHomeRouteConfig(options: {
+  defaultTitle: string;
+  pendingComponent?: () => any;
+}) {
+  return {
+    loader: async () => {
+      const page = await loadCmsHomePage();
+      if (!isServer && page?.resolvedSections) {
+        const keys = page.resolvedSections.map((s: ResolvedSection) => s.component);
+        await preloadSectionComponents(keys);
+      }
+      return page;
+    },
+    ...(options.pendingComponent ? { pendingComponent: options.pendingComponent } : {}),
+    ...routeCacheDefaults("static"),
+    headers: () => cacheHeaders("static"),
+    head: () => ({
+      meta: [{ title: options.defaultTitle }],
+    }),
+  };
+}

package/src/routes/components.tsx

@@ -0,0 +1,34 @@
+import { Link } from "@tanstack/react-router";
+import type { ResolvedSection } from "../cms/resolve";
+import { DecoPageRenderer } from "../hooks/DecoPageRenderer";
+
+/**
+ * Default CMS page component. Renders all resolved sections.
+ * Sites can use this directly or build their own.
+ */
+export function CmsPage({ sections }: { sections: ResolvedSection[] }) {
+  return (
+    <div>
+      <DecoPageRenderer sections={sections} />
+    </div>
+  );
+}
+
+/**
+ * Default 404 page for CMS routes.
+ * Sites can override with their own branded version.
+ */
+export 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">Page Not Found</h2>
+        <p className="text-base-content/60 mb-6">No CMS page block matches this URL.</p>
+        <Link to="/" className="btn btn-primary">
+          Go Home
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/routes/index.ts

@@ -0,0 +1,15 @@
+export {
+  decoInvokeRoute,
+  decoMetaRoute,
+  decoRenderRoute,
+} from "./adminRoutes";
+export {
+  CmsPagePendingFallback,
+  type CmsRouteOptions,
+  cmsHomeRouteConfig,
+  cmsRouteConfig,
+  loadCmsHomePage,
+  loadCmsPage,
+  loadDeferredSection,
+} from "./cmsRoute";
+export { CmsPage, NotFoundPage } from "./components";