rankrunners-cms 0.0.20 → 0.0.21

package/README.md

@@ -541,19 +541,22 @@ This single route handles ALL CMS pages:
 
 ```typescript
 import { config } from '@/editor'
-import { initialData } from '@/editor/initial-data'
-import { PageRendererTanstack } from 'rankrunners-cms/src/tanstack'
+import { allPageData } from '@/editor/initial-data'
+import { withCMS } from 'rankrunners-cms/src/tanstack'
 import { createFileRoute } from '@tanstack/react-router'
 
-export const Route = createFileRoute('/\$')({
-  component: () =>
-    PageRendererTanstack({
-      config,
-      allPageData: initialData,
-    })(),
-})
+export const Route = createFileRoute('/$')(
+  withCMS({
+    config,
+    allPageData,
+  }),
+)
 ```
 
+The CMS functionality can be overriden like any other Tanstack route, by providing `loader`, `loaderDeps` and `component` values. If types are invalid, please let Disyer know.
+
+The catch-all page route is responsible for both server-side and client-side rendering of all pages provided by the CMS. It will return 404 for pages that do not have any content and it will serve the editor when in edit mode.
+
 ### 8.3 How the Page Renderer Works
 
 1. Extracts the pathname from the URL (e.g., `/contact` -> `contact`)

package/bun.lock

