rankrunners-cms 0.0.17 → 0.0.19

package/README.md

@@ -1,200 +1,798 @@
 # RankRunners CMS Integration Guide
 
-This guide provides a comprehensive overview of how to integrate `rankrunners-cms` into a TanStack React website (specifically using TanStack Start and TanStack Router).
+A comprehensive guide for integrating `rankrunners-cms` into TanStack Start websites with a block-based visual editor powered by [Puck](https://puckeditor.com).
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Sample Projects](#2-sample-projects)
+3. [Installation](#3-installation)
+4. [Project Structure](#4-project-structure)
+5. [Setting Up the Editor](#5-setting-up-the-editor)
+6. [Creating Component Blocks](#6-creating-component-blocks)
+7. [Creating Page Data](#7-creating-page-data)
+8. [Setting Up Routes](#8-setting-up-routes)
+9. [Sitemap & Robots.txt](#9-sitemap--robotstxt)
+10. [Best Practices](#10-best-practices)
+11. [Developer Checklist](#11-developer-checklist)
+12. [Troubleshooting](#12-troubleshooting)
+
+---
 
 ## 1. Overview
 
-`rankrunners-cms` is a specialized library designed to enhance TanStack-based websites with SEO capabilities and a modular CMS editor powered by [Puck](https://puckeditor.com). It provides utilities for SEO management, script injection, and a structured pattern for building editable components.
+`rankrunners-cms` is a specialized library that provides:
+
+- **Visual Block Editor**: Real-time content editing using Puck
+- **SEO Management**: Automatic meta tags and script injection
+- **Reusable Components**: Pattern for creating editable component blocks
+- **Page Renderer**: Automatic page rendering from initial data
+
+### Key Concepts
+
+- **Blocks**: Editable components with configurable fields
+- **Initial Data**: Default page content that can be edited in the CMS
+- **Root Config**: Layout wrapper (Header, Footer) applied to all pages
+- **Page Renderer**: Component that renders pages based on URL path
 
 ---
 
-## 2. Prerequisites
+## 2. Sample Projects
+
+**Only TypeScript-based projects are supported. JavaScript projects are not supported.**
+
+There are two implementations of the CMS support library as of now:
+1. **The TanStack Start implementation**: This is the recommended implementation. Use this for new projects. Full support for `HeaderScripts` and `FooterScripts`.
+2. **The Next.js implementation**: This implementation exists for legacy sites. There are outstanding issues with the SEO integration. Next.js hydration does not load the script tags in time, and often removes them after hydration. There are many issues with Next.js script tags. `HeaderScripts` and `FooterScripts` are completely impossible to implement.
+
+The following projects use the Next.js implementation:
+- [Dependable Roofing](https://github.com/rankrunners-dev/dependable-roofing)
+- [Pristine Roofing](https://github.com/rankrunners-dev/pristine-roofing)
+
+The following projects use the TanStack Start implementation:
+- [A+ Handyman Services](https://github.com/rankrunners-dev/aplus-handyman-services)
+
+## 3. Installation
+
+### Add Dependencies
+
+```bash
+# Using bun
+bun add rankrunners-cms @puckeditor/core
+
+# Using npm
+npm install rankrunners-cms @puckeditor/core
+```
 
-Ensure your project has the following dependencies installed:
+### Required Peer Dependencies
+
+Ensure you have TanStack Start and Router installed:
 
 ```bash
-bun add rankrunners-cms @puckeditor/core @tanstack/react-router @tanstack/react-start
+bun add @tanstack/react-router @tanstack/react-start
+```
+
+### Environment Variables
+
+Add the following to your `.env` file:
+
+```env
+VITE_PUBLIC_SITE_ID=your-site-id
 ```
 
+> **Important**: Also add `VITE_PUBLIC_SITE_ID` to your Dockerfile for production builds.
+
 ---
 
-## 3. SEO Integration
+## 4. Project Structure
 
-The CMS provides a seamless way to handle SEO metadata and scripts across all routes.
+Create the following structure in your `src/` directory:
 
-### Root Route Configuration
-In your [src/routes/__root.tsx](src/routes/__root.tsx), use `headWithSEO` and `seoScripts` to initialize the global SEO state.
+```
+src/
+├── editor/
+│   ├── index.ts              # Main config export
+│   ├── root.tsx              # Root layout (Header/Footer wrapper)
+│   ├── types.ts              # TypeScript type definitions
+│   ├── blocks/
+│   │   ├── main-page-blocks.tsx    # Home page specific blocks
+│   │   ├── page-blocks.tsx         # General page blocks
+│   │   └── service-page-blocks.tsx # Service-specific blocks, etc.
+│   └── initial-data/
+│       ├── index.ts               # Exports all page data
+│       ├── initial.ts             # Maps paths to page data
+│       ├── index-page.ts          # Home page data
+│       ├── contact-page.ts        # Contact page data
+│       └── ...                    # Other page data files
+├── components/
+│   ├── Hero.tsx              # React components
+│   ├── TrustBar.tsx
+│   └── ...
+└── routes/
+    ├── __root.tsx            # Root route with SEO
+    ├── $.ts                  # Catch-all route for CMS pages
+    └── ...
+```
 
-You can freely configure the head meta, links and scripts if you want.
+---
+
+## 5. Setting Up the Editor
+
+### 5.1 Root Configuration (`src/editor/root.tsx`)
+
+The root config wraps all pages with your site's Header and Footer:
 
 ```tsx
-import { headWithSEO } from 'rankrunners-cms/src/tanstack/seo/head';
-import { seoScripts } from 'rankrunners-cms/src/tanstack/seo/scripts';
+import { Footer } from '@/components/Footer'
+import { Header } from '@/components/Header'
+import { ContactUs } from '@/components/ContactUs'
+import { ScrollToTopButton } from '@/components/ScrollToTopButton'
+import type { DefaultRootProps, RootConfig } from '@puckeditor/core'
 
-export const Route = createRootRoute({
-  head: headWithSEO<any>(() => ({
-    meta: [
-      { charSet: 'utf-8' },
-      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
-    ],
-    links: [
-      { rel: 'stylesheet', href: appCss },
-      { rel: 'icon', href: '/favicon.png' },
-    ],
-  })),
-  scripts: seoScripts as any,
-  shellComponent: RootDocument,
-});
+export type RootProps = DefaultRootProps
+
+export const Root: RootConfig = {
+  defaultProps: {
+    title: 'Your Site Title',
+  },
+  render: ({ children }) => {
+    return (
+      <>
+        <Header />
+        {children}
+        <ContactUs title="Contact Us" />
+        <Footer />
+        <ScrollToTopButton />
+      </>
+    )
+  },
+}
+
+export default Root
 ```
 
-### Individual Route SEO
-For specific pages, use `seoHead` to allow the CMS to inject page-specific metadata.
+### 5.2 Type Definitions (`src/editor/types.ts`)
 
-```tsx
-import { seoHead } from 'rankrunners-cms/src/tanstack/seo/head';
+Define types for your custom components:
+
+```typescript
+import type { CMSUserConfig, CMSUserData } from 'rankrunners-cms/src/editor/types'
+
+import type { MainPageBlockTypes } from './blocks/main-page-blocks'
+import type { PageBlockTypes } from './blocks/page-blocks'
+import type { ServicePageBlockTypes } from './blocks/service-page-blocks'
+
+// Combine all block types
+export type CustomComponents = MainPageBlockTypes & PageBlockTypes & ServicePageBlockTypes
+
+// Export config and data types
+export type UserConfig = CMSUserConfig<CustomComponents, ['custom']>
+export type UserData = CMSUserData<CustomComponents>
+```
 
-export const Route = createFileRoute('/my-page')({
-  head: seoHead as any,
-  component: MyPageComponent,
-});
+### 5.3 Main Config (`src/editor/index.ts`)
+
+Register all blocks and create the config:
+
+```typescript
+import Root from './root'
+import type { CustomComponents } from './types'
+import { createCMSConfig } from 'rankrunners-cms/src/editor/index'
+import { MainPageBlocks } from './blocks/main-page-blocks'
+import { PageBlocks } from './blocks/page-blocks'
+import { ServicePageBlocks } from './blocks/service-page-blocks'
+
+// Define categories for the editor sidebar
+export const customCategories = {
+  custom: {
+    title: 'Custom',
+    components: [
+      'HeroBlock',
+      'TrustBarBlock',
+      'IntroductionBlock',
+      'PageTitleBlock',
+      'ContactTodayBlock',
+      // ... list all block names
+    ],
+  },
+}
+
+// Combine all blocks
+export const customComponents = {
+  ...MainPageBlocks,
+  ...PageBlocks,
+  ...ServicePageBlocks,
+}
+
+// Create and export the config
+export const config = createCMSConfig<CustomComponents, ['custom']>(
+  Root,
+  customCategories,
+  customComponents
+)
 ```
 
 ---
 
-## 4. CMS Editor Setup (Puck)
+## 6. Creating Component Blocks
+
+### 6.1 Block Naming Convention
 
-The CMS editor is typically located at `/editor` and allows real-time content editing.
+**Important**: All block names must end with `Block` suffix (e.g., `HeroBlock`, `TrustBarBlock`).
 
-### The Editor Route
-Implement the editor in [src/routes/editor.tsx](src/routes/editor.tsx). It should toggle between the `Puck` editor and the `Render` component based on query parameters.
+### 6.2 Block Structure Pattern
+
+Each block wraps a React component with Puck configuration:
 
 ```tsx
-import { Puck, Render } from '@puckeditor/core';
-import config from '@/editor';
-import { initialData } from '@/editor/initial-data';
-import '@puckeditor/core/no-external.css';
-
-export const Route = createFileRoute('/editor')({
-  component: () => {
-    const params = new URLSearchParams(window.location.search);
-    const isEdit = params.get('edit') === 'true';
-
-    if (isEdit) {
-      return (
-        <Puck
-          config={config}
-          data={initialData}
-          onPublish={(data) => {
-            // Save data to localStorage or your API
-            localStorage.setItem('cms-data', JSON.stringify(data));
-          }}
-        />
-      );
-    }
-
-    return <Render config={config} data={initialData} />;
+import type { ComponentConfig } from '@puckeditor/core'
+import { withLayout } from 'rankrunners-cms/src/editor/components/Layout'
+import { MyComponent, type MyComponentProps } from '@/components/MyComponent'
+
+export const MyComponentBlock: ComponentConfig<MyComponentProps> = withLayout({
+  label: 'My Component',      // Display name in editor
+  fields: {
+    title: { 
+      type: 'text', 
+      label: 'Title',
+      contentEditable: true,  // Allow inline editing
+    },
+    description: { 
+      type: 'textarea', 
+      label: 'Description' 
+    },
+    // ... more fields
+  },
+  defaultProps: {
+    title: 'Default Title',
+    description: 'Default description text',
+    // ... default values for all props
   },
-});
+  render: (props) => <MyComponent {...props} />,
+})
 ```
 
----
+### 6.3 Available Field Types
 
-## 5. Developing Component Blocks
+| Type | Description | Example |
+|------|-------------|---------|
+| `text` | Single-line text input | `{ type: 'text', label: 'Title' }` |
+| `textarea` | Multi-line text input | `{ type: 'textarea', label: 'Description' }` |
+| `number` | Numeric input | `{ type: 'number', label: 'Count' }` |
+| `select` | Dropdown selection | See below |
+| `array` | List of items | See below |
+| `object` | Nested object | `{ type: 'object', objectFields: {...} }` |
 
-Each editable component (Block) should be modular and define its props and configuration.
+### 6.4 Select Field Example
 
-### Example Block: [src/editor/blocks/Heading/index.tsx](src/editor/blocks/Heading/index.tsx)
 ```tsx
-import { ComponentConfig } from '@puckeditor/core';
+category: {
+  type: 'select',
+  label: 'Category',
+  options: [
+    { label: 'Repairs', value: 'Repairs' },
+    { label: 'Installations', value: 'Installations' },
+    { label: 'Remodeling', value: 'Remodeling' },
+  ],
+},
+```
 
-export type HeadingProps = {
-  text: string;
-  level: 'h1' | 'h2' | 'h3';
-};
+### 6.5 Array Field Example
 
-export const Heading: ComponentConfig<HeadingProps> = {
-  fields: {
-    text: { type: 'text' },
-    level: {
-      type: 'select',
-      options: [
-        { label: 'H1', value: 'h1' },
-        { label: 'H2', value: 'h2' },
-        { label: 'H3', value: 'h3' },
-      ],
-    },
+```tsx
+services: {
+  type: 'array',
+  label: 'Services',
+  getItemSummary: (item) => item.name || 'Service',
+  arrayFields: {
+    name: { type: 'text', label: 'Service Name' },
+    description: { type: 'textarea', label: 'Description' },
+    imageUrl: { type: 'text', label: 'Image URL' },
   },
-  render: ({ text, level: Tag }) => <Tag>{text}</Tag>,
-};
+  defaultItemProps: {
+    name: 'New Service',
+    description: '',
+    imageUrl: '/assets/placeholder.webp',
+  },
+},
 ```
 
----
+### 6.6 The `withLayout` Wrapper
 
-## 6. Sitemap & Robots.txt Support
+**Critical**: Always wrap your block config with `withLayout()` to enable grid/flex layout support:
 
-To add support for these, you need to create the following server-side routes in your TanStack Router setup.
+```tsx
+// ✅ CORRECT
+export const MyBlock: ComponentConfig<MyProps> = withLayout({
+  label: 'My Block',
+  fields: { ... },
+  defaultProps: { ... },
+  render: (props) => <MyComponent {...props} />,
+})
+
+// ❌ WRONG - Will cause "Element type is invalid" error
+export const MyBlock: ComponentConfig<MyProps> = {
+  label: 'My Block',
+  fields: { ... },
+  defaultProps: { ... },
+  render: withLayout((props) => <MyComponent {...props} />),  // DON'T do this
+}
+```
 
-### Sitemap Support
-Create a file called `src/routes/$sitemap.xml.tsx`:
+### 6.7 Complete Block File Example
 
 ```tsx
-import { createFileRoute } from '@tanstack/react-router'
-import { downloadSitemapAsResponse } from 'rankrunners-cms/src/api/client/sitemap'
+// src/editor/blocks/page-blocks.tsx
+import type { ComponentConfig } from '@puckeditor/core'
+import { withLayout } from 'rankrunners-cms/src/editor/components/Layout'
+import { PageTitle, type PageTitleProps } from '@/components/PageTitle'
+import { ContactToday, type ContactTodayProps } from '@/components/ContactToday'
+
+// PageTitle Block
+export const PageTitleBlock: ComponentConfig<PageTitleProps> = withLayout({
+  label: 'Page Title',
+  fields: {
+    title: { type: 'text', label: 'Title' },
+    backgroundImageUrl: { type: 'text', label: 'Background Image URL' },
+  },
+  defaultProps: {
+    title: 'Page Title',
+    backgroundImageUrl: '/assets/hero-bg.webp',
+  },
+  render: (props) => <PageTitle {...props} />,
+})
 
-export const Route = createFileRoute('/$sitemap.xml')({
-  server: {
-    handlers: {
-      GET: ({ params }) => downloadSitemapAsResponse(params['sitemap.xml']),
-    },
+// ContactToday Block
+export const ContactTodayBlock: ComponentConfig<ContactTodayProps> = withLayout({
+  label: 'Contact Today',
+  fields: {
+    mainTitle: { type: 'text', label: 'Main Title' },
+    phoneNumber: { type: 'text', label: 'Phone Number' },
+    // ... more fields
+  },
+  defaultProps: {
+    mainTitle: 'Contact Us Today',
+    phoneNumber: '15551234567',
+    // ... more defaults
   },
+  render: (props) => <ContactToday {...props} />,
 })
+
+// Export types for type.ts
+export type PageBlockTypes = {
+  PageTitleBlock: PageTitleProps
+  ContactTodayBlock: ContactTodayProps
+}
+
+// Export blocks for index.ts
+export const PageBlocks = {
+  PageTitleBlock,
+  ContactTodayBlock,
+}
 ```
 
-### Robots.txt Support
-Create a file called `src/routes/robots[.]txt.tsx`:
+### 6.8 Component Design Guidelines
+
+When creating React components for use with the CMS:
+
+1. **Make ALL text configurable via props**
+2. **Use the same defaults in both the component AND the block**
+3. **Export the props interface for type safety**
 
 ```tsx
-import { createFileRoute } from '@tanstack/react-router'
-import { downloadSitemapAsResponse } from 'rankrunners-cms/src/api/client/sitemap'
+// src/components/PageTitle.tsx
+import { Link } from '@tanstack/react-router'
+import React from 'react'
+
+export interface PageTitleProps {
+  title?: string
+  backgroundImageUrl?: string
+  homeText?: string
+}
+
+// Default props - keep in sync with block defaultProps
+const defaultProps: Required<PageTitleProps> = {
+  title: 'Page Title',
+  backgroundImageUrl: '/assets/hero-bg.webp',
+  homeText: 'Home',
+}
+
+export const PageTitle: React.FC<PageTitleProps> = (props) => {
+  const { title, backgroundImageUrl, homeText } = { ...defaultProps, ...props }
+
+  return (
+    <div
+      className="relative bg-cover bg-center min-h-[15rem] flex justify-center items-center"
+      style={{ backgroundImage: `url('\${backgroundImageUrl}')` }}
+    >
+      <div className="absolute inset-0 bg-black/25" />
+      <div className="relative text-center text-white">
+        <h1 className="text-4xl uppercase">{title}</h1>
+        <div className="mt-2">
+          <Link to="/">{homeText}</Link> / {title}
+        </div>
+      </div>
+    </div>
+  )
+}
+```
 
-export const Route = createFileRoute('/robots.txt')({
-  server: {
-    handlers: {
-      GET: () => downloadSitemapAsResponse('robots.txt'),
-    },
+---
+
+## 7. Creating Page Data
+
+### 7.1 Page Data Structure
+
+Each page has an initial data file:
+
+```typescript
+// src/editor/initial-data/contact-page.ts
+// @ts-nocheck
+import type { UserData } from '../types'
+
+export const contactPageData: UserData = {
+  root: {
+    title: 'Contact Us | Your Site Name',  // Page title for SEO
   },
+  content: [
+    {
+      type: 'PageTitleBlock',  // Must match block name exactly
+      props: {
+        id: 'page-title',     // Unique ID required
+        title: 'Contact Us',
+        backgroundImageUrl: '/assets/contact-bg.webp',
+        homeText: 'Home',
+      },
+    },
+    {
+      type: 'ContactTodayBlock',
+      props: {
+        id: 'contact-section',
+        mainTitle: 'Get In Touch',
+        phoneNumber: '15551234567',
+        // ... all props for the block
+      },
+    },
+  ],
+  zones: {},  // For advanced layouts with drop zones
+}
+```
+
+### 7.2 Registering Page Data (`src/editor/initial-data/initial.ts`)
+
+Map URL paths to page data:
+
+```typescript
+import { indexPageData } from './index-page'
+import { contactPageData } from './contact-page'
+import { testimonialsPageData } from './testimonials-page'
+import { plumbingPageData } from './services/plumbing-page'
+
+export const allPageData = {
+  '': indexPageData,                    // Home page (/)
+  contact: contactPageData,             // /contact
+  testimonials: testimonialsPageData,   // /testimonials
+  'services/plumbing': plumbingPageData, // /services/plumbing
+}
+
+export {
+  indexPageData,
+  contactPageData,
+  testimonialsPageData,
+  plumbingPageData,
+}
+```
+
+### 7.3 Export Initial Data (`src/editor/initial-data/index.ts`)
+
+```typescript
+export { allPageData as initialData } from './initial'
+export * from './initial'
+```
+
+---
+
+## 8. Setting Up Routes
+
+### 8.1 Root Route (`src/routes/__root.tsx`)
+
+In your [src/routes/__root.tsx](src/routes/__root.tsx), use `headWithSEO` and `seoScripts` to initialize the global SEO state.
+
+You can freely configure the head meta, links and scripts if you want.
+
+```tsx
+import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
+import { headWithSEO, seoScripts } from 'rankrunners-cms/src/tanstack'
+import appCss from '../styles.css?url'
+
+export const Route = createRootRoute({
+  head: headWithSEO<any>(() => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+    ],
+    links: [
+      { rel: 'stylesheet', href: appCss },
+      { rel: 'icon', href: '/favicon.png' },
+    ],
+  })),
+  scripts: seoScripts as any,
+  shellComponent: RootDocument,
 })
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
 ```
 
+### 8.2 Catch-All Page Route (`src/routes/$.ts`)
+
+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 { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/\$')({
+  component: () =>
+    PageRendererTanstack({
+      config,
+      allPageData: initialData,
+    })(),
+})
+```
+
+### 8.3 How the Page Renderer Works
+
+1. Extracts the pathname from the URL (e.g., `/contact` -> `contact`)
+2. Looks up the page data in `allPageData`
+3. If `?preview=token` query param exists, shows the Puck editor
+4. Otherwise, renders the page using the `Render` component
+
 ---
 
-## 7. Developer Checklist
+## 9. Sitemap & Robots.txt
+
+Update the `server.ts` script, or add a Tanstack Start middleware to handle `[sitemap].xml` and `robots.txt` requests:
+
+```typescript
+  // Build static routes with intelligent preloading
+  const { routes } = await initializeStaticRoutes(CLIENT_DIRECTORY)
+
+  // Import sitemap handler dynamically to help Bun bundle it
+  const downloadSitemapAsResponse = (
+    await import('rankrunners-cms/src/api/client/sitemap')
+  ).downloadSitemapAsResponse
+
+  // Create Bun server
+  const server = Bun.serve({
+    port: SERVER_PORT,
+
+    routes: {
+      // Serve static assets, robots.txt, sitemaps (*.xml), and all other routes
+      ...routes,
+      '/*': (req: Request) => {
+        const url = new URL(req.url)
+        const pathname = url.pathname
+
+        // Check if it's a sitemap file (ends with .xml)
+        if (pathname === 'robots.txt' || pathname.endsWith('.xml')) {
+          const sitemapFile = pathname.substring(1) // Remove leading slash
+          return downloadSitemapAsResponse(sitemapFile)
+        }
+
+        // Otherwise, pass to TanStack Start handler
+        try {
+          return handler.fetch(req)
+        } catch (error) {
+          log.error(`Server handler error: ${String(error)}`)
+          return new Response('Internal Server Error', { status: 500 })
+        }
+      },
+    },
 
-Use this checklist to ensure a complete and correct integration:
+    // Global error handler
+    error(error) {
+      log.error(
+        `Uncaught server error: ${error instanceof Error ? error.message : String(error)}`,
+      )
+      return new Response('Internal Server Error', { status: 500 })
+    },
+  })
+```
 
-### Core Setup
-- [ ] Install `rankrunners-cms` and `@puckeditor/core`.
-- [ ] Add `headWithSEO` to `createRootRoute` in [src/routes/__root.tsx](src/routes/__root.tsx).
-- [ ] Add `seoScripts` to `createRootRoute` in [src/routes/__root.tsx](src/routes/__root.tsx).
-- [ ] Add `<Scripts />` after the body and `<HeadContent />` in the `<head>` to [src/routes/__root.tsx](src/routes/__root.tsx)
+---
 
-### SEO & Metadata
-- [ ] Include `seoHead` in all page routes (`createFileRoute`).
-- [ ] Ensure `VITE_PUBLIC_SITE_ID` and other CMS-related environment variables are set, as well in Dockerfile.
+## 10. Best Practices
 
-### Editor Infrastructure
-- [ ] Create `src/editor/` structure.
-- [ ] Define `UserConfig` and `UserData` types in `types.ts`.
-- [ ] Set up `src/editor/root.tsx` with Header/Footer and `DropZone`.
-- [ ] Create `initial-data.ts` to populate the editor initially.
+### Component Design
+- ✅ Make ALL text configurable (no hardcoded strings)
+- ✅ Keep default props in sync between component and block
+- ✅ Export component props interface
+- ✅ Use semantic HTML for accessibility
+
+### Block Design
+- ✅ Always use `withLayout()` wrapper
+- ✅ End block names with `Block` suffix
+- ✅ Provide meaningful `label` for editor sidebar
+- ✅ Use `contentEditable: true` for inline-editable text fields
+- ✅ Use `getItemSummary` for array fields to show previews
+
+### Page Data
+- ✅ Always include unique `id` in each block's props
+- ✅ Match block `type` exactly to exported block name
+
+### Common Pitfalls
+- ❌ Don't use `@measured/puck` - it's been renamed to `@puckeditor/core`
+- ❌ Don't wrap only the render function with `withLayout()`
+- ❌ Don't use `type: 'list'` for array fields (use `type: 'array'`)
+
+---
+
+## 11. Developer Checklist
+
+### Initial Setup
+- [ ] Install `rankrunners-cms` and `@puckeditor/core`
+- [ ] Set `VITE_PUBLIC_SITE_ID` environment variable
+- [ ] Add `VITE_PUBLIC_SITE_ID` to Dockerfile
+
+### Root Route Configuration
+- [ ] Add `headWithSEO` to `createRootRoute`
+- [ ] Add `seoScripts` to `createRootRoute`
+- [ ] Add `<HeadContent />` in `<head>`
+- [ ] Add `<Scripts />` after body content
+
+### Editor Structure
+- [ ] Create `src/editor/index.ts` with config export
+- [ ] Create `src/editor/root.tsx` with Header/Footer wrapper
+- [ ] Create `src/editor/types.ts` with type definitions
+
+### Block Implementation
+- [ ] Create blocks in `src/editor/blocks/`
+- [ ] Use `withLayout()` wrapper for each block
+- [ ] Export block types (e.g., `PageBlockTypes`)
+- [ ] Export blocks object (e.g., `PageBlocks`)
+- [ ] Register blocks in `customCategories`
+- [ ] Register blocks in `customComponents`
+
+### Page Data
+- [ ] Create page data files in `src/editor/initial-data/`
+- [ ] Register paths in `initial.ts` `allPageData` object
+
+### Routes
+- [ ] Create catch-all route `src/routes/$.ts`
+
+### Sitemaps
+- [ ] Implement sitemap serving middleware in `server.ts`
 
 ### Component Implementation
 - [ ] Migrate/Create components in `src/editor/blocks/`.
 - [ ] Register all blocks in `src/editor/index.tsx`.
 - [ ] Organize blocks into `categories` within the config.
 
-### Sitemap & Robots.txt
-- [ ] Add `src/routes/$sitemap.xml.tsx` for dynamic sitemap support.
-- [ ] Add `src/routes/robots.txt.tsx` for `robots.txt` support.
+### CMS configuration
+- [ ] Added the new pages to the site in the [CMS user interface](https://cms.rankrunners.net) and saved at least once.
+
+---
+
+## 12. Troubleshooting
+
+### "Element type is invalid: expected a string...but got: object"
+
+**Cause**: Using `withLayout()` incorrectly.
+
+**Fix**: Wrap the entire ComponentConfig object, not just the render function:
+
+```tsx
+// ✅ Correct
+export const MyBlock = withLayout({
+  label: '...',
+  fields: {...},
+  render: (props) => <MyComponent {...props} />,
+})
+
+// ❌ Wrong
+export const MyBlock = {
+  label: '...',
+  fields: {...},
+  render: withLayout((props) => <MyComponent {...props} />),
+}
+```
+
+### Page shows "Loading page..." forever
+
+**Cause**: Path mismatch between URL and `allPageData` keys.
+
+**Fix**: Ensure keys in `allPageData` match URL paths without leading slashes:
+- URL `/contact` -> key `contact`
+- URL `/services/plumbing` -> key `services/plumbing`
+- URL `/` -> key `''` (empty string)
+
+### Build error: Unexpected character
+
+**Cause**: Using special characters in strings.
+
+**Fix**: Replace curly quotes and em-dashes:
+- Curly single quotes -> straight single quote `'`
+- Curly double quotes -> straight double quote `"`
+- Em-dash -> hyphen `-` or double hyphen `--`
+
+### TypeScript error with field type
+
+**Cause**: Using unsupported field type.
+
+**Fix**: Use supported types: `text`, `textarea`, `number`, `select`, `array`, `object`
 
 ---
+
+## Quick Start Template
+
+Create a new CMS-enabled page in 3 steps:
+
+**1. Create the component** (`src/components/MyPage.tsx`)
+```tsx
+export interface MyPageProps {
+  title?: string
+  content?: string
+}
+
+export const MyPage: React.FC<MyPageProps> = ({ 
+  title = 'Default Title',
+  content = 'Default content'
+}) => (
+  <div className="max-w-4xl mx-auto py-8 px-4">
+    <h1>{title}</h1>
+    <p>{content}</p>
+  </div>
+)
+```
+
+**2. Create the block** (add to `src/editor/blocks/page-blocks.tsx`)
+```tsx
+export const MyPageBlock: ComponentConfig<MyPageProps> = withLayout({
+  label: 'My Page',
+  fields: {
+    title: { type: 'text', label: 'Title' },
+    content: { type: 'textarea', label: 'Content' },
+  },
+  defaultProps: {
+    title: 'Default Title',
+    content: 'Default content',
+  },
+  render: (props) => <MyPage {...props} />,
+})
+```
+
+**3. Create the page data** (`src/editor/initial-data/mypage-page.ts`)
+```typescript
+export const mypagePageData: UserData = {
+  root: { title: 'My Page | Site Name' },
+  content: [
+    {
+      type: 'MyPageBlock',
+      props: { id: 'my-page', title: 'Welcome', content: 'Hello world!' },
+    },
+  ],
+  zones: {},
+}
+```
+
+Then register in `initial.ts`:
+```typescript
+export const allPageData = {
+  // ...
+  'mypage': mypagePageData,
+}
+```

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "rankrunners-cms",
   "type": "module",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "peerDependencies": {
-    "@puckeditor/core": "^0.21.0",
+    "@puckeditor/core": "^0.21.1",
     "next": "^16.1.2",
     "@tanstack/router-core": "^1.150.0",
     "@tanstack/react-router": "^1.150.0",
@@ -29,15 +29,14 @@
     }
   },
   "devDependencies": {
-    "@types/react": "^19.2.8",
-    "bun-types": "^1.3.6",
+    "@types/react": "^19.2.11",
+    "bun-types": "^1.3.8",
     "typescript": "^5.9.3",
-    "@tanstack/router-core": "^1.150.0",
-    "@tanstack/react-router": "^1.150.0",
-    "next": "^16.1.3",
+    "@tanstack/router-core": "^1.158.0",
+    "@tanstack/react-router": "^1.158.0",
+    "next": "^16.1.6",
     "valibot": "^1.2.0",
-    "lucide-react": "^0.562.0",
-    "react": "^19.2.3"
+    "lucide-react": "^0.563.0"
   },
   "dependencies": {
     "classnames": "^2.5.1",

package/src/api/client/pages.ts

@@ -0,0 +1,57 @@
+import type { CMSUserData } from "../../editor";
+import { fetchWithCache } from "../../libs";
+import { CMS_BASE_URL, SITE_ID } from "../constants";
+
+export const getPageContents = async (
+  pathname: string,
+  allPageData: Record<string, CMSUserData<any>>,
+  previewToken?: string,
+) => {
+  // remove trailing (left and right) slashes
+  pathname = pathname.replace(/^\/+|\/+$/g, "");
+
+  try {
+    const res = await fetchWithCache(
+      `${CMS_BASE_URL}/public/seo/${SITE_ID}/pages/${pathname}`,
+      {
+        headers: {
+          "Content-Type": "application/json",
+        },
+      },
+    );
+
+    if (res.ok) {
+      const json = (await res.json()) as { content?: string };
+
+      if (json.content) {
+        const content = JSON.parse(json.content) as CMSUserData<any>;
+
+        if (content.root && content.content) {
+          return content;
+        }
+      }
+    }
+
+    const actualData = allPageData[pathname as keyof typeof allPageData];
+
+    if (actualData) {
+      // Starting new page from existing published data
+      return actualData as CMSUserData<any>;
+    }
+
+    // Starting new blank page
+  } catch (error) {
+    console.error("Error fetching page data:", error);
+  }
+
+  if (previewToken) {
+    // New blank page in preview mode
+    return {
+      content: [],
+      root: { props: { title: "New Page" } },
+      zones: {},
+    };
+  }
+
+  return null;
+};

package/src/editor/render/PageRendererContent.tsx

@@ -1,56 +1,7 @@
 import { useEffect, useState } from "react";
 import type { CMSUserData } from "../types";
 import { Render, type Config } from "@puckeditor/core";
-import { CMS_BASE_URL, SITE_ID } from "../../api";
-import { fetchWithCache } from "../../libs";
-
-const getPageContents = async (
-  pathname: string,
-  allPageData: Record<string, CMSUserData<any>>,
-) => {
-  // remove trailing (left and right) slashes
-  pathname = pathname.replace(/^\/+|\/+$/g, "");
-
-  try {
-    const res = await fetchWithCache(
-      `${CMS_BASE_URL}/public/seo/${SITE_ID}/pages/${pathname}`,
-      {
-        headers: {
-          "Content-Type": "application/json",
-        },
-      },
-    );
-
-    if (res.ok) {
-      const json = (await res.json()) as { content?: string };
-
-      if (json.content) {
-        const content = JSON.parse(json.content) as CMSUserData<any>;
-
-        if (content.root && content.content) {
-          return content;
-        }
-      }
-    }
-
-    const actualData = allPageData[pathname as keyof typeof allPageData];
-
-    if (actualData) {
-      // Starting new page from existing published data
-      return actualData as CMSUserData<any>;
-    }
-
-    // Starting new blank page
-  } catch (error) {
-    console.error("Error fetching page data:", error);
-  }
-
-  return {
-    content: [],
-    root: { props: { title: "New Page" } },
-    zones: {},
-  };
-};
+import { getPageContents } from "../../api/client/pages";
 
 export type PageRendererContentProps = {
   pathname: string;
@@ -82,4 +33,4 @@ export const PageRendererContent = ({
   }
 
   return <Render config={config} data={data} />;
-};
+};

package/src/editor/render/PageRendererSSR.tsx

@@ -0,0 +1,15 @@
+import { Render, type Config } from "@puckeditor/core";
+import type { CMSUserData } from "../types";
+
+export type PageRendererSSRProps = {
+  config: Config;
+  data: CMSUserData<any>;
+};
+
+/**
+ * SSR-compatible PageRenderer that receives pre-fetched data from the loader.
+ * Use this component with TanStack Router's loader for server-side rendering.
+ */
+export const PageRendererSSR = ({ config, data }: PageRendererSSRProps) => {
+  return <Render config={config} data={data} />;
+};

package/src/editor/render/Preview.tsx

@@ -126,7 +126,7 @@ export const BaseEditor =
               alert("Failed to upload changes to CMS");
             } else {
               alert(
-                "Changes uploaded successfully to CMS! The page will now reflect the changes."
+                "Changes uploaded successfully to CMS! The page will now reflect the changes.",
               );
             }
           } catch (error) {
@@ -141,9 +141,6 @@ export const BaseEditor =
         iframe={{
           enabled: true,
         }}
-        fieldTransforms={{
-          userField: ({ value }) => value, // Included to check types
-        }}
         overrides={{
           fieldTypes: {
             // Example of user field provided via overrides

package/src/tanstack/editor/Editor.tsx

@@ -1,9 +1,7 @@
-"use client";
-
-import { BaseEditor } from "../../editor/render/Preview";
-import { usePathnameTanstack, useSearchParamsTanstack } from "../hooks";
+import { BaseEditor } from '../../editor/render/Preview'
+import { usePathnameTanstack, useSearchParamsTanstack } from '../hooks'
 
 export const EditorTanstack = BaseEditor({
   usePathname: usePathnameTanstack,
   useSearchParams: useSearchParamsTanstack,
-});
+})

package/src/tanstack/editor/PageRenderer.tsx

@@ -9,6 +9,10 @@ export type PageRendererTanstackInitializerProps = {
   allPageData: Record<string, CMSUserData<any>>;
 };
 
+/**
+ * Use PageRendererTanstackSSR for SSR support instead.
+ * This component fetches data on the client side.
+ */
 export const PageRendererTanstack =
   ({ config, allPageData }: PageRendererTanstackInitializerProps) =>
   () => {