@iterant/site-runtime 3.0.2

package/src/components/seo-json.tsx

@@ -0,0 +1,157 @@
+/**
+ * Consolidated JSON-LD rendering for schema.org structured data.
+ *
+ * Use this file in two ways:
+ * 1. Page-level schemas: pass `jsonLd` to <Layout />. This keeps the schema in
+ *    the page shell with the rest of the SEO metadata.
+ * 2. Section-level schemas: render <SeoJson schema={...} /> inside the React
+ *    section that owns the matching visible content, such as an FAQ section.
+ *
+ * Keep helpers limited to low-variance schemas this project renders from
+ * repeated local UI patterns. For customer-specific schema.org types, use
+ * schema-dts directly and pass the object to SeoJson.
+ *
+ * Example:
+ *
+ * const faqItems = [
+ *   {
+ *     question: "Can I use custom schemas?",
+ *     answer: "Yes. Pass any schema.org JSON-LD object to SeoJson.",
+ *   },
+ * ];
+ *
+ * <SeoJson
+ *   schema={createFaqPageSchema(faqItems, {
+ *     name: "Product FAQ",
+ *     url: "https://example.com/pricing",
+ *   })}
+ * />
+ *
+ * For schema.org types without a local helper, create a typed object with
+ * WithContext from schema-dts:
+ *
+ * const serviceJsonLd: WithContext<Service> = {
+ *   "@context": "https://schema.org",
+ *   "@type": "Service",
+ *   name: "Website redesign",
+ *   provider: { "@type": "Organization", name: "Example Studio" },
+ * };
+ *
+ * <SeoJson schema={serviceJsonLd} />
+ *
+ * SeoJson safely serializes the payload, removes duplicate per-node contexts,
+ * and combines multiple schemas into one @graph.
+ */
+import type { FAQPage, Question, WithContext } from "schema-dts";
+
+export type SeoJsonNode = object & {
+  "@context"?: "https://schema.org";
+  "@type"?: string | readonly string[];
+};
+export type SeoJsonGraph = object & {
+  "@context"?: "https://schema.org";
+  "@graph": readonly SeoJsonNode[];
+};
+export type SeoJsonSchema = SeoJsonNode | SeoJsonGraph;
+
+type SeoJsonInput =
+  | SeoJsonSchema
+  | readonly SeoJsonSchema[]
+  | null
+  | false
+  | undefined;
+
+interface SeoJsonProps {
+  schema?: SeoJsonInput;
+  schemas?: SeoJsonInput;
+}
+
+export interface FaqItem {
+  question: string;
+  answer: string;
+}
+
+export interface FaqSchemaOptions {
+  name?: string;
+  description?: string;
+  url?: string;
+}
+
+export function SeoJson({ schema, schemas }: SeoJsonProps) {
+  const nodes = normalizeSchemas(schema, schemas);
+
+  if (nodes.length === 0) return null;
+
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{ __html: serializeJsonLd(nodes) }}
+    />
+  );
+}
+
+export function createFaqPageSchema(
+  items: readonly FaqItem[],
+  { name, description, url }: FaqSchemaOptions = {},
+): WithContext<FAQPage> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    ...(name && { name }),
+    ...(description && { description }),
+    ...(url && { url }),
+    mainEntity: items.map(
+      ({ question, answer }): Question => ({
+        "@type": "Question",
+        name: question,
+        acceptedAnswer: {
+          "@type": "Answer",
+          text: answer,
+        },
+      }),
+    ),
+  };
+}
+
+function normalizeSchemas(...inputs: readonly SeoJsonInput[]): SeoJsonNode[] {
+  const nodes: SeoJsonNode[] = [];
+
+  for (const input of inputs) {
+    if (!input) continue;
+
+    const schemas = Array.isArray(input) ? input : [input];
+
+    for (const value of schemas) {
+      if (isGraph(value)) {
+        nodes.push(...value["@graph"].map(stripContext));
+      } else {
+        nodes.push(stripContext(value));
+      }
+    }
+  }
+
+  return nodes;
+}
+
+function isGraph(value: SeoJsonSchema): value is SeoJsonGraph {
+  return "@graph" in value;
+}
+
+function stripContext(value: SeoJsonNode): SeoJsonNode {
+  const node = { ...(value as Record<string, unknown>) };
+  delete node["@context"];
+
+  return node as SeoJsonNode;
+}
+
+function serializeJsonLd(nodes: readonly SeoJsonNode[]): string {
+  const payload =
+    nodes.length === 1
+      ? {
+          "@context": "https://schema.org",
+          ...(nodes[0] as Record<string, unknown>),
+        }
+      : { "@context": "https://schema.org", "@graph": nodes };
+
+  return JSON.stringify(payload).replace(/</g, "\\u003c");
+}

