create-vitnode-app 1.2.0-canary.9 → 2.0.0-canary.2

package/copy-of-vitnode-app/root/src/routes/_admin.tsx

@@ -0,0 +1,258 @@
+import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
+import {
+  ADMIN_ENTRY_PATH,
+  AdminNotFound,
+  adminReturnToFor,
+  canEnterAdmin,
+  ensureAdminAccess,
+  loadAdminMessages,
+  preloadAdminAccess,
+} from "@vitnode/core/tanstack/admin";
+import { ErrorActions } from "@vitnode/core/tanstack/layout";
+
+import { AdminShell } from "#/components/admin-shell";
+import { pageHead } from "#/lib/page-head";
+
+/**
+ * The boundary every AdminCP page sits under - the admin session guard, and the
+ * shell.
+ *
+ * Pathless: the leading underscore means it contributes no URL segment, so
+ * `routes/_admin/core/index.tsx` is `/admin/core`, guarded, and the guard is
+ * this file. A page joins the AdminCP by *where its file lives*, not by
+ * remembering to check a session.
+ *
+ * ## It is not under `_authenticated`, and must not be
+ *
+ * The AdminCP has its own session, under its own cookie (`vitnode_auth_admin`),
+ * with its own model and its own endpoint. Stacking the public guard above this
+ * one would bounce an administrator to `/login` for a session the AdminCP does
+ * not use - and `AuthState.isAdmin`, which lives on the *public* session, means
+ * "may be offered the AdminCP", not "is inside it". Two cookies, two questions.
+ *
+ * ## Exactly one splat may live under here, and nothing wider
+ *
+ * `admin.content.$.tsx` claims `/admin/content/*` - the Content Engine's own
+ * namespace, which Stage 13 moved into this router. That one is deliberate and
+ * narrow; a second is how the AdminCP breaks.
+ *
+ * `$.tsx`, `admin.$.tsx` or any other catch-all beside it would consume every
+ * *remaining* admin URL, including the ones no route declares. The AdminCP's own
+ * not-found would stop being reachable, a plugin's admin route would be shadowed
+ * by whichever splat sat above it, and nothing would report either - silently,
+ * and all at once. `src/tests/admin-routes.test.ts` pins both halves: that the
+ * content splat sits at exactly that path, and that it is the only one.
+ *
+ * ## Why the check is in `beforeLoad`
+ *
+ * It runs before the loader and long before React, so a visitor without admin
+ * access never receives a byte of an AdminCP page - not a flash, not a
+ * hydration, not a `useEffect` that redirects afterwards. A component-level
+ * check would render the page first and then take it away, which on the server
+ * means admin markup already written into the stream.
+ *
+ * ## A hover is not a navigation
+ *
+ * `defaultPreload: 'intent'` means the router runs this whole chain when a
+ * pointer rests on an admin link, and router-core has no staleness gate on
+ * `beforeLoad` the way it has on a loader - it re-runs it from the top of the
+ * branch every time. With `ADMIN_SESSION_STALE_TIME` at zero that made crossing
+ * the sidebar one server-function POST and one Hono call *per link the mouse
+ * passed over*, for a question nobody had asked yet.
+ *
+ * So the read is chosen by the `preload` flag the router already hands in.
+ * `preloadAdminAccess` is the same query, the same key and the same rejection
+ * behaviour, trusted for thirty seconds - the identical window the public
+ * session has always used for the identical reason. `ensureAdminAccess` and its
+ * `staleTime: 0` are untouched on the path that matters, and that is the whole
+ * of the revocation guarantee: entering a screen is a real navigation, this runs
+ * again with `preload: false`, and the API is asked. Router-core never lets a
+ * preloaded `beforeLoad` result stand in for a navigation's.
+ *
+ * The redirect below is deliberately *not* conditional on `preload`. It is not a
+ * navigation - `preloadClientRoute` catches it and preloads the sign-in page
+ * instead of moving anybody - and skipping it would leave a denied preload
+ * walking into the screen loaders underneath, which would then send admin
+ * requests the API is going to refuse.
+ *
+ * ## A failed read is not a denial
+ *
+ * `ensureAdminAccess` resolves only for an answer the API actually gave - `200`
+ * or `403`. A `429` from the rate limiter, a `500`, an API that is not listening:
+ * all three reject, and that rejection is deliberately left to propagate as an
+ * ordinary route error.
+ *
+ * Only `canEnterAdmin` answering `false` sends anybody to `/admin`. Catching the
+ * rejection and redirecting instead would sign every administrator out of the
+ * AdminCP during an outage and present them with a sign-in form for a session
+ * they already hold - which is precisely what the Next.js `getSessionAdminApi()`
+ * does today, and precisely what this shape exists to stop.
+ *
+ * ## What it is not
+ *
+ * A navigation guard, and only that. `api/config.ts` puts
+ * `globalAdminMiddleware()` in front of every request whose path contains
+ * `/admin/`, each handler re-checks the staff tables, and
+ * `SessionAdminModel.getUser()` re-runs `checkIfUserIsAdmin` against the
+ * database on every request - deleting the session the moment the answer turns
+ * false. So an administrator who edits this app's cached permission set in
+ * devtools gets a visible button and an API that still refuses them. Nothing
+ * here is, or may become, the security boundary.
+ */
+export const Route = createFileRoute("/_admin")({
+  beforeLoad: async ({ context, location, preload }) => {
+    const access = preload
+      ? await preloadAdminAccess(context.queryClient)
+      : await ensureAdminAccess(context.queryClient);
+
+    if (!canEnterAdmin(access)) {
+      // TanStack Router's own control-flow signal: `redirect()` returns a typed
+      // redirect object that the router catches and turns into a navigation
+      // (or, during SSR, a 302). Throwing it is what stops the guard.
+      //
+      // `/admin` is a sibling leaf, not a child of this route, so this cannot
+      // loop: the sign-in page's own guard only redirects *away* on a granted
+      // session, and `sanitizeAdminReturnTo` rejects `/admin` as a target.
+      //
+      // Cast because `/admin` is not in this router's type table: it is
+      // `@vitnode/core`'s code-based route now, mounted by `withCoreRootRoutes`,
+      // and code-based routes are outside the generated tree's types. The
+      // *runtime* is unaffected, and `ADMIN_ENTRY_PATH` is the package's own
+      // constant - so the path and the sign-in route that serves it are still one
+      // fact in one place.
+      // eslint-disable-next-line @typescript-eslint/only-throw-error
+      throw redirect({
+        search: { returnTo: adminReturnToFor(location) },
+        to: ADMIN_ENTRY_PATH,
+      } as unknown as Parameters<typeof redirect>[0]);
+    }
+
+    // Merged into the context of everything below, so a child route reads
+    // `context.adminAccess` already narrowed to the granted half of the union.
+    // It is the same object the guard decided on, from the same cache entry, so
+    // a page cannot disagree with the guard that let it render.
+    return { adminAccess: access };
+  },
+  /**
+   * The shell's strings, warmed before React renders.
+   *
+   * `adminNav.namespaces` is the same array `AdminShell` hands the shell, and it
+   * has to be: the provider reads back the identical `intlQueryOptions` entry
+   * this fills, so warming a different namespace set would fill an entry nobody
+   * looks at and cost a round trip on the first paint anyway. It is not a fixed
+   * list because it cannot be - a plugin group's headings live under that
+   * plugin's own id, and which plugins this installation configured is decided
+   * in `src/admin-nav.gen.ts`.
+   *
+   * ## Imported inside the loader, not above it
+   *
+   * A route file's `loader` body runs only for a navigation into this shell; the
+   * file itself is evaluated in the client entry, on every page of the site. The
+   * generated navigation is not small - it carries every configured plugin's
+   * sidebar icons and its content type definitions, and through those the whole
+   * Content Engine and `zod` - so a static import here put ~45 KB of AdminCP
+   * data, plus `zod`, in front of the front page's first paint. `AdminShell`
+   * imports the same module, and `AdminShell` is this route's `component`, which
+   * is code-split: the two land in the same chunk, so an administrator pays for
+   * it once and everybody else not at all.
+   */
+  loader: async ({ context }) => {
+    const { adminNav } = await import("#/lib/admin-nav");
+
+    await loadAdminMessages({ ...context, namespaces: adminNav.namespaces });
+  },
+  /**
+   * Stated once for the whole panel rather than on each screen.
+   *
+   * The AdminCP is behind a session and must never be indexed. Router merges the
+   * `head` of every matched route and dedupes `meta` by `name`, preferring the
+   * deepest, so an admin screen inherits this by saying nothing - which is
+   * exactly what `RouteHeadOptions` describes. A screen's own `pageHead` adds
+   * only its title and description.
+   */
+  head: () => pageHead({ robots: "noindex, nofollow" }),
+  /**
+   * The AdminCP's 404, rendered inside the shell.
+   *
+   * What reaches it is a screen whose loader called `requireAdminPermission`
+   * and was refused - the same answer `app/[locale]/admin/(auth)/not-found.tsx`
+   * gives in the Next.js AdminCP. Declared here rather than per screen so every
+   * one of them answers a missing permission identically.
+   *
+   * A content URL that resolves to no content type reaches it too, and by the
+   * same route: `loadContentAdminRoute` throws `notFound()` for a splat its
+   * registry cannot name, which is the answer the Next.js catch-all's
+   * `notFound()` gives one navigation later.
+   *
+   * A URL under `/admin` that matches no route at all does *not* reach this one.
+   * Outside `/admin/content`, `_admin` has only declared children - see above -
+   * so such a path matches nothing in this subtree and the router falls back to
+   * its own not-found at the root. That is the correct trade, and the cost is
+   * paid deliberately: rendering an unmigrated admin URL inside this shell would
+   * mean claiming it. (The root has no `notFoundComponent` of its own yet, so
+   * that fallback is currently the router's bare one - for every unmatched URL
+   * in this application, not only admin ones. Giving the root a real 404 page is
+   * its own piece of work.)
+   */
+  notFoundComponent: AdminNotFoundScreen,
+  component: AdminLayout,
+});
+
+/**
+ * The refusal, wearing the panel it was refused inside.
+ *
+ * ## It mounts the shell itself, and has to
+ *
+ * A `notFoundComponent` renders *instead of* the component of the route that
+ * handles the error, not inside it - so this replaces `AdminLayout`, sidebar
+ * and header and palette included. An administrator who opened a screen they
+ * lack the permission for would otherwise be dropped onto a bare 404 page with
+ * no way back into the AdminCP but the browser's back button, which is not what
+ * the Next.js AdminCP does: its `not-found.tsx` sits *under*
+ * `admin/(auth)/layout.tsx` and keeps the panel around the message.
+ *
+ * Mounting `AdminShell` here restores that, and it costs nothing: `beforeLoad`
+ * has already resolved the admin session and the loader above has already
+ * warmed the shell's messages, so the providers inside read the same two cache
+ * entries the working screens read and nothing suspends or fetches again.
+ *
+ * ## What is bound rather than defaulted
+ *
+ * `ErrorActions` is this app's binding rather than core's default: `/` is served
+ * by the Next.js application on some installs and by this one on others, and
+ * only the route tree knows which. It is passed as an element from module scope
+ * so the type is stable across renders.
+ */
+function AdminNotFoundScreen() {
+  return (
+    <AdminShell>
+      <AdminNotFound actions={<ErrorActions />} />
+    </AdminShell>
+  );
+}
+
+/**
+ * The AdminCP shell.
+ *
+ * `AdminShell` is this app's binding of `AdminShellContent` - the sidebar, the
+ * command palette, the breadcrumb area, the user menu and the one `<main>` every
+ * admin page renders inside. It mounts `AdminPermissionsProvider` itself, from
+ * the same admin session query the guard above has already filled, so
+ * `AdminStaffPermissionGate` and `useAdminStaffPermission` work identically here
+ * and in the Next.js AdminCP. It cannot suspend in practice and nothing below it
+ * can suspend at all; see the note on the provider.
+ *
+ * What `#/components/admin-shell` adds on top is only what a package cannot
+ * answer for a particular installation: where the user lookup runs, which
+ * plugins this app configured, and how the command palette moves without a link.
+ *
+ * The guard, the loader and the route options above are the parts that must not
+ * move.
+ */
+function AdminLayout() {
+  return (
+    <AdminShell>
+      <Outlet />
+    </AdminShell>
+  );
+}

