@decocms/start 0.43.0 → 1.1.0

package/src/sdk/router.ts

@@ -0,0 +1,92 @@
+/**
+ * Deco-flavored TanStack Router factory.
+ *
+ * Uses standard URLSearchParams serialization instead of TanStack's default
+ * JSON-based format. Required because VTEX (and most commerce platforms) uses
+ * filter URLs like `?filter.brand=Nike&filter.brand=Adidas` which must
+ * round-trip correctly through the router's search system.
+ */
+import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+import type {
+	SearchSerializer,
+	SearchParser,
+	AnyRoute,
+	TrailingSlashOption,
+} from "@tanstack/react-router";
+
+export const decoParseSearch: 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;
+};
+
+export const decoStringifySearch: 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 interface CreateDecoRouterOptions {
+	routeTree: AnyRoute;
+	scrollRestoration?: boolean;
+	defaultPreload?: "intent" | "viewport" | "render" | false;
+	trailingSlash?: TrailingSlashOption;
+	/**
+	 * Router context — passed to all route loaders/components via routeContext.
+	 * Commonly used for { queryClient } per TanStack Query integration docs.
+	 */
+	context?: Record<string, unknown>;
+	/**
+	 * Non-DOM provider component to wrap the entire router.
+	 * Per TanStack docs, only non-DOM-rendering components (providers) should
+	 * be used — anything else causes hydration errors.
+	 *
+	 * Example: QueryClientProvider wrapping
+	 *   Wrap: ({ children }) => <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+	 */
+	Wrap?: (props: { children: any }) => any;
+}
+
+/**
+ * Create a TanStack Router with Deco defaults:
+ * - URLSearchParams-based search serialization (not JSON)
+ * - Scroll restoration enabled
+ * - Preload on intent
+ */
+export function createDecoRouter(options: CreateDecoRouterOptions) {
+	const {
+		routeTree,
+		scrollRestoration = true,
+		defaultPreload = "intent",
+		trailingSlash,
+		context,
+		Wrap,
+	} = options;
+
+	return createTanStackRouter({
+		routeTree,
+		scrollRestoration,
+		defaultPreload,
+		trailingSlash,
+		context: context as any,
+		Wrap,
+		parseSearch: decoParseSearch,
+		stringifySearch: decoStringifySearch,
+	});
+}

package/src/sdk/workerEntry.ts

