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

package/templates/marketing-site/src/lib/metadata.ts

@@ -1,27 +1,28 @@
 import type { Metadata } from "next"
 
-import { fetchQuery } from "convex/nextjs"
-
 import { api } from "@convex/_generated/api"
-import { anyApi } from "convex/server"
+import { vexMetadata } from "@vexcms/next/seo"
+
+import { env } from "~/env.mjs"
+import { vex } from "~/lib/vex"
 
 const TITLE_SUFFIX = " | Vex CMS"
 
 /**
- * Resolves an `upload()` field's stored media id to a public URL via the
- * Convex file storage adapter. Returns `undefined` when the media document
- * no longer exists or the deployment is unreachable.
+ * Returns the first candidate that is a non-blank string.
+ *
+ * Optional text fields in a vexcms collection seed as `""` rather than being
+ * absent, so `??` chains cannot express "fall back to the site default" — an
+ * empty override would win. Mirrors `apps/www/src/lib/metadata.ts`'s helper
+ * of the same name.
  */
-async function resolveMediaUrl(mediaId: string): Promise<string | undefined> {
-  try {
-    const result = (await fetchQuery(anyApi.vex.media.getUrl, {
-      adapter: "convex",
-      mediaId,
-    })) as { url?: string; error?: string }
-    return result.url
-  } catch {
-    return undefined
+function firstNonBlank(...candidates: unknown[]): string | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      return candidate
+    }
   }