package/copy-of-vitnode-app/root/src/routes/_main/index.tsx

@@ -0,0 +1,60 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { pageHead } from "#/lib/page-head";
+
+/**
+ * The front page.
+ *
+ * One route file serving every public URL of the home page: `/` and `/pl` both
+ * match here, because the locale is stripped before matching and written back
+ * into every link the router builds. There is no `routes/pl/index.tsx` and there
+ * does not need to be one.
+ *
+ * **`head` must be written after `loader`** on routes that have one -
+ * `loaderData` is inferred from `loader` in the same object literal, and
+ * TypeScript reads a literal's members in order. This route has no loader: it
+ * fetches nothing, and the shell above it already warmed everything the header
+ * reads.
+ *
+ * `robots: 'index, follow'` is stated rather than assumed. `_main` says nothing
+ * about indexing, and a page that wants to be found should say so where somebody
+ * editing it will see it.
+ */
+export const Route = createFileRoute("/_main/")({
+  head: () =>
+    pageHead({
+      description: "A VitNode application.",
+      robots: "index, follow",
+      title: "Home",
+    }),
+  component: HomeRoute,
+});
+
+/**
+ * Replace this with your own home page.
+ *
+ * No `<main>`: the shell owns the document's one `main` landmark, and a page
+ * that renders a second gives a screen reader two to choose between. A page owns
+ * its container - width, padding, vertical rhythm - and nothing above it.
+ *
+ * The copy is hard-coded because a new app has no strings of its own yet. To
+ * translate it, add the keys to `src/locales/` and read them with
+ * `useTranslations` from `use-intl` - the same hook every VitNode component
+ * uses, on every host.
+ */
+function HomeRoute() {
+  return (
+    <div className="container mx-auto flex max-w-2xl flex-col gap-4 p-4">
+      <h1 className="text-3xl font-semibold tracking-tight text-balance">
+        Welcome to VitNode
+      </h1>
+
+      <p className="text-muted-foreground leading-relaxed text-pretty">
+        Edit <code>src/routes/_main/index.tsx</code> to change this page. The
+        header, the footer and the shell around it are{" "}
+        <code>@vitnode/core</code>&rsquo;s; everything under{" "}
+        <code>src/routes</code> is yours.
+      </p>
+    </div>
+  );
+}

