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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-vexcms",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.21",
   "description": "Scaffold a new VexCMS project",
   "keywords": [
     "cms",
@@ -51,7 +51,7 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",
-    "dev": "tsup src/index.ts --format esm --watch",
+    "dev": "tsup src/index.ts --format esm --watch src",
     "test": "vitest run"
   }
 }

package/templates/base-nextjs/README.md

@@ -31,9 +31,21 @@ NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
 NEXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
 ```
 
-Then, in the [Convex Dashboard](https://dashboard.convex.dev) → Settings →
-Environment Variables, add `BETTER_AUTH_SECRET` (same value as `.env.local`)
-and `SITE_URL` (`http://localhost:3010` for local dev).
+`next.config.ts` reads `NEXT_PUBLIC_CONVEX_URL` at build/start time and adds that
+deployment's hostname to `images.remotePatterns` automatically, so `next/image` can serve
+uploaded media without a manual edit.
+
+Better Auth runs inside your Convex deployment, not in the Next.js server —
+it does **not** read `.env.local`. Set the same two values on the
+deployment itself:
+
+```bash
+npx convex env set SITE_URL http://localhost:3010
+npx convex env set BETTER_AUTH_SECRET <the BETTER_AUTH_SECRET value from .env.local>
+```
+
+Skipping this step is the most common cause of a `403` on your first sign-in
+attempt.
 
 ### 4. Run the dev servers
 
@@ -65,10 +77,11 @@ see `convex/vex/firstUser.ts`. From there, "Go to Admin Panel" opens `/admin`.
 │   ├── auth/                   # Auth client + server helpers, access control
 │   ├── components/             # React components
 │   ├── vexcms/collections/     # Collection definitions
-│   ├── vex.config.ts           # VexCMS config
+│   ├── vex.config.ts           # VexCMS client config (collections, globals, access)
+│   ├── vex.config.server.ts    # VexCMS server config (auth adapter, storage adapters)
 │   └── env.mjs                 # Typed environment variables
 ├── convex/                     # Convex backend
-│   ├── auth/                   # Better Auth config + plugins
+│   ├── auth/                   # Better Auth config + plugins (schema.ts, options.ts)
 │   ├── vex/                    # Bootstrap, media, globals endpoints
 │   └── schema.ts               # Database schema
 └── .env.local                  # Environment variables (not committed)

package/templates/base-nextjs/convex/auth/index.ts

@@ -3,10 +3,10 @@ import type { GenericActionCtx } from "convex/server"
 import { createBetterAuthAdapter } from "@vexcms/better-auth"
 import { betterAuth } from "better-auth"
 
-import { authOptions } from "./options"
-
 import type { DataModel } from "../_generated/dataModel"
 
