create-vexcms 0.0.3

package/templates/base-nextjs/eslint.config.mjs

@@ -0,0 +1,164 @@
+import convexPlugin from "@convex-dev/eslint-plugin"
+import { FlatCompat } from "@eslint/eslintrc"
+import importX from "eslint-plugin-import-x"
+import perfectionist from "eslint-plugin-perfectionist"
+import tseslint from "typescript-eslint"
+
+const compat = new FlatCompat({
+  baseDirectory: import.meta.dirname,
+})
+
+const convexConfig = convexPlugin.configs.recommended[0]
+const convexRules = convexConfig.rules
+
+export const defaultESLintIgnores = [
+  "**/.temp",
+  "**/.git",
+  "**/.hg",
+  "**/.pnp.*",
+  "**/.svn",
+  "**/.next",
+  "**/.open-next",
+  "**/.sst",
+  "**/playwright.config.ts",
+  "**/vitest.config.ts",
+  "**/tsconfig.tsbuildinfo",
+  "**/README.md",
+  "**/eslint.config.js",
+  "**/dist/",
+  "**/.yarn/",
+  "**/build/",
+  "**/node_modules/",
+  "**/temp/",
+  "**/registry/",
+  "**/public/",
+  "**/convex/_generated/",
+  "**/.source/",
+  "**/sst.config.ts",
+  "**/sst.workflow.ts",
+]
+
+export default tseslint.config(
+  {
+    ignores: defaultESLintIgnores,
+  },
+  ...compat.extends("next/core-web-vitals"),
+  perfectionist.configs["recommended-natural"],
+  {
+    extends: [
+      ...tseslint.configs.recommended,
+      ...tseslint.configs.recommendedTypeChecked,
+      ...tseslint.configs.stylisticTypeChecked,
+    ],
+    files: ["**/*.ts", "**/*.tsx"],
+    plugins: {
+      "import-x": importX,
+    },
+    rules: {
+      "@typescript-eslint/array-type": "off",
+      "@typescript-eslint/ban-tslint-comment": "off",
+      "@typescript-eslint/consistent-type-definitions": "off",
+      "@typescript-eslint/consistent-type-imports": [
+        "warn",
+        { fixStyle: "inline-type-imports", prefer: "type-imports" },
+      ],
+      "@typescript-eslint/no-misused-promises": [
+        "error",
+        { checksVoidReturn: { attributes: false } },
+      ],
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          argsIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^(_|ignore)",
+          destructuredArrayIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+        },
+      ],
+      "@typescript-eslint/require-await": "off",
+      "@typescript-eslint/unbound-method": "off",
+
+      curly: ["warn", "all"],
+      "import-x/no-duplicates": "warn",
+      "import-x/prefer-default-export": "off",
+      "no-console": "off",
+      // Allow default exports for Next.js
+      "no-restricted-exports": "off",
+      "no-underscore-dangle": "off",
+      "no-useless-escape": "warn",
+
+      "object-shorthand": "warn",
+
+      "perfectionist/sort-imports": "warn",
+      "perfectionist/sort-interfaces": "warn",
+      "perfectionist/sort-intersection-types": "warn",
+      // Perfectionist sorting configuration (from PayloadCMS)
+      "perfectionist/sort-jsx-props": "warn",
+      "perfectionist/sort-modules": "warn",
+      "perfectionist/sort-named-imports": "warn",
+      "perfectionist/sort-object-types": "warn",
+      "perfectionist/sort-objects": [
+        "warn",
+        {
+          customGroups: [
+            {
+              elementNamePattern: "^(_id|id|name|slug|type)$",
+              groupName: "top",
+            },
+          ],
+          groups: ["top", "unknown"],
+          order: "asc",
+          partitionByComment: true,
+          partitionByNewLine: true,
+          type: "natural",
+        },
+      ],
+      "perfectionist/sort-switch-case": "off",
+      "perfectionist/sort-union-types": "warn",
+    },
+  },
+  {
+    // Disable rules for test files and config files
+    files: ["src/test/**/*.js", "src/test/**/*.ts", "tests/**/*.ts", "*.config.js", "*.config.mjs"],
+    rules: {
+      "import/no-anonymous-default-export": "off",
+    },
+  },
+  {
+    // Disable object sorting in VEX collection/config files — field order determines
+    // the order of fields in admin panel forms
+    files: [
+      "**/vexcms/collections/**/*.ts",
+      "**/vexcms/access.*",
+      "**/vex.config.*",
+      "**/db/constants/**/*.ts",
+    ],
+    rules: {
+      "perfectionist/sort-objects": "off",
+    },
+  },
+  {
+    files: ["**/src/convex/**/*.ts"],
+    plugins: {
+      "@convex-dev": convexPlugin,
+    },
+    rules: convexRules,
+  },
+  {
+    languageOptions: {
+      parserOptions: {
+        ecmaVersion: "latest",
+        project: "./tsconfig.json",
+        sourceType: "module",
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    linterOptions: {
+      reportUnusedDisableDirectives: "error",
+    },
+    settings: {
+      // Workaround for ESLint flat config circular reference in diagnostics
+      _internalSilentUse: true,
+    },
+  }
+)

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

@@ -0,0 +1,10 @@
+import type { NextConfig } from "next"
+
+import "./src/env.mjs"
+
+const nextConfig: NextConfig = {
+  allowedDevOrigins: ["127.0.01", "localhost"],
+  reactCompiler: true,
+}
+
+export default nextConfig

package/templates/base-nextjs/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --port=3010",
+    "vex:dev": "vex dev",
+    "vex:generate": "vex dev --once",
+    "vex:update": "pnpm add @vexcms/core@latest @vexcms/cli@latest @vexcms/admin-next@latest @vexcms/ui@latest @vexcms/richtext@latest @vexcms/better-auth@latest @vexcms/file-storage-convex@latest",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "typecheck": "tsc --noEmit",
+    "secret:create": "openssl rand -base64 32 | tr -d '\\n' | tee /dev/stderr | pbcopy && echo '\\n✓ Secret copied to clipboard'"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.1.0",
+    "@convex-dev/better-auth": "^0.10.10",
+    "@convex-dev/react-query": "^0.1.0",
+    "@daveyplate/better-auth-ui": "^3.3.15",
+    "@t3-oss/env-nextjs": "^0.13.10",
+    "@tanstack/react-form": "^1.27.7",
+    "@tanstack/react-query": "^5.90.17",
+    "@vexcms/admin-next": "^0.0.2",
+    "@vexcms/better-auth": "^0.0.2",
+    "@vexcms/core": "^0.0.2",
+    "@vexcms/richtext": "^0.0.2",
+    "@vexcms/ui": "^0.0.2",
+    "@vexcms/file-storage-convex": "^0.0.2",
+    "better-auth": ">=1.4.9 <1.5.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "convex": "^1.31.5",
+    "convex-helpers": "^0.1.111",
+    "lucide-react": "^0.562.0",
+    "next": "^16.1.0",
+    "next-themes": "^0.4.6",
+    "nuqs": "^2.8.8",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "shadcn": "^3.6.3",
+    "tailwind-merge": "^3.4.0",
+    "tw-animate-css": "^1.4.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@convex-dev/eslint-plugin": "^1.1.1",
+    "@eslint/eslintrc": "^3.3.3",
+    "@next/eslint-plugin-next": "^15.4.3",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vexcms/cli": "^0.0.2",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^9",
+    "eslint-config-next": "15.5.9",
+    "eslint-plugin-import-x": "^4.16.1",
+    "eslint-plugin-perfectionist": "^5.3.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "prettier": "^3.8.1",
+    "tailwindcss": "^4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.53.0"
+  }
+}