package/copy-of-vitnode-app/root/src/routes/_main.tsx

@@ -0,0 +1,64 @@
+import { createFileRoute, Outlet } from "@tanstack/react-router";
+import { MainBreadcrumb } from "@vitnode/core/tanstack/breadcrumb";
+import {
+  loadMainShell,
+  ThemeLayoutContent,
+} from "@vitnode/core/tanstack/layout";
+
+import { MainHeader } from "#/components/main-header";
+
+/**
+ * The main application shell - the header, the breadcrumb area and the one
+ * `<main>` landmark that every public page renders inside.
+ *
+ * Pathless, so it contributes no URL segment: `/discover` is `/discover`, not
+ * `/_main/discover`. A page joins the shell by *where its file lives*, which is
+ * the same rule `_authenticated` uses for the session guard - and the reason
+ * `_authenticated` lives underneath this one: a signed-in page is still a page
+ * on the public site, so it wants the shell *and* the guard rather than a second
+ * copy of the shell.
+ *
+ * ## What is deliberately outside it
+ *
+ * The four auth screens: `/login`, `/login/sso/$providerId`, `/register` and
+ * `/login/reset-password`. An auth screen is a full-height card on an otherwise
+ * empty document, and the header it would render is a header whose only
+ * interesting control is "sign in". Keeping them out is what makes this a shell
+ * that routes opt into rather than one every route is subject to.
+ * `routes/api/$` is outside for a different reason: it is a server route and
+ * renders no document at all. Note this is a visual difference from the Next.js
+ * app, where all four sit inside `(main)` and do render the header.
+ *
+ * `src/tests/main-shell.test.ts` asserts both halves - the settings paths
+ * inside, the four auth screens outside.
+ *
+ * ## The slots
+ *
+ * `ThemeLayoutContent`'s, and two of the same three the Next.js `ThemeLayout`
+ * fills: `header` and `breadcrumb`.
+ *
+ * `listeners` is deliberately left empty here. The Next.js app puts the
+ * notification toasts and the WebSocket's sign-in resync in it because its
+ * `/login` is inside the main shell; this app's is not, so a sync mounted here
+ * would not exist during the sign-in it has to notice. They are mounted by
+ * `__root` instead, next to the connection whose lifetime they share.
+ *
+ * ## What it is not
+ *
+ * A provider. Every technical provider this app has - the QueryClient, the two
+ * intl records, the theme, the WebSocket - is mounted once by `__root`, above
+ * every route, because a login screen needs them just as much as a page under
+ * this shell does. What lives here is structure: markup, and where the slots go.
+ */
+export const Route = createFileRoute("/_main")({
+  loader: async ({ context }) => await loadMainShell(context),
+  component: MainLayout,
+});
+
+function MainLayout() {
+  return (
+    <ThemeLayoutContent breadcrumb={<MainBreadcrumb />} header={<MainHeader />}>
+      <Outlet />
+    </ThemeLayoutContent>
+  );
+}