+import { authOptions } from "./options"
+
 export const createAuth = (ctx: GenericActionCtx<DataModel>, { optionsOnly } = { optionsOnly: false }) => {
   return betterAuth({
     database: createBetterAuthAdapter(ctx),

package/templates/base-nextjs/convex/auth/options.ts

@@ -1,39 +1,40 @@
 import type { BetterAuthOptions } from "better-auth"
 
-import {
-  TABLE_SLUG_ACCOUNTS,
-  TABLE_SLUG_SESSIONS,
-  TABLE_SLUG_USERS,
-  TABLE_SLUG_VERIFICATIONS,
-  USER_ROLES,
-} from "~/db/constants"
+import { anonRoleDatabaseHook } from "@vexcms/better-auth"
+
+import { USER_ROLES } from "~/db/constants"
 
 import { createPlugins } from "./plugins"
+import { authSchema } from "./schema"
+
+// `plugins` on the shared schema is a descriptor map for
+// `betterAuthCollections`, not Better Auth plugin instances — dropped by name
+// so the intent survives a reordering of the object literal below.
+const { plugins: _pluginDescriptors, ...schemaOptions } = authSchema
 
+/**
+ * Better Auth options for this project.
+ *
+ * Model names and `user.additionalFields` come from `./schema`, the one module
+ * both this file and `src/vex.config.ts` read, so a field added there reaches
+ * the database and the admin panel without being written twice. Everything
+ * below the spread is server-only.
+ *
+ * @see ./schema for the shared, client-safe half
+ */
 export const authOptions: BetterAuthOptions = {
-  account: {
-    modelName: TABLE_SLUG_ACCOUNTS,
-  },
+  ...schemaOptions,
   baseURL: process.env.SITE_URL,
+  databaseHooks: {
+    // Ties Better Auth's anonymous-plugin users to `access.anonRole` (see
+    // `~/auth/access.ts`) by stamping the same role explicitly, rather than
+    // relying solely on `roles`' `defaultValue` below — which every new user
+    // gets regardless of `isAnonymous`, anon-plugin or not.
+    user: anonRoleDatabaseHook(USER_ROLES.user),
+  },
   // {{EMAIL_PASSWORD_AUTH}}
   // {{OAUTH_PROVIDERS}}
   plugins: createPlugins(),
   secret: process.env.BETTER_AUTH_SECRET,
-  session: {
-    modelName: TABLE_SLUG_SESSIONS,
-  },
   trustedOrigins: [process.env.SITE_URL!],
-  user: {
-    additionalFields: {
-      roles: {
-        type: "string[]",
-        defaultValue: [USER_ROLES.user],
-        required: true,
-      },
-    },
-    modelName: TABLE_SLUG_USERS,
-  },
-  verification: {
-    modelName: TABLE_SLUG_VERIFICATIONS,
-  },
 }

package/templates/base-nextjs/convex/auth/schema.ts

@@ -0,0 +1,51 @@
+import type { BetterAuthSchemaInput } from "@vexcms/better-auth/client"
+
+import {
+  TABLE_SLUG_ACCOUNTS,
+  TABLE_SLUG_SESSIONS,
+  TABLE_SLUG_USERS,
+  TABLE_SLUG_VERIFICATIONS,
+  USER_ROLES,
+} from "~/db/constants"
+
+/**
+ * Everything about your Better Auth setup that determines which collections
+ * exist and which fields they carry — and nothing else.
+ *
+ * This is the one auth module the browser reads: `src/vex.config.ts` passes it
+ * to `betterAuthCollections()` to build the admin panel's auth collections,
+ * and `./options` spreads it so the same model names and fields reach the
+ * database. Add a `user.additionalFields` entry here and it shows up in both.
+ *
+ * Keep it inert. `./options` reads `process.env` and `./plugins` pulls
+ * `better-auth/next-js` (→ `next/headers`), which is why they are separate
+ * files — importing either from the client config would drag the server into
+ * your browser bundle. Runtime plugin options (admin roles, mailers, OAuth
+ * secrets) belong on the real plugin instances in `./plugins`; only options
+ * that change which TABLES exist belong here.
+ *
+ * @see betterAuthCollections in @vexcms/better-auth/client
+ * @see ./options for the server-side options that spread this
+ */
+export const authSchema = {
+  account: { modelName: TABLE_SLUG_ACCOUNTS },
+  session: { modelName: TABLE_SLUG_SESSIONS },
+  user: {
+    modelName: TABLE_SLUG_USERS,
+    additionalFields: {
+      roles: {
+        type: "string[]",
+        defaultValue: [USER_ROLES.user],
+        required: true,
+      },
+    },
+  },
+  verification: { modelName: TABLE_SLUG_VERIFICATIONS },
+  plugins: {
+    admin: true,
+    anonymous: true,
+    apiKey: true,
+    convex: true,
+    // {{ORGANIZATIONS_SCHEMA}}
+  },
+} satisfies BetterAuthSchemaInput

package/templates/base-nextjs/convex/auth/sessions.ts

@@ -19,7 +19,7 @@ export const getSessionWithUser = query({
       .withIndex("by_token", (q) => q.eq("token", args.sessionToken))
       .first()
 
-    if (!session) return null
+    if (!session) {return null}
 
     if (session.expiresAt < Date.now()) {
       console.error("[getSessionWithUser] Session Expired")
@@ -27,10 +27,10 @@ export const getSessionWithUser = query({
     }
 
     const userId = session.userId
-    if (!userId) return null
+    if (!userId) {return null}
 
     const user = await ctx.db.get(userId as Id<typeof TABLE_SLUG_USERS>)
-    if (!user) return null
+    if (!user) {return null}
 
     return {
       session: {

package/templates/base-nextjs/convex/tsconfig.json

@@ -8,16 +8,16 @@
     "allowSyntheticDefaultImports": true,
     "target": "ESNext",
     "lib": ["ES2023", "dom", "dom.iterable"],
+    "types": ["node"],
     "forceConsistentCasingInFileNames": true,
     "module": "ESNext",
     "isolatedModules": true,
     "noEmit": true,
-    "baseUrl": ".",
     "paths": {
       "~/*": ["../src/*"],
       "@convex/*": ["./*"]
     }
   },
-  "include": ["./**/*"],
+  "include": ["./**/*", "../src/vex.types.ts"],
   "exclude": ["./_generated"]
 }

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

@@ -1,10 +1,10 @@
 import { ConvexError } from "convex/values"
 
-import { mutation, query } from "../_generated/server"
-
 import { TABLE_SLUG_USERS } from "~/db/constants"
 import { USER_ROLES } from "~/db/constants/auth"
 
+import { mutation, query } from "../_generated/server"
+
 /**
  * Check whether the admin panel has been bootstrapped (at least one admin
  * exists). Used by `WelcomePage` to decide between "Sign Up" and "Sign In".

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

@@ -2,9 +2,10 @@ import { createGetAuth } from "@vexcms/better-auth";
 import { globalsApi } from "@vexcms/core/server";
 
 import { TABLE_SLUG_ORGANIZATIONS, TABLE_SLUG_SESSIONS, TABLE_SLUG_USERS } from "~/db/constants";
-import config from "~/vex.config";
+import config from "~/vex.config.server";
 
-import { mutation, query } from "../_generated/server";
+import { query } from "../_generated/server";
+import { vexMutation as mutation } from "../vex";
 
 export const { get, find, upsert } = globalsApi({
   config,

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

@@ -2,9 +2,10 @@ import { createGetAuth } from "@vexcms/better-auth";
 import { mediaApi } from "@vexcms/core";
 
 import { TABLE_SLUG_ORGANIZATIONS, TABLE_SLUG_SESSIONS, TABLE_SLUG_USERS } from "~/db/constants";
-import config from "~/vex.config";
+import config from "~/vex.config.server";
 
-import { mutation, query } from "../_generated/server";
+import { query } from "../_generated/server";
+import { vexMutation as mutation } from "../vex";
 
 export const { getUrl, generateUploadUrl, createMediaDocument, deleteMedia } = mediaApi({
   config,

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

@@ -130,6 +130,7 @@ export const images = defineTable({
   src: v.string(),
   width: v.optional(v.number()),
   height: v.optional(v.number()),
+  updatedAt: v.optional(v.number()),
 })
   .index("by_deleted", ["deleted"])
   .searchIndex("search_filename", {

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

@@ -1,15 +1,28 @@
 import { createGetAuth } from "@vexcms/better-auth";
-import { collectionsApi } from "@vexcms/core/server";
+import { collectionsApi, createVexMutations } from "@vexcms/core/server";
 
 import { TABLE_SLUG_ORGANIZATIONS, TABLE_SLUG_SESSIONS, TABLE_SLUG_USERS } from "~/db/constants";
-import config from "~/vex.config";
+import config from "~/vex.config.server";
 
-import { mutation, query } from "./_generated/server";
+import { internalMutation, mutation, query } from "./_generated/server";
+
+/**
+ * Trigger-wrapped `mutation`/`internalMutation` builders — every write made
+ * through them fires the written collection's `afterChange`/`afterDelete`
+ * hooks (`@vexcms/core`'s `createVexMutations`). Used, not exported: this
+ * file's own `create`/`update`/`remove` (below) and `globals.ts`/`media.ts`
+ * build their mutations on `vexMutation`, never the raw builder above.
+ */
+export const { mutation: vexMutation, internalMutation: vexInternalMutation } = createVexMutations({
+  config,
+  mutation,
+  internalMutation,
+});
 
 export const { find, get, search, create, update, remove } = collectionsApi({
   config,
   query,
-  mutation,
+  mutation: vexMutation,
   getAuth: createGetAuth({
     orgCollectionSlug: TABLE_SLUG_ORGANIZATIONS,
     userCollectionSlug: TABLE_SLUG_USERS,

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

@@ -1,6 +1,38 @@
 import type { NextConfig } from "next"
 
-import "./src/env.mjs"
+import { existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+import { env } from "./src/env.mjs"
+
+/**
+ * Walks up from the app directory looking for `pnpm-workspace.yaml`.
+ *
+ * @param from - Directory to start from.
+ * @returns The workspace root when this app is a workspace member, otherwise
+ *   `from` unchanged.
+ */
+function findWorkspaceRoot(from: string): string {
+  let dir = resolve(from)
+  for (;;) {
+    if (existsSync(join(dir, "pnpm-workspace.yaml"))) {return dir}
+    const parent = dirname(dir)
+    if (parent === dir) {return resolve(from)}
+    dir = parent
+  }
+}
+
+// Convex file storage URLs (`next/image` sources for uploaded media) are
+// served from `<deployment>.convex.cloud` — derive the hostname from the
+// validated NEXT_PUBLIC_CONVEX_URL so scaffolds work without a manual
+// next.config.ts edit. Falls back to an empty list when the URL is unset or
+// unparsable (e.g. a deployment-less build with SKIP_ENV_VALIDATION set).
+let convexImageRemotePatterns: NonNullable<NextConfig["images"]>["remotePatterns"] = []
+try {
+  convexImageRemotePatterns = [{ hostname: new URL(env.NEXT_PUBLIC_CONVEX_URL).hostname }]
+} catch {
+  // No deployment yet — leave remotePatterns empty.
+}
 
 const nextConfig: NextConfig = {
   devIndicators: {
@@ -8,12 +40,26 @@ const nextConfig: NextConfig = {
   },
   allowedDevOrigins: ["127.0.01", "localhost"],
   reactCompiler: true,
+  // Turbopack's root sets the file-tracing root AND Tailwind's source-scan
+  // root, so it has to be the directory that actually owns `node_modules`.
+  //
+  // Standalone scaffold: that is this app. Pinning it stops Next walking up
+  // and adopting an unrelated outer lockfile.
+  //
+  // pnpm workspace member: it is the workspace root — dependencies are
+  // hoisted into the root virtual store and `next` is only reachable from
+  // there. Pinning to the app dir makes the build fail with "Could not find
+  // the Next.js package".
+  //
+  // Detecting `pnpm-workspace.yaml` picks the right answer in both cases
+  // without the template needing a monorepo-specific variant.
+  turbopack: {
+    root: findWorkspaceRoot(import.meta.dirname),
+  },
   images: {
-    remotePatterns: [
-      // Add your Convex deployment's hostname here once `npx convex dev` has
-      // run — Convex file storage URLs are served from `<deployment>.convex.cloud`,
-      // e.g. { hostname: "your-deployment-575.convex.cloud" }.
-    ],
+    // Additional remote image hosts (e.g. an external CMS or CDN) can be
+    // added here alongside the auto-derived Convex hostname above.
+    remotePatterns: convexImageRemotePatterns,
   },
 }
 

package/templates/base-nextjs/package.json

@@ -24,18 +24,17 @@
     "@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.2",
-    "@vexcms/core": "~0.1.0-alpha.2",
-    "@vexcms/file-storage-convex": "~0.1.0-alpha.2",
-    "@vexcms/next": "~0.1.0-alpha.2",
-    "@vexcms/react": "~0.1.0-alpha.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",
     "better-auth": "1.6.23",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
     "convex": "1.44.0",
     "convex-helpers": "0.1.120",
     "lucide-react": "0.577.0",
-    "motion": "13.1.1",
     "next": "16.3.3",
     "nuqs": "2.9.0",
     "react": "19.2.7",
@@ -53,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.2",
+    "@vexcms/cli": "~0.1.0-alpha.21",
     "babel-plugin-react-compiler": "1.0.0",
     "eslint": "9.39.5",
     "eslint-config-next": "15.5.9",
@@ -64,5 +63,17 @@
     "tailwindcss": "4.3.2",
     "typescript": "6.0.3",
     "typescript-eslint": "8.63.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "@better-auth/passkey": "1.6.23"
+    },
+    "peerDependencyRules": {
+      "allowedVersions": {
+        "@convex-dev/better-auth>better-auth": "1.6.23",
+        "better-call": "2",
+        "typescript": "6"
+      }
+    }
   }
 }

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

@@ -1,12 +1,13 @@
 "use client";
 
 import { AuthView } from "@daveyplate/better-auth-ui";
-import { useSearchParams } from "next/navigation";
+import { useRouter, useSearchParams } from "next/navigation";
 import { Activity } from "react";
 
 import { Dialog, DialogContent, DialogTitle } from "~/components/ui/dialog";
 
 export default function AuthCard({ pathname }: { pathname: string }) {
+  const router = useRouter();
   const searchParams = useSearchParams();
   const isGuardRedirect = searchParams.has("redirectTo");
   if (isGuardRedirect) {
@@ -16,20 +17,31 @@ export default function AuthCard({ pathname }: { pathname: string }) {
       </main>
     );
   }
+  // No in-flow wrapper here on purpose. The Dialog portals into <body>, so a
+  // wrapping <main> would be an empty element sitting after the footer (the
+  // @auth slot renders last in the frontend layout). Next's post-navigation
+  // scroll handler targets the new segment's first DOM node and would scroll
+  // that empty element into view — i.e. jump the page to the bottom behind
+  // the modal. With only a portal rendered there is no node to target.
   return (
-    <main>
-      <Dialog open>
-        <Activity mode="hidden">
-          <DialogTitle />
-        </Activity>
-        <DialogContent
-          aria-describedby={undefined}
-          className="grid place-items-center bg-transparent shadow-none ring-transparent"
-          showCloseButton={false}
-        >
-          <AuthView path={pathname} />
-        </DialogContent>
-      </Dialog>
-    </main>
+    <Dialog
+      onOpenChange={(open) => {
+        if (!open) {
+          router.back();
+        }
+      }}
+      open
+    >
+      <Activity mode="hidden">
+        <DialogTitle />
+      </Activity>
+      <DialogContent
+        aria-describedby={undefined}
+        className="grid place-items-center bg-transparent shadow-none ring-transparent"
+        showCloseButton={false}
+      >
+        <AuthView path={pathname} />
+      </DialogContent>
+    </Dialog>
   );
 }

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

@@ -1,10 +1,10 @@
 import { api } from "@convex/_generated/api";
-import { NextAdminPage } from "@vexcms/next/server";
 import { canAccessAdminPanel } from "@vexcms/core";
+import { NextAdminPage } from "@vexcms/next/server";
 import { redirect } from "next/navigation";
 
 import { fetchAuthQuery, getToken } from "~/auth/server";
-import config from "~/vex.config";
+import config from "~/vex.config.server";
 
 export const dynamic = "force-dynamic";
 

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

@@ -1,22 +1,17 @@
-"use client";
+"use client"
 
-import { uploadFile } from "@vexcms/file-storage-convex";
-import { StorageAdapterContextProvider, VexAccessProvider } from "@vexcms/react";
+import { VexConfigProvider } from "@vexcms/react"
 
-import { access } from "~/auth/access";
+import config from "~/vex.config"
 
 /**
- * Provides client-side upload functions for VexCMS storage adapters.
+ * Mounts the single `VexConfigProvider` for the admin panel's client tree.
  *
- * This is a "use client" component so that uploadFile is imported and
- * owned on the client — it never crosses the RSC boundary as a prop.
- *
- * Add a new entry here when registering an additional storage adapter.
+ * 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 (
-    <StorageAdapterContextProvider adapterClients={{ convex: uploadFile }}>
-      <VexAccessProvider access={access}>{children}</VexAccessProvider>
-    </StorageAdapterContextProvider>
-  );
+  return <VexConfigProvider config={config}>{children}</VexConfigProvider>
 }

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

@@ -2,18 +2,20 @@ import type { ReactNode } from "react"
 
 import { NextAdminLayout } from "@vexcms/next/client"
 
+import { AuthServerProvider } from "~/components/providers/auth"
 import { getCurrentUser } from "~/auth/serverUtils"
-import config from "~/vex.config"
 
 import { ClientProviders } from "./clientProviders"
 
 export default async function AdminLayout({ children }: { children: ReactNode }) {
   const user = await getCurrentUser()
   return (
-    <ClientProviders>
-      <NextAdminLayout config={config} user={user ?? undefined}>
-        {children}
-      </NextAdminLayout>
-    </ClientProviders>
+    <AuthServerProvider>
+      <ClientProviders>
+        <NextAdminLayout user={user ?? undefined}>
+          {children}
+        </NextAdminLayout>
+      </ClientProviders>
+    </AuthServerProvider>
   )
 }

package/templates/base-nextjs/src/app/api/vex/revalidate/route.ts

@@ -0,0 +1,19 @@
+import { api } from "@convex/_generated/api"
+import { createVexRevalidateRoute } from "@vexcms/next/cache"
+
+import { fetchAuthQuery, getToken } from "~/auth/server"
+import config from "~/vex.config.server"
+
+/**
+ * `POST /api/vex/revalidate` — session-authorized path purge.
+ *
+ * Called by `useVexMutation` after every admin-panel write, same origin, and
+ * by the admin panel's Revalidate control over the same session. Never
+ * secret-authorized: the caller must hold a real session with write
+ * permission on the affected collection.
+ */
+export const { POST } = createVexRevalidateRoute({
+  config,
+  getToken,
+  getAuth: () => fetchAuthQuery(api.auth.api.getUserOrg, {}),
+})

package/templates/base-nextjs/src/app/globals.css

@@ -25,15 +25,16 @@
 @import "shadcn/tailwind.css";
 @import "@vexcms/next/styles";
 
-/* Workspace source scan (belt-and-suspenders — normal dev relies on tsup
-   watchers rebuilding each package dist/, which Tailwind already scans via
-   @vexcms/next/styles). These two lines also point Tailwind at the raw
-   .tsx so classes appear immediately even if a tsup watcher dies. They
-   are workspace-relative and resolve only inside this monorepo. */
-@source "../../../../packages/react/src/**/*.ts";
-@source "../../../../packages/react/src/**/*.tsx";
-@source "../../../../packages/next/src/**/*.ts";
-@source "../../../../packages/next/src/**/*.tsx";
+/* Scan the installed @vexcms packages for class candidates (their dist output
+   ships alongside this app in node_modules; @vexcms/next/styles above pulls
+   the stylesheet, these make sure every utility used by the admin UI exists).
+   Globbed to `*.js` only — the same `dist` directories also carry `.map`
+   sourcemaps and `.d.ts` declaration files, and Tailwind's scanner extracts
+   garbage "class candidates" from their base64/binary-ish content and emits
+   unparseable CSS, exactly like the raw `public/` binary assets below. */
+@source "../../node_modules/@vexcms/react/dist/**/*.js";
+@source "../../node_modules/@vexcms/next/dist/**/*.js";
+@source not "../../public";
 
 @custom-variant dark (&:is(.dark *));
 

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

@@ -2,6 +2,7 @@ import type { Metadata } from "next"
 
 import "./globals.css"
 
+import { ThemeScript } from "@vexcms/react"
 import { Geist, Geist_Mono } from "next/font/google"
 
 import ClientProviders from "~/components/providers/client"
@@ -30,6 +31,11 @@ export default function RootLayout({
 }>) {
   return (
     <html className={`${geistSans.variable} ${geistMono.variable} antialiased`} lang="en" suppressHydrationWarning>
+      <head>
+        {/* Applies the persisted light/dark class before first paint —
+            without it the admin flashes light before the saved mode lands. */}
+        <ThemeScript />
+      </head>
       <body>
         <ServerProviders>
           <ClientProviders>{children}</ClientProviders>