TanStack Start is no joke.

What this video covers

Goal: Build a local monorepo containing Payload CMS as the backend and TanStack Start as the frontend, sharing types and calling Payload’s local API from TanStack Start.

• Tools demonstrated: Payload CMS, TanStack Start (RC), pnpm workspaces, TypeScript, Vite, Zod, payload rich-text converter packages, and various CLI project generators.
• End result: a monorepo where the frontend calls the local Payload API via TanStack Start server functions, with shared TypeScript types across packages.

Key technological concepts & product features

TanStack Start

• Full‑stack framework for React (and Solid) with SSR, streaming, and server functions.
• File-based routing with automatic route/layout generation.
• Does not yet ship React Server Components — you must use server functions for local API calls.
• Strong developer experience: fast startup, automatic routing, simple DX compared to some other setups.

Payload CMS

• Headless CMS used as the backend (collections, media relations, rich text, slug generation).
• Can generate TypeScript types for use across the monorepo to keep the frontend type-safe.
• Provides a local API usable from TanStack server functions (via getPayload / payload.find).

Integration patterns demonstrated

Monorepo setup

• Create pnpm-workspace.yaml and top-level package.json scripts (dev scripts for CMS and website, generate-types, etc.).
• Generate a Payload app (create payload app) and a TanStack Start app (pnpm create tanstack-start).
• Export Payload config and types from the CMS source/index.ts so the website can import config & types.

Calling Payload from TanStack Start

Because TanStack Start pages aren’t React Server Components yet, use server functions to fetch data from Payload:

• Create a server function that validates input (Zod).
• In the handler, dynamically import Payload and the CMS config (getPayload + config import from the CMS source).
• Use payload.find to query collections (e.g., posts) and return the result to the page’s loader.
• On the page, use a route loader + useLoaderData to access returned data.

File-based routing and dynamic routes

• Create files like posts/$slug.tsx (TanStack Start file-based routing) and use server functions/loaders to fetch the document by slug.

Types & shared typings

• Generate Payload types via a script and import them in the frontend so collections and documents are strongly typed across the monorepo.

Practical implementation details, problems encountered & workarounds

• React Server Components are not yet supported in TanStack Start — use server functions for server-side data fetching.
• Type errors when fetching documents with rich text:
  • Selecting full rich-text fields sometimes led to type/SSR problems. Workarounds:
    • Use payload.find with select to limit fields and avoid problematic nested structures.
    • If you need the full document, a temporary coercion is JSON.stringify / JSON.parse to remove runtime/typing artifacts (not ideal long-term).
    • Regenerate types and restart dev servers to refresh types after changes.
• Vite SSR issues with Payload imports:
  • Add optimizeDeps / exclude entries (exclude payload and related packages) in Vite config to avoid SSR build/runtime errors.
• Images:
  • Payload media returns a media object — cast/handle it on the frontend as needed.
  • TanStack Start recommends image tools like unpic for image handling (unlike Next.js’ built-in Image).
• Rich text rendering:
  • Install Payload’s conversion utilities (e.g., payload rich-text lexical-html) to convert rich text to HTML.
  • Render converted HTML in the page (e.g., dangerouslySetInnerHTML) or use a proper renderer.
• Misc essentials:
  • Install Zod for server function input validation.
  • Use pnpm scripts to run both CMS and website concurrently.
  • Pay attention to ports and CORS when running CMS + website locally.

Step-by-step checklist (high level)

1. Create Payload backend: npx create-payload-app (blank template) — remove front-end if unused.
2. Create TanStack Start app: pnpm create tanstack-start (enable file-based routing).
3. Set up pnpm-workspace.yaml and top-level package.json scripts for dev, generate types, etc.
4. Export Payload config & types from CMS source/index.ts for cross-package imports.
5. Create collections (e.g., posts) in Payload with fields: title, slug, rich text, image relation.
6. Generate types (script) and install needed packages (Zod, payload rich-text converter).
7. In the TanStack Start route:
   • Create a server function (createServerFunction) with input validation (Zod).
   • Dynamically import Payload and CMS config in the server function handler.
   • Query Payload (payload.find) and return results.
   • In the route loader, call the server function and use useLoaderData in the component to render results.
8. Handle images & rich text: cast media types, use image tooling (e.g., unpic), convert rich text to HTML for rendering.
9. If encountering SSR/type issues: try Vite optimizeDeps exclude, regenerate types, or use JSON.stringify/JSON.parse as a temporary coercion.

Reviewer observations / opinions

• Presenter liked TanStack Start’s developer experience (speed, automatic routing) and sees potential for it as a competitor to Next.js.
• Rough edges exist due to RC status: missing React Server Components and some type friction with rich text and SSR.
• Overall, integration with Payload CMS was straightforward and performant.
• Monorepo approach is recommended for shared types and tighter integration.

Resources & references mentioned

• Payload CMS templates & docs (examples, rich text conversion).
• TanStack Start docs and example repo (routing, server functions).
• Packages referenced: Zod, Payload’s rich-text lexical-html converter, unpic (for images), plus pnpm workspace tooling.

Main speaker / sources

• Presenter: NLV Codes (YouTuber; references nlvcodes.com and his channel).
• Primary sources: Payload CMS documentation & templates, TanStack Start documentation & example repo, and community/chat examples used during the coding session.