@@ -9,22 +9,22 @@
         "tailwindcss": "^4.1.18",
       },
       "devDependencies": {
-        "@tanstack/react-router": "^1.158.0",
-        "@tanstack/router-core": "^1.158.0",
-        "@types/react": "^19.2.11",
-        "bun-types": "^1.3.8",
-        "lucide-react": "^0.563.0",
+        "@tanstack/react-router": "^1.160.2",
+        "@tanstack/router-core": "^1.160.0",
+        "@types/react": "^19.2.14",
+        "bun-types": "^1.3.9",
+        "lucide-react": "^0.564.0",
         "next": "^16.1.6",
         "typescript": "^5.9.3",
         "valibot": "^1.2.0",
       },
       "peerDependencies": {
         "@puckeditor/core": "^0.21.1",
-        "@tanstack/react-router": "^1.150.0",
-        "@tanstack/router-core": "^1.150.0",
-        "lucide-react": "^0.562.0",
-        "next": "^16.1.2",
-        "react": "^19.2.3",
+        "@tanstack/react-router": "^1.160.2",
+        "@tanstack/router-core": "^1.160.0",
+        "lucide-react": "^0.564.0",
+        "next": "^16.1.6",
+        "react": "^19.2.4",
         "valibot": "^1.2.0",
       },
       "optionalPeers": [
@@ -180,11 +180,11 @@
 
     "@tanstack/history": ["@tanstack/history@1.154.14", "", {}, "sha512-xyIfof8eHBuub1CkBnbKNKQXeRZC4dClhmzePHVOEel4G7lk/dW+TQ16da7CFdeNLv6u6Owf5VoBQxoo6DFTSA=="],
 
-    "@tanstack/react-router": ["@tanstack/react-router@1.158.0", "", { "dependencies": { "@tanstack/history": "1.154.14", "@tanstack/react-store": "^0.8.0", "@tanstack/router-core": "1.158.0", "isbot": "^5.1.22", "tiny-invariant": "^1.3.3", "tiny-warning": "^1.0.3" }, "peerDependencies": { "react": ">=18.0.0 || >=19.0.0", "react-dom": ">=18.0.0 || >=19.0.0" } }, "sha512-kvTaO6zjq9WWPyo1wwSZx95AjJ9KOvu23cOMgKeDdDQWKF3Z9q3fwhToKMKJoC11T2Vuivz+o/anrxCcOvdRzw=="],
+    "@tanstack/react-router": ["@tanstack/react-router@1.160.2", "", { "dependencies": { "@tanstack/history": "1.154.14", "@tanstack/react-store": "^0.8.0", "@tanstack/router-core": "1.160.0", "isbot": "^5.1.22", "tiny-invariant": "^1.3.3", "tiny-warning": "^1.0.3" }, "peerDependencies": { "react": ">=18.0.0 || >=19.0.0", "react-dom": ">=18.0.0 || >=19.0.0" } }, "sha512-EJWAMS4qCfWKNCzzYGy6ZuWTdBATYEEWieaQdmM7zUesyOQ01j7o6aKXdmCp9rWuSKjPHXagWubEnEo+Puhi3w=="],
 
     "@tanstack/react-store": ["@tanstack/react-store@0.8.0", "", { "dependencies": { "@tanstack/store": "0.8.0", "use-sync-external-store": "^1.6.0" }, "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-1vG9beLIuB7q69skxK9r5xiLN3ztzIPfSQSs0GfeqWGO2tGIyInZx0x1COhpx97RKaONSoAb8C3dxacWksm1ow=="],
 
-    "@tanstack/router-core": ["@tanstack/router-core@1.158.0", "", { "dependencies": { "@tanstack/history": "1.154.14", "@tanstack/store": "^0.8.0", "cookie-es": "^2.0.0", "seroval": "^1.4.2", "seroval-plugins": "^1.4.2", "tiny-invariant": "^1.3.3", "tiny-warning": "^1.0.3" } }, "sha512-dRMcWY0UB/6OZqSCx/7iUvom0ol18rHSQladygVT8mlth7uxYx3n5BNse8C03efIE8y1Bx+VDOBAKpAZ9BgKog=="],
+    "@tanstack/router-core": ["@tanstack/router-core@1.160.0", "", { "dependencies": { "@tanstack/history": "1.154.14", "@tanstack/store": "^0.8.0", "cookie-es": "^2.0.0", "seroval": "^1.4.2", "seroval-plugins": "^1.4.2", "tiny-invariant": "^1.3.3", "tiny-warning": "^1.0.3" } }, "sha512-vbh6OsE0MG+0c+SKh2uk5yEEZlWsxT96Ub2JaTs7ixOvZp3Wu9PTEIe2BA3cShNZhEsDI0Le4NqgY4XIaHLLvA=="],
 
     "@tanstack/store": ["@tanstack/store@0.8.0", "", {}, "sha512-Om+BO0YfMZe//X2z0uLF2j+75nQga6TpTJgLJQBiq85aOyZNIhkCgleNcud2KQg4k4v9Y9l+Uhru3qWMPGTOzQ=="],
 
@@ -240,7 +240,7 @@
 
     "@types/node": ["@types/node@25.0.9", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-/rpCXHlCWeqClNBwUhDcusJxXYDjZTyE8v5oTO7WbL8eij2nKhUeU89/6xgjU7N4/Vh3He0BtyhJdQbDyhiXAw=="],
 
-    "@types/react": ["@types/react@19.2.11", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-tORuanb01iEzWvMGVGv2ZDhYZVeRMrw453DCSAIn/5yvcSVnMoUMTyf33nQJLahYEnv9xqrTNbgz4qY5EfSh0g=="],
+    "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
 
     "@types/react-dom": ["@types/react-dom@19.2.3", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ=="],
 
@@ -256,7 +256,7 @@
 
     "baseline-browser-mapping": ["baseline-browser-mapping@2.9.15", "", { "bin": "dist/cli.js" }, "sha512-kX8h7K2srmDyYnXRIppo4AH/wYgzWVCs+eKr3RusRSQ5PvRYoEFmR/I0PbdTjKFAoKqp5+kbxnNTFO9jOfSVJg=="],
 
-    "bun-types": ["bun-types@1.3.8", "", { "dependencies": { "@types/node": "*" } }, "sha512-fL99nxdOWvV4LqjmC+8Q9kW3M4QTtTR1eePs94v5ctGqU8OeceWrSUaRw3JYb7tU3FkMIAjkueehrHPPPGKi5Q=="],
+    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
 
     "caniuse-lite": ["caniuse-lite@1.0.30001764", "", {}, "sha512-9JGuzl2M+vPL+pz70gtMF9sHdMFbY9FJaQBi186cHKH3pSzDvzoUJUPV6fqiKIMyXbud9ZLg4F3Yza1vJ1+93g=="],
 
@@ -294,7 +294,7 @@
 
     "linkifyjs": ["linkifyjs@4.3.2", "", {}, "sha512-NT1CJtq3hHIreOianA8aSXn6Cw0JzYOuDQbOrSPe7gqFnCpKP++MQe3ODgO3oh2GJFORkAAdqredOa60z63GbA=="],
 
-    "lucide-react": ["lucide-react@0.563.0", "", { "peerDependencies": { "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-8dXPB2GI4dI8jV4MgUDGBeLdGk8ekfqVZ0BdLcrRzocGgG75ltNEmWS+gE7uokKF/0oSUuczNDT+g9hFJ23FkA=="],
+    "lucide-react": ["lucide-react@0.564.0", "", { "peerDependencies": { "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-JJ8GVTQqFwuliifD48U6+h7DXEHdkhJ/E87kksGByII3qHxtPciVb8T8woQONHBQgHVOl7rSMrrip3SeVNy7Fg=="],
 
     "markdown-it": ["markdown-it@14.1.0", "", { "dependencies": { "argparse": "^2.0.1", "entities": "^4.4.0", "linkify-it": "^5.0.0", "mdurl": "^2.0.0", "punycode.js": "^2.3.1", "uc.micro": "^2.1.0" }, "bin": "bin/markdown-it.mjs" }, "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg=="],
 

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "rankrunners-cms",
   "type": "module",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "peerDependencies": {
     "@puckeditor/core": "^0.21.1",
     "next": "^16.1.6",
-    "@tanstack/router-core": "^1.158.0",
-    "@tanstack/react-router": "^1.158.0",
+    "@tanstack/router-core": "^1.160.0",
+    "@tanstack/react-router": "^1.160.2",
     "valibot": "^1.2.0",
-    "lucide-react": "^0.563.0",
+    "lucide-react": "^0.564.0",
     "react": "^19.2.4"
   },
   "peerDependenciesMeta": {
@@ -29,14 +29,14 @@
     }
   },
   "devDependencies": {
-    "@types/react": "^19.2.11",
-    "bun-types": "^1.3.8",
+    "@types/react": "^19.2.14",
+    "bun-types": "^1.3.9",
     "typescript": "^5.9.3",
-    "@tanstack/router-core": "^1.158.0",
-    "@tanstack/react-router": "^1.158.0",
+    "@tanstack/router-core": "^1.160.0",
+    "@tanstack/react-router": "^1.160.2",
     "next": "^16.1.6",
     "valibot": "^1.2.0",
-    "lucide-react": "^0.563.0"
+    "lucide-react": "^0.564.0"
   },
   "dependencies": {
     "classnames": "^2.5.1",

package/src/api/client/index.ts

@@ -1,2 +1,3 @@
+export * from "./posts";
 export * from "./public";
 export * from "./sitemap";

package/src/api/client/posts.ts

@@ -0,0 +1,50 @@
+import { CMS_BASE_URL, SITE_ID } from "../constants";
+import { fetchAs } from "../../libs/validator";
+import {
+  PublicPostSeoDetailsSchema,
+  PublicSeoDetailsSchema,
+  type PublicPostDTO,
+  type PublicPostSeoDetailsDTO,
+} from "../types/public";
+
+/**
+ * Get a list of published blog posts for the current site.
+ * Optionally filter by a post category name.
+ */
+export const getPublicPosts = async (
+  category?: string,
+): Promise<PublicPostDTO[]> => {
+  const url = new URL(`${CMS_BASE_URL}/public/seo/${SITE_ID}`);
+  if (category) {
+    url.searchParams.set("category", category);
+  }
+
+  const response = await fetchAs(PublicSeoDetailsSchema, url.toString());
+  return response.posts;
+};
+
+/**
+ * Get a single blog post's full SEO details by its slug.
+ */
+export const getPublicPostBySlug = async (
+  slug: string,
+): Promise<PublicPostSeoDetailsDTO> => {
+  const response = await fetchAs(
+    PublicPostSeoDetailsSchema,
+    `${CMS_BASE_URL}/public/seo/${SITE_ID}/posts/${encodeURIComponent(slug)}`,
+  );
+  return response;
+};
+
+/**
+ * Get a single blog post's full SEO details by its ID (or slug).
+ */
+export const getPublicPostById = async (
+  postId: string,
+): Promise<PublicPostSeoDetailsDTO> => {
+  const response = await fetchAs(
+    PublicPostSeoDetailsSchema,
+    `${CMS_BASE_URL}/public/sites/${SITE_ID}/posts/${encodeURIComponent(postId)}`,
+  );
+  return response;
+};

package/src/api/types/public.ts

@@ -1,31 +1,146 @@
-import { object, string, array, optional, type InferOutput } from "valibot";
+import {
+  object,
+  string,
+  array,
+  optional,
+  nullable,
+  boolean,
+  type InferOutput,
+} from "valibot";
 import { IdSchema } from "../types/common";
 
-export const PublicPageSeoDetailsSchema = object({
-  id: optional(IdSchema), // ok
-  siteId: optional(string()), // ok
-  title: optional(string()), // ok
-  slug: optional(string()), // ok
-  content: optional(string()), // ok
-  metaTitle: string(), // ok
-  metaDescription: string(), // ok
-  seoKeywords: array(string()), // ok
-  openGraphTitle: optional(string()), // ok
-  openGraphDescription: optional(string()), // ok
-  openGraphImage: optional(string()), // ok
-  googleAnalyticsId: optional(string()), // ok
-  googleTagManagerId: optional(string()), // ok
-  metaPixelId: optional(string()), // ok
-  universalPixelId: optional(string()), // ok
-  universalPixelAdvertiserId: optional(string()), // ok
+// --- Media Schema (for hero images) ---
+
+export const PublicMediaSchema = object({
+  id: string(),
+  name: string(),
+  altText: string(),
+  seoKeywords: array(string()),
+  url: string(),
+});
+
+export type PublicMediaDTO = InferOutput<typeof PublicMediaSchema>;
+
+// --- Shared SEO fields (reused across page & post SEO DTOs) ---
+
+const SeoTrackingFields = {
+  googleAnalyticsId: optional(string()),
+  googleTagManagerId: optional(string()),
+  metaPixelId: optional(string()),
+  universalPixelId: optional(string()),
+  universalPixelAdvertiserId: optional(string()),
   googleSiteVerificationId: optional(string()),
   callrailScript: optional(string()),
-  twitterCardType: optional(string()),
+} as const;
+
+const SeoOpenGraphFields = {
+  openGraphTitle: optional(string()),
+  openGraphDescription: optional(string()),
+  openGraphImage: optional(string()),
+} as const;
+
+const SeoMetaFields = {
+  metaTitle: string(),
+  metaDescription: string(),
+  seoKeywords: array(string()),
+  ...SeoOpenGraphFields,
+  ...SeoTrackingFields,
+} as const;
+
+const SeoScriptFields = {
   headerScripts: string(),
   footerScripts: string(),
   structuredData: string(),
+} as const;
+
+/**
+ * All common SEO detail fields shared between pages and posts.
+ */
+const CommonSeoDetailFields = {
+  ...SeoMetaFields,
+  ...SeoScriptFields,
+} as const;
+
+// --- Post Schemas ---
+
+export const PublicPostSchema = object({
+  id: IdSchema,
+  title: string(),
+  slug: string(),
+  author: nullable(string()),
+  publishedAt: nullable(string()),
+  shortContent: string(),
+  heroImage: nullable(PublicMediaSchema),
+});
+
+export type PublicPostDTO = InferOutput<typeof PublicPostSchema>;
+
+export const PublicPostSeoDetailsSchema = object({
+  id: IdSchema,
+  siteId: string(),
+  title: string(),
+  slug: string(),
+  content: string(),
+  publishedAt: nullable(string()),
+  author: nullable(string()),
+  heroImage: nullable(PublicMediaSchema),
+  ...CommonSeoDetailFields,
+  twitterCardType: string(),
+});
+
+export type PublicPostSeoDetailsDTO = InferOutput<
+  typeof PublicPostSeoDetailsSchema
+>;
+
+// --- Page Schema ---
+
+export const PublicPageSchema = object({
+  id: IdSchema,
+  title: string(),
+  slug: string(),
+});
+
+export type PublicPageDTO = InferOutput<typeof PublicPageSchema>;
+
+// --- SEO Details Schema (includes pages + posts) ---
+
+export const PublicSeoDetailsSchema = object({
+  siteTitle: string(),
+  siteDescription: string(),
+  siteKeywords: string(),
+  robotsTxt: string(),
+  ...SeoTrackingFields,
+  ...SeoOpenGraphFields,
+  twitterCardType: string(),
+  headerScripts: string(),
+  footerScripts: string(),
+  enableRobotsTxt: boolean(),
+  enableOpenGraph: boolean(),
+  enableTwitterCards: boolean(),
+  pages: array(PublicPageSchema),
+  posts: array(PublicPostSchema),
+});
+
+export type PublicSeoDetailsDTO = InferOutput<typeof PublicSeoDetailsSchema>;
+
+// --- Page SEO Details Schema ---
+
+export const PublicPageSeoDetailsSchema = object({
+  id: optional(IdSchema),
+  siteId: optional(string()),
+  title: optional(string()),
+  slug: optional(string()),
+  content: optional(string()),
+  ...CommonSeoDetailFields,
+  twitterCardType: optional(string()),
 });
 
 export type PublicPageSeoDetailsDTO = InferOutput<
   typeof PublicPageSeoDetailsSchema
 >;
+
+/**
+ * Union type of any entity that carries the common SEO detail fields.
+ * Useful for building meta/scripts generically from either a page or post response.
+ */
+export type AnySeoDetails = PublicPageSeoDetailsDTO | PublicPostSeoDetailsDTO;

package/src/tanstack/seo/head.ts

@@ -1,4 +1,5 @@
 import { getPublicPageSEODetails } from "../../api/client/public";
+import { getPublicPostBySlug } from "../../api/client/posts";
 import type { RouteHead } from "./types";
 import { SITE_ID } from "../../api/constants";
 import type { RouteOptions } from "@tanstack/router-core";
@@ -12,19 +13,27 @@ import {
   parseAndAppendScripts,
 } from "../../libs/parser/parseScripts";
 import { extractPathname } from "./extractors";
+import type { AnySeoDetails } from "../../api/types/public";
+import type { CMSBlogConfig } from "./types";
 
-export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
-  const { match } = ctx;
-  const pathname = extractPathname(match);
-  const seoDetails = await getPublicPageSEODetails(SITE_ID, pathname);
-  const meta: DetailedHTMLProps<
-    MetaHTMLAttributes<HTMLMetaElement>,
-    HTMLMetaElement
-  >[] = [{ charSet: "utf-8" }];
-
-  if (!seoDetails) {
-    return { meta };
-  }
+// ---------------------------------------------------------------------------
+// Generic SEO builders (work for both page and post SEO details)
+// ---------------------------------------------------------------------------
+
+type MetaTag = DetailedHTMLProps<
+  MetaHTMLAttributes<HTMLMetaElement>,
+  HTMLMetaElement
+>;
+type ScriptTag = DetailedHTMLProps<
+  ScriptHTMLAttributes<HTMLScriptElement>,
+  HTMLScriptElement
+>;
+
+/**
+ * Build `<meta>` tags from any SEO details object (page or post).
+ */
+export function buildSeoMeta(seoDetails: AnySeoDetails): MetaTag[] {
+  const meta: MetaTag[] = [];
 
   if (seoDetails.metaTitle && seoDetails.metaTitle.length > 0) {
     meta.push({ title: seoDetails.metaTitle });
@@ -34,12 +43,10 @@ export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
     meta.push({ name: "description", content: seoDetails.metaDescription });
   }
 
-  // SEO Keywords
   if (seoDetails.seoKeywords && seoDetails.seoKeywords.length > 0) {
     meta.push({ name: "keywords", content: seoDetails.seoKeywords.join(", ") });
   }
 
-  // Google Site Verification
   if (seoDetails.googleSiteVerificationId) {
     meta.push({
       name: "google-site-verification",
@@ -47,7 +54,7 @@ export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
     });
   }
 
-  // Open Graph tags
+  // Open Graph
   if (seoDetails.openGraphTitle && seoDetails.openGraphTitle.length > 0) {
     meta.push({ property: "og:title", content: seoDetails.openGraphTitle });
   }
@@ -64,9 +71,10 @@ export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
     meta.push({ property: "og:image", content: seoDetails.openGraphImage });
   }
 
-  meta.push({ property: "og:type", content: "website" });
+  const isPost = "author" in seoDetails;
+  meta.push({ property: "og:type", content: isPost ? "article" : "website" });
 
-  // Twitter Card tags
+  // Twitter Card
   if (seoDetails.twitterCardType && seoDetails.twitterCardType.length > 0) {
     meta.push({ name: "twitter:card", content: seoDetails.twitterCardType });
     if (seoDetails.openGraphTitle && seoDetails.openGraphTitle.length > 0) {
@@ -86,11 +94,15 @@ export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
     }
   }
 
-  // Build scripts array for head
-  const scripts: DetailedHTMLProps<
-    ScriptHTMLAttributes<HTMLScriptElement>,
-    HTMLScriptElement
-  >[] = [];
+  return meta;
+}
+
+/**
+ * Build `<script>` tags (structured data, pixels, analytics, custom header
+ * scripts) from any SEO details object (page or post).
+ */
+export function buildSeoScripts(seoDetails: AnySeoDetails): ScriptTag[] {
+  const scripts: ScriptTag[] = [];
 
   // Structured Data (JSON-LD)
   if (seoDetails.structuredData) {
@@ -181,11 +193,78 @@ export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
   // Custom header scripts
   parseAndAppendScripts(scripts, seoDetails.headerScripts);
 
-  return {
-    meta,
-    scripts: dedupeScripts(scripts),
+  return scripts;
+}
+
+// ---------------------------------------------------------------------------
+// Resolve SEO details for a pathname, considering blog routes
+// ---------------------------------------------------------------------------
+
+/**
+ * Given a pathname and optional blog configs, fetch the appropriate SEO details.
+ *
+ * - If the pathname matches `{prefix}/{slug}`, fetch the post by slug.
+ * - If the pathname matches `{prefix}` exactly, return page SEO (the list page
+ *   itself is a CMS page; the blog posts are loaded separately in the loader).
+ * - Otherwise fall back to normal page SEO lookup.
+ */
+async function resolveSeoDetails(
+  pathname: string,
+  blogs?: CMSBlogConfig[],
+): Promise<AnySeoDetails | null> {
+  if (blogs) {
+    for (const blog of blogs) {
+      const prefix = blog.prefix.replace(/^\/+|\/+$/g, "");
+
+      // Detail page: {prefix}/{slug}
+      if (pathname.startsWith(`${prefix}/`)) {
+        const slug = pathname.slice(prefix.length + 1);
+        if (slug.length > 0) {
+          try {
+            return await getPublicPostBySlug(slug);
+          } catch {
+            return null;
+          }
+        }
+      }
+    }
+  }
+
+  // Default: fetch page SEO details
+  return getPublicPageSEODetails(SITE_ID, pathname);
+}
+
+// ---------------------------------------------------------------------------
+// seoHead — now blog-aware
+// ---------------------------------------------------------------------------
+
+export const createSeoHead = (
+  blogs?: CMSBlogConfig[],
+): RouteHead<RouteOptions<any, any>> =>
+  async (ctx) => {
+    const { match } = ctx;
+    const pathname = extractPathname(match);
+
+    const meta: MetaTag[] = [{ charSet: "utf-8" }];
+
+    const seoDetails = await resolveSeoDetails(pathname, blogs);
+
+    if (!seoDetails) {
+      return { meta };
+    }
+
+    return {
+      meta: [...meta, ...buildSeoMeta(seoDetails)],
+      scripts: dedupeScripts(buildSeoScripts(seoDetails)),
+    };
   };
-};
+
+/** Default seoHead (no blog config — backwards-compatible). */
+export const seoHead: RouteHead<RouteOptions<any, any>> = createSeoHead();
+
+// ---------------------------------------------------------------------------
+// headWithSEO
+// ---------------------------------------------------------------------------
 
 const toArray = <T>(v?: T | T[]): T[] => {
   if (v === undefined || v === null) return [];
@@ -195,10 +274,12 @@ const toArray = <T>(v?: T | T[]): T[] => {
 export const headWithSEO =
   <T extends RouteOptions<any, any>>(
     originalHead: RouteHead<T>,
+    blogs?: CMSBlogConfig[],
   ): RouteHead<T> =>
   async (...params) => {
+    const seoHeadFn = blogs ? createSeoHead(blogs) : seoHead;
     const ourHeadResult = await originalHead(...params);
-    const seoHeadResult = await seoHead(...params);
+    const seoHeadResult = await seoHeadFn(...params);
 
     return {
       meta: [

package/src/tanstack/seo/scripts.ts

@@ -1,5 +1,6 @@
 import { getPublicPageSEODetails } from "../../api/client/public";
-import type { RouteScripts } from "./types";
+import { getPublicPostBySlug } from "../../api/client/posts";
+import type { RouteScripts, CMSBlogConfig } from "./types";
 import { SITE_ID } from "../../api/constants";
 import {
   dedupeScripts,
@@ -8,27 +9,60 @@ import {
 import type { RouteOptions } from "@tanstack/router-core";
 import { extractPathname } from "./extractors";
 import type { DetailedHTMLProps, ScriptHTMLAttributes } from "react";
+import type { AnySeoDetails } from "../../api/types/public";
 
-export const seoScripts: RouteScripts<RouteOptions<any, any>> = async (ctx) => {
-  const { match } = ctx;
-  const pathname = extractPathname(match);
-  const seoDetails = await getPublicPageSEODetails(SITE_ID, pathname);
+/**
+ * Resolve footer-level SEO details, taking blog routes into account.
+ */
+async function resolveFooterSeoDetails(
+  pathname: string,
+  blogs?: CMSBlogConfig[],
+): Promise<AnySeoDetails | null> {
+  if (blogs) {
+    for (const blog of blogs) {
+      const prefix = blog.prefix.replace(/^\/+|\/+$/g, "");
+      if (pathname.startsWith(`${prefix}/`)) {
+        const slug = pathname.slice(prefix.length + 1);
+        if (slug.length > 0) {
+          try {
+            return await getPublicPostBySlug(slug);
+          } catch {
+            return null;
+          }
+        }
+      }
+    }
+  }
+  return getPublicPageSEODetails(SITE_ID, pathname);
+}
 
-  const scripts: DetailedHTMLProps<
-    ScriptHTMLAttributes<HTMLScriptElement>,
-    HTMLScriptElement
-  >[] = [];
+export const createSeoScripts = (
+  blogs?: CMSBlogConfig[],
+): RouteScripts<RouteOptions<any, any>> =>
+  async (ctx) => {
+    const { match } = ctx;
+    const pathname = extractPathname(match);
+    const seoDetails = await resolveFooterSeoDetails(pathname, blogs);
 
-  if (!seoDetails) {
-    return scripts;
-  }
+    const scripts: DetailedHTMLProps<
+      ScriptHTMLAttributes<HTMLScriptElement>,
+      HTMLScriptElement
+    >[] = [];
 
-  if (seoDetails.callrailScript) {
-    scripts.push({
-      src: seoDetails.callrailScript,
-    });
-  }
+    if (!seoDetails) {
+      return scripts;
+    }
+
+    if (seoDetails.callrailScript) {
+      scripts.push({
+        src: seoDetails.callrailScript,
+      });
+    }
+
+    parseAndAppendScripts(scripts, seoDetails.footerScripts);
+    return dedupeScripts(scripts);
+  };
 
-  parseAndAppendScripts(scripts, seoDetails.footerScripts);
-  return dedupeScripts(scripts);
-};
+/** Default seoScripts (no blog config — backwards-compatible). */
+export const seoScripts: RouteScripts<RouteOptions<any, any>> =
+  createSeoScripts();

package/src/tanstack/seo/types.ts

@@ -1,4 +1,9 @@
 import type { RouteOptions } from "@tanstack/router-core";
+import type React from "react";
+import type {
+  PublicPostDTO,
+  PublicPostSeoDetailsDTO,
+} from "../../api/types/public";
 
 export type RouteHead<T extends RouteOptions<any, any>> = NonNullable<
   T["head"]
@@ -7,3 +12,30 @@ export type RouteHead<T extends RouteOptions<any, any>> = NonNullable<
 export type RouteScripts<T extends RouteOptions<any, any>> = NonNullable<
   T["scripts"]
 >;
+
+/**
+ * Configuration for a single blog section served by the CMS catch-all route.
+ *
+ * - `prefix`  – URL prefix without leading/trailing slashes (e.g. `"blog"`).
+ *               `/{prefix}` renders the list page, `/{prefix}/{slug}` the detail.
+ * - `category` – Optional post category name used to filter posts from the API.
+ *                When `undefined`/`null`, all posts are returned.
+ * - `listComponent` – React component rendered at `/{prefix}` receiving the
+ *                      filtered post list.
+ * - `detailComponent` – React component rendered at `/{prefix}/{slug}` receiving
+ *                        the full post SEO details.
+ */
+export interface CMSBlogConfig {
+  prefix: string;
+  category?: string | null;
+  listComponent: (posts: PublicPostDTO[]) => React.ReactNode;
+  detailComponent: (post: PublicPostSeoDetailsDTO) => React.ReactNode;
+}
+
+/**
+ * Optional CMS-specific configuration that can be passed to `withCMS` and
+ * `headWithSEO` / `createSeoHead`.
+ */
+export interface CMSConfig {
+  blogs?: CMSBlogConfig[];
+}

package/src/tanstack/withCMS.tsx

@@ -14,18 +14,69 @@ import {
   type InferOutput,
 } from "valibot";
 import { getPageContents } from "../api/client/pages";
+import { getPublicPosts } from "../api/client/posts";
+import { getPublicPostBySlug } from "../api/client/posts";
 import { EditorTanstack } from "./editor/Editor";
 import { PageRendererSSR } from "../editor/render/PageRendererSSR";
 import React from "react";
 import type { Config } from "@puckeditor/core";
 import type { CMSUserData } from "../editor/types";
 import { NotFound } from "./components/NotFound";
+import type {
+  CMSBlogConfig,
+  CMSConfig,
+} from "./seo/types";
+import type {
+  PublicPostDTO,
+  PublicPostSeoDetailsDTO,
+} from "../api/types/public";
 
 // CMS-specific search entries
 const cmsSearchEntries = {
   preview: optional(string()),
 };
 
+// ---------------------------------------------------------------------------
+// Blog route matching helpers
+// ---------------------------------------------------------------------------
+
+interface BlogMatch {
+  kind: "list" | "detail";
+  blog: CMSBlogConfig;
+  /** Slug of the post (only set when kind === "detail") */
+  slug?: string;
+}
+
+function matchBlogRoute(
+  pathname: string,
+  blogs?: CMSBlogConfig[],
+): BlogMatch | null {
+  if (!blogs) return null;
+
+  for (const blog of blogs) {
+    const prefix = blog.prefix.replace(/^\/+|\/+$/g, "");
+
+    // Detail: {prefix}/{slug}
+    if (pathname.startsWith(`${prefix}/`)) {
+      const slug = pathname.slice(prefix.length + 1);
+      if (slug.length > 0) {
+        return { kind: "detail", blog, slug };
+      }
+    }
+
+    // List: exact match on prefix
+    if (pathname === prefix) {
+      return { kind: "list", blog };
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// withCMS
+// ---------------------------------------------------------------------------
+
 export interface WithCMSOptions<
   TComponents extends Record<string, unknown> = Record<string, unknown>,
   TEntries extends ObjectEntries = Record<string, never>,
@@ -34,6 +85,8 @@ export interface WithCMSOptions<
 > {
   config: Config;
   allPageData: Record<string, CMSUserData<TComponents>>;
+  /** Optional CMS-specific settings (blog routing, etc.) */
+  cms?: CMSConfig;
   loader?: (args: {
     params: Record<string, string | undefined>;
     deps: TLoaderDeps & { preview?: string };
@@ -62,6 +115,7 @@ export function withCMS<
   const {
     config,
     allPageData,
+    cms,
     loader,
     component,
     notFoundComponent,
@@ -69,6 +123,8 @@ export function withCMS<
     loaderDeps,
   } = options;
 
+  const blogs = cms?.blogs;
+
   const mergedValidateSearch = object({
     ...(validateSearch?.entries ?? {}),
     ...cmsSearchEntries,
@@ -97,8 +153,57 @@ export function withCMS<
       deps: TLoaderDeps & { preview?: string };
     }) => {
       const { params, deps } = args;
-      const pathname = params._splat || "";
+      const pathname = (params._splat || "").replace(/^\/+|\/+$/g, "");
+
+      // ---- Blog route handling ----
+      const blogMatch = matchBlogRoute(pathname, blogs);
+
+      if (blogMatch) {
+        if (blogMatch.kind === "detail" && blogMatch.slug) {
+          // Fetch full post data by slug
+          try {
+            const postData = await getPublicPostBySlug(blogMatch.slug);
+            return {
+              pageData: null,
+              preview: deps.preview,
+              blogMatch: {
+                kind: "detail" as const,
+                blog: blogMatch.blog,
+                postData,
+              },
+            };
+          } catch {
+            throw notFound();
+          }
+        }
 
+        if (blogMatch.kind === "list") {
+          // Fetch post list (optionally filtered by category)
+          const posts = await getPublicPosts(
+            blogMatch.blog.category ?? undefined,
+          );
+
+          // Also try to load CMS page data for the list page itself
+          // (the user may have created a CMS page at the prefix path)
+          const pageData = await getPageContents(
+            pathname,
+            allPageData,
+            deps.preview,
+          );
+
+          return {
+            pageData,
+            preview: deps.preview,
+            blogMatch: {
+              kind: "list" as const,
+              blog: blogMatch.blog,
+              posts,
+            },
+          };
+        }
+      }
+
+      // ---- Normal CMS page handling ----
       const pageData = await getPageContents(
         pathname,
         allPageData,
@@ -117,19 +222,50 @@ export function withCMS<
       return {
         pageData,
         preview: deps.preview,
+        blogMatch: null,
         ...customData,
       };
     },
     component:
       component ||
       (() => {
-        const { pageData, preview } = useLoaderData({
+        const loaderData = useLoaderData({
           strict: false,
         }) as unknown as {
-          pageData: CMSUserData<TComponents>;
+          pageData: CMSUserData<TComponents> | null;
           preview?: string;
+          blogMatch?: {
+            kind: "list" | "detail";
+            blog: CMSBlogConfig;
+            posts?: PublicPostDTO[];
+            postData?: PublicPostSeoDetailsDTO;
+          } | null;
         };
 
+        const { pageData, preview, blogMatch } = loaderData;
+
+        // ---- Blog rendering ----
+        if (blogMatch) {
+          if (blogMatch.kind === "detail" && blogMatch.postData) {
+            return <>{blogMatch.blog.detailComponent(blogMatch.postData)}</>;
+          }
+
+          if (blogMatch.kind === "list" && blogMatch.posts) {
+            // If there's also a CMS page for the list prefix, render it
+            // above/around the blog list -- or just render the list component.
+            if (pageData && !preview) {
+              return (
+                <>
+                  <PageRendererSSR config={config} data={pageData} />
+                  {blogMatch.blog.listComponent(blogMatch.posts)}
+                </>
+              );
+            }
+            return <>{blogMatch.blog.listComponent(blogMatch.posts)}</>;
+          }
+        }
+
+        // ---- Normal CMS page rendering ----
         if (preview) {
           return (
             <EditorTanstack
@@ -144,6 +280,10 @@ export function withCMS<
           );
         }
 
+        if (!pageData) {
+          return <NotFound />;
+        }
+
         return <PageRendererSSR config={config} data={pageData} />;
       }),
     notFoundComponent: notFoundComponent || NotFound,