package/copy-of-vitnode-app/root/src/server/messages.server.ts

@@ -0,0 +1,21 @@
+import "@tanstack/react-start/server-only";
+import { createIntlMessagesLoader } from "@vitnode/core/tanstack/i18n/server";
+
+import { vitNodeServerConfig } from "#/vitnode.server.config";
+
+export type { IntlMessages } from "@vitnode/core/tanstack/i18n/server";
+
+/**
+ * The messages one page needs, in one language - this app's loader.
+ *
+ * Everything about *how* messages load is core's: the source order (core, then
+ * each plugin, then this app's overrides, later ones winning), the `web` scope
+ * stamped on each so the API's tree in this same process cannot be served in its
+ * place, the per-key fallback to the default locale, and the namespace pick that
+ * keeps every plugin's AdminCP copy out of a page that renders none of it.
+ *
+ * What is this app's is the server config it is handed - the plugins it
+ * registered, the languages it declares, and the loaders that stand in for each
+ * package's own locale barrel.
+ */
+export const loadIntlMessages = createIntlMessagesLoader(vitNodeServerConfig);

package/copy-of-vitnode-app/root/src/start.ts

@@ -0,0 +1,24 @@
+import { createVitNodeStart } from "@vitnode/core/tanstack/start";
+
+import { vitNodeConfig } from "#/vitnode.config";
+
+/**
+ * This app's Start instance.
+ *
+ * The whole request pipeline is VitNode's, and it is mandatory rather than a
+ * default: CSRF protection on server functions, canonical locale redirects with
+ * the remembered-locale cookie, and the `private, no-store` directive every
+ * document carrying a dehydrated session needs.
+ *
+ * Add this app's own request middleware - a request id, a tracing span, a
+ * maintenance gate - with `requestMiddleware`. It runs after all of the above,
+ * which is the only safe place for it: a redirect ends the request, so anything
+ * in front of the locale rule would run twice for every visitor arriving at a
+ * non-canonical URL.
+ *
+ *     export const startInstance = createVitNodeStart({
+ *       config: vitNodeConfig,
+ *       requestMiddleware: [myMiddleware],
+ *     })
+ */
+export const startInstance = createVitNodeStart({ config: vitNodeConfig });

