create-vexcms 0.1.0-alpha.21 → 0.1.0-alpha.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-vexcms",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.23",
   "description": "Scaffold a new VexCMS project",
   "keywords": [
     "cms",

package/templates/base-nextjs/convex/vex.ts

@@ -19,7 +19,7 @@ export const { mutation: vexMutation, internalMutation: vexInternalMutation } =
   internalMutation,
 });
 
-export const { find, get, search, create, update, remove } = collectionsApi({
+export const { find, get, search, create, update, remove, livePreviewUrl } = collectionsApi({
   config,
   query,
   mutation: vexMutation,

package/templates/base-nextjs/package.json

@@ -24,11 +24,11 @@
     "@t3-oss/env-nextjs": "0.13.11",
     "@tanstack/react-form": "1.33.1",
     "@tanstack/react-query": "5.101.2",
-    "@vexcms/better-auth": "~0.1.0-alpha.21",
-    "@vexcms/core": "~0.1.0-alpha.21",
-    "@vexcms/file-storage-convex": "~0.1.0-alpha.21",
-    "@vexcms/next": "~0.1.0-alpha.21",
-    "@vexcms/react": "~0.1.0-alpha.21",
+    "@vexcms/better-auth": "~0.1.0-alpha.23",
+    "@vexcms/core": "~0.1.0-alpha.23",
+    "@vexcms/file-storage-convex": "~0.1.0-alpha.23",
+    "@vexcms/next": "~0.1.0-alpha.23",
+    "@vexcms/react": "~0.1.0-alpha.23",
     "better-auth": "1.6.23",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
@@ -52,7 +52,7 @@
     "@types/node": "20.19.43",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
-    "@vexcms/cli": "~0.1.0-alpha.21",
+    "@vexcms/cli": "~0.1.0-alpha.23",
     "babel-plugin-react-compiler": "1.0.0",
     "eslint": "9.39.5",
     "eslint-config-next": "15.5.9",

package/templates/base-nextjs/src/app/(vexcms)/admin/layout.tsx

@@ -5,17 +5,13 @@ import { NextAdminLayout } from "@vexcms/next/client"
 import { AuthServerProvider } from "~/components/providers/auth"
 import { getCurrentUser } from "~/auth/serverUtils"
 
-import { ClientProviders } from "./clientProviders"
-
 export default async function AdminLayout({ children }: { children: ReactNode }) {
   const user = await getCurrentUser()
   return (
+    // `VexConfigProvider` is mounted once by the root layout's
+    // `ClientProviders`, for the admin and the public site alike.
     <AuthServerProvider>
-      <ClientProviders>
-        <NextAdminLayout user={user ?? undefined}>
-          {children}
-        </NextAdminLayout>
-      </ClientProviders>
+      <NextAdminLayout user={user ?? undefined}>{children}</NextAdminLayout>
     </AuthServerProvider>
   )
 }

package/templates/base-nextjs/src/components/providers/client.tsx

@@ -2,13 +2,31 @@
 
 import { type PropsWithChildren } from "react"
 
+import { VexConfigProvider } from "@vexcms/react"
+
 import BetterAuthClientProvider from "~/auth/client"
 import ConvexClientProvider from "~/components/providers/convex"
+import config from "~/vex.config"
 
+/**
+ * Mounts the app-wide client providers, including the single
+ * `VexConfigProvider` for the WHOLE app — admin and public site alike.
+ *
+ * One mount, at the root, because both trees need the config now: the admin
+ * views always did, and `LivePreviewProvider` reads its collections, globals,
+ * and allowed origins from the same context rather than from props. Two mounts
+ * would be two provenances for one config.
+ *
+ * `"use client"` so `vex.config` is imported and owned on the client — it never
+ * crosses the RSC boundary as a prop, which React would refuse: the config
+ * carries functions (field validators, `admin.livePreview.url` resolvers).
+ */
 export default function ClientProviders({ children }: PropsWithChildren) {
   return (
     <ConvexClientProvider>
-      <BetterAuthClientProvider>{children}</BetterAuthClientProvider>
+      <BetterAuthClientProvider>
+        <VexConfigProvider config={config}>{children}</VexConfigProvider>
+      </BetterAuthClientProvider>
     </ConvexClientProvider>
   )
 }

package/templates/base-nextjs/src/vex.types.ts

@@ -5,7 +5,7 @@
 /* eslint-disable perfectionist/sort-interfaces */
 /* eslint-disable perfectionist/sort-modules */
 
-import type { Id } from "@convex/_generated/dataModel"
+import type { DataModel, Id } from "@convex/_generated/dataModel"
 import type { VexDocument, VexDocumentGlobal } from "@vexcms/core"
 
 export interface UserDocument extends VexDocument {
@@ -290,5 +290,6 @@ declare module "@vexcms/core" {
       user: "user"
       organization: "organization"
     }
+    DataModel: DataModel
   }
 }

package/templates/marketing-site/convex/theme.ts

@@ -6,6 +6,8 @@ import config from "~/vex.config.server"
 import type { Doc, Id } from "./_generated/dataModel"
 import type { QueryCtx } from "./_generated/server"
 
+import { v } from "convex/values"
+
 import { query } from "./_generated/server"
 
 /** A theme document, or `null` when none is selected. */
@@ -67,3 +69,19 @@ export const getAdmin = query({
     (await resolveTheme({ ctx, field: "adminTheme" })) ??
     (await resolveTheme({ ctx, field: "activeTheme" })),
 })
+
+/**
+ * One theme document by id, for the client to resolve a theme reference itself.
+ *
+ * Exists for live preview: `getActive`/`getAdmin` resolve
+ * `siteSettings -> theme` on the SERVER, so they answer from the saved global
+ * and cannot see an editor's unsaved `activeTheme`. `<ThemeLive />` therefore
+ * does the join on the client — overlaid settings, then this lookup.
+ *
+ * Access is bypassed for the same reason as `resolveTheme`: a palette is public.
+ */
+export const byId = query({
+  args: { id: v.string() },
+  handler: async (ctx, args): Promise<ActiveTheme> =>
+    await ctx.db.get(args.id as Id<typeof TABLE_SLUG_THEMES>),
+})

package/templates/marketing-site/src/app/(frontend)/(site)/layout.tsx

@@ -8,7 +8,6 @@ import { SiteFooter } from "~/components/SiteFooter"
 import { SiteHeader } from "~/components/SiteHeader"
 import { ThemeStyle } from "~/components/ThemeStyle"
 import { vex } from "~/lib/vex"
-import { SiteLivePreviewProvider } from "./SiteLivePreviewProvider"
 
 /**
  * Marketing chrome: header + footer around every site page. Auth routes live
@@ -32,7 +31,7 @@ export default async function SiteLayout({
   }
 
   return (
-    <SiteLivePreviewProvider>
+    <>
       <ThemeStyle />
       {/* Sits above the sticky header so it is the first tab stop on every
           page. Visually hidden until focused. */}
@@ -45,6 +44,6 @@ export default async function SiteLayout({
       <SiteHeader initialData={headerData} />
       <main id="main">{children}</main>
       <SiteFooter initialData={footerData} />
-    </SiteLivePreviewProvider>
+    </>
   )
 }

package/templates/marketing-site/src/app/(vexcms)/admin/layout.tsx

@@ -7,8 +7,6 @@ import { getCurrentUser } from "~/auth/serverUtils";
 import { ThemeLive } from "~/components/ThemeLive";
 import { ThemeStyle } from "~/components/ThemeStyle";
 
-import { ClientProviders } from "./clientProviders";
-
 /**
  * Overlays `base-nextjs`'s admin layout to wire the theme system in: base
  * ships no theme, so its admin layout has nothing to render here. `<ThemeStyle
@@ -21,12 +19,12 @@ import { ClientProviders } from "./clientProviders";
 export default async function AdminLayout({ children }: { children: ReactNode }) {
   const user = await getCurrentUser();
   return (
+    // `VexConfigProvider` is no longer mounted here — the root layout's
+    // `ClientProviders` mounts it once for the whole app.
     <AuthServerProvider>
-      <ClientProviders>
-        <ThemeStyle scope="admin" />
-        <ThemeLive scope="admin" />
-        <NextAdminLayout user={user ?? undefined}>{children}</NextAdminLayout>
-      </ClientProviders>
+      <ThemeStyle scope="admin" />
+      <ThemeLive scope="admin" />
+      <NextAdminLayout user={user ?? undefined}>{children}</NextAdminLayout>
     </AuthServerProvider>
   );
 }

package/templates/marketing-site/src/app/layout.tsx

@@ -2,7 +2,7 @@ import type { Metadata } from "next"
 
 import "./globals.css"
 
-import { ThemeScript } from "@vexcms/react"
+import { LivePreviewProvider, ThemeScript } from "@vexcms/react"
 import { Geist, Geist_Mono } from "next/font/google"
 
 import ClientProviders from "~/components/providers/client"
@@ -75,8 +75,17 @@ export default function RootLayout({
       <body>
         <ServerProviders>
           <ClientProviders>
-            <ThemeLive />
-            {children}
+            {/* Wraps the whole app, not just `(site)`: `<ThemeLive />` lives
+                here (it skins every route, auth pages included) and the overlay
+                only reaches consumers inside the provider. Rendered directly —
+                it takes nothing but `children`, reading collections, globals,
+                and allowed origins from `VexConfigContext` — and gates itself
+                on `?vexLivePreview=1` plus the session-verified cookie, so
+                every public route stays prerenderable. */}
+            <LivePreviewProvider>
+              <ThemeLive />
+              {children}
+            </LivePreviewProvider>
           </ClientProviders>
         </ServerProviders>
       </body>

package/templates/marketing-site/src/components/SiteFooter.tsx

@@ -2,8 +2,7 @@
 
 import { convexQuery } from "@convex-dev/react-query"
 import { api } from "@convex/_generated/api"
-import { useQuery } from "@tanstack/react-query"
-import { type RenderableBlock, RenderBlocks } from "@vexcms/react"
+import { type RenderableBlock, RenderBlocks, useLivePreviewDocumentQuery } from "@vexcms/react"
 
 import type { FootersDocument } from "~/vex.types"
 
@@ -16,10 +15,15 @@ export function SiteFooter({
 }: {
   initialData?: FootersDocument | null
 }) {
-  const { data: footer } = useQuery({
-    ...convexQuery(api.footers.getFirst, {}),
-    initialData: initialData ?? undefined,
-  })
+  // See `SiteHeader`: the overlay only reaches documents a consumer hands it,
+  // so editing the footer while previewing a page needs this wrapper.
+  const { data: footer } = useLivePreviewDocumentQuery(
+    {
+      ...convexQuery(api.footers.getFirst, {}),
+      initialData: initialData ?? undefined,
+    },
+    "footers",
+  )
 
   const content = footer?.content as null | PageBlockLike[] | undefined
   if (!content) {return null}

package/templates/marketing-site/src/components/SiteHeader.tsx

@@ -2,8 +2,7 @@
 
 import { convexQuery } from "@convex-dev/react-query"
 import { api } from "@convex/_generated/api"
-import { useQuery } from "@tanstack/react-query"
-import { type RenderableBlock, RenderBlocks } from "@vexcms/react"
+import { type RenderableBlock, RenderBlocks, useLivePreviewDocumentQuery } from "@vexcms/react"
 
 import type { HeadersDocument } from "~/vex.types"
 
@@ -16,10 +15,16 @@ export function SiteHeader({
 }: {
   initialData?: HeadersDocument | null
 }) {
-  const { data: header } = useQuery({
-    ...convexQuery(api.headers.getFirst, {}),
-    initialData: initialData ?? undefined,
-  })
+  // `useLivePreviewDocumentQuery`, not a bare `useQuery`: the live-preview
+  // overlay only reaches documents a consumer hands it, so a plain query here
+  // means editing the header while previewing a page changes nothing.
+  const { data: header } = useLivePreviewDocumentQuery(
+    {
+      ...convexQuery(api.headers.getFirst, {}),
+      initialData: initialData ?? undefined,
+    },
+    "headers",
+  )
 
   const content = header?.content as null | PageBlockLike[] | undefined
   if (!content) {return null}

package/templates/marketing-site/src/components/ThemeLive.tsx

@@ -1,30 +1,41 @@
 "use client"
 
+import { convexQuery } from "@convex-dev/react-query"
 import { api } from "@convex/_generated/api"
+import { useQuery } from "@tanstack/react-query"
 import { buildThemeCss, type ThemeScope } from "@vexcms/core"
-import { useQuery } from "convex/react"
-import { useEffect } from "react"
+import { useLivePreviewDocumentQuery } from "@vexcms/react"
+import { useEffect, useRef } from "react"
+
+import type { SiteSettingsGlobal, Theme } from "~/vex.types"
+
+import { GLOBAL_SLUG_SITE_SETTINGS } from "~/db/constants"
 
 /**
  * Client companion to the server `<ThemeStyle />`: keeps the applied theme
  * live without a page reload.
  *
- * `useQuery` is a Convex subscription — the deployment pushes every change to
- * the active theme document (or to which theme is active), so saving in the
- * admin re-skins every open tab immediately. No polling, no preview channel,
- * no drafts machinery.
+ * Resolves `siteSettings -> theme` on the CLIENT, in two steps, rather than
+ * subscribing to `api.theme.getActive`. That query does the join on the server,
+ * so it answers from the saved global and is structurally blind to an editor's
+ * unsaved `activeTheme` — switching themes in live preview changed nothing
+ * until save. Reading the global through `useLivePreviewDocumentQuery` lets the
+ * overlay reach it, then `api.theme.byId` resolves whichever theme it now
+ * names. Outside preview the overlay is absent and this behaves exactly as the
+ * server join did, still as a live Convex subscription.
  *
- * The CSS goes into an effect-managed `<style>` tag appended to `<head>`
- * rather than a React-hoisted one: hoisted styles are deduplicated by `href`
- * and are not guaranteed to update in place when their text changes, and an
- * appended tag deterministically follows the server-rendered block — equal
- * specificity, later in the document, so it wins the moment it exists. The
- * first push matches the server CSS byte-for-byte, so nothing visibly changes
- * until a real edit lands.
+ * The CSS goes into an effect-managed `<style>` appended to the end of
+ * `<body>` rather than a React-hoisted one: hoisted styles are deduplicated by
+ * `href` and are not guaranteed to update in place when their text changes.
+ * The end of `<body>` is the one position that follows *both* server blocks —
+ * the hoisted site block in `<head>` and the admin layout's in-tree block — so
+ * at equal specificity this one wins the moment it exists. The first push
+ * matches the server CSS byte-for-byte, so nothing visibly changes until a
+ * real edit lands.
  *
- * Distinguishes loading from empty: while the query is unresolved
- * (`undefined`) the server CSS stands; once it resolves to `null` (no active
- * theme) the override is cleared and `globals.css` shows through.
+ * Distinguishes loading from empty: while either query is unresolved the server
+ * CSS stands; once the reference resolves to nothing the override is cleared
+ * and `globals.css` shows through.
  *
  * @param props - Input props.
  * @param props.scope - Same contract as `<ThemeStyle />`: `"site"` emits
@@ -33,26 +44,58 @@ import { useEffect } from "react"
  */
 export function ThemeLive(props: { scope?: ThemeScope }) {
   const scope = props.scope ?? "site"
-  const theme = useQuery(scope === "admin" ? api.theme.getAdmin : api.theme.getActive)
 
+  const { data: settings } = useLivePreviewDocumentQuery<typeof GLOBAL_SLUG_SITE_SETTINGS>(
+    convexQuery(api.siteSettings.get, {}) as never,
+    GLOBAL_SLUG_SITE_SETTINGS,
+  )
+
+  // `adminTheme ?? activeTheme` mirrors `theme.getAdmin`'s own fallback: the
+  // admin adopts the site's palette unless it opts out.
+  const reference = settings as SiteSettingsGlobal | undefined
+  const themeIds = (
+    scope === "admin" ? (reference?.adminTheme ?? reference?.activeTheme) : reference?.activeTheme
+  ) as string[] | undefined
+  const themeId = themeIds?.[0]
+
+  const { data: theme } = useQuery({
+    ...convexQuery(api.theme.byId, themeId ? { id: themeId } : "skip"),
+    enabled: Boolean(themeId),
+  })
+
+  // Owning the element in its own mount-scoped effect is load-bearing. Creating
+  // it inside the effect that writes the CSS meant every dependency change ran
+  // that effect's cleanup first — removing the element and exposing the server
+  // CSS underneath. Selecting a theme the page had not fetched yet left it
+  // removed for the length of the round trip, which is the flash back to the
+  // saved theme between edits; an already-cached theme resolved in the same
+  // tick, which is why it only happened the first time.
+  const styleElementRef = useRef<HTMLStyleElement | null>(null)
   useEffect(() => {
-    if (theme === undefined) {return} // still loading — leave the server CSS alone
-
-    const id = `vex-theme-live-${scope}`
-    let el = document.getElementById(id) as HTMLStyleElement | null
-    if (!el) {
-      el = document.createElement("style")
-      el.id = id
-      document.head.appendChild(el)
-    }
-    el.textContent = theme ? buildThemeCss({ theme, scope }) : ""
+    const element = document.createElement("style")
+    element.id = `vex-theme-live-${scope}`
+    document.body.appendChild(element)
+    styleElementRef.current = element
 
     return () => {
       // Admin routes unmount their scope on navigation back to the site; the
       // override must not outlive the layout that owns it.
-      el?.remove()
+      element.remove()
+      styleElementRef.current = null
     }
-  }, [theme, scope])
+  }, [scope])
+
+  useEffect(() => {
+    const element = styleElementRef.current
+    if (!element) {return}
+
+    // Still resolving — hold whatever is already applied. Before first paint
+    // that is the server CSS; mid-preview it is the last previewed theme.
+    if (settings === undefined) {return}
+    if (themeId && theme === undefined) {return}
+
+    element.textContent = theme ? buildThemeCss({ theme: theme as Theme, scope }) : ""
+  }, [settings, theme, themeId, scope])
 
   return null
 }

package/templates/marketing-site/src/components/ThemeStyle.tsx

@@ -14,8 +14,10 @@ import { vex } from "~/lib/vex"
  * `:root:root` is specificity (0,2,0) against `:root`'s (0,1,0), so the admin
  * block wins wherever both are present without depending on style-injection
  * order. On public routes the admin layout never renders, so there is exactly
- * one block. Leave `siteSettings.adminTheme` empty and `getAdmin` falls back to
- * the site theme, which is the default: **the admin adopts the site's palette.**
+ * one block — and the admin block is deliberately *not* hoisted, so React tears
+ * it down with the admin layout instead of leaving it in `<head>` (see below).
+ * Leave `siteSettings.adminTheme` empty and `getAdmin` falls back to the site
+ * theme, which is the default: **the admin adopts the site's palette.**
  *
  * Values are written through verbatim. A `color()` field storing
  * `oklch(60.5% 0.175 42)` needs no conversion, because that is already the
@@ -48,12 +50,25 @@ export async function ThemeStyle(props: { scope?: ThemeScope }) {
   const css = buildThemeCss({ theme, scope })
   if (!css) {return null}
 
-  // `precedence` opts into React 19 style hoisting, so this lands in <head>
-  // before first paint instead of mid-body.
+  // Only the **site** block opts into React 19 style hoisting. A hoisted
+  // `<style>` (`href` + `precedence`) is a stylesheet *resource*: react-dom
+  // keeps it in `<head>` for the life of the document and merely decrements a
+  // refcount when the component that rendered it unmounts
+  // (`commitDeletionEffectsOnFiber`, fiber tag 26). That is correct for the
+  // site theme, which is document-wide — and wrong for the admin theme: the
+  // hoisted `:root:root` block outlived a client-side nav out of `/admin` and
+  // re-skinned the public site until a full reload. Rendering the admin block
+  // in place ties its lifetime to the admin layout, at the cost of nothing:
+  // it still streams ahead of any admin markup, and `:root:root` outranks the
+  // site block wherever both apply, whatever the document order.
+  if (scope === "admin") {
+    return <style dangerouslySetInnerHTML={{ __html: css }} data-vex-theme="admin" />
+  }
+
   return (
     <style
       dangerouslySetInnerHTML={{ __html: css }}
-      href={`vex-theme-${scope}`}
+      href="vex-theme-site"
       precedence="high"
     />
   )

package/templates/marketing-site/src/vex.config.ts

@@ -26,6 +26,12 @@ const vexConfig = defineConfig({
     sidebar: {
       side: "right",
     },
+    livePreview: {
+      allowedOrigins: [
+        "http://localhost:3000",
+        ...(process.env.NEXT_PUBLIC_SITE_URL ? [process.env.NEXT_PUBLIC_SITE_URL] : []),
+      ],
+    },
   },
   storage: {
     clientUploads: { convex: uploadFile },
@@ -42,12 +48,6 @@ const vexConfig = defineConfig({
       return path === undefined ? [] : [path]
     },
   },
-  livePreview: {
-    allowedOrigins: [
-      "http://localhost:3000",
-      ...(process.env.NEXT_PUBLIC_SITE_URL ? [process.env.NEXT_PUBLIC_SITE_URL] : []),
-    ],
-  },
 })
 
 export default vexConfig

package/templates/marketing-site/src/vex.types.ts

@@ -7,7 +7,7 @@
 /* eslint-disable perfectionist/sort-object-types */
 /* eslint-disable @typescript-eslint/no-empty-object-type */
 
-import type { Id } from "@convex/_generated/dataModel"
+import type { DataModel, Id } from "@convex/_generated/dataModel"
 import type { VexDocument, VexDocumentGlobal } from "@vexcms/core"
 
 export interface UserDocument extends VexDocument {
@@ -656,5 +656,6 @@ declare module "@vexcms/core" {
       user: "user"
       organization: never
     }
+    DataModel: DataModel
   }
 }

package/templates/marketing-site/src/vexcms/blocks/Roadmap/config.ts

@@ -90,25 +90,25 @@ export const roadmapBlock = defineBlock({
         {
           feature: "Versioning & Drafts",
           description: "Draft/publish workflow with autosave and version history — in active development.",
-          status: "coming-soon",
+          status: "planned",
         },
         {
           feature: "Live Preview",
           description:
             "Side-by-side preview of draft content against the real frontend before publishing — builds on the drafts infrastructure.",
-          status: "coming-soon",
+          status: "planned",
         },
         {
           feature: "Form Builder & Lifecycle Hooks",
           description:
             "Composable form fields beyond content editing, plus beforeChange/afterChange hooks for custom side effects.",
-          status: "coming-soon",
+          status: "planned",
         },
         {
           feature: "Field Input Consistency Pass",
           description:
             "Touch-ups across field inputs — starting with the relationship field — for consistent interaction patterns in the admin panel.",
-          status: "coming-soon",
+          status: "planned",
         },
         {
           feature: "Richtext, JSON, Email & Textarea Fields",

package/templates/marketing-site/src/vexcms/collections/headers.ts

@@ -8,6 +8,9 @@ export const headers = defineCollection({
   admin: {
     useAsTitle: "name",
     icon: "PanelTop",
+    livePreview: {
+      url: "/",
+    },
   },
   fields: {
     name: text({

package/templates/marketing-site/src/vexcms/collections/pages.ts

@@ -1,6 +1,7 @@
-import type { DataModel } from "@convex/_generated/dataModel"
 
-import { blocks, defineCollection, text, textValidator, upload } from "@vexcms/core"
+import { ConvexError } from "convex/values"
+
+import { blocks, defineCollection, text, upload } from "@vexcms/core"
 
 import { resolvePagePath } from "~/lib/resolvePagePath"
 import { TABLE_SLUG_IMAGES, TABLE_SLUG_PAGES } from "~/db/constants"
@@ -21,23 +22,28 @@ export const pages = defineCollection({
       label: "Title",
       required: true,
     }),
-    slug: text({
+    // One type argument — the collection's own slug — types `doc`, `value` and
+    // `ctx` (the project's `DataModel` arrives through the generated
+    // `@vexcms/core` augmentation).
+    slug: text<typeof TABLE_SLUG_PAGES>({
       description: "URL-friendly page path",
       index: "by_slug",
       label: "Slug",
       required: true,
-      validate: textValidator<typeof TABLE_SLUG_PAGES, DataModel>(
-        TABLE_SLUG_PAGES,
-        async ({ value, doc, ctx }) => {
-          const existing = await ctx.db
-            .query("pages")
-            .withIndex("by_slug", (q) => q.eq("slug", value))
-            .first()
-          if (existing && existing._id !== doc._id) {
-            return `This slug is already in use by the page '${existing.title}'.`
-          }
-        },
-      ),
+      validate: async ({ value, doc, ctx }) => {
+        const existing = await ctx.db
+          .query("pages")
+          .withIndex("by_slug", (q) => q.eq("slug", value))
+          .first()
+        if (existing && existing._id !== doc._id) {
+          // Rejection is a throw, so the payload can carry more than a message.
+          throw new ConvexError({
+            code: "SLUG_CONFLICT",
+            conflictingPageId: existing._id,
+            message: `This slug is already in use by the page '${existing.title}'.`,
+          })
+        }
+      },
     }),
     blocks: blocks({
       admin: {

package/templates/base-nextjs/src/app/(vexcms)/admin/clientProviders.tsx

@@ -1,17 +0,0 @@
-"use client"
-
-import { VexConfigProvider } from "@vexcms/react"
-
-import config from "~/vex.config"
-
-/**
- * Mounts the single `VexConfigProvider` for the admin panel's client tree.
- *
- * This is a "use client" component so `vex.config` is imported and owned on
- * the client — it never crosses the RSC boundary as a prop. `access` and
- * `storage.clientUploads` (the two fields that used to need their own
- * providers) are already part of the config this imports.
- */
-export function ClientProviders({ children }: { children: React.ReactNode }) {
-  return <VexConfigProvider config={config}>{children}</VexConfigProvider>
-}

package/templates/marketing-site/src/app/(frontend)/(site)/SiteLivePreviewProvider.tsx

@@ -1,31 +0,0 @@
-"use client"
-
-import type { ReactNode } from "react"
-
-import { LivePreviewProvider } from "@vexcms/react"
-
-import config from "~/vex.config"
-
-/**
- * Mounts the live-preview listener for the public site's client tree.
- *
- * A `"use client"` component so `vex.config` is imported and owned on the
- * client — it never crosses the RSC boundary as a prop (ADR-013; the config's
- * `admin.livePreview.url` resolvers and field validators are functions, which
- * React refuses to serialize). Mirrors `admin/clientProviders.tsx`.
- *
- * `LivePreviewProvider` gates itself on `?vexLivePreview=1` plus the
- * session-verified `vex-live-preview` cookie `proxy.ts` sets, so wrapping the
- * layout unconditionally costs a disabled provider and nothing else — and
- * keeps every public route statically prerenderable.
- */
-export function SiteLivePreviewProvider({ children }: { children: ReactNode }) {
-  return (
-    <LivePreviewProvider
-      allowedOrigins={config.livePreview.allowedOrigins}
-      collections={config.collections}
-    >
-      {children}
-    </LivePreviewProvider>
-  )
-}