+  return undefined
 }
 
 /**
@@ -29,32 +30,32 @@ async function resolveMediaUrl(mediaId: string): Promise<string | undefined> {
  *
  * Fetches site settings and, when a slug is given, the matching page
  * document, then merges them — page-level `metaTitle`/`metaDescription`/
- * `ogImage` win over the site's defaults from `siteSettings`.
+ * `ogImage` win over the site's defaults from `siteSettings` — and delegates
+ * the `Metadata` shape (title, description, `metadataBase`, canonical,
+ * conditional OG image) to `vexMetadata` (`@vexcms/next/seo`).
  *
  * @param props.slug - Optional page slug to fetch per-page SEO overrides
  */
 export async function generatePageMetadata(props: { slug?: string }): Promise<Metadata> {
   try {
-    const settings = (await fetchQuery(api.siteSettings.get)) as Record<string, unknown> | null
+    const settings = (await vex.query(api.siteSettings.get)) as null | Record<string, unknown>
     if (!settings) {
       return { title: "Untitled" }
     }
 
     let pageData: Record<string, unknown> | undefined
     if (props.slug) {
-      const pages = (await fetchQuery(api.pages.getBySlug, { slug: props.slug })) as
+      const pages = (await vex.query(api.pages.getBySlug, { slug: props.slug })) as
         | Record<string, unknown>[]
         | undefined
       pageData = pages?.[0]
     }
 
-    const pageTitle = (pageData?.metaTitle as string | undefined) ?? (pageData?.title as string | undefined)
-    const siteName = settings.name as string | undefined
-    const title = (pageTitle ?? (settings.metaTitle as string | undefined) ?? siteName ?? "Untitled") + TITLE_SUFFIX
-    const description =
-      (pageData?.metaDescription as string | undefined) ??
-      (settings.metaDescription as string | undefined) ??
-      (settings.description as string | undefined)
+    const pageTitle = firstNonBlank(pageData?.metaTitle, pageData?.title)
+    const siteName = firstNonBlank(settings.name)
+    const title =
+      (firstNonBlank(pageTitle, settings.metaTitle, siteName) ?? "Untitled") + TITLE_SUFFIX
+    const description = firstNonBlank(pageData?.metaDescription, settings.metaDescription, settings.description)
 
     // `upload()` fields always store an array of media ids — the first entry
     // is the selection. Page-level ogImage wins over the site default.
@@ -63,16 +64,26 @@ export async function generatePageMetadata(props: { slug?: string }): Promise<Me
     const ogImageId = pageOgImageId ?? siteOgImageId
     const ogImageUrl = ogImageId ? await resolveMediaUrl(ogImageId) : undefined
 
-    const twitterHandle = settings.twitterHandle as string | undefined
+    const twitterHandle = firstNonBlank(settings.twitterHandle)
+    const canonicalPath = props.slug && props.slug !== "home" ? `/${props.slug}` : "/"
 
-    const metadata: Metadata = { title, description }
-
-    if (ogImageUrl) {
-      metadata.openGraph = { title, description, images: [{ url: ogImageUrl }] }
-    }
+    const metadata = vexMetadata({
+      title,
+      description,
+      siteUrl: env.NEXT_PUBLIC_SITE_URL,
+      path: canonicalPath,
+      imageUrl: ogImageUrl,
+    })
 
-    if (twitterHandle) {
-      metadata.twitter = { card: "summary_large_image", site: twitterHandle }
+    // Discord, Slack and X pick the large-image layout from `twitter:card`, not
+    // from `og:image` alone — and Next auto-fills `card: "summary"` (a small
+    // thumbnail) whenever `twitter` is omitted. So the card type must be emitted
+    // whenever an image resolved, independently of whether a handle exists.
+    if (ogImageUrl || twitterHandle) {
+      metadata.twitter = {
+        card: ogImageUrl ? "summary_large_image" : "summary",
+        ...(twitterHandle ? { site: twitterHandle } : {}),
+      }
     }
 
     return metadata
@@ -81,3 +92,20 @@ export async function generatePageMetadata(props: { slug?: string }): Promise<Me
     return { title: "Vex CMS" }
   }
 }
+
+/**
+ * Resolves an `upload()` field's stored media id to a public URL via the
+ * Convex file storage adapter. Returns `undefined` when the media document
+ * no longer exists or the deployment is unreachable.
+ */
+async function resolveMediaUrl(mediaId: string): Promise<string | undefined> {
+  try {
+    const result = (await vex.query(api.vex.media.getUrl, {
+      adapter: "convex",
+      mediaId,
+    })) as { error?: string; url?: string }
+    return result.url
+  } catch {
+    return undefined
+  }
+}

package/templates/marketing-site/src/lib/resolvePagePath.ts

@@ -0,0 +1,8 @@
+/**
+ * Maps a `pages` document's slug to its public path. Shared by `vex.config.ts`'s
+ * `routes.map` and `pages.ts`'s `admin.livePreview.url`.
+ */
+export function resolvePagePath(slug: string | undefined): string | undefined {
+  if (!slug) return undefined
+  return slug === "home" ? "/" : `/${slug}`
+}

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

@@ -0,0 +1,18 @@
+import { createVexServerClient } from "@vexcms/next/cache"
+
+import { env } from "~/env.mjs"
+
+/**
+ * The single shared Convex read client for every server component and route
+ * in this project.
+ *
+ * `createVexServerClient` (`@vexcms/next/cache`) wraps its `query` method in
+ * a `React.cache` created fresh on every call — so two files that each call
+ * `createVexServerClient()` themselves get two independent caches and never
+ * share a round trip, no matter how identical their reads are. Importing
+ * this one instance everywhere is what lets `generatePageMetadata`
+ * (`~/lib/metadata`) and the page calling it collapse their identical
+ * `pages.getBySlug` read into a single Convex call within one request,
+ * instead of two.
+ */
+export const vex = createVexServerClient({ url: env.NEXT_PUBLIC_CONVEX_URL })

package/templates/marketing-site/src/proxy.ts

@@ -0,0 +1,179 @@
+import { api } from "@convex/_generated/api";
+import {
+  LIVE_PREVIEW_COOKIE,
+  LIVE_PREVIEW_COOKIE_MAX_AGE_SECONDS,
+  LIVE_PREVIEW_QUERY_PARAM,
+} from "@vexcms/core";
+import { fetchQuery } from "convex/nextjs";
+import { cookies } from "next/headers";
+import { type NextRequest, NextResponse } from "next/server";
+
+const SESSION_COOKIES = {
+  https: "__Secure-better-auth.session_token",
+  http: "better-auth.session_token",
+} as const;
+
+/**
+ * Paths the proxy must never guard, because they are where it sends people.
+ * Guarding them turns a Convex outage into an infinite redirect loop.
+ */
+const ALWAYS_ALLOWED: Record<string, true> = { "/": true, "/unauthorized": true };
+
+/**
+ * Session gate for the private surfaces named in `config.matcher`.
+ *
+ * **This is the marketing-site variant.** The base template guards every route
+ * except a small allowlist, which is right for a private app and wrong here:
+ * a marketing site's pages are public content served from the CMS, so a
+ * fail-closed gate over `/(.*)` sends anonymous visitors from `/features` and
+ * `/roadmap` straight to sign-in. The matcher below inverts that — only the
+ * admin panel is gated, and the public site is public.
+ *
+ * The admin panel is not defended by this gate alone: every collection query
+ * runs the RBAC rules from `vex.config.ts`, and unauthenticated callers
+ * resolve through `anonRole`. The proxy is defence in depth and a redirect
+ * convenience, not the access control.
+ *
+ * Fails **closed**: if the session cannot be verified — no cookie, no matching
+ * session, or the Convex lookup throwing — the request is redirected rather than
+ * served. A verification error is not evidence of a valid session, and serving
+ * the page anyway would drop authentication for every guarded route the moment
+ * Convex became unreachable.
+ *
+ * Two distinct outcomes, deliberately:
+ * - **No/invalid session** → `/auth/sign-in`, clearing the stale cookie so the
+ *   presence check cannot lie on the next request.
+ * - **Verification failed** (Convex unreachable, timeout) → `/unauthorized`,
+ *   leaving cookies intact: the session may well be fine, so signing the user
+ *   out and discarding it would be wrong.
+ *
+ * @param request - The incoming request.
+ * @returns `NextResponse.next()` when the session is verified, otherwise a
+ *   redirect to sign-in or to the unauthorized page.
+ */
+export async function proxy(request: NextRequest) {
+  if (ALWAYS_ALLOWED[request.nextUrl.pathname]) {
+    return NextResponse.next();
+  }
+
+  if (request.nextUrl.pathname.startsWith("/admin")) {
+    return guardAdminRequest(request);
+  }
+
+  return grantPreviewIfRequested(request);
+}
+
+/** Session gate for the admin panel — fails closed, per the docstring above. */
+async function guardAdminRequest(request: NextRequest) {
+  const sessionStatus = await resolveSessionStatus();
+
+  if (sessionStatus === "verification-failed") {
+    return redirectToUnauthorized(request);
+  }
+  if (sessionStatus === "unauthenticated") {
+    return redirectToSignIn(request);
+  }
+  return NextResponse.next();
+}
+
+/**
+ * Grants live-preview mode to a public-route request carrying `?vexLivePreview=1`
+ * and a verified admin session, by setting the `vex-live-preview` marker
+ * cookie that `LivePreviewProvider` gates on client-side. Fails **open** — an
+ * unauthenticated or unverifiable session here renders the page normally
+ * rather than redirecting.
+ *
+ * A cookie rather than a forwarded request header: a header would have to be
+ * read with `next/headers` in the site layout, which opts every public route
+ * out of static prerendering.
+ */
+async function grantPreviewIfRequested(request: NextRequest) {
+  if (request.nextUrl.searchParams.get(LIVE_PREVIEW_QUERY_PARAM) !== "1") {
+    return NextResponse.next();
+  }
+
+  const sessionStatus = await resolveSessionStatus();
+  if (sessionStatus !== "authenticated") {
+    return NextResponse.next();
+  }
+
+  const response = NextResponse.next();
+  response.cookies.set(LIVE_PREVIEW_COOKIE, "1", {
+    path: "/",
+    maxAge: LIVE_PREVIEW_COOKIE_MAX_AGE_SECONDS,
+    sameSite: "lax",
+    // Read by `LivePreviewProvider` in the browser — the whole point of the
+    // cookie. It carries no secret, only the fact that a session verified.
+    httpOnly: false,
+  });
+  return response;
+}
+
+/** Reads and verifies the Better Auth session cookie — shared by both branches above. */
+async function resolveSessionStatus(): Promise<
+  "authenticated" | "unauthenticated" | "verification-failed"
+> {
+  const cookieStore = await cookies();
+  const sessionToken =
+    cookieStore.get(SESSION_COOKIES.https)?.value ?? cookieStore.get(SESSION_COOKIES.http)?.value;
+  if (!sessionToken) return "unauthenticated";
+
+  try {
+    const session = await fetchQuery(api.auth.sessions.getSessionWithUser, {
+      sessionToken: extractToken(sessionToken),
+    });
+    return session?.user ? "authenticated" : "unauthenticated";
+  } catch {
+    // Fail closed for the admin branch; grantPreviewIfRequested treats this as
+    // "no preview" rather than an error.
+    return "verification-failed";
+  }
+}
+
+/** Extract the raw token — better-auth stores "<raw_token>.<hmac_signature>" */
+function extractToken(cookieValue: string) {
+  return cookieValue.includes(".") ? cookieValue.split(".")[0] : cookieValue;
+}
+
+/**
+ * Redirect for a caller with no usable session. Clears the session cookies so
+ * the presence check cannot lie on the next request.
+ *
+ * @param request - The request being rejected.
+ * @returns A redirect to sign-in preserving the intended destination.
+ */
+function redirectToSignIn(request: NextRequest) {
+  const signInUrl = new URL("/auth/sign-in", request.url);
+  // Preserve where the user was headed (path + query)
+  signInUrl.searchParams.set("redirectTo", request.nextUrl.pathname + request.nextUrl.search);
+
+  const response = NextResponse.redirect(signInUrl);
+  for (const cookie of Object.values(SESSION_COOKIES)) {
+    // Clear the stale cookie so the presence-check never lies again
+    response.cookies.delete(cookie);
+  }
+  return response;
+}
+
+/**
+ * Redirect for a caller whose session could not be *verified* — as opposed to
+ * one who has none.
+ *
+ * Cookies are deliberately left intact: the session is probably valid and the
+ * verification path (Convex) is simply unavailable, so discarding it would sign
+ * out every user during an outage. `/unauthorized` is exempt from this proxy, so
+ * this cannot loop.
+ *
+ * @param request - The request that could not be verified.
+ * @returns A redirect to the unauthorized page.
+ */
+function redirectToUnauthorized(request: NextRequest) {
+  return NextResponse.redirect(new URL("/unauthorized", request.url));
+}
+
+export const config = {
+  // Allowlist, not denylist. The base template denies everything except a few
+  // paths; here the public site IS the product, so the gate names the private
+  // surfaces explicitly. Anything added under `(vexcms)` must be added here.
+  matcher: ["/admin/:path*", "/((?!_next/static|_next/image|favicon.ico).*)"],
+};

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

@@ -0,0 +1,27 @@
+import { authOptions } from "@convex/auth/options"
+import { betterAuthAdapter } from "@vexcms/better-auth"
+import { defineServerConfig } from "@vexcms/core"
+import { convexFileStorage } from "@vexcms/file-storage-convex"
+
+import vexConfig from "./vex.config"
+
+/**
+ * VexCMS server-only configuration for the marketing site.
+ *
+ * Layers the Better Auth adapter and Convex file storage onto the
+ * client-safe `vexConfig`. You write this file once at scaffold time and
+ * rarely revisit it — day-to-day settings live in `vex.config.ts`.
+ *
+ * @see ./vex.config for the client-safe half this layers onto
+ */
+const config = defineServerConfig({
+  config: vexConfig,
+  server: {
+    auth: { adapter: betterAuthAdapter({ config: authOptions }) },
+    storage: {
+      adapters: [convexFileStorage()],
+    },
+  },
+})
+
+export default config

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

@@ -1,35 +1,53 @@
-import { betterAuthAdapter } from "@vexcms/better-auth"
+import { betterAuthCollections } from "@vexcms/better-auth/client"
 import { defineConfig } from "@vexcms/core"
-import { convexFileStorage } from "@vexcms/file-storage-convex"
+import { uploadFile } from "@vexcms/file-storage-convex/client"
 
-import { authOptions } from "@convex/auth/options"
+import { authSchema } from "@convex/auth/schema"
 
 import { access } from "~/auth/access"
+import { resolvePagePath } from "~/lib/resolvePagePath"
 import { footers, headers, images, pages, themes, users } from "~/vexcms/collections"
 import { siteSettings } from "~/vexcms/globals"
 
 /**
- * VexCMS configuration for the marketing site.
+ * VexCMS client-safe configuration for the marketing site.
  *
  * Replaces `templates/base-nextjs`'s bare config wholesale (overlay copy is
  * file-level, not a merge): carries base's `users`/`images` forward unchanged
- * and adds the four marketing collections plus `siteSettings`. `vex dev`/
- * `vex generate` consume this to produce the Convex schema and TypeScript
- * types.
+ * and adds the four marketing collections plus `siteSettings`. Imported
+ * directly by the browser via `VexConfigProvider`.
+ *
+ * @see ./vex.config.server for the auth adapter and storage adapter wiring
  */
 const vexConfig = defineConfig({
   access,
+  authCollections: betterAuthCollections(authSchema),
   admin: {
     sidebar: {
       side: "right",
     },
   },
-  authAdapter: betterAuthAdapter({ config: authOptions }),
   storage: {
-    adapters: [convexFileStorage({ mediaCollections: [images] })],
+    clientUploads: { convex: uploadFile },
   },
   collections: [users, pages, headers, footers, themes],
+  mediaCollections: [images],
   globals: [siteSettings],
+  routes: {
+    map: ({ collection, doc }) => {
+      if (collection !== pages.slug) return []
+      const { slug } = doc
+      if (typeof slug !== "string") return []
+      const path = resolvePagePath(slug)
+      return path === undefined ? [] : [path]
+    },
+  },
+  livePreview: {
+    allowedOrigins: [
+      "http://localhost:3000",
+      ...(process.env.NEXT_PUBLIC_SITE_URL ? [process.env.NEXT_PUBLIC_SITE_URL] : []),
+    ],
+  },
 })
 
 export default vexConfig