rankrunners-cms 0.0.16 → 0.0.18

package/README.md

@@ -1,35 +1,509 @@
 # 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
 
-Ensure your project has the following dependencies installed:
+```bash
+# Using bun
+bun add rankrunners-cms @puckeditor/core
+
+# Using npm
+npm install rankrunners-cms @puckeditor/core
+```
+
+### 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:
+
+```
+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
+    └── ...
+```
+
+---
+
+## 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 { 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 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
+```
+
+### 5.2 Type Definitions (`src/editor/types.ts`)
+
+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>
+```
+
+### 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
+)
+```
+
+---
+
+## 6. Creating Component Blocks
+
+### 6.1 Block Naming Convention
+
+**Important**: All block names must end with `Block` suffix (e.g., `HeroBlock`, `TrustBarBlock`).
+
+### 6.2 Block Structure Pattern
+
+Each block wraps a React component with Puck configuration:
+
+```tsx
+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
+
+| 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: {...} }` |
+
+### 6.4 Select Field Example
+
+```tsx
+category: {
+  type: 'select',
+  label: 'Category',
+  options: [
+    { label: 'Repairs', value: 'Repairs' },
+    { label: 'Installations', value: 'Installations' },
+    { label: 'Remodeling', value: 'Remodeling' },
+  ],
+},
+```
+
+### 6.5 Array Field Example
+
+```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' },
+  },
+  defaultItemProps: {
+    name: 'New Service',
+    description: '',
+    imageUrl: '/assets/placeholder.webp',
+  },
+},
+```
+
+### 6.6 The `withLayout` Wrapper
+
+**Critical**: Always wrap your block config with `withLayout()` to enable grid/flex layout support:
+
+```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
+}
+```
+
+### 6.7 Complete Block File Example
+
+```tsx
+// 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} />,
+})
+
+// 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,
+}
+```
+
+### 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
+// 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>
+  )
+}
+```
+
+---
+
+## 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`)
 
-### Root Route Configuration
 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 { headWithSEO } from 'rankrunners-cms/src/tanstack/seo/head';
-import { seoScripts } from 'rankrunners-cms/src/tanstack/seo/scripts';
+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>(() => ({
@@ -44,120 +518,260 @@ export const Route = createRootRoute({
   })),
   scripts: seoScripts as any,
   shellComponent: RootDocument,
-});
+})
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
 ```
 
-### Individual Route SEO
-For specific pages, use `seoHead` to allow the CMS to inject page-specific metadata.
+### 8.2 Catch-All Page Route (`src/routes/$.ts`)
 
-```tsx
-import { seoHead } from 'rankrunners-cms/src/tanstack/seo/head';
+This single route handles ALL CMS pages:
 
-export const Route = createFileRoute('/my-page')({
-  head: seoHead as any,
-  component: MyPageComponent,
-});
+```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
+
 ---
 
-## 4. CMS Editor Setup (Puck)
+## 9. Sitemap & Robots.txt
 
-The CMS editor is typically located at `/editor` and allows real-time content editing.
+Update the `server.ts` script, or add a Tanstack Start middleware to handle `[sitemap].xml` and `robots.txt` requests:
 
-### 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.
+```typescript
+  // Build static routes with intelligent preloading
+  const { routes } = await initializeStaticRoutes(CLIENT_DIRECTORY)
 
-```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));
-          }}
-        />
-      );
+  // Add sitemap routes
+  routes['/*'] = (req: Request) => {
+    const url = new URL(req.url)
+    const pathname = url.pathname
+
+    // Serve the sitemap if we are asking for it
+    if (pathname === 'robots.txt' || pathname.endsWith('.xml')) {
+      const sitemapFile = pathname.substring(1)
+      return downloadSitemapAsResponse(sitemapFile)
     }
 
-    return <Render config={config} data={initialData} />;
-  },
-});
+    // 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 })
+    }
+  }
 ```
 
 ---
 
-## 5. Developing Component Blocks
+## 10. Best Practices
 
-Each editable component (Block) should be modular and define its props and configuration.
+### 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
 
-### Example Block: [src/editor/blocks/Heading/index.tsx](src/editor/blocks/Heading/index.tsx)
-```tsx
-import { ComponentConfig } from '@puckeditor/core';
+### 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
 
-export type HeadingProps = {
-  text: string;
-  level: 'h1' | 'h2' | 'h3';
-};
+### Page Data
+- ✅ Always include unique `id` in each block's props
+- ✅ Match block `type` exactly to exported block name
 
-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' },
-      ],
-    },
-  },
-  render: ({ text, level: Tag }) => <Tag>{text}</Tag>,
-};
-```
+### 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'`)
 
 ---
 