package/templates/base-nextjs/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+}
+
+export default config

package/templates/base-nextjs/public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

package/templates/base-nextjs/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/templates/base-nextjs/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/templates/base-nextjs/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/templates/base-nextjs/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/templates/base-nextjs/src/app/(frontend)/@auth/(...)auth/[pathname]/page.tsx

@@ -0,0 +1,9 @@
+import AuthView from "./view"
+
+export const dynamic = "force-dynamic"
+
+export default async function AuthPage({ params }: { params: Promise<{ pathname: string }> }) {
+  const { pathname } = await params
+
+  return <AuthView pathname={pathname} />
+}

package/templates/base-nextjs/src/app/(frontend)/@auth/(...)auth/[pathname]/view.tsx

@@ -0,0 +1,23 @@
+import { AuthView } from "@daveyplate/better-auth-ui"
+import { Activity } from "react"
+
+import { Dialog, DialogContent, DialogTitle } from "~/components/ui/dialog"
+
+export default function AuthCard({ pathname }: { pathname: string }) {
+  return (
+    <main>
+      <Dialog open>
+        <Activity mode="hidden">
+          <DialogTitle />
+        </Activity>
+        <DialogContent
+          aria-describedby={undefined}
+          className="grid place-items-center border-none bg-transparent shadow-none ring-0"
+          showCloseButton={false}
+        >
+          <AuthView path={pathname} />
+        </DialogContent>
+      </Dialog>
+    </main>
+  )
+}

