create-vexcms 0.0.8 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-vexcms",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "type": "module",
   "bin": {
     "create-vexcms": "./dist/index.js"

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

@@ -0,0 +1,82 @@
+import type { DataModel } from "@convex/_generated/dataModel"
+import type { TableNamesInDataModel } from "convex/server"
+
+import { query } from "@convex/_generated/server"
+import { getPreviewSnapshot } from "@vexcms/core"
+import { v } from "convex/values"
+
+import config from "../../vex.config"
+import * as Versions from "./model/versions"
+
+/**
+ * Get the single document for a global, with draft awareness.
+ *
+ * - No _vexDrafts or _vexDrafts: false → returns the published document
+ * - _vexDrafts: true → returns the latest version (draft or published)
+ * - _vexDrafts: "snapshot" → overlays the preview snapshot on the document
+ */
+export const get = query({
+  args: {
+    globalSlug: v.string(),
+    _vexDrafts: v.optional(v.union(v.literal("snapshot"), v.boolean())),
+  },
+  handler: async (ctx, { globalSlug, _vexDrafts }) => {
+    const doc = await ctx.db
+      .query(globalSlug as TableNamesInDataModel<DataModel>)
+      .first()
+
+    if (!doc) return null
+
+    const documentId = doc._id as string
+
+    // Check if this global has versioning enabled
+    const globalDef = config.globals?.find((g) => g.slug === globalSlug)
+    const isVersioned = !!globalDef?.versions?.drafts
+
+    // If draft mode is "snapshot", overlay the preview snapshot
+    if (_vexDrafts === "snapshot") {
+      const snapshot = await getPreviewSnapshot<DataModel>({
+        ctx,
+        collection: globalSlug,
+        documentId,
+      })
+
+      if (snapshot) {
+        return {
+          ...doc,
+          ...(snapshot as Record<string, unknown>),
+          _id: doc._id,
+          _creationTime: doc._creationTime,
+        }
+      }
+    }
+
+    // If versioned and draft-aware, return the latest version's snapshot
+    if (isVersioned && _vexDrafts !== false) {
+      const latestVersion = await Versions.getLatestVersion<DataModel>({
+        ctx,
+        collection: globalSlug,
+        documentId,
+      })
+
+      if (latestVersion) {
+        return {
+          _id: doc._id,
+          ...(latestVersion.snapshot as Record<string, unknown>),
+          vex_status: (latestVersion as any).status ?? (doc as any).vex_status ?? "draft",
+          vex_version: latestVersion.version,
+          vex_publishedAt: (doc as any).vex_publishedAt,
+          _creationTime: doc._creationTime,
+        }
+      }
+
+      // No versions yet — treat as published
+      const raw = doc as Record<string, unknown>
+      if (!raw.vex_status) {
+        raw.vex_status = "published"
+      }
+    }
+
+    return doc
+  },
+})

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

@@ -16,8 +16,8 @@ import { access } from "../../src/vexcms/access"
 import * as Versions from "./model/versions"
 
 function requireVersionedCollection(slug: string) {
-  const collections = [...config.collections, ...(config.media?.collections ?? [])]
-  const match = collections.find((c) => c.slug === slug)
+  const collections = [...config.collections, ...(config.media?.collections ?? []), ...(config.globals ?? [])]
+  const match = collections.find((c: any) => c.slug === slug)
   if (!match) {
     throw new ConvexError(`Collection not found: ${slug}`)
   }
@@ -503,11 +503,19 @@ export const getDocumentForEdit = query({
     documentId: v.string(),
   },
   handler: async (ctx, { collectionSlug, documentId }) => {
-    requireVersionedCollection(collectionSlug)
-
     const mainDoc = await ctx.db.get(documentId as any)
     if (!mainDoc) return null
 
+    // Check if this collection/global actually has versioning enabled in config.
+    // If not (e.g. config not yet redeployed), just return the raw document.
+    const collections = [...config.collections, ...(config.media?.collections ?? []), ...(config.globals ?? [])]
+    const match = collections.find((c: any) => c.slug === collectionSlug)
+    if (!match?.versions?.drafts) {
+      const doc = mainDoc as Record<string, unknown>
+      if (!doc.vex_status) doc.vex_status = "published"
+      return doc
+    }
+
     const latestVersion = await Versions.getLatestVersion<DataModel>({
       ctx,
       collection: collectionSlug,
@@ -518,8 +526,6 @@ export const getDocumentForEdit = query({
       return {
         _id: mainDoc._id,
         ...(latestVersion.snapshot as Record<string, unknown>),
-        // Use the latest version's status, not the main doc's — the main doc
-        // only updates on publish, but the latest version may be a draft
         vex_status: (latestVersion as any).status ?? (mainDoc as any).vex_status ?? "draft",
         vex_version: latestVersion.version,
         vex_publishedAt: (mainDoc as any).vex_publishedAt,
@@ -537,6 +543,60 @@ export const getDocumentForEdit = query({
   },
 })
 
+/**
+ * Creates an initial version entry for a document that has none.
+ * Called by the admin edit view when it detects a versioned document
+ * without any version records (e.g., versioning was just enabled on
+ * an existing collection).
+ *
+ * Preserves the document's current status — if vex_status is "published",
+ * the version is created as published. Otherwise defaults to "draft".
+ *
+ * No-ops if the document already has version entries.
+ */
+export const initializeVersion = mutation({
+  args: {
+    collectionSlug: v.string(),
+    documentId: v.string(),
+  },
+  handler: async (ctx, { collectionSlug, documentId }) => {
+    const mainDoc = await ctx.db.get(documentId as any)
+    if (!mainDoc) return null
+
+    // Check if versions already exist
+    const existing = await Versions.getLatestVersion<DataModel>({
+      ctx,
+      collection: collectionSlug,
+      documentId,
+    })
+    if (existing) return existing
+
+    // Build snapshot from the main document's current fields
+    const { _id, _creationTime, ...snapshot } = mainDoc as Record<string, unknown>
+
+    // Determine status from the document's current state
+    const status = (snapshot.vex_status as string) === "published" ? "published" : "draft"
+
+    // Ensure the main doc has vex_status set
+    if (!snapshot.vex_status) {
+      await ctx.db.patch(documentId as any, { vex_status: "published" } as any)
+      snapshot.vex_status = "published"
+    }
+
+    // Create the initial version
+    const versionId = await Versions.createVersion<DataModel>({
+      ctx,
+      collection: collectionSlug,
+      documentId,
+      snapshot,
+      status: status as "draft" | "published",
+      createdBy: null,
+    })
+
+    return versionId
+  },
+})
+
 /**
  * Backfills vex_status on existing documents in a versioned collection
  * that don't have the field yet (e.g. versioning was just enabled on

package/templates/base-nextjs/package.json

@@ -22,12 +22,12 @@
     "@t3-oss/env-nextjs": "^0.13.10",
     "@tanstack/react-form": "^1.27.7",
     "@tanstack/react-query": "^5.90.17",
-    "@vexcms/admin-next": "~0.0.8",
-    "@vexcms/better-auth": "~0.0.8",
-    "@vexcms/core": "~0.0.8",
-    "@vexcms/richtext": "~0.0.8",
-    "@vexcms/ui": "~0.0.8",
-    "@vexcms/file-storage-convex": "~0.0.8",
+    "@vexcms/admin-next": "~0.0.9",
+    "@vexcms/better-auth": "~0.0.9",
+    "@vexcms/core": "~0.0.9",
+    "@vexcms/richtext": "~0.0.9",
+    "@vexcms/ui": "~0.0.9",
+    "@vexcms/file-storage-convex": "~0.0.9",
     "better-auth": ">=1.4.9 <1.5.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -52,7 +52,7 @@
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@vexcms/cli": "~0.0.8",
+    "@vexcms/cli": "~0.0.9",
     "babel-plugin-react-compiler": "^1.0.0",
     "eslint": "^9",
     "eslint-config-next": "15.5.9",

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

@@ -1,8 +1,10 @@
 import { SidebarTrigger } from "@vexcms/ui"
-import { sanitizeConfigForClient } from "@vexcms/core"
+import { checkAdminAccess, sanitizeConfigForClient } from "@vexcms/core"
+import { redirect } from "next/navigation"
 
 import config from "~/../vex.config"
 import { getCurrentUser } from "~/auth/serverUtils"
+import { access } from "~/vexcms/access"
 import { AdminLayoutWrapper } from "./AdminLayoutWrapper"
 
 const clientConfig = sanitizeConfigForClient(config)
@@ -10,20 +12,36 @@ const clientConfig = sanitizeConfigForClient(config)
 export default async function AdminLayout({ children }: { children: React.ReactNode }) {
   const user = await getCurrentUser()
 
-  const permissionUser = user
-    ? {
-        id: user.id,
-        roles: Array.isArray(user.role) ? user.role : [user.role].filter(Boolean),
-        name: user.name,
-        email: user.email,
-        avatar: user.image,
-      }
-    : undefined
+  // No user — redirect to sign in
+  if (!user) {
+    redirect("/auth/sign-in")
+  }
+
+  const userRoles = Array.isArray(user.role) ? user.role : [user.role].filter(Boolean)
+
+  // Check admin panel access
+  const hasAccess = checkAdminAccess({
+    access,
+    user: user as Record<string, any>,
+    userRoles,
+  })
+
+  if (!hasAccess) {
+    redirect("/?error=unauthorized")
+  }
+
+  const permissionUser = {
+    id: user.id,
+    roles: userRoles,
+    name: user.name,
+    email: user.email,
+    avatar: user.image,
+  }
 
   return (
     <AdminLayoutWrapper
       config={clientConfig}
-      user={user ? { name: user.name, avatar: user.image, email: user.email } : undefined}
+      user={{ name: user.name, avatar: user.image, email: user.email }}
       permissionUser={permissionUser}
     >
       <SidebarTrigger />

package/templates/base-nextjs/src/db/constants/auth.ts

@@ -1,8 +1,6 @@
 export const USER_ROLES = {
   admin: "admin",
-  user: "user",
   editor: "editor",
-  member: "member",
-  author: "author",
+  user: "user",
 } as const
 export type UserRole = (typeof USER_ROLES)[keyof typeof USER_ROLES]

package/templates/base-nextjs/src/vexcms/access.ts

@@ -1,28 +1,44 @@
 import { defineAccess } from "@vexcms/core"
 
-import { TABLE_SLUG_USERS, USER_ROLES } from "~/db/constants"
-import { users } from "~/vexcms/collections"
+import { USER_ROLES } from "~/db/constants"
+import { users } from "~/vexcms/collections/users"
 
+/**
+ * Access control configuration for the admin panel.
+ *
+ * - `admin` on each role controls whether that role can access the admin panel.
+ * - Resource permissions control CRUD access per collection.
+ * - Add your own collections to `resources` for autocomplete in `permissions`.
+ *
+ * @see https://vexcms.dev/docs/access-control
+ */
 export const access = defineAccess({
+  roles: [USER_ROLES.admin, USER_ROLES.editor, USER_ROLES.user],
+  adminRoles: [USER_ROLES.admin],
+  resources: [users],
+  userCollection: users,
   permissions: {
     admin: {
-      // Admins have full access to all resources
+      admin: true,
       user: true,
     },
+    editor: {
+      admin: true,
+      user: {
+        create: false,
+        delete: false,
+        read: true,
+        update: false,
+      },
+    },
     user: {
-      [TABLE_SLUG_USERS]: {
+      admin: false,
+      user: {
         create: false,
         delete: false,
-        read: ({ data: targetUser, user }) => {
-          return targetUser._id === user._id
-        },
-        update: ({ data: targetUser, user }) => {
-          return targetUser._id === user._id
-        },
+        read: ({ data, user }) => data._id === user._id,
+        update: ({ data, user }) => data._id === user._id,
       },
     },
   },
-  resources: [users],
-  roles: [USER_ROLES.user, USER_ROLES.admin],
-  userCollection: users,
 })

package/templates/base-nextjs/src/vexcms/collections/users.ts

@@ -27,9 +27,9 @@ export const users = defineCollection({
         singular: "Role",
       },
       options: [
-        { badgeColor: "#ff0000", label: "Admin", value: "admin" },
+        { label: "Admin", value: "admin" },
         { label: "Editor", value: "editor" },
-        { badgeColor: "#333333", label: "User", value: "user" },
+        { label: "User", value: "user" },
       ],
       required: true,
     }),

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

@@ -2,8 +2,10 @@ import { defineConfig } from "@vexcms/core"
 import { convexFileStorage } from "@vexcms/file-storage-convex"
 
 import { auth } from "~/vexcms/auth"
+import { access } from "~/vexcms/access"
 
 export default defineConfig({
+  access,
   admin: {
     meta: {
       titleSuffix: " | Admin",

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

@@ -0,0 +1,14 @@
+import { query } from "./_generated/server"
+
+/**
+ * Get the first published footer.
+ * Used by the public site layout for server-side preloading.
+ */
+export const getFirst = query({
+  args: {},
+  handler: async (ctx) => {
+    const footer = await ctx.db.query("footers").first()
+    if (!footer || footer.vex_status === "draft") return null
+    return footer
+  },
+})

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

@@ -0,0 +1,14 @@
+import { query } from "./_generated/server"
+
+/**
+ * Get the first published header.
+ * Used by the public site layout for server-side preloading.
+ */
+export const getFirst = query({
+  args: {},
+  handler: async (ctx) => {
+    const header = await ctx.db.query("headers").first()
+    if (!header || header.vex_status === "draft") return null
+    return header
+  },
+})

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

@@ -0,0 +1,14 @@
+import { query } from "./_generated/server"
+
+/**
+ * Get the published site settings.
+ * Used by server components for SEO metadata generation.
+ */
+export const get = query({
+  args: {},
+  handler: async (ctx) => {
+    const settings = await ctx.db.query("site_settings").first()
+    if (!settings) return null
+    return settings
+  },
+})

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

@@ -0,0 +1,75 @@
+import { getPreviewSnapshot } from "@vexcms/core"
+
+import { query } from "./_generated/server"
+import * as Versions from "./vex/model/versions"
+
+/**
+ * Get the active theme from site settings (published).
+ * Returns the full theme document or null if no active theme is set.
+ * Used for server-side CSS variable injection on public pages.
+ */
+export const getActive = query({
+  args: {},
+  handler: async (ctx) => {
+    const settings = await ctx.db.query("site_settings").first()
+    if (!settings?.activeTheme) return null
+
+    const theme = await ctx.db.get(settings.activeTheme)
+    if (!theme) return null
+
+    // Only return published themes
+    if (theme.vex_status === "draft") return null
+
+    return theme
+  },
+})
+
+/**
+ * Get the active theme for preview/draft mode.
+ * Reads site settings with preview snapshot overlay to get the draft activeTheme,
+ * then fetches the latest version of that theme (draft or published).
+ * Used for server-side CSS variable injection on preview pages.
+ */
+export const getActivePreview = query({
+  args: {},
+  handler: async (ctx) => {
+    // Get site settings, overlaying any preview snapshot
+    const settings = await ctx.db.query("site_settings").first()
+    if (!settings) return null
+
+    const settingsId = settings._id as string
+
+    // Check for a preview snapshot on site_settings
+    const snapshot = await getPreviewSnapshot({
+      ctx,
+      collection: "site_settings",
+      documentId: settingsId,
+    })
+
+    const merged = snapshot
+      ? { ...settings, ...(snapshot as Record<string, unknown>) }
+      : settings
+
+    const activeThemeId = (merged as any).activeTheme as string | undefined
+    if (!activeThemeId) return null
+
+    // Get the theme — prefer the latest draft version
+    const theme = await ctx.db.get(activeThemeId as any)
+    if (!theme) return null
+
+    const latestVersion = await Versions.getLatestVersion({
+      ctx,
+      collection: "themes",
+      documentId: activeThemeId,
+    })
+
+    if (latestVersion?.snapshot) {
+      return {
+        ...theme,
+        ...(latestVersion.snapshot as Record<string, unknown>),
+      }
+    }
+
+    return theme
+  },
+})

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

@@ -0,0 +1,74 @@
+"use client"
+
+import { RenderBlocks } from "@vexcms/ui"
+import { convexQuery } from "@convex-dev/react-query"
+import { useQuery } from "@tanstack/react-query"
+import Link from "next/link"
+import { anyApi } from "convex/server"
+
+import { blockComponents } from "~/vexcms/blocks"
+
+/**
+ * Client component that renders a page using TanStack Query + convexQuery.
+ * When initialData is provided (from server fetchQuery), renders immediately.
+ * The reactive subscription keeps data up-to-date after hydration.
+ */
+export function PageContent({
+  slug,
+  initialData,
+}: {
+  slug?: string
+  initialData?: Record<string, unknown> | null
+}) {
+  const { data: page, isPending } = useQuery({
+    ...convexQuery(anyApi.pages.getBySlug, {
+      slug: slug ?? "home",
+      _vexDrafts: false,
+    }),
+    initialData: initialData ?? undefined,
+  })
+
+  if (isPending && initialData === undefined) {
+    return (
+      <div className="flex min-h-screen items-center justify-center">
+        <p className="text-muted-foreground">Loading...</p>
+      </div>
+    )
+  }
+
+  if (!page) {
+    if (!slug || slug === "home") {
+      return (
+        <div className="flex min-h-screen flex-col items-center justify-center gap-4 p-8">
+          <h1 className="text-4xl font-bold tracking-tight">Vex CMS</h1>
+          <p className="text-lg text-muted-foreground">
+            Create a page with slug &ldquo;home&rdquo; to get started.
+          </p>
+        </div>
+      )
+    }
+
+    return (
+      <div className="mx-auto max-w-3xl px-4 py-12">
+        <h1 className="text-2xl font-bold">Page not found</h1>
+        <p className="mt-2 text-muted-foreground">
+          The page &ldquo;{slug}&rdquo; doesn&apos;t exist or hasn&apos;t been
+          published yet.
+        </p>
+        <Link
+          className="mt-4 inline-block text-sm text-primary hover:underline"
+          href="/"
+        >
+          &larr; Back to home
+        </Link>
+      </div>
+    )
+  }
+
+  return (
+    <RenderBlocks
+      blocks={page.content as any}
+      components={blockComponents}
+    />
+  )
+}

package/templates/marketing-site/src/app/(frontend)/[slug]/page.tsx

@@ -1,58 +1,26 @@
-"use client"
-
-import type { RichTextDocument } from "@vexcms/core"
-
 import { api } from "@convex/_generated/api"
-import { RichText } from "@vexcms/richtext/render"
-import { useQuery } from "convex/react"
-import Link from "next/link"
-import { useParams } from "next/navigation"
-
-/**
- * Public page route — renders published pages by slug.
- * Passes _vexDrafts: false to only get published content.
- */
-export default function PublicPage() {
-  const { slug } = useParams<{ slug: string }>()
+import { fetchQuery } from "convex/nextjs"
 
-  const page = useQuery(api.pages.getBySlug, {
-    slug,
-    _vexDrafts: false,
-  })
+import { generatePageMetadata } from "~/lib/metadata"
+import { PageContent } from "../PageContent"
 
-  if (page === undefined) {
-    return (
-      <div className="mx-auto max-w-3xl px-4 py-12">
-        <p className="text-muted-foreground">Loading…</p>
-      </div>
-    )
-  }
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params
+  return generatePageMetadata({ slug })
+}
 
-  if (page === null) {
-    return (
-      <div className="mx-auto max-w-3xl px-4 py-12">
-        <h1 className="text-2xl font-bold">Page not found</h1>
-        <p className="mt-2 text-muted-foreground">
-          The page &ldquo;{slug}&rdquo; doesn&apos;t exist or hasn&apos;t been published yet.
-        </p>
-        <Link className="mt-4 inline-block text-sm text-primary hover:underline" href="/">
-          ← Back to home
-        </Link>
-      </div>
-    )
+export default async function PublicPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params
+
+  let initialData: null | Record<string, unknown> = null
+  try {
+    initialData = await fetchQuery(api.pages.getBySlug, {
+      slug,
+      _vexDrafts: false,
+    })
+  } catch {
+    // Fall back to client-only fetch
   }
 
-  return (
-    <div className="mx-auto max-w-3xl px-4 py-12">
-      <h1 className="text-3xl font-bold mb-6">{page.title ?? "Untitled"}</h1>
-
-      {page.content ? (
-        <div className="prose prose-lg max-w-none">
-          <RichText content={page.content as RichTextDocument} />
-        </div>
-      ) : (
-        <p className="text-muted-foreground">This page has no content yet.</p>
-      )}
-    </div>
-  )
+  return <PageContent initialData={initialData} slug={slug} />
 }