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

package/copy-of-vitnode-app/root/src/locales/packages.ts

@@ -0,0 +1,43 @@
+import type { LocaleMessagesMap } from "@vitnode/core/lib/i18n/types";
+
+import { CONFIG_PLUGIN as CORE } from "@vitnode/core/config";
+
+/**
+ * Where this app reads each installed package's translations from.
+ *
+ * Every VitNode package ships a locale barrel - `@vitnode/core/locales/index` -
+ * that loads its own files with a runtime
+ * `import("./en.json", { with: { type: "json" } })`. Under Node that is exactly
+ * right, and it is how an API app reads them.
+ *
+ * It cannot work here, and the reason is the import attribute rather than
+ * anything about VitNode. Vite and Nitro inline `@vitnode/core`'s build output
+ * into this app's server chunks - `ssr.external` applies to the SSR pass, not to
+ * Nitro's own bundling - but Rollup will not follow a dynamic import that
+ * carries `with: { type: "json" }`, so it neither emits the JSON nor rewrites
+ * the specifier. What ships is a relative import pointing next to a chunk that
+ * the JSON was never copied to, and every string on the page renders as its own
+ * key.
+ *
+ * So the loaders are declared here instead, with static specifiers a bundler can
+ * follow. Each resolves through the package's `./locales/*.json` export to the
+ * real file and lands in the build as a chunk fetched on demand, which is the
+ * same laziness the barrels wanted.
+ *
+ * **Add a line here for every plugin you install.** A plugin registered in
+ * `vitnode.config.ts` with no entry in this map renders its own strings as keys:
+ *
+ *     import { CONFIG_PLUGIN as BLOG } from '@acme/blog/const'
+ *
+ *     [BLOG.pluginId]: {
+ *       en: async () => await import('@acme/blog/locales/en.json'),
+ *     },
+ *
+ * This is the app's only copy of that list - `vitnode.server.config.ts` reads it
+ * from here.
+ */
+export const packageMessages: Record<string, LocaleMessagesMap> = {
+  [CORE.pluginId]: {
+    en: async () => await import("@vitnode/core/locales/en.json"),
+  },
+};

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

@@ -0,0 +1,227 @@
+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 { RoutePendingSpinner } from "@vitnode/core/tanstack/pending";
+import {
+  pluginRouteSpecs,
+  withPluginRoutes,
+} from "@vitnode/core/tanstack/plugin-routes";
+import {
+  withCoreAdminRoutes,
+  withCoreMainRoutes,
+  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 { 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;
+
+/**
+ * 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 },
+    ),
+    { 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({
+    context: { queryClient },
+    defaultPendingComponent: RoutePendingSpinner,
+    defaultPendingMs: 150,
+    defaultPendingMinMs: 300,
+    defaultPreload: "intent",
+    defaultPreloadStaleTime: 0,
+    defaultStaleReloadMode: "blocking",
+    rewrite: createLocaleRewrite(() => holder.current),
+    routeTree,
+    scrollRestoration: true,
+  });
+
+  holder.current = router;
+
+  setupRouterSsrQueryIntegration({ queryClient, router });
+
+  return router;
+}
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: ReturnType<typeof getRouter>;
+  }
+}

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

@@ -0,0 +1,212 @@
+import type { QueryClient } from "@tanstack/react-query";
+
+import { TanStackDevtools } from "@tanstack/react-devtools";
+import { ReactQueryDevtoolsPanel } from "@tanstack/react-query-devtools";
+import {
+  createRootRouteWithContext,
+  HeadContent,
+  Outlet,
+  Scripts,
+} from "@tanstack/react-router";
+import { TanStackRouterDevtoolsPanel } from "@tanstack/react-router-devtools";
+import { ThemeScript } from "@vitnode/core/components/theme-script";
+import {
+  intlQueryOptions,
+  publicPathnameOf,
+  resolveLocale,
+  useLocale,
+} from "@vitnode/core/tanstack/i18n";
+import {
+  ErrorActions,
+  NotFound,
+  VitNodeRootProviders,
+} from "@vitnode/core/tanstack/layout";
+
+import type { Locale } from "#/lib/i18n/shared";
+
+import { vitNodeConfig } from "#/vitnode.config";
+
+import appCss from "../styles.css?url";
+
+const { debug, 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)),
+  }),
+  component: RootComponent,
+  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",
+        sizes: "32x32",
+        type: "image/x-icon",
+      },
+    ],
+    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 }),
+    );
+  },
+  /**
+   * 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 }}>
+      <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();
+
+  return (
+    <html lang={locale} suppressHydrationWarning>
+      <head>
+        <HeadContent />
+        <ThemeScript {...theme} />
+      </head>
+
+      <body suppressHydrationWarning>
+        {children}
+
+        {import.meta.env.DEV ? (
+          <TanStackDevtools
+            config={{
+              position: "bottom-right",
+            }}
+            plugins={[
+              {
+                name: "TanStack Router",
+                render: <TanStackRouterDevtoolsPanel />,
+              },
+              {
+                name: "TanStack Query",
+                render: <ReactQueryDevtoolsPanel />,
+              },
+            ]}
+          />
+        ) : null}
+
+        <Scripts />
+      </body>
+    </html>
+  );
+}

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

@@ -0,0 +1,69 @@
+import { createFileRoute } from "@tanstack/react-router";
+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 declares widgets in its `admin.dashboard.widgets`, which reaches a
+ * Next.js board through `getVitNodeConfig()`. This route does not read the
+ * config - the AdminCP takes its plugin data from the generated projections, and
+ * neither of those carries widgets - so the board shows core's own, which is the
+ * complete set for this install because no configured plugin declares any. It is
+ * the same seam `AdminShell` leaves open for nav `declarations`.
+ */
+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"]} />,
+  },
+});
+
+function AdminDashboardRoute() {
+  return <AdminDashboardRouteContent {...Route.useLoaderData()} />;
+}