package/templates/base-nextjs/src/app/(frontend)/@auth/default.tsx

@@ -0,0 +1,3 @@
+export default function Page() {
+  return null
+}

package/templates/base-nextjs/src/app/(frontend)/@auth/page.tsx

@@ -0,0 +1,3 @@
+export default function Page() {
+  return null
+}

package/templates/base-nextjs/src/app/(frontend)/auth/[pathname]/page.tsx

@@ -0,0 +1,9 @@
+import AuthView from "./view"
+
+export const dynamic = "force-dynamic"
+
+export default async function AuthPage({ params }: { params: Promise<{ pathname: string }> }) {
+  const { pathname } = await params
+
+  return <AuthView pathname={pathname} />
+}

package/templates/base-nextjs/src/app/(frontend)/auth/[pathname]/view.tsx

@@ -0,0 +1,11 @@
+"use client"
+
+import { AuthView } from "@daveyplate/better-auth-ui"
+
+export default function AuthCard({ pathname }: { pathname: string }) {
+  return (
+    <main className="absolute inset-0 grid place-items-center">
+      <AuthView path={pathname} />
+    </main>
+  )
+}

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

@@ -0,0 +1,14 @@
+export default function FrontendLayout({
+  auth,
+  children,
+}: Readonly<{
+  auth: React.ReactNode
+  children: React.ReactNode
+}>) {
+  return (
+    <>
+      {children}
+      {auth}
+    </>
+  )
+}

package/templates/base-nextjs/src/app/(frontend)/page.tsx