package/copy-of-vitnode-app/root/src/styles.css

@@ -0,0 +1,139 @@
+@import "tailwindcss";
+@import "shadcn/tailwind.css";
+@import "tw-animate-css";
+
+@source "../node_modules/@vitnode/core/dist/src/components";
+@source "../node_modules/@vitnode/core/dist/src/tanstack";
+@source "../node_modules/@vitnode/core/dist/src/views";
+
+:root:not(.dark) {
+  --background: oklch(0.97 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.51 0.16 262.61);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.967 0.001 286.375);
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+  --muted: oklch(0.967 0.001 286.375);
+  --muted-foreground: oklch(0.552 0.016 285.938);
+  --accent: oklch(0.967 0.001 286.375);
+  --accent-foreground: oklch(0.21 0.006 285.885);
+  --destructive: oklch(0.577 0.245 27.325);
+  --warn: oklch(0.54 0.12 82.58);
+  --border: oklch(0.92 0.004 286.32);
+  --input: oklch(0.92 0.004 286.32);
+  --ring: oklch(0.705 0.015 286.067);
+  --chart-1: oklch(0.871 0.006 286.286);
+  --chart-2: oklch(0.552 0.016 285.938);
+  --chart-3: oklch(0.442 0.017 285.786);
+  --chart-4: oklch(0.37 0.013 285.805);
+  --chart-5: oklch(0.274 0.006 286.033);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.141 0.005 285.823);
+  --sidebar-primary: oklch(0.21 0.006 285.885);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.967 0.001 286.375);
+  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
+  --sidebar-border: oklch(0.92 0.004 286.32);
+  --sidebar-ring: oklch(0.705 0.015 286.067);
+}
+
+.dark {
+  --background: oklch(0.14 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.21 0.006 285.885);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.21 0.006 285.885);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.6 0.18 262.65);
+  --primary-foreground: oklch(0.98 0 0);
+  --secondary: oklch(0.274 0.006 286.033);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.274 0.006 286.033);
+  --muted-foreground: oklch(0.705 0.015 286.067);
+  --accent: oklch(0.274 0.006 286.033);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --warn: oklch(0.76 0.18 81.84);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.552 0.016 285.938);
+  --chart-1: oklch(0.871 0.006 286.286);
+  --chart-2: oklch(0.552 0.016 285.938);
+  --chart-3: oklch(0.442 0.017 285.786);
+  --chart-4: oklch(0.37 0.013 285.805);
+  --chart-5: oklch(0.274 0.006 286.033);
+  --sidebar: oklch(0.21 0.006 285.885);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.274 0.006 286.033);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.552 0.016 285.938);
+}
+
+:root {
+  --radius: 0.625rem;
+}
+
+@theme inline {
+  --font-heading: var(--font-sans);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-warn: var(--warn);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --color-foreground: var(--foreground);
+  --color-background: var(--background);
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+
+  html,
+  body {
+    min-height: 100%;
+  }
+
+  body {
+    @apply bg-background text-foreground antialiased;
+  }
+}