@@ -257,6 +257,44 @@ export interface DecoWorkerEntryOptions {
    */
   cacheVersionEnv?: string | false;
 
+  /**
+   * Security headers appended to every SSR response (HTML pages).
+   * Pass `false` to disable entirely.
+   *
+   * Default headers: X-Content-Type-Options, X-Frame-Options, Referrer-Policy,
+   * Permissions-Policy, X-XSS-Protection, HSTS, Cross-Origin-Opener-Policy.
+   *
+   * Custom entries are merged with defaults (custom values take precedence).
+   *
+   * @default DEFAULT_SECURITY_HEADERS
+   */
+  securityHeaders?: Record<string, string> | false;
+
+  /**
+   * Content Security Policy directives (report-only by default).
+   * Pass an array of directive strings which are joined with "; ".
+   * Pass `false` to omit CSP entirely.
+   *
+   * @example
+   * ```ts
+   * csp: [
+   *   "default-src 'self'",
+   *   "script-src 'self' 'unsafe-inline' https://www.googletagmanager.com",
+   *   "img-src 'self' data: https:",
+   * ]
+   * ```
+   */
+  csp?: string[] | false;
+
+  /**
+   * Automatically inject Cloudflare geo data (country, region, city)
+   * as internal cookies on every request so location matchers can read
+   * them from MatcherContext.cookies. The cookies are only visible
+   * within the Worker — they are never sent to the browser.
+   *
+   * @default true
+   */
+  autoInjectGeoCookies?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -327,6 +365,20 @@ export function injectGeoCookies(request: Request): Request {
 
 const ONE_YEAR = 31536000;
 
+/**
+ * Sensible security headers for any production storefront.
+ * CSP is intentionally not included — it's site-specific (third-party script domains).
+ */
+export const DEFAULT_SECURITY_HEADERS: Record<string, string> = {
+  "X-Content-Type-Options": "nosniff",
+  "X-Frame-Options": "SAMEORIGIN",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+  "X-XSS-Protection": "1; mode=block",
+  "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload",
+  "Cross-Origin-Opener-Policy": "same-origin-allow-popups",
+};
+
 const DEFAULT_BYPASS_PATHS = ["/_server", "/_build", "/deco/", "/live/", "/.decofile"];
 
 const FINGERPRINTED_ASSET_RE = /(?:\/_build)?\/assets\/.*-[a-zA-Z0-9_-]{8,}\.\w+$/;
@@ -366,8 +418,35 @@ export function createDecoWorkerEntry(
     stripTrackingParams: shouldStripTracking = true,
     previewShell: customPreviewShell,
     cacheVersionEnv = "BUILD_HASH",
+    securityHeaders: securityHeadersOpt,
+    csp: cspOpt,
+    autoInjectGeoCookies: geoOpt = true,
   } = options;
 
+  // Build the final security headers map (merged defaults + custom + CSP)
+  const secHeaders: Record<string, string> | null = (() => {
+    if (securityHeadersOpt === false) return null;
+    const base = { ...DEFAULT_SECURITY_HEADERS };
+    if (securityHeadersOpt) {
+      for (const [k, v] of Object.entries(securityHeadersOpt)) base[k] = v;
+    }
+    if (cspOpt && cspOpt.length > 0) {
+      base["Content-Security-Policy-Report-Only"] = cspOpt.join("; ");
+    }
+    return base;
+  })();
+
+  function applySecurityHeaders(resp: Response): Response {
+    if (!secHeaders) return resp;
+    const ct = resp.headers.get("content-type") ?? "";
+    if (!ct.includes("text/html")) return resp;
+    const out = new Response(resp.body, resp);
+    for (const [k, v] of Object.entries(secHeaders)) {
+      if (!out.headers.has(k)) out.headers.set(k, v);
+    }
+    return out;
+  }
+
   const allBypassPaths = [...(bypassPaths ?? DEFAULT_BYPASS_PATHS), ...extraBypassPaths];
 
   // -- Helpers ----------------------------------------------------------------
@@ -659,10 +738,15 @@ export function createDecoWorkerEntry(
       env: Record<string, unknown>,
       ctx: WorkerExecutionContext,
     ): Promise<Response> {
+      // Inject CF geo data as cookies for location matchers (before anything reads cookies)
+      if (geoOpt) {
+        request = injectGeoCookies(request);
+      }
+
       // Wrap the entire request in a RequestContext so that all code
       // in the call stack (loaders, invoke handlers, vtexFetchWithCookies)
       // can access the request and write response headers.
-      return RequestContext.run(request, async () => {
+      const response = await RequestContext.run(request, async () => {
       // Run app middleware (injects app state into RequestContext.bag,
       // runs registered middleware like VTEX cookie forwarding).
       const appMw = getAppMiddleware();
@@ -671,6 +755,8 @@ export function createDecoWorkerEntry(
       }
       return handleRequest(request, env, ctx);
       });
+
+      return applySecurityHeaders(response);
     },
   };
 

package/src/setup.ts

@@ -0,0 +1,192 @@
+/**
+ * One-call site bootstrap that composes framework registration functions.
+ *
+ * Sites pass their Vite-resolved globs, generated blocks, meta, CSS, fonts,
+ * and optional platform hooks. createSiteSetup wires them into the CMS engine,
+ * admin protocol, matchers, and rendering infrastructure.
+ *
+ * Everything site-specific (section loaders, cacheable sections, async rendering,
+ * layout sections, commerce loaders, sync sections) remains in the site's own
+ * setup file — createSiteSetup only handles the framework-generic wiring.
+ */
+
+import {
+	loadBlocks,
+	onBeforeResolve,
+	registerSections,
+	setBlocks,
+	setDanglingReferenceHandler,
+	setResolveErrorHandler,
+} from "./cms/index";
+import { registerBuiltinMatchers } from "./matchers/builtins";
+import { registerProductionOrigins } from "./sdk/normalizeUrls";
+import {
+	setInvokeLoaders,
+	setMetaData,
+	setPreviewWrapper,
+	setRenderShell,
+} from "./admin/index";
+
+export interface SiteSetupOptions {
+	/**
+	 * Section glob from Vite — pass `import.meta.glob("./sections/**\/*.tsx")`.
+	 * Keys are transformed from `./sections/X.tsx` → `site/sections/X.tsx`.
+	 */
+	sections: Record<string, () => Promise<any>>;
+
+	/**
+	 * Generated blocks object — import and pass directly:
+	 * `import { blocks } from "./server/cms/blocks.gen";`
+	 */
+	blocks: Record<string, unknown>;
+
+	/**
+	 * Lazy loader for admin meta schema — only fetched when admin requests it:
+	 * `() => import("./server/admin/meta.gen.json").then(m => m.default)`
+	 */
+	meta: () => Promise<any>;
+
+	/** CSS file URL from Vite `?url` import. */
+	css: string;
+
+	/** Font URLs to preload in admin preview shell. */
+	fonts?: string[];
+
+	/** Production origins for URL normalization. */
+	productionOrigins?: string[];
+
+	/**
+	 * Custom matcher registrations to run alongside builtins.
+	 * Each function is called once during setup.
+	 */
+	customMatchers?: Array<() => void>;
+
+	/** Preview wrapper component for admin preview iframe. */
+	previewWrapper?: React.ComponentType<any>;
+
+	/** Error handler for CMS resolution errors. */
+	onResolveError?: (
+		error: unknown,
+		resolveType: string,
+		context: string,
+	) => void;
+
+	/** Handler for dangling CMS references (missing __resolveType targets). */
+	onDanglingReference?: (resolveType: string) => any;
+
+	/**
+	 * Called after blocks are loaded — use for platform initialization.
+	 * Also called on every onBeforeResolve (decofile hot-reload).
+	 *
+	 * @example
+	 * ```ts
+	 * import { initVtexFromBlocks } from "@decocms/apps/vtex";
+	 * { initPlatform: (blocks) => initVtexFromBlocks(blocks) }
+	 * ```
+	 */
+	initPlatform?: (blocks: any) => void;
+
+	/**
+	 * Commerce loaders getter — passed to `setInvokeLoaders`.
+	 * Use a thunk so the full map (including site-specific loaders
+	 * defined after createSiteSetup) is captured.
+	 *
+	 * @example
+	 * ```ts
+	 * { getCommerceLoaders: () => COMMERCE_LOADERS }
+	 * ```
+	 */
+	getCommerceLoaders?: () => Record<string, (props: any) => Promise<any>>;
+}
+
+/**
+ * Bootstrap a Deco site — registers sections, matchers, blocks, meta,
+ * render shell, preview wrapper, error handlers, and platform hooks.
+ *
+ * Call once at the top of your `setup.ts`, before site-specific registrations.
+ *
+ * @example
+ * ```ts
+ * import "./cache-config";
+ * import { createSiteSetup } from "@decocms/start/setup";
+ * import { blocks } from "./server/cms/blocks.gen";
+ * import PreviewProviders from "./components/PreviewProviders";
+ * import appCss from "./styles/app.css?url";
+ * import { initVtexFromBlocks } from "@decocms/apps/vtex";
+ *
+ * createSiteSetup({
+ *   sections: import.meta.glob("./sections/**\/*.tsx"),
+ *   blocks,
+ *   meta: () => import("./server/admin/meta.gen.json").then(m => m.default),
+ *   css: appCss,
+ *   fonts: ["/fonts/Lato-Regular.woff2", "/fonts/Lato-Bold.woff2"],
+ *   productionOrigins: ["https://www.example.com"],
+ *   previewWrapper: PreviewProviders,
+ *   initPlatform: (blocks) => initVtexFromBlocks(blocks),
+ * });
+ * ```
+ */
+export function createSiteSetup(options: SiteSetupOptions): void {
+	// 1. Error handlers (set first so they catch issues during registration)
+	if (options.onResolveError) {
+		setResolveErrorHandler(options.onResolveError);
+	}
+	if (options.onDanglingReference) {
+		setDanglingReferenceHandler(options.onDanglingReference);
+	}
+
+	// 2. Section glob registration — transform Vite paths to CMS keys
+	const sections: Record<string, () => Promise<any>> = {};
+	for (const [path, loader] of Object.entries(options.sections)) {
+		sections[`site/${path.slice(2)}`] = loader;
+	}
+	registerSections(sections);
+
+	// 3. Matchers
+	registerBuiltinMatchers();
+	if (options.customMatchers) {
+		for (const register of options.customMatchers) {
+			register();
+		}
+	}
+
+	// 4. Production origins
+	if (options.productionOrigins?.length) {
+		registerProductionOrigins(options.productionOrigins);
+	}
+
+	// 5. Blocks + platform init (server-only)
+	if (typeof document === "undefined") {
+		setBlocks(options.blocks);
+		if (options.initPlatform) {
+			options.initPlatform(loadBlocks());
+		}
+	}
+
+	// 6. onBeforeResolve — re-init platform on decofile hot-reload
+	if (options.initPlatform) {
+		const init = options.initPlatform;
+		onBeforeResolve(() => {
+			init(loadBlocks());
+		});
+	}
+
+	// 7. Admin meta schema (lazy)
+	options.meta().then((data) => setMetaData(data));
+
+	// 8. Render shell
+	setRenderShell({
+		css: options.css,
+		fonts: options.fonts,
+	});
+
+	// 9. Preview wrapper
+	if (options.previewWrapper) {
+		setPreviewWrapper(options.previewWrapper);
+	}
+
+	// 10. Commerce loaders → invoke
+	if (options.getCommerceLoaders) {
+		setInvokeLoaders(options.getCommerceLoaders);
+	}
+}