@@ -0,0 +1,116 @@
+"use client"
+
+import { useMutation, useQuery } from "convex/react"
+import { usePathname, useRouter } from "next/navigation"
+import { useEffect, useState } from "react"
+
+import { api } from "@convex/_generated/api"
+import { useSession } from "~/auth/client"
+
+function LoadingSpinner() {
+  return (
+    <svg className="animate-spin h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+    </svg>
+  )
+}
+
+export default function Page() {
+  const isBootstrapped = useQuery(api.vex.firstUser.isBootstrapped)
+  const promoteFirstAdmin = useMutation(api.vex.firstUser.promoteFirstAdmin)
+  const { data: session } = useSession()
+  const router = useRouter()
+  const pathname = usePathname()
+  const [promoting, setPromoting] = useState(false)
+  const [navigating, setNavigating] = useState(false)
+
+  // Reset navigating state when the user comes back to the home page
+  // (e.g. closing the intercepting auth dialog)
+  useEffect(() => {
+    if (pathname === "/") {
+      setNavigating(false)
+    }
+  }, [pathname])
+
+  // If user is signed in and this is a fresh project, try to promote them
+  useEffect(() => {
+    if (session?.user && isBootstrapped === false && !promoting) {
+      setPromoting(true)
+      setNavigating(true)
+      promoteFirstAdmin()
+        .then((result) => {
+          if (result.promoted) {
+            router.push("/admin")
+          } else {
+            setNavigating(false)
+          }
+        })
+        .catch(() => {
+          setPromoting(false)
+          setNavigating(false)
+        })
+    }
+  }, [session, isBootstrapped, promoting, promoteFirstAdmin, router])
+
+  // Treat undefined (query still loading) as not bootstrapped — show the welcome page immediately
+  const bootstrapped = isBootstrapped === true
+
+  const buttonClass =
+    "inline-flex items-center justify-center gap-2 rounded-md bg-primary px-6 py-3 text-sm font-medium text-primary-foreground shadow hover:bg-primary/90 disabled:opacity-50 disabled:cursor-not-allowed transition-opacity"
+
+  const handleNavigate = (path: string) => {
+    setNavigating(true)
+    router.push(path)
+  }
+
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center gap-8 p-8">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold tracking-tight">VEX CMS</h1>
+        <p className="mt-3 text-lg text-muted-foreground">
+          {bootstrapped
+            ? "Your content management system is ready."
+            : "Welcome! Create your admin account to get started."}
+        </p>
+      </div>
+
+      <div className="flex gap-4">
+        {session?.user ? (
+          <button
+            onClick={() => handleNavigate("/admin")}
+            disabled={navigating}
+            className={buttonClass}
+          >
+            {navigating && <LoadingSpinner />}
+            {navigating ? "Loading..." : "Go to Admin Panel"}
+          </button>
+        ) : bootstrapped ? (
+          <button
+            onClick={() => handleNavigate("/auth/sign-in")}
+            disabled={navigating}
+            className={buttonClass}
+          >
+            {navigating && <LoadingSpinner />}
+            {navigating ? "Loading..." : "Sign In"}
+          </button>
+        ) : (
+          <button
+            onClick={() => handleNavigate("/auth/sign-up")}
+            disabled={navigating}
+            className={buttonClass}
+          >
+            {navigating && <LoadingSpinner />}
+            {navigating ? "Loading..." : "Create Admin Account"}
+          </button>
+        )}
+      </div>
+
+      {promoting && (
+        <p className="text-sm text-muted-foreground animate-pulse">
+          Setting up your admin account...
+        </p>
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,33 @@
+"use client"
+
+import { AdminLayout } from "@vexcms/admin-next"
+import type { PermissionUser } from "@vexcms/admin-next"
+import type { ClientVexConfig } from "@vexcms/core"
+import { access } from "~/vexcms/access"
+
+/**
+ * Client wrapper that provides the access config directly (not through RSC serialization).
+ * The access config contains callback functions that can't be serialized through RSC.
+ */
+export function AdminLayoutWrapper({
+  config,
+  user,
+  permissionUser,
+  children,
+}: {
+  config: ClientVexConfig
+  user?: { name: string; email: string; avatar?: string }
+  permissionUser?: PermissionUser
+  children: React.ReactNode
+}) {
+  return (
+    <AdminLayout
+      config={config}
+      user={user}
+      permissionUser={permissionUser}
+      access={access}
+    >
+      {children}
+    </AdminLayout>
+  )
+}

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

@@ -0,0 +1,38 @@
+"use client"
+
+import { AdminPage } from "@vexcms/admin-next"
+import type { ClientVexConfig } from "@vexcms/core"
+import { extractLivePreviewConfigs, sanitizeConfigForClient } from "@vexcms/core"
+import { RichTextFieldWithMedia } from "./RichTextFieldWithMedia"
+import originalConfig from "~/../vex.config"
+
+const livePreviewConfigs = extractLivePreviewConfigs(originalConfig)
+// Sanitize on the client so component references in admin.components survive
+// (they can't cross the RSC serialization boundary)
+const clientConfig = sanitizeConfigForClient(originalConfig)
+
+export function AdminPageWrapper({
+  config: _serverConfig,
+  path,
+}: {
+  config: ClientVexConfig
+  path?: string[]
+}) {
+  return (
+    <AdminPage
+      config={clientConfig}
+      path={path}
+      livePreviewConfigs={livePreviewConfigs}
+      renderRichTextField={(props: any) => (
+        <RichTextFieldWithMedia
+          field={props.field}
+          fieldDef={props.fieldDef}
+          name={props.name}
+          generateUploadUrl={props.generateUploadUrl}
+          createMediaDocument={props.createMediaDocument}
+          onUploadNew={props.onUploadNew}
+        />
+      )}
+    />
+  )
+}

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

@@ -0,0 +1,101 @@
+"use client"
+
+import { PlateEditorField } from "@vexcms/richtext/editor"
+import { defaultFeatures } from "@vexcms/richtext/editor"
+import { useMediaPickerState } from "@vexcms/admin-next"
+
+/**
+ * Inner component that always calls useMediaPickerState (no conditional hook).
+ */
+function WithMedia({
+  field,
+  fieldDef,
+  name,
+  mediaCollection,
+  generateUploadUrl,
+  createMediaDocument,
+  onUploadNew,
+}: {
+  field: any
+  fieldDef: any
+  name: string
+  mediaCollection: string
+  generateUploadUrl?: () => Promise<string>
+  createMediaDocument?: (props: { collectionSlug: string; fields: Record<string, unknown> }) => Promise<string>
+  onUploadNew?: () => void
+}) {
+  const mediaPicker = useMediaPickerState({
+    collectionSlug: mediaCollection,
+    searchField: "filename",
+    searchIndexName: "search_filename",
+    selectedId: null,
+  })
+
+  return (
+    <PlateEditorField
+      value={field.state.value}
+      onChange={(val: any) => field.handleChange(val)}
+      name={name}
+      label={fieldDef.label ?? name}
+      description={fieldDef.description}
+      features={defaultFeatures}
+      mediaCollection={mediaCollection}
+      mediaResults={mediaPicker.results}
+      mediaSearchTerm={mediaPicker.searchTerm}
+      onMediaSearchChange={mediaPicker.setSearchTerm}
+      mediaCanLoadMore={mediaPicker.canLoadMore}
+      onMediaLoadMore={mediaPicker.loadMore}
+      mediaIsLoading={mediaPicker.isLoading}
+      onUploadNew={onUploadNew}
+      generateUploadUrl={generateUploadUrl}
+      createMediaDocument={createMediaDocument}
+    />
+  )
+}
+
+/**
+ * Wrapper that creates media picker state for a richtext field
+ * when mediaCollection is configured.
+ */
+export function RichTextFieldWithMedia({
+  field,
+  fieldDef,
+  name,
+  generateUploadUrl,
+  createMediaDocument,
+  onUploadNew,
+}: {
+  field: any
+  fieldDef: any
+  name: string
+  generateUploadUrl?: () => Promise<string>
+  createMediaDocument?: (props: { collectionSlug: string; fields: Record<string, unknown> }) => Promise<string>
+  onUploadNew?: () => void
+}) {
+  const mediaCollection = fieldDef?.mediaCollection as string | undefined
+
+  if (mediaCollection) {
+    return (
+      <WithMedia
+        field={field}
+        fieldDef={fieldDef}
+        name={name}
+        mediaCollection={mediaCollection}
+        generateUploadUrl={generateUploadUrl}
+        createMediaDocument={createMediaDocument}
+        onUploadNew={onUploadNew}
+      />
+    )
+  }
+
+  return (
+    <PlateEditorField
+      value={field.state.value}
+      onChange={(val: any) => field.handleChange(val)}
+      name={name}
+      label={fieldDef.label ?? name}
+      description={fieldDef.description}
+      features={defaultFeatures}
+    />
+  )
+}

package/templates/base-nextjs/src/app/admin/[[...path]]/page.tsx

@@ -0,0 +1,15 @@
+import { sanitizeConfigForClient } from "@vexcms/core"
+
+import config from "~/../vex.config"
+import { AdminPageWrapper } from "../AdminPageWrapper"
+
+const clientConfig = sanitizeConfigForClient(config)
+
+interface Props {
+  params: Promise<{ path?: string[] }>
+}
+
+export default async function Page({ params }: Props) {
+  const { path } = await params
+  return <AdminPageWrapper config={clientConfig} path={path} />
+}