package/src/components/seo.tsx

@@ -0,0 +1,294 @@
+import { localeFromPath } from "../lib/locales";
+import {
+  SeoJson,
+  type SeoJsonGraph,
+  type SeoJsonNode,
+  type SeoJsonSchema,
+} from "./seo-json";
+
+const SCHEMA_CONTEXT = "https://schema.org" as const;
+
+// What a page IS, mirrored from the entry's `meta.pageType`
+// (the page schema in ../content/schema.ts). Drives the page node's @type
+// and, for product, a companion Product node. "page" is the absent-field
+// default.
+export type PageType = "page" | "article" | "product" | "about" | "contact";
+
+const PAGE_NODE_TYPE: Record<PageType, string> = {
+  page: "WebPage",
+  article: "Article",
+  product: "WebPage",
+  about: "AboutPage",
+  contact: "ContactPage",
+};
+
+export interface OrganizationInfo {
+  logo?: string;
+  sameAs?: string[];
+}
+
+interface SEOProps {
+  title: string;
+  description?: string;
+  canonicalUrl?: string;
+  imageUrl?: string;
+  imageAlt?: string;
+  /** Legacy alias kept for existing shells; `pageType` wins when both are set. */
+  type?: "website" | "article";
+  pageType?: PageType;
+  datePublished?: string;
+  dateModified?: string;
+  noindex?: boolean;
+  siteName?: string;
+  organization?: OrganizationInfo;
+  jsonLd?: SeoJsonSchema | SeoJsonSchema[];
+}
+
+export function SEO({
+  title,
+  description,
+  canonicalUrl,
+  imageUrl,
+  imageAlt,
+  type = "website",
+  pageType,
+  datePublished,
+  dateModified,
+  noindex = false,
+  siteName,
+  organization,
+  jsonLd,
+}: SEOProps) {
+  const resolvedSiteName = siteName ?? title;
+  const fullTitle =
+    title === resolvedSiteName ? title : `${title} | ${resolvedSiteName}`;
+  const robots = noindex ? "noindex, nofollow" : "index, follow";
+  const twitterCard = imageUrl ? "summary_large_image" : "summary";
+  const resolvedPageType: PageType =
+    pageType ?? (type === "article" ? "article" : "page");
+  const ogType = resolvedPageType === "article" ? "article" : "website";
+
+  const graph = noindex
+    ? []
+    : buildJsonLdGraph({
+        title,
+        fullTitle,
+        description,
+        canonicalUrl,
+        imageUrl,
+        pageType: resolvedPageType,
+        datePublished,
+        dateModified,
+        siteName: resolvedSiteName,
+        organization,
+        extras: jsonLd,
+      });
+
+  return (
+    <>
+      <title>{fullTitle}</title>
+      {description && <meta name="description" content={description} />}
+      <meta name="robots" content={robots} />
+      {canonicalUrl && <link rel="canonical" href={canonicalUrl} />}
+
+      <meta property="og:type" content={ogType} />
+      <meta property="og:title" content={fullTitle} />
+      <meta property="og:site_name" content={resolvedSiteName} />
+      {description && <meta property="og:description" content={description} />}
+      {canonicalUrl && <meta property="og:url" content={canonicalUrl} />}
+      {imageUrl && <meta property="og:image" content={imageUrl} />}
+      {imageAlt && <meta property="og:image:alt" content={imageAlt} />}
+
+      <meta name="twitter:card" content={twitterCard} />
+      <meta name="twitter:title" content={fullTitle} />
+      {description && <meta name="twitter:description" content={description} />}
+      {imageUrl && <meta name="twitter:image" content={imageUrl} />}
+
+      <SeoJson schemas={graph} />
+    </>
+  );
+}
+
+export interface BuildGraphArgs {
+  title: string;
+  fullTitle: string;
+  description?: string;
+  canonicalUrl?: string;
+  imageUrl?: string;
+  pageType: PageType;
+  datePublished?: string;
+  dateModified?: string;
+  siteName: string;
+  organization?: OrganizationInfo;
+  extras?: SeoJsonSchema | SeoJsonSchema[];
+}
+
+// Deterministic schema.org graph for every indexable page. Emitted nodes:
+// Organization + WebSite (site-scoped, @id-anchored at the origin), the page
+// node (@type from pageType), BreadcrumbList derived from the canonical
+// path, and a companion Product node on product pages. Page-specific extras
+// (the `jsonLd` prop) merge in and suppress any default node sharing their
+// @type, so a page can override without forking the defaults.
+// Exported for tests.
+export function buildJsonLdGraph({
+  title,
+  fullTitle,
+  description,
+  canonicalUrl,
+  imageUrl,
+  pageType,
+  datePublished,
+  dateModified,
+  siteName,
+  organization,
+  extras,
+}: BuildGraphArgs): SeoJsonSchema[] {
+  const siteUrl = canonicalUrl ? new URL(canonicalUrl).origin : undefined;
+  const organizationId = siteUrl ? `${siteUrl}/#organization` : undefined;
+  const websiteId = siteUrl ? `${siteUrl}/#website` : undefined;
+  const breadcrumb = canonicalUrl
+    ? buildBreadcrumbList({ canonicalUrl, title, siteName })
+    : undefined;
+
+  const pageNode = {
+    "@context": SCHEMA_CONTEXT,
+    "@type": PAGE_NODE_TYPE[pageType],
+    ...(pageType === "article"
+      ? { headline: title, name: title }
+      : { name: fullTitle }),
+    ...(description && { description }),
+    ...(canonicalUrl && { url: canonicalUrl, "@id": canonicalUrl }),
+    ...(imageUrl && { image: imageUrl }),
+    ...(websiteId && { isPartOf: { "@id": websiteId } }),
+    ...(breadcrumb && { breadcrumb: { "@id": breadcrumbId(canonicalUrl!) } }),
+    ...(pageType === "article" && {
+      ...(datePublished && { datePublished }),
+      ...((dateModified ?? datePublished) && {
+        dateModified: dateModified ?? datePublished,
+      }),
+      ...(canonicalUrl && { mainEntityOfPage: canonicalUrl }),
+      ...(organizationId && {
+        publisher: { "@id": organizationId },
+        author: { "@id": organizationId },
+      }),
+    }),
+  };
+
+  const defaults = [
+    {
+      "@context": SCHEMA_CONTEXT,
+      "@type": "Organization",
+      ...(organizationId && { "@id": organizationId }),
+      name: siteName,
+      ...(siteUrl && { url: siteUrl }),
+      ...(organization?.logo && { logo: organization.logo }),
+      ...(organization?.sameAs?.length && { sameAs: organization.sameAs }),
+    },
+    {
+      "@context": SCHEMA_CONTEXT,
+      "@type": "WebSite",
+      ...(websiteId && { "@id": websiteId }),
+      name: siteName,
+      ...(siteUrl && { url: siteUrl }),
+      ...(organizationId && { publisher: { "@id": organizationId } }),
+    },
+    pageNode,
+    ...(breadcrumb ? [breadcrumb] : []),
+    ...(pageType === "product"
+      ? [
+          {
+            "@context": SCHEMA_CONTEXT,
+            "@type": "Product",
+            ...(canonicalUrl && { "@id": `${canonicalUrl}#product` }),
+            name: title,
+            ...(description && { description }),
+            ...(imageUrl && { image: imageUrl }),
+            brand: { "@type": "Brand", name: siteName },
+          },
+        ]
+      : []),
+  ];
+
+  const extraNodes = extras ? (Array.isArray(extras) ? extras : [extras]) : [];
+  const overridden = new Set(
+    extraNodes.flatMap((node) =>
+      isGraph(node) ? node["@graph"].map(getType) : [getType(node)],
+    ),
+  );
+
+  return [
+    ...defaults.filter((n) => !overridden.has(getType(n))),
+    ...extraNodes,
+  ];
+}
+
+function breadcrumbId(canonicalUrl: string): string {
+  return `${canonicalUrl}#breadcrumb`;
+}
+
+interface BreadcrumbArgs {
+  canonicalUrl: string;
+  title: string;
+  siteName: string;
+}
+
+// BreadcrumbList from the canonical path. The root crumb is the site (or the
+// locale home for localized paths), intermediate crumbs are titleized
+// segments, and the last crumb is the page's own title without a link (per
+// Google's guidance the current page needs no item URL). The locale segment
+// itself is never a crumb; it only shifts where the root points. Home pages
+// (no segments) emit no breadcrumb.
+function buildBreadcrumbList({
+  canonicalUrl,
+  title,
+  siteName,
+}: BreadcrumbArgs) {
+  const url = new URL(canonicalUrl);
+  const segments = url.pathname.split("/").filter(Boolean);
+  const locale = localeFromPath(url.pathname);
+  const crumbSegments = locale ? segments.slice(1) : segments;
+  if (crumbSegments.length === 0) return undefined;
+
+  const rootPath = locale ? `/${locale}` : "/";
+  const items = [
+    { name: siteName, item: new URL(rootPath, url.origin).toString() },
+    ...crumbSegments.map((segment, index) => {
+      const isLast = index === crumbSegments.length - 1;
+      const path = `${rootPath === "/" ? "" : rootPath}/${crumbSegments
+        .slice(0, index + 1)
+        .join("/")}`;
+      return {
+        name: isLast ? title : titleizeSegment(segment),
+        ...(isLast ? {} : { item: new URL(path, url.origin).toString() }),
+      };
+    }),
+  ];
+
+  return {
+    "@context": SCHEMA_CONTEXT,
+    "@type": "BreadcrumbList",
+    "@id": breadcrumbId(canonicalUrl),
+    itemListElement: items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      ...item,
+    })),
+  };
+}
+
+function titleizeSegment(segment: string): string {
+  return segment
+    .split("-")
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+function isGraph(node: SeoJsonSchema): node is SeoJsonGraph {
+  return "@graph" in node;
+}
+
+function getType(node: SeoJsonNode): string | undefined {
+  const type = node["@type"];
+  return typeof type === "string" ? type : type?.[0];
+}

package/src/config/preset.ts

@@ -0,0 +1,198 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import cloudflare from "@astrojs/cloudflare";
+import react from "@astrojs/react";
+import tailwindcss from "@tailwindcss/vite";
+import type { AstroUserConfig } from "astro";
+import { sessionDrivers } from "astro/config";
+
+import iterantPlugins from "../integrations/iterant-plugins.mjs";
+import newFileReload from "../integrations/new-file-reload.mjs";
+import previewErrorShell from "../integrations/preview-error-shell.mjs";
+import { sitemapWithCustomPages } from "../lib/sitemap";
+
+// The Astro configuration every brand site runs on, as one spreadable fragment:
+//
+//   // astro.config.mjs
+//   import { defineConfig } from "astro/config";
+//   import { iterantStarter } from "@iterant/site-runtime/config";
+//
+//   export default defineConfig({
+//     // Patched at deploy time by the platform — must remain a string literal.
+//     site: "https://example.com",
+//     ...iterantStarter(),
+//   });
+//
+// Adapter, integrations, vite tuning and sitemap wiring live here so a change to
+// any of them reaches every brand as a version bump instead of a per-repo edit.
+// Paths resolve against process.cwd(), the repo Astro is running in.
+
+export interface IterantStarterOptions {
+  /**
+   * The site's canonical origin. Usually left OUT and kept as a literal in the
+   * repo's astro.config.mjs (the platform patches that literal at deploy time);
+   * pass it only when something else owns the value.
+   */
+  site?: string;
+  /**
+   * Dev-server host allow-list. `true` (the default) accepts any host: tunnel
+   * and preview hostnames are random per boot, so allow-listing is impossible
+   * and access control lives outside the dev server.
+   */
+  allowedHosts?: true | string[];
+  /**
+   * Page entry directory, relative to the project root, if a repo moved it.
+   * The same value goes to `createCollections` in src/content.config.ts: one
+   * knob, so the sitemap and the collection can never read different dirs.
+   */
+  pagesDir?: string;
+  /**
+   * Extensions for a diverged repo. These are the two keys a spread cannot
+   * express: extra `integrations` APPEND after the platform's, and `vite`
+   * merges one level deep with `plugins` appended. Everything else a repo needs
+   * to change it writes in its own `defineConfig` object after the spread,
+   * where plain spread precedence already does the right thing. Extending beats
+   * ejecting — an ejected config stops receiving platform changes.
+   */
+  overrides?: {
+    integrations?: NonNullable<AstroUserConfig["integrations"]>;
+    vite?: NonNullable<AstroUserConfig["vite"]>;
+  };
+}
+
+// The return type is inferred on purpose: it carries exactly the keys the
+// preset sets. A full `AstroUserConfig` annotation makes every optional key
+// (i18n above all) part of the spread the consumer hands `defineConfig`, and
+// its `const` generic inference then resolves them against `never` and fails.
+export function iterantStarter({
+  site,
+  allowedHosts = true,
+  pagesDir,
+  overrides,
+}: IterantStarterOptions = {}) {
+  // The platform generates the wrangler config at deploy time; it isn't checked
+  // in. Only pass configPath to the Cloudflare adapter when one of the supported
+  // wrangler config files actually exists so local `astro dev` works without one.
+  const wranglerConfig = ["wrangler.toml", "wrangler.jsonc", "wrangler.json"]
+    .map((name) => join(process.cwd(), name))
+    .find((path) => existsSync(path));
+
+  // Separate vite cache dirs so `astro dev` and `astro build`/`check` don't conflict.
+  const astroCommand = process.argv
+    .slice(2)
+    .find((arg) => !arg.startsWith("-"));
+  const viteCacheDir =
+    astroCommand === "dev" || astroCommand === "preview"
+      ? "node_modules/.vite-dev"
+      : "node_modules/.vite-build";
+
+  const integrations: NonNullable<AstroUserConfig["integrations"]> = [
+    react(),
+    // For SSR-only dynamic routes, the page entries' routes are read from disk.
+    ...sitemapWithCustomPages({ pagesDir }),
+    // Dev-only: platform visual editor, gated on ?editor=1 in an iframe.
+    iterantPlugins(),
+    // Dev-only: swap 5xx error pages for the branded in-progress shell.
+    previewErrorShell(),
+    // Dev-only: broadcast a reload when a new src/ file matches no module.
+    newFileReload(),
+  ];
+
+  const vite: NonNullable<AstroUserConfig["vite"]> = {
+    cacheDir: viteCacheDir,
+    plugins: [tailwindcss()],
+    resolve: {
+      // Use react-dom/server.edge instead of react-dom/server.browser for React 19.
+      // Without this, MessageChannel from node:worker_threads needs to be polyfilled.
+      alias: import.meta.env.PROD
+        ? { "react-dom/server": "react-dom/server.edge" }
+        : undefined,
+      // Belt-and-braces against the "two React copies" invalid-hook crash: force a
+      // single physical copy even if a transitive dep pulls its own.
+      dedupe: ["react", "react-dom"],
+    },
+    ssr: {
+      noExternal: ["xxhash-wasm"],
+      ...(import.meta.env.PROD && {
+        resolve: {
+          conditions: ["workerd", "worker", "node"],
+          externalConditions: ["workerd", "worker", "node"],
+        },
+      }),
+    },
+    optimizeDeps: {
+      // Pre-bundle every client-side dep up front: discovering one
+      // mid-session re-optimizes with a new ?v hash, and a stale
+      // module graph then loads TWO React copies (invalid-hook
+      // crash in every island).
+      include: [
+        "react",
+        "react-dom",
+        "react-dom/client",
+        // The island SSR renderer: omitting it let the FIRST server-render of an
+        // island discover react-dom/server un-prebundled and trigger a mid-session
+        // re-optimize, briefly splitting React in two (the invalid-hook crash the
+        // comment above warns about — seen intermittently in navbar SSR).
+        "react-dom/server",
+        "react-dom/server.edge",
+        "react/jsx-runtime",
+        "react/jsx-dev-runtime",
+        "lucide-react",
+        "motion/react",
+        "clsx",
+        "tailwind-merge",
+        "class-variance-authority",
+        "@radix-ui/react-slot",
+      ],
+    },
+    server: {
+      strictPort: true,
+      // Tunnel/preview hostnames are random per boot, so hostname
+      // allow-listing is impossible; access control lives outside the dev server.
+      allowedHosts,
+    },
+  };
+
+  const base = {
+    ...(site !== undefined && { site }),
+    output: "server" as const,
+    trailingSlash: "never" as const,
+    // No Astro sessions: the in-memory driver stops the Cloudflare adapter from
+    // auto-provisioning a KV namespace per deploy.
+    session: {
+      driver: sessionDrivers.lruCache(),
+    },
+    adapter: cloudflare({
+      imageService: "compile",
+      ...(wranglerConfig && { configPath: wranglerConfig }),
+    }),
+    integrations,
+    vite,
+    // Port 4321 (Astro's default), NOT 3000: inside a Cloudflare Sandbox port
+    // 3000 is reserved by the sandbox control agent. host: true so the sandbox
+    // preview tunnel can reach the server.
+    server: {
+      port: 4321,
+      host: true,
+      open: false,
+    },
+    devToolbar: {
+      enabled: false,
+    },
+  };
+
+  if (!overrides) return base;
+
+  // Integrations and vite plugins APPEND: a repo adds to the platform's set, it
+  // never silently replaces it. The rest of `vite` merges one level deep.
+  const { integrations: extraIntegrations, vite: extraVite } = overrides;
+  return {
+    ...base,
+    integrations: [...integrations, ...(extraIntegrations ?? [])],
+    vite: {
+      ...vite,
+      ...extraVite,
+      plugins: [...(vite.plugins ?? []), ...(extraVite?.plugins ?? [])],
+    },
+  };
+}