create-vitnode-app 2.0.0-canary.1 → 2.0.0-canary.10

package/copy-of-vitnode-app/root/src/router.tsx

@@ -3,6 +3,8 @@ import type { AnyRouter } from "@tanstack/react-router";
 import { createRouter as createTanStackRouter } from "@tanstack/react-router";
 import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";
 import { createVitNodeQueryClient } from "@vitnode/core/lib/query-client";
+import { createLocaleRewrite } from "@vitnode/core/tanstack/i18n";
+import { pageHead } from "@vitnode/core/tanstack/metadata";
 import { RoutePendingSpinner } from "@vitnode/core/tanstack/pending";
 import {
   pluginRouteSpecs,
@@ -14,190 +16,32 @@ import {
   withCoreRootRoutes,
 } from "@vitnode/core/tanstack/routes";
 
-/**
- * The auth transport, registered by importing the module that declares it.
- *
- * `@vitnode/core/tanstack/auth` owns every auth decision this app makes but may
- * not declare a `createServerFn` - uncompiled on the server, one silently
- * resolves to `undefined` - so `lib/auth.ts` declares the eight wrappers and
- * hands them over at module scope. A bare import because there is nothing to
- * name: the registration *is* the module's effect.
- *
- * Here because a router is the one module both entry points load, so the
- * registration has happened before any route, loader or component can reach for
- * it, in the browser bundle and on the server alike.
- */
-import "./lib/auth";
-/**
- * The admin transport, registered the same way and for the same reason.
- *
- * One server function rather than eight, reading the AdminCP's own session under
- * its own cookie. It is a separate registration from the auth one on purpose:
- * they are two sessions, two cookies and two cache entries, and nothing in
- * VitNode may let the public session answer an admin question.
- */
-import "./lib/admin-auth";
-import { createLocaleRewrite, localeRouting } from "./lib/i18n/runtime";
-import { pageHead } from "./lib/page-head";
+import { localeRouting } from "./lib/i18n";
 import { pluginRouteSources } from "./plugin-routes.gen";
 import { Route as adminShellRoute } from "./routes/_admin";
 import { Route as mainShellRoute } from "./routes/_main";
 import { routeTree as fileRouteTree } from "./routeTree.gen";
 
-/**
- * The Content Engine registry, behind a literal dynamic import.
- *
- * Awaited by the one loader that needs it - `/admin/content/*` - rather than
- * imported here. Building the registry reaches `@vitnode/core/content` and
- * every configured plugin's admin form components, and this module is the one
- * the client entry evaluates on every page: as a static import it put `zod`,
- * every plugin's content registrations, the content form primitives and
- * `react-hook-form` in front of the front page's first paint. See
- * `CoreAdminRouteContext.loadContentRegistry`.
- */
 const loadContentRegistry = async () =>
-  (await import("./lib/content-registry")).contentRegistry;
+  (await import("./content-registry.gen")).contentRegistry;
 
-/**
- * One route tree: this app's route files, plus the AdminCP screens `@vitnode/core`
- * owns, plus the pages its plugins declare.
- *
- * At module scope rather than inside `getRouter`, because `getRouter` runs once
- * per server request and mounting the plugin routes mutates the route tree - the
- * generated tree is a module singleton. `withPluginRoutes` is idempotent anyway;
- * doing it once is simply where it belongs.
- *
- * The plugin half comes from one generated file: a static import of each
- * configured plugin's own route tree. No plugin page is copied into
- * `src/routes`, no route path is written by hand, and nothing here knows which
- * plugins are installed - see `@vitnode/core/tanstack/plugin-routes`.
- *
- * A page is reached only through the literal `lazy(() => import(...))` its route
- * declared, so every one of them is a chunk of its own. The one part of a plugin
- * route that is not lazy is a `search` schema: a router's `validateSearch` runs
- * during path matching, before any chunk is fetched, so it lives in the tree
- * rather than in the page.
- *
- * `mountUnder` names one route per shell, which is the whole of what "a plugin
- * route renders in the application shell" amounts to here. A plugin declares
- * `area: "main"` or `area: "admin"`; `_main` is the route that renders the
- * public shell and `_admin` the one that renders the AdminCP, and being a child
- * of one of them is what gives `/example` the header and the one `<main>` that
- * `/discover` has, or gives `/admin/reports` the sidebar, the breadcrumb area
- * and the admin session guard that `/admin/core` has. No new field, no per-route
- * layout metadata and no second copy of either shell - route composition, which
- * the area declaration already described.
- *
- * Neither shell changes a path: both are pathless, so `/example` stays
- * `/example` and an admin plugin route's `/admin/…` is the path its own route
- * spells out in full. An area VitNode knows and this app has not named here
- * fails the composition rather than being mounted under the other one.
- *
- * `_main` and `_admin` are imported for their route objects, and they are the
- * same objects the generated tree holds: `createFileRoute` produces one instance
- * per module and `routeTree.gen.ts` mutates it in place.
- *
- * `withCoreMainRoutes`, `withCoreAdminRoutes` and `withCoreRootRoutes` mount
- * core's own screens the same way, one per mount point: the public pages under
- * the main shell, the AdminCP's under its own, and the shell-less ones - the auth
- * cards and the AdminCP sign-in - straight under the root.
- *
- * They were twenty-nine route files in this application until
- * `@vitnode/core/tanstack/routes` existed, every one of them pure wiring around
- * something imported from the package - so an app carried a copy of VitNode's own
- * routing table and core adding a screen meant an edit here. They are code-based
- * rather than declared as plugin routes because they need the router's full
- * option set: a real `validateSearch` that clamps `?page=999` before anything
- * renders, a `beforeLoad` guard that runs before any chunk is fetched, and a
- * splat path a plugin route path does not represent.
- *
- * `localeRouting` goes to the last of the three because a sign-in navigates to a
- * path a *visitor* supplied: the route tree carries no locale, so the prefix has
- * to be stripped before the router sees it, and which prefixes exist is this
- * app's answer. It is the same object the `rewrite` below uses.
- *
- * `pageHead` is this app's own `createRouteHead(metadata)` binding, handed over
- * because a package cannot know the site's name: a plugin page's `<title>` goes
- * through the same `"<page> - <site>"` rule every other VitNode page's does,
- * rather than through a second one the plugin invented.
- */
 const routeTree = withCoreRootRoutes(
   withCoreAdminRoutes(
     withCoreMainRoutes(
-      withPluginRoutes(
-        fileRouteTree,
-        pluginRouteSpecs(pluginRouteSources),
-        {
-          mountUnder: { admin: adminShellRoute, main: mainShellRoute },
-          pageHead,
-        },
-      ),
-      { mountUnder: mainShellRoute, pageHead },
+      withPluginRoutes(fileRouteTree, pluginRouteSpecs(pluginRouteSources), {
+        mountUnder: { admin: adminShellRoute, main: mainShellRoute },
+        pageHead,
+      }),
+      { localeRouting, mountUnder: mainShellRoute, pageHead },
     ),
     { loadContentRegistry, mountUnder: adminShellRoute, pageHead },
   ),
   { localeRouting, mountUnder: fileRouteTree, pageHead },
 );
 
-/**
- * The app's router, and the QueryClient it owns.
- *
- * Start calls this once per server request and once in the browser, which is
- * exactly the lifetime a QueryClient should have: created here, it is per
- * request on the server - never a module-level client shared by every visitor
- * being rendered at once - and a single long-lived one on the client.
- *
- * It goes into the router context, so a route loader reaches it as
- * `context.queryClient` and can `ensureQueryData` before its component renders.
- * That is the whole point of putting it here rather than in a provider: a
- * loader runs before React does, so a client mounted by a component would be
- * out of reach of the code that most wants it.
- *
- * `setupRouterSsrQueryIntegration` wires the two together: it dehydrates the
- * cache into the SSR stream (including queries that resolve mid-render),
- * hydrates it on the client before the first render, routes `redirect()` thrown
- * inside a query or mutation through the router, and wraps the app in the one
- * `QueryClientProvider` for this client. Nothing else in this app may create a
- * `QueryClient` or a provider for one - two clients in a page means a query a
- * loader cached is invisible to the component that reads it.
- *
- * `defaultPreloadStaleTime: 0` leaves caching to Query rather than having the
- * router keep a second copy of the same data with its own expiry.
- *
- * `defaultStaleReloadMode: 'blocking'` is what makes a route's pending shape
- * reachable at all once preloading is on. Router core's default is
- * `'background'`, and a background reload never opens a pending window - but it
- * still waits for the route's component chunk before it commits. So the common
- * desktop path, hover a link and click it, took the one branch that renders
- * nothing: the hover filled the loader, the click was therefore a background
- * reload, and the chunk downloaded with the previous page still on screen and
- * no skeleton in sight.
- *
- * It costs nothing here because a VitNode loader does not block on a warm cache:
- * `ensureQueryData` with `revalidateIfStale` hands back the cached entry and
- * refreshes behind it, so "blocking" describes a promise that resolves in a
- * microtask. What changes is only that the router now marks the match pending
- * while that happens, which is what `defaultPendingMs` is for.
- *
- * `defaultPendingMs: 150` is that threshold, and it is not zero for the same
- * reason. At zero, every navigation opens a pending window, so
- * `defaultPendingMinMs` holds a *fully cached* navigation behind a skeleton for
- * 300ms - a page that could have been instant, made slow to look busy. At 150ms
- * a cached navigation goes straight through with nothing shown and a slow one
- * still gets its shape, in the content area and the breadcrumb together.
- *
- * `rewrite` is what makes one route tree serve two public URL shapes: `/pl/...`
- * arrives, `/...` is matched, and every link the router builds gets the prefix
- * back. No route file mentions a locale, so nothing here has to be duplicated
- * per language - see `@vitnode/core/tanstack/i18n`.
- */
 export function getRouter() {
   const queryClient = createVitNodeQueryClient();
 
-  // The rewrite reads the locale off the router's own current location, and the
-  // router needs the rewrite to parse that location - so it is handed a getter
-  // rather than the router itself. `output` only ever runs once a link is built,
-  // which is long after the assignment below.
   const holder: { current?: AnyRouter } = {};
 
   const router = createTanStackRouter({

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

@@ -16,41 +16,21 @@ import {
   resolveLocale,
   useLocale,
 } from "@vitnode/core/tanstack/i18n";
-import {
-  ErrorActions,
-  NotFound,
-  VitNodeRootProviders,
-} from "@vitnode/core/tanstack/layout";
+import { VitNodeRootProviders } from "@vitnode/core/tanstack/layout";
 
-import type { Locale } from "#/lib/i18n/shared";
+import type { Locale } from "@/vitnode.config";
 
-import { vitNodeShellConfig } from "#/vitnode.shell.config";
+import { vitNodeConfig } from "@/vitnode.config";
 
 import appCss from "../styles.css?url";
 
-const { debug, i18n, metadata, theme } = vitNodeShellConfig;
+const { debug, editor, i18n, metadata, theme } = vitNodeConfig;
 
-/**
- * What the router itself provides, before any route has run.
- *
- * The QueryClient, and nothing else. `beforeLoad` below adds `locale` on top, so
- * what a loader actually receives is `{ queryClient, locale }` - the language
- * included, because a loader that fetches anything user-facing needs to know
- * which one it is fetching.
- */
 export interface RootRouterContext {
   queryClient: QueryClient;
 }
 
 export const Route = createRootRouteWithContext<RootRouterContext>()({
-  /**
-   * The request's language, resolved once and handed to every loader below.
-   *
-   * The same function the rewrite and the components use, so there is one answer
-   * per request rather than one per consumer. Note that a language switch does
-   * not change the *internal* URL - only the public one - so the switcher
-   * invalidates the router to bring this back in step.
-   */
   beforeLoad: ({ location }) => ({
     locale: resolveLocale<Locale>(publicPathnameOf(location)),
   }),
@@ -58,16 +38,7 @@ export const Route = createRootRouteWithContext<RootRouterContext>()({
   head: () => ({
     links: [
       { href: appCss, rel: "stylesheet" },
-      /*
-       * The tab icon, from `public/favicon.ico`.
-       *
-       * Stated rather than left to the browser's automatic `/favicon.ico`
-       * request, because that request is a 404 until the file exists and a
-       * silently missing icon is easy to never notice. Drop your own 32px `.ico`
-       * at `public/favicon.ico`; it lives there rather than being imported so
-       * that the URL is stable and the file is still reachable at the well-known
-       * path browsers ask for unprompted.
-       */
+
       {
         href: "/favicon.ico",
         rel: "icon",
@@ -78,102 +49,28 @@ export const Route = createRootRouteWithContext<RootRouterContext>()({
     meta: [
       { charSet: "utf-8" },
       { content: "width=device-width, initial-scale=1", name: "viewport" },
-      // The default title, from the app's config. A route that names itself
-      // renders `"<page> - <shortTitle>"` instead, through `formatPageTitle` -
-      // the same rule Next.js applies through `title.template`.
       { title: metadata.title },
     ],
   }),
-  /**
-   * Warm this language's shell strings before anything renders.
-   *
-   * `context.locale` rather than a default: `/pl` has to arrive with Polish
-   * already in the cache, or the first paint is English and the page flips after
-   * hydration.
-   */
   loader: async ({ context }) => {
-    await context.queryClient.ensureQueryData(
-      intlQueryOptions({ locale: context.locale }),
-    );
+    await context.queryClient.query({
+      ...intlQueryOptions({ locale: context.locale }),
+      staleTime: "static",
+    });
   },
-  /**
-   * Every URL this application does not serve.
-   *
-   * The last resort, and until now there was none: a path that matched no route
-   * at all fell through to TanStack Router's own `<p>Not Found</p>` - no shell,
-   * no strings, no way back - and the router warned about the missing option on
-   * every such navigation. `/admin/contents` and a hand-typed `/blog/post-30`
-   * both landed there.
-   *
-   * ## What reaches it, and what does not
-   *
-   * Only a path **no route matched**. A route that matched and then answered
-   * `notFound()` from its own loader is caught by the nearest
-   * `notFoundComponent` above it, which is why `/admin/content/nope` and
-   * `/admin/content/blog/articles/999999/edit` render the AdminCP's 404 inside
-   * the panel rather than this - see `_admin`'s, which mounts the shell around
-   * the same message.
-   *
-   * ## It is a 404, and not a redirect anywhere
-   *
-   * The route tree is the whole application, so a URL that reaches here is one
-   * somebody typed or a stale bookmark, and saying so is the honest answer.
-   * Bouncing an unmatched path at some other origin would hide a genuinely
-   * missing page behind a hop to a server that 404s it anyway. Where a URL is
-   * served from is a deployment question, and a proxy in front of the app
-   * answers it better than this route can.
-   */
-  notFoundComponent: RootNotFound,
   shellComponent: RootDocument,
 });
 
-/**
- * Rendered inside `RootComponent`, which is what makes the strings work: the
- * providers it mounts include `RouteMessages` with `core.global`, and that is
- * the namespace `NotFound` reads its two lines from. The root's loader has
- * already warmed that entry, so nothing suspends.
- */
-function RootNotFound() {
-  return <NotFound actions={<ErrorActions />} />;
-}
-
-/**
- * The VitNode provider tree, mounted once above every route.
- *
- * Every provider in it is shared with the Next.js app - the theme, the toaster,
- * the tooltip provider, the WebSocket - plus the pair of `use-intl` records that
- * only a package can name. `VitNodeRootProviders` owns all of it, including the
- * argument for why the realtime listeners are inside it rather than in the main
- * shell.
- *
- * What this route contributes is the two things an application owns: which
- * languages it serves, and its theme defaults.
- *
- * Because the locale comes from router state, changing language re-renders this:
- * new locale, new query key, new messages, no page reload.
- */
 function RootComponent() {
   return (
-    <VitNodeRootProviders config={{ debug, locales: i18n.locales, theme }}>
+    <VitNodeRootProviders
+      config={{ debug, editor, locales: i18n.locales, theme }}
+    >
       <Outlet />
     </VitNodeRootProviders>
   );
 }
 
-/**
- * The document itself.
- *
- * `lang` is the language this request actually resolved to - `en` for `/`, `pl`
- * for `/pl`, and on a route outside the localized URL space (`/admin`) whatever
- * the visitor's cookie says. It comes from the same router state the provider
- * reads, so the two cannot disagree and hydration has nothing to complain about.
- *
- * `ThemeScript` has to be in the head, and it has to be inline: it applies the
- * stored theme to `<html>` before the browser paints, so the first frame is the
- * theme the visitor chose rather than a flash of the default one.
- * `suppressHydrationWarning` covers the attributes it writes, which by design
- * differ from what the server rendered.
- */
 function RootDocument({ children }: { children: React.ReactNode }) {
   const locale = useLocale();
 

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

@@ -1,67 +1,17 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { AdminBreadcrumb } from "@vitnode/core/tanstack/admin";
+import { adminBreadcrumb } from "@vitnode/core/tanstack/admin";
 import {
   AdminDashboardRouteContent,
   loadAdminDashboardRoute,
 } from "@vitnode/core/tanstack/admin/dashboard";
 
-/**
- * `/admin/core` - the AdminCP dashboard, and the one route file `_admin` keeps.
- *
- * Topology only. The layout query, the widget catalogue, the drag-and-drop
- * board, the settings dialogs and the four mutations behind them are
- * `@vitnode/core/tanstack/admin/dashboard`.
- *
- * ## Why this one file is still here
- *
- * Every other AdminCP screen is `@vitnode/core`'s, mounted by
- * `withCoreAdminRoutes` as a code-based route - see `src/router.tsx`. This one
- * stays because the file-based generator requires it to, and the requirement is
- * sharp rather than stylistic:
- *
- * - A pathless layout with no file children is **dropped from the generated
- *   tree**. `buildRouteTreeConfig` skips it outright, so `_admin` would not be
- *   in `routeTree.gen.ts` at all and the route object `src/router.tsx` mounts
- *   core's screens under would be an orphan.
- * - It also collapses to a full path of `/`, which collides with `_main/index.tsx`
- *   and fails the generator's uniqueness check by name.
- *
- * So `_admin` needs one file-based child with a real path in order to exist, and
- * this is it - which is the same job it has always had. It was the shell's first
- * child for exactly this reason, and now it is the only one.
- *
- * Deleting it does not remove a screen; it removes the AdminCP.
- *
- * ## No `head`, deliberately
- *
- * The Next.js page exports no `generateMetadata`, so the tab keeps the site's
- * own name. Declaring `title: 'VitNode'` here would render "VitNode - VitNode"
- * through `formatPageTitle`; saying nothing inherits the root's title and
- * `_admin`'s `noindex`, which is the parity-preserving answer.
- *
- * ## `pluginWidgets` is not passed
- *
- * A plugin's dashboard widgets reach the Next.js board through
- * `getVitNodeConfig()`, which is server-side config kept out of this app's
- * browser bundle by `vitnode.shell.config.ts` - and this app registers its
- * plugins by id and messages only (see `src/vitnode.config.ts`). So the board
- * shows core's own widgets, which is the complete set for this install. It is
- * the same seam `AdminShell` leaves open for nav `declarations`, and it changes
- * here when plugin AdminCP registration moves over.
- */
+
 export const Route = createFileRoute("/_admin/admin/core/")({
   loader: async ({ context }) => await loadAdminDashboardRoute(context),
   component: AdminDashboardRoute,
-  /**
-   * The whole of how an admin route contributes to the trail in the shell's
-   * header: the route declares its own crumb next to its own component, the
-   * shell renders whichever matched route declared the deepest one, and there is
-   * no map from pathname to breadcrumb anywhere. The label comes from the
-   * *visible* navigation, so this reads "Core" in whatever language the
-   * administrator is using without this file naming a string.
-   */
+  
   staticData: {
-    breadcrumb: <AdminBreadcrumb segments={["core"]} />,
+    breadcrumb: adminBreadcrumb({ segments: ["core"] }),
   },
 });