-## 6. Developer Checklist
-
-Use this checklist to ensure a complete and correct integration:
+## 11. Developer Checklist
 
-### 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)
+### Initial Setup
+- [ ] Install `rankrunners-cms` and `@puckeditor/core`
+- [ ] Set `VITE_PUBLIC_SITE_ID` environment variable
+- [ ] Add `VITE_PUBLIC_SITE_ID` to Dockerfile
 
-### 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.
-
-### 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.
+### 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.
 
-### Persistence & Deployment
-- [ ] Implement `onPublish` logic in the editor route.
-- [ ] (Optional) Set up `server.tsx` blocks for optimal SSR performance.
-- [ ] Verify that `@puckeditor/core/no-external.css` is imported in the editor route.
+### 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,7 +1,7 @@
 {
   "name": "rankrunners-cms",
   "type": "module",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "peerDependencies": {
     "@puckeditor/core": "^0.21.0",
     "next": "^16.1.2",
@@ -34,7 +34,7 @@
     "typescript": "^5.9.3",
     "@tanstack/router-core": "^1.150.0",
     "@tanstack/react-router": "^1.150.0",
-    "next": "^16.1.2",
+    "next": "^16.1.3",
     "valibot": "^1.2.0",
     "lucide-react": "^0.562.0",
     "react": "^19.2.3"

package/src/editor/render/PageRendererContent.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+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";
@@ -6,7 +6,7 @@ import { fetchWithCache } from "../../libs";
 
 const getPageContents = async (
   pathname: string,
-  allPageData: Record<string, CMSUserData<any>>
+  allPageData: Record<string, CMSUserData<any>>,
 ) => {
   // remove trailing (left and right) slashes
   pathname = pathname.replace(/^\/+|\/+$/g, "");
@@ -18,13 +18,10 @@ const getPageContents = async (
         headers: {
           "Content-Type": "application/json",
         },
-      }
+      },
     );
 
     if (res.ok) {
-      //  console.error("Failed to fetch page data from CMS");
-      //  throw new Error("Failed to fetch page data from CMS");
-      //}
       const json = (await res.json()) as { content?: string };
 
       if (json.content) {
@@ -68,13 +65,13 @@ export const PageRendererContent = ({
 }: PageRendererContentProps) => {
   const [data, setData] = useState<CMSUserData<any> | null>(null);
 
-  useState(() => {
+  useEffect(() => {
     const fetchData = async () => {
       const pageData = await getPageContents(pathname, allPageData);
       setData(pageData);
     };
     fetchData();
-  });
+  }, [pathname]);
 
   if (!data) {
     return (

package/src/tanstack/editor/PageRenderer.tsx

@@ -0,0 +1,30 @@
+import type { Config } from "@puckeditor/core";
+import { PageRendererContent } from "../../editor";
+import { EditorTanstack } from ".";
+import { usePathnameTanstack, useSearchParamsTanstack } from "../hooks";
+import type { CMSUserData } from "../../editor";
+
+export type PageRendererTanstackInitializerProps = {
+  config: Config;
+  allPageData: Record<string, CMSUserData<any>>;
+};
+
+export const PageRendererTanstack =
+  ({ config, allPageData }: PageRendererTanstackInitializerProps) =>
+  () => {
+    const pathname = usePathnameTanstack();
+    const searchParams = useSearchParamsTanstack();
+    const previewToken = searchParams.get("preview");
+
+    if (previewToken) {
+      return <EditorTanstack config={config} allPageData={allPageData} />;
+    }
+
+    return (
+      <PageRendererContent
+        config={config}
+        allPageData={allPageData}
+        pathname={pathname}
+      />
+    );
+  };

package/src/tanstack/editor/index.ts

@@ -1 +1,2 @@
 export * from "./Editor";
+export * from "./PageRenderer";

package/src/tanstack/seo/sitemap.tsx

@@ -1,31 +0,0 @@
-import { downloadSitemap } from "../../api/client/sitemap";
-
-/**
- * Handler for sitemap routes in TanStack Router
- * Use this in your route file with a loader
- */
-export const createSitemapRoute = async (sitemap: string) => {
-  const sitemapData = await downloadSitemap(`${sitemap}.xml`);
-  
-  return new Response(sitemapData, {
-    status: 200,
-    headers: {
-      "Content-Type": "application/xml",
-    },
-  });
-};
-
-/**
- * Handler for robots.txt route in TanStack Router
- * Use this in your route file with a loader
- */
-export const createRobotsTxtRoute = async () => {
-  const robotsTxt = await downloadSitemap("robots.txt");
-
-  return new Response(robotsTxt, {
-    status: 200,
-    headers: {
-      "Content-Type": "text/plain",
-    },
-  });
-};