createVexRevalidateRoute

createVexRevalidateRoute(props): object

Defined in: packages/next/src/cache/createVexRevalidateRoute.ts:102

Creates a Next.js route handler that purges the cached paths affected by a document write. The admin panel calls this via useVexMutation after every successful create/update/delete, same-origin, as a relative fetch — no URL config, no shared secret.

Session-authorized, not secret-authorized. The caller is a signed-in admin, so this reuses getToken/getAuth exactly like the admin panel route does, rather than introducing an env var or a shared secret. There is no API-key fallback: a caller with no browser session cannot reach this route as designed.

Path-based, not tag-based. revalidatePath is the only purge mechanism. cacheComponents: true — required for cacheTag/revalidateTag — is incompatible with the dynamic/runtime segment configs the auth and admin routes require (measured: 5 files fail to build with it enabled), so revalidateTag is not an option in this codebase. Do not “upgrade” this to tag-based revalidation without first removing that segment-config dependency everywhere.

Never fails the caller past authorization. A missing session returns 401, a session without write permission 403, and an oversized changes batch 413 — all three reject before any map work runs. Past that point the handler never throws or returns 5xx: an unconfigured map, a throwing map, or an individual revalidatePath failure all resolve to 200 with the failures reported in the body. A failed purge is a stale page; failing the endpoint would only teach the fire-and-forget caller to retry pointlessly.

Parameters

props

CreateVexRevalidateRouteProps

Config and the host app’s auth accessors.

Returns

object

{ POST } — mount directly as the route module’s named export.

POST

POST: (request) => Promise<NextResponse<VexRevalidateResponse | { error: string; }>>

Parameters

request

NextRequest

Returns

Promise<NextResponse<VexRevalidateResponse | { error: string; }>>

Example

app/api/vex/revalidate/route.ts

import { api } from "@convex/_generated/api";
import { createVexRevalidateRoute } from "@vexcms/next/cache";
import { fetchAuthQuery, getToken } from "~/auth/server";
import config from "~/vex.config";

export const { POST } = createVexRevalidateRoute({
  config,
  getToken,
  getAuth: () => fetchAuthQuery(api.auth.api.getUserOrg, {}),
});