package/copy-of-vitnode-app/root/src/vitnode.config.ts

@@ -0,0 +1,73 @@
+import { buildConfig } from "@vitnode/core/vitnode.config";
+
+/**
+ * This app's configuration - the one file every VitNode app edits first.
+ *
+ * **Browser-safe, and everything here has to stay that way.** Three very
+ * different readers depend on it: `routes/__root.tsx` renders the document shell
+ * from `metadata`, `theme` and `debug`; `lib/i18n/runtime.ts` derives the locale
+ * routing from `i18n`; and Vite's own plugin registry loads this file with
+ * `jiti` while it is still resolving its config, to find out which plugins to
+ * generate route, navigation and content-registry imports for. So it is plain
+ * data and plugin *identity* - never a `() => import(...)` message loader, never
+ * a module that reaches a database. Anything like that goes in
+ * `vitnode.server.config.ts`.
+ *
+ * ## Adding a language
+ *
+ * Add an entry to `locales`. Packages ship their own translations, so a new
+ * locale needs nothing else: anything a package has not translated falls back to
+ * `defaultLocale` key by key. Register the package's file for that language in
+ * `src/locales/packages.ts`, and put your own rewording in
+ * `src/locales/app.ts` - both of which `vitnode.server.config.ts` picks up.
+ *
+ * `vitnode i18n:create de Deutsch` does all of it for you.
+ *
+ * ## Adding a plugin
+ *
+ * With the plugin's own factory:
+ *
+ *     import { blogPlugin } from '@acme/blog/config'
+ *
+ *     plugins: [blogPlugin()]
+ *
+ * That is the whole registration - the factory carries the plugin's content
+ * types, its AdminCP navigation and its translations. Register its locale files
+ * in `src/locales/packages.ts` as well, which is what the message loader
+ * actually reads.
+ *
+ * What the AdminCP renders comes back through `src/admin-nav.gen.ts` and
+ * `src/content-registry.gen.ts` rather than out of this object: the build writes
+ * one literal import per configured plugin, and `src/router.tsx` loads the
+ * content registry behind a dynamic `import()`, so a content type's editing
+ * screen arrives with the route that renders it.
+ *
+ * A plugin's *pages* need nothing in this file at all. It declares them in its
+ * own `src/routes.ts`, and this app's Vite build compiles them into
+ * `src/plugin-routes.gen.ts`, which `src/router.tsx` mounts under the shell the
+ * plugin's `area` names. No page is ever copied into `src/routes`.
+ *
+ * `buildConfig` also registers this object process-wide, which is how core's own
+ * route files find it without being handed it as a prop.
+ */
+export const vitNodeConfig = buildConfig({
+  debug: false,
+  i18n: {
+    defaultLocale: "en",
+    locales: [{ code: "en", name: "English" }],
+    /**
+     * Explicit, because the app renders on a server: without one, `use-intl`
+     * formats dates in whatever zone the server happens to run in and warns
+     * that the client will disagree.
+     */
+    timeZone: "UTC",
+  },
+  metadata: {
+    shortTitle: "VitNode",
+    title: "VitNode",
+  },
+  plugins: [],
+  theme: {
+    defaultTheme: "system",
+  },
+});

package/copy-of-vitnode-app/root/src/vitnode.server.config.ts

@@ -0,0 +1,23 @@
+import "@tanstack/react-start/server-only";
+import { buildServerConfig } from "@vitnode/core/vitnode.config";
+
+import { appMessages } from "#/locales/app";
+import { packageMessages } from "#/locales/packages";
+import { vitNodeConfig } from "#/vitnode.config";
+
+/**
+ * The half of this app's configuration a browser may never hold.
+ *
+ * Both entries are `() => import(...)` loaders that read JSON out of a package's
+ * build output, which is exactly what `vitnode.config.ts` cannot carry - so they
+ * live here, beside the shared config rather than duplicating any of it. The
+ * `server-only` marker makes an accidental import from a component a build error
+ * instead of a browser bundle with every plugin's AdminCP copy in it.
+ *
+ * `src/server/messages.server.ts` is the only reader.
+ */
+export const vitNodeServerConfig = buildServerConfig({
+  config: vitNodeConfig,
+  messages: appMessages,
+  packageMessages,
+});