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

package/README.md

@@ -59,8 +59,14 @@ pnpm create vitnode-app@latest --plugin
 npm create vitnode-app@latest -- --plugin
 ```
 
-The generator creates the package and adds its workspace dependency. Register it
-in the host’s `vitnode.config.ts` to enable the feature.
+The generator creates the package and adds its workspace dependency. Enable the
+feature by registering it in the host’s `vitnode.config.ts`:
+
+```ts
+import { myPlugin } from '@acme/my-plugin/config'
+
+plugins: [myPlugin()]
+```
 
 ## Options
 

package/copy-of-vitnode-app/README.md

@@ -38,3 +38,25 @@ To start the development server, run the following command:
 ```bash
 pnpm dev
 ```
+
+## Configuration
+
+Two files, and the line between them is one question: may a browser hold this?
+
+| File                           | Holds                                                                                                                    |
+| :----------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
+| `src/vitnode.config.ts`        | locales, metadata, theme, `debug`, enabled plugin ids - plain data, read by the browser, the server, and your Vite build |
+| `src/vitnode.server.config.ts` | message loaders - server only                                                                                            |
+
+Add a language to `i18n.locales` in the shared config; register the files that
+translate it in `src/locales/packages.ts` (a package's own translations) or
+`src/locales/app.ts` (your rewordings). `pnpm vitnode i18n:create de Deutsch`
+does all three.
+
+`src/start.ts` is one call to `createVitNodeStart`, which installs CSRF
+protection for server functions, canonical locale redirects with the
+remembered-locale cookie, and the `private, no-store` directive every rendered
+document needs. Add your own request middleware with `requestMiddleware` - it
+runs after all of it.
+
+See [Configuration](https://vitnode.com/docs/dev/configuration).

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

@@ -3,8 +3,6 @@ import { config } from "dotenv";
 import { coreRelations } from "@vitnode/core/database/relations";
 import { drizzle } from "drizzle-orm/postgres-js";
 
-import { i18n } from "./i18n.js";
-
 config({
   quiet: true,
 });
@@ -15,14 +13,33 @@ export const POSTGRES_URL =
 export const vitNodeApiConfig = buildApiConfig({
   plugins: [],
   /**
-   * The installation's languages - see `src/i18n.ts`, and keep it in step with
-   * the web app's file of the same name.
+   * The languages this installation serves.
+   *
+   * The API half of a split deployment. `apps/web/src/vitnode.config.ts`
+   * declares the same list, and the two are one declaration in two places by
+   * necessity rather than by design: they are separate packages, so neither can
+   * import the other's. Nothing walks the filesystem looking for the web app's
+   * config either - a bootstrap that guessed at a sibling application is exactly
+   * what that replaced, and it guessed wrong the moment the two were not laid
+   * out the way it expected.
    *
-   * This app owns the schema, so `vitnode db:prepare` seeds `core_languages`
-   * from this list. Leave it out and the seed falls back to `en` alone, whatever
-   * the site serves.
+   * They have to agree, and this is the copy that matters most: this app owns
+   * the schema, so `vitnode db:prepare` seeds `core_languages` from *this* list.
+   * A language that is here and not in the web app's renders nowhere; one that
+   * is in the web app's and not here has no row in the database.
+   *
+   * Packages ship their own translations, so a new locale needs no `messages`
+   * entry - anything untranslated falls back to `defaultLocale` key by key.
    */
-  i18n,
+  i18n: {
+    defaultLocale: "en",
+    locales: [{ code: "en", name: "English" }],
+    /**
+     * Explicit, because this API renders emails on a server: without one, dates
+     * format in whatever zone the host happens to run in.
+     */
+    timeZone: "UTC",
+  },
   dbProvider: drizzle({
     connection: POSTGRES_URL,
     relations: coreRelations,

package/copy-of-vitnode-app/api-single-app/src/vitnode.api.config.ts

@@ -2,7 +2,7 @@ import { buildApiConfig } from "@vitnode/core/vitnode.config";
 import { coreRelations } from "@vitnode/core/database/relations";
 import { drizzle } from "drizzle-orm/postgres-js";
 
-import { i18n } from "./i18n";
+import { vitNodeConfig } from "./vitnode.config";
 
 export const POSTGRES_URL =
   process.env.POSTGRES_URL ?? "postgresql://root:root@localhost:5432/vitnode";
@@ -14,16 +14,15 @@ export const vitNodeApiConfig = buildApiConfig({
   },
   plugins: [],
   /**
-   * The same `src/i18n.ts` the frontend config reads, because this app is both:
-   * one declaration of which languages exist, spread into `buildConfig` through
-   * `vitnode.shell.config.ts` and passed here.
+   * The site's own locale declaration, because this app is both: `vitnode.config.ts`
+   * is the one statement of which languages exist, and both configs read it.
    *
    * It is also what `vitnode db:prepare` seeds `core_languages` from - this app
-   * owns the schema - so adding a language here and re-running `dev` inserts its
-   * row. Leave it out and the seed falls back to `en` alone, whatever the site
-   * serves.
+   * owns the schema - so adding a language there and re-running `dev` inserts
+   * its row. Leave it out and the seed falls back to `en` alone, whatever the
+   * site serves.
    */
-  i18n,
+  i18n: vitNodeConfig.i18n,
   dbProvider: drizzle({
     connection: POSTGRES_URL,
     relations: coreRelations,

package/copy-of-vitnode-app/root/src/lib/admin-nav.ts

@@ -17,13 +17,13 @@ import { pluginAdminNav } from "#/admin-nav.gen";
  *
  * ## Why it is not read from `vitnode.config.ts`
  *
- * That config is server-side on purpose (`vitnode.shell.config.ts` explains the
- * split): it carries message loaders and API wiring, which a browser bundle has
- * no business holding. A sidebar needs the ids, the hrefs, the permissions, the
- * icons and the content type definitions, all of which are plain data. The
- * generated projection is exactly that half, so the browser gets the navigation
- * without the Content Engine's UI - which arrives, when a content screen
- * actually renders, through `src/lib/content-registry.ts` instead.
+ * The config does carry each plugin's registration, and a Next.js host walks it
+ * in its render pass. Reading it here would make every configured plugin's
+ * editing screens reachable from the module the document shell imports, which is
+ * the one graph that is never lazy. The generated projection carries exactly
+ * what a sidebar needs instead - ids, hrefs, permissions, icons and content type
+ * definitions, all plain data - and the Content Engine's UI arrives separately,
+ * when a content screen actually renders, through `src/lib/content-registry.ts`.
  *
  * ## Module scope, and why that matters twice
  *

package/copy-of-vitnode-app/root/src/lib/content-registry.ts

@@ -20,12 +20,13 @@ import { pluginContentTypes } from "#/content-registry.gen";
  *
  * ## Why it is not read from `vitnode.config.ts`
  *
- * That config is server-side on purpose (`vitnode.shell.config.ts` explains the
- * split): it carries message loaders and API wiring, which a browser bundle has
- * no business holding. The generated projection is the browser-safe half - the
- * definitions, the icons and the override components - so the AdminCP gets the
- * content screens without the server config. The same arrangement
- * `src/lib/admin-nav.ts` uses for the sidebar, one layer deeper.
+ * The config does carry each plugin's registration, and a Next.js host reads it
+ * from there. What it cannot give is *when*: it is imported by the document
+ * shell, so anything reachable from it is reachable eagerly. This module is
+ * loaded behind a dynamic `import()` in `src/router.tsx` instead, so the
+ * definitions, the icons and the override components arrive with the content
+ * route - the same arrangement `src/lib/admin-nav.ts` uses for the sidebar, one
+ * layer deeper.
  *
  * ## Registration, and where it belongs in the import graph
  *

package/copy-of-vitnode-app/root/src/lib/i18n/runtime.ts

@@ -2,8 +2,8 @@ import { createServerFn } from "@tanstack/react-start";
 import { configureIntl, validateIntlInput } from "@vitnode/core/tanstack/i18n";
 import { IntlProvider } from "use-intl";
 
-import { i18n } from "#/i18n";
 import { loadIntlMessages } from "#/server/messages.server";
+import { vitNodeConfig } from "#/vitnode.config";
 
 /**
  * One language's messages for one set of namespaces, fetched on the server.
@@ -29,9 +29,9 @@ export const getIntlMessages = createServerFn()
  * Everything in `@vitnode/core/tanstack/i18n` reads what this registers, so a
  * route file imports `RouteMessages` and `intlQueryOptions` straight from the
  * package. What must not happen is a route running before this module has been
- * evaluated - so the two framework entry points, `src/router.tsx` and
- * `src/start.ts`, both import from here, and `src/tests/intl-runtime.test.ts`
- * fails if either stops doing so.
+ * evaluated - so `src/router.tsx`, which owns the route tree, imports from
+ * here. The request pipeline needs no such guarantee: `createVitNodeStart`
+ * derives its own locale routing from the config it is handed.
  *
  * The registration is at module scope but reads `getIntlMessages` above only by
  * reference, so the order within this file does not matter: the validator and
@@ -61,7 +61,7 @@ export const {
    * back to client rendering, and the page still appears.
    */
   hostIntlProvider: IntlProvider,
-  i18n,
+  i18n: vitNodeConfig.i18n,
 });
 
 /**

package/copy-of-vitnode-app/root/src/lib/i18n/shared.ts

@@ -1,17 +1,17 @@
-import type { i18n } from "#/i18n";
+import type { vitNodeConfig } from "#/vitnode.config";
 
 import { localeRouting } from "#/lib/i18n/runtime";
 
 /**
- * A language this app serves, as a type. `"en" | "pl"`, derived from the config
- * rather than written twice.
+ * A language this app serves, as a type. `"en"`, or `"en" | "de"` once a second
+ * one is declared - derived from the config rather than written twice.
  *
  * The one i18n thing this app still owns, and it has to: `@vitnode/core` is
  * installed by apps with different language lists, so it types a locale as
  * `string` and takes this union as a type argument where the value originates
  * (`useLocale<Locale>()`, `resolveLocale<Locale>()`).
  */
-export type Locale = (typeof i18n.locales)[number]["code"];
+export type Locale = (typeof vitNodeConfig.i18n.locales)[number]["code"];
 
 export { defaultLocale, localeRouting } from "#/lib/i18n/runtime";
 

package/copy-of-vitnode-app/root/src/lib/page-head.ts

@@ -1,6 +1,6 @@
 import { createRouteHead } from "@vitnode/core/tanstack/metadata";
 
-import { vitNodeShellConfig } from "#/vitnode.shell.config";
+import { vitNodeConfig } from "#/vitnode.config";
 
 /**
  * A route's `head`, bound to this app's name.
@@ -16,4 +16,4 @@ import { vitNodeShellConfig } from "#/vitnode.shell.config";
  *
  *     head: ({ loaderData }) => pageHead({ robots: 'index, follow', ...loaderData })
  */
-export const pageHead = createRouteHead(vitNodeShellConfig.metadata);
+export const pageHead = createRouteHead(vitNodeConfig.metadata);

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

@@ -21,8 +21,8 @@ import type { AppMessagesMap } from "@vitnode/core/lib/i18n/types";
  * everything it leaves out falls back to the package's, and then to the default
  * locale, key by key.
  *
- * Server-side only, and kept out of `src/i18n.ts` on purpose: these are
- * functions, and `src/i18n.ts` is spread into the shell config, which crosses to
- * the browser and has to stay serializable.
+ * Server-side only, and kept out of `src/vitnode.config.ts` on purpose: these
+ * are functions, and the shared config crosses to the browser and has to stay
+ * serializable. `src/vitnode.server.config.ts` is what registers this map.
  */
 export const appMessages: AppMessagesMap = {};

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

@@ -33,8 +33,8 @@ import { CONFIG_PLUGIN as CORE } from "@vitnode/core/config";
  *       en: async () => await import('@acme/blog/locales/en.json'),
  *     },
  *
- * This is the app's *only* copy of that list - `vitnode.config.ts` and
- * `server/messages.server.ts` both read it from here.
+ * 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]: {

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

@@ -24,11 +24,11 @@ import {
 
 import type { Locale } from "#/lib/i18n/shared";
 
-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, i18n, metadata, theme } = vitNodeConfig;
 
 /**
  * What the router itself provides, before any route has run.

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

@@ -41,13 +41,12 @@ import {
  *
  * ## `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.
+ * 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),

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

@@ -1,8 +1,7 @@
 import "@tanstack/react-start/server-only";
 import { createIntlMessagesLoader } from "@vitnode/core/tanstack/i18n/server";
 
-import { packageMessages } from "#/locales/packages";
-import { vitNodeConfig } from "#/vitnode.config";
+import { vitNodeServerConfig } from "#/vitnode.server.config";
 
 export type { IntlMessages } from "@vitnode/core/tanstack/i18n/server";
 
@@ -15,15 +14,8 @@ export type { IntlMessages } from "@vitnode/core/tanstack/i18n/server";
  * 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, and can only be: the plugins it registered, the languages
- * it declares, and `packageMessages` - the static loaders that stand in for each
- * package's own locale barrel, because a barrel's
- * `import("./en.json", { with: { type: "json" } })` is a specifier Rollup will
- * not follow. See `src/locales/packages.ts` for the reproduction.
+ * 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({
-  appMessages: vitNodeConfig.i18n.messages,
-  defaultLocale: vitNodeConfig.i18n.defaultLocale,
-  packageMessages,
-  plugins: vitNodeConfig.plugins,
-});
+export const loadIntlMessages = createIntlMessagesLoader(vitNodeServerConfig);

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

@@ -1,88 +1,24 @@
-import {
-  createCsrfMiddleware,
-  createMiddleware,
-  createStart,
-} from "@tanstack/react-start";
-import { handleLocaleRequest } from "@vitnode/core/tanstack/i18n/server";
+import { createVitNodeStart } from "@vitnode/core/tanstack/start";
 
-import {
-  applyDocumentCacheControl,
-  applyRedirectCacheControl,
-} from "#/lib/document-headers";
-import { localeRouting } from "#/lib/i18n/runtime";
+import { vitNodeConfig } from "#/vitnode.config";
 
 /**
- * Locale routing, as the first thing that happens to a request.
- *
- * A global request middleware rather than a wrapper around the server entry:
- * Start runs these before route matching and before SSR, which is exactly where
- * a canonical redirect belongs - the alternative is rendering a page and then
- * throwing it away.
- *
- * `handlerType` narrows it to page requests. Server function calls arrive on
- * `/_serverFn/*` with `handlerType: "serverFn"`, and redirecting an RPC to a
- * canonical URL would break it rather than tidy it.
- *
- * `/api/*` reaches here too and is deliberately ignored by
- * `handleLocaleRequest`, so the Stage 1 Hono bridge sees the request exactly as
- * the client sent it.
- *
- * `localeRouting` is handed in rather than read from the package's registered
- * runtime: Start runs request middleware before route matching, so this is the
- * one caller that cannot assume the router entry has been evaluated. Importing
- * it from `#/lib/i18n/runtime` is also what guarantees this app's i18n is
- * configured before the first request touches it.
+ * This app's Start instance.
  *
- * ## And what a document is allowed to say about itself
+ * 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.
  *
- * The cache directive rides along here for one reason: this is already the only
- * place in the application that holds every page response, before and after
- * rendering, and a second middleware would be a second thing to remember. Every
- * document this app produces carries a dehydrated Query cache containing the
- * visitor's own session - and, under `/admin`, an administrator's whole
- * permission set - so none of them may be stored by a shared cache. See
- * `#/lib/document-headers`, which owns the rule and says why; this file only
- * applies it.
- */
-const localeMiddleware = createMiddleware().server(
-  async ({ handlerType, next, request }) => {
-    if (handlerType !== "router") return await next();
-
-    const { redirect, setCookie } = handleLocaleRequest(request, localeRouting);
-    if (redirect) {
-      applyRedirectCacheControl(redirect);
-
-      return redirect;
-    }
-
-    const result = await next();
-
-    // `append`, not `set`: the API mounted at `/api/*` and the auth flow both
-    // mint their own cookies, and overwriting the header would sign people out.
-    if (setCookie) result.response.headers.append("set-cookie", setCookie);
-
-    // After the cookie, so a document that just wrote one is covered by the
-    // same directive as one that did not. Only an HTML response is touched -
-    // `/api/*` reaches here too, and the API's own caching is not this
-    // middleware's to decide.
-    applyDocumentCacheControl(result.response);
-
-    return result;
-  },
-);
-
-/**
- * This app's Start instance.
+ * 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.
  *
- * `createCsrfMiddleware` is not optional here. Start installs it *only* while an
- * app declares no `requestMiddleware` of its own - the moment this file exists,
- * the default is replaced by whatever it lists, and leaving CSRF out would
- * expose every server function as an unauthenticated cross-site endpoint. It is
- * declared first so it runs before anything else.
+ *     export const startInstance = createVitNodeStart({
+ *       config: vitNodeConfig,
+ *       requestMiddleware: [myMiddleware],
+ *     })
  */
-export const startInstance = createStart(() => ({
-  requestMiddleware: [
-    createCsrfMiddleware({ filter: ctx => ctx.handlerType === "serverFn" }),
-    localeMiddleware,
-  ],
-}));
+export const startInstance = createVitNodeStart({ config: vitNodeConfig });

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

@@ -1,37 +1,11 @@
-@import 'tailwindcss';
-@import 'shadcn/tailwind.css';
-@import 'tw-animate-css';
+@import "tailwindcss";
+@import "shadcn/tailwind.css";
+@import "tw-animate-css";
 
-
-/*
- * VitNode's components ship compiled, so Tailwind cannot find their classes by
- * scanning this app's source. Pointing it at core's build output is what makes
- * the toaster, the tooltip and everything else that follows look like VitNode
- * instead of unstyled markup.
- *
- * `dist/src/tanstack` is the line that is easiest to leave off and hardest to
- * diagnose. `@vitnode/core/tanstack/*` is markup as much as it is orchestration
- * - the header bar, the language switcher, the debug ribbon, the not-found
- * screen - and a class written *there* exists nowhere else, because this app
- * inherits those components rather than writing their markup. Without it a class
- * like `.w-34` is never generated, an `<svg>` with a viewBox and no width
- * collapses, and the header renders with no logo at all.
- *
- * Add a line per plugin that ships compiled components of its own.
- *
- * The paths are relative to this file. In a monorepo where the package manager
- * hoists to the repository root, that is `../../../node_modules/...` - the
- * generator rewrites them when it knows.
- */
 @source "../node_modules/@vitnode/core/dist/src/components";
 @source "../node_modules/@vitnode/core/dist/src/tanstack";
 @source "../node_modules/@vitnode/core/dist/src/views";
 
-/*
- * The design tokens every VitNode component reads. `.dark` is what
- * `ThemeScript` and `ThemeProvider` put on `<html>`, so the whole palette
- * switches from that one class.
- */
 :root:not(.dark) {
   --background: oklch(0.97 0 0);
   --foreground: oklch(0.145 0 0);
@@ -149,12 +123,6 @@
   --radius-4xl: calc(var(--radius) * 2.6);
 }
 
-/*
- * Last, so that a stylesheet a package brings in cannot outrank it in this
- * layer: `@layer base` rules are ordered by where they appear, and a library
- * that sets its own `body { background-color: ... }` would otherwise repaint
- * whichever pages happen to load it.
- */
 @layer base {
   * {
     @apply border-border outline-ring/50;

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

@@ -1,58 +1,73 @@
 import { buildConfig } from "@vitnode/core/vitnode.config";
 
-import { appMessages } from "./locales/app";
-import { vitNodeShellConfig } from "./vitnode.shell.config";
-
 /**
- * This app's frontend config, in the shape every VitNode app builds it.
+ * 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
  *
- * `plugins` is empty, and a plugin is added here by id and translations rather
- * than through its own `blogPlugin()` entry:
+ * 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.
  *
- *     import { buildPlugin } from '@vitnode/core/lib/plugin'
- *     import { CONFIG_PLUGIN as BLOG } from '@acme/blog/const'
+ * `vitnode i18n:create de Deutsch` does all of it for you.
  *
- *     import { packageMessages } from './locales/packages'
+ * ## Adding a plugin
  *
- *     plugins: [
- *       buildPlugin({
- *         messages: packageMessages[BLOG.pluginId],
- *         pluginId: BLOG.pluginId,
- *       }),
- *     ]
+ * With the plugin's own factory:
  *
- * That is a *scope* decision rather than a compatibility one. This object's one
- * reader takes `pluginId` and `messages` off each plugin and nothing else, so a
- * full registration would add every content type's editing screen to a
- * server-only graph where nothing would ever look at them. The AdminCP gets its
- * content types from `src/content-registry.gen.ts` instead - one literal import
- * per configured plugin - so a browser loads them with the content route and not
- * before.
+ *     import { blogPlugin } from '@acme/blog/config'
  *
- * The same split, one layer up, feeds the sidebar: `src/admin-nav.gen.ts` is the
- * navigation half - ids, hrefs, permissions, icons - and nothing that renders a
- * screen. See `src/lib/admin-nav.ts` and `src/lib/content-registry.ts`; both
- * explain why they are generated rather than read from here.
+ *     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`.
  *
- * Server-side only, and deliberately so - see `vitnode.shell.config.ts`.
- * `src/server/messages.server.ts` is the only importer, and it carries the
- * `server-only` guard that keeps it that way.
- *
  * `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({
-  ...vitNodeShellConfig,
-  /**
-   * The shell's locale declaration, plus the message loaders that must not be in
-   * it: `src/i18n.ts` is spread into the browser-facing shell config, and these
-   * are functions.
-   */
-  i18n: { ...vitNodeShellConfig.i18n, messages: appMessages },
+  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,
+});

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

@@ -2,11 +2,7 @@ import tailwindcss from "@tailwindcss/vite";
 import { devtools } from "@tanstack/devtools-vite";
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
 import viteReact from "@vitejs/plugin-react";
-import {
-  vitNodeEnv,
-  vitNodeOptimizeDeps,
-  vitNodePluginRoutes,
-} from "@vitnode/core/framework/vite";
+import { vitnode } from "@vitnode/core/framework/vite";
 import { nitro } from "nitro/vite";
 import { defineConfig } from "vite";
 
@@ -85,29 +81,20 @@ const config = defineConfig({
   },
   plugins: [
     /**
-     * All three from `@vitnode/core/framework/vite`.
+     * Environment handling, the dev server's dependency pre-bundling and the
+     * plugin route registry, in the order they have to run.
      *
-     * `vitNodeOptimizeDeps` takes nothing at all: it names the browser
-     * dependencies of the package's own `dist` so `vite dev` pre-bundles them on
-     * a cold start. Nothing crawls that `dist` before it is requested, so
-     * without this list a screen that is opened for the first time discovers a
-     * dependency mid-session, the optimizer re-runs, and a page holding modules
-     * from the previous run ends up with two copies of React.
+     * `appRoot` is `import.meta.dirname` because a Vite config is loaded with
+     * the working directory set to wherever the command ran, which in a
+     * monorepo is regularly the repository root.
      *
-     * `vitNodeEnv` takes no `clientEnv`: this app publishes nothing to the
-     * browser beyond the two keys the package inlines for every VitNode install
+     * `clientEnv` is not passed: this app publishes nothing to the browser
+     * beyond the two keys VitNode inlines for every install
      * (`NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_WEB_URL`). Anything named there is
-     * compiled into JavaScript anyone can read, so an empty list is the right
-     * default and a key is added only when something in the browser genuinely
-     * reads it.
-     *
-     * `appRoot` is `import.meta.dirname` because a Vite config is loaded with the
-     * working directory set to wherever the command ran, which in this monorepo
-     * is regularly the repository root.
+     * compiled into JavaScript anyone can read, so a key is added only when
+     * something in the browser genuinely reads it.
      */
-    vitNodeEnv(),
-    vitNodeOptimizeDeps(),
-    vitNodePluginRoutes({ appRoot: import.meta.dirname }),
+    vitnode({ appRoot: import.meta.dirname }),
     devtools(),
     nitro({ rollupConfig: { external: [/^@sentry\//] } }),
     tailwindcss(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-vitnode-app",
-  "version": "2.0.0-canary.1",
+  "version": "2.0.0-canary.2",
   "description": "Create a new VitNode app in seconds.",
   "author": "VitNode Team",
   "license": "MIT",
@@ -42,7 +42,7 @@
     "eslint": "^10.7.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@vitnode/config": "2.0.0-canary.1"
+    "@vitnode/config": "2.0.0-canary.2"
   },
   "scripts": {
     "build:scripts": "tsc -p tsconfig.build.json && node dist/src/prepare/prepare.js",

package/copy-of-vitnode-app/api/src/i18n.ts

@@ -1,38 +0,0 @@
-import type { VitNodeI18nConfig } from "@vitnode/core/lib/i18n/types";
-
-/**
- * The languages this installation serves.
- *
- * The API half of a split deployment. `apps/web` has a file of the same name,
- * and the two are one declaration in two places by necessity rather than by
- * design: they are separate packages, so neither can import the other's.
- *
- * They have to agree, and this is the copy that matters most - this app owns the
- * schema, so `vitnode db:prepare` seeds `core_languages` from *this* list. A
- * language that is here and not in the web app's renders nowhere; one that is in
- * the web app's and not here has no row in the database, and everything keyed on
- * a language row has nowhere to put it.
- *
- * Deliberately not discovered: nothing walks the filesystem looking for the web
- * app's config. A bootstrap that guessed at a sibling application is exactly
- * what this replaced, and it guessed wrong the moment the two were not laid out
- * the way it expected.
- *
- * Packages ship their own translations, so a new locale needs no `messages`
- * entry - anything untranslated falls back to `defaultLocale` key by key.
- */
-export const i18n = {
-  defaultLocale: "en",
-  /**
-   * Explicit, because this API renders emails on a server: without one, dates
-   * format in whatever zone the host happens to run in.
-   */
-  timeZone: "UTC",
-  locales: [
-    {
-      code: "en",
-      name: "English",
-    },
-  ],
-  messages: {},
-} satisfies VitNodeI18nConfig;

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

@@ -1,36 +0,0 @@
-import type { VitNodeI18nConfig } from "@vitnode/core/lib/i18n/types";
-
-/**
- * The languages this app serves.
- *
- * Its own module so the web config and the API config can point at the same
- * object instead of drifting apart - the site and the emails it sends have to
- * agree on which languages exist.
- *
- * Add a language by adding an entry. Packages ship their own translations, so a
- * new locale needs no `messages` here: anything a package has not translated
- * falls back to `defaultLocale` key by key. Register the package's own file for
- * that language in `src/locales/packages.ts`, and put your own rewording in
- * `src/locales/app.ts`.
- */
-export const i18n = {
-  defaultLocale: "en" as const,
-  /**
-   * 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. Stage 3, which owns the locale runtime, is where a
-   * per-visitor zone would come from.
-   */
-  timeZone: "UTC",
-  /**
-   * `as const` on each code, and nothing else: it keeps `"en" | "pl"` out of
-   * the widening `satisfies` would otherwise do, which is what makes `Locale`
-   * in `lib/i18n/shared.ts` a real union rather than an alias for `string`.
-   */
-  locales: [
-    {
-      code: "en" as const,
-      name: "English",
-    },
-  ],
-} satisfies VitNodeI18nConfig;

package/copy-of-vitnode-app/root/src/lib/document-headers.ts

@@ -1,128 +0,0 @@
-/**
- * What a VitNode document response may say about being stored.
- *
- * `private, no-store`, and it is not a precaution - it is a description of what
- * is in the body. Every page this application renders streams a dehydrated Query
- * cache into its HTML, and that cache always holds `["vitnode","session"]`: the
- * visitor's own name, avatar and `isAdmin` flag. Inside `/admin` it also holds
- * `["vitnode","admin-session"]`, which is that administrator's entire permission
- * set. `tanstack/auth/session-query` and `tanstack/admin/session-query` both say
- * so in their own words - "that document is personalised and must not be served
- * from a shared cache" - and until now nothing on the response said it back.
- *
- * Nothing caches these documents today. That is a property of the current
- * deployment, not of the application: the moment a CDN, a reverse proxy or a
- * `Cache-Control`-respecting edge sits in front of the Node server, an absent
- * directive is an invitation to store one visitor's HTML and serve it to the
- * next. Stage 15 is when that becomes likely, so the header belongs here now.
- *
- * ## It is an invariant, not a default
- *
- * This started as a fallback for documents that said nothing, and that was
- * wrong. A default is something a route may override, and at this architecture
- * level there is no override a route could correctly choose: the dehydrated
- * cache is written into the stream by `setupRouterSsrQueryIntegration` for
- * *every* document, so a route opting into `public, max-age=60` would be
- * publishing whichever visitor rendered first to everyone who asked next. The
- * route cannot know that, because the private payload is not something the route
- * put there.
- *
- * So the directive is forced rather than filled in, and a route that sets its
- * own is overwritten rather than obeyed. That is the whole difference between
- * this being a hardening measure and it being a security invariant.
- *
- * Public document caching is not forbidden forever - it is forbidden *while the
- * session is dehydrated into the document*. Introducing it later is a separate,
- * explicit piece of architecture in which the private state is kept out of the
- * shared body (a public shell fetching its session client-side, say), and the
- * invariant here would move with it rather than being quietly relaxed by a route
- * that wanted a faster page.
- *
- * `private` bars a shared cache. `no-store` bars every cache, including the
- * browser's own disk cache - which is the half that matters on a shared machine,
- * where the previous person's permission set should not be recoverable from
- * `chrome://cache` after they sign out. The pair is the standard spelling for
- * "this body belongs to exactly one person, once".
- *
- * The known cost is the back/forward cache. `no-store` used to make a page
- * outright ineligible for bfcache in Chromium; current versions keep such pages
- * eligible but evict them when cookies change - which for this app means a
- * sign-in or sign-out invalidates a back-navigation that would otherwise have
- * restored a page rendered for the previous session. That is the correct trade
- * and the outcome anybody would want, but it is a real difference and it is
- * worth a look during a manual pass rather than a surprise later.
- */
-export const DOCUMENT_CACHE_CONTROL = "private, no-store";
-
-/**
- * Whether this response is one of the documents the rule above describes.
- *
- * One question, and it is what keeps the API out of it. `/api/*` is served by
- * the Hono bridge through this same middleware, and a bare `GET` from it carries
- * no `Cache-Control` of its own - so a rule that applied to every response would
- * quietly forbid clients from caching the API. An HTML content-type is the
- * honest way to ask "is this a page", it needs no path list to be kept in step
- * with the router, and it cannot be wrong about a response that has already been
- * produced.
- *
- * It deliberately does *not* ask whether a directive is already present. That
- * used to be the second half of this predicate, and it is exactly the exemption
- * the invariant above cannot afford - see {@link applyDocumentCacheControl}.
- *
- * A redirect is deliberately not matched here - it has no content type - and is
- * handled by {@link applyRedirectCacheControl} instead, which wants a narrower
- * rule.
- */
-const isRenderedDocument = (headers: Headers): boolean =>
-  (headers.get("content-type") ?? "").toLowerCase().startsWith("text/html");
-
-/**
- * Says what a rendered document is, on the response about to be sent.
- *
- * `set` rather than a conditional fill, and that is the fix: whatever the
- * response was carrying is replaced. A route cannot opt out, because a route is
- * not in a position to know what is in the body it is opting out for.
- *
- * Only `text/html` is touched. Everything else the middleware sees - the API,
- * assets, client chunks, a `204` with no content type at all - keeps whatever it
- * had, including nothing.
- *
- * Mutates rather than returning a new `Response`, because the middleware already
- * holds the one Start produced and rebuilding it would mean copying a stream.
- * The same reason `set-cookie` is appended in place a few lines away.
- */
-export const applyDocumentCacheControl = (response: Response): void => {
-  if (!isRenderedDocument(response.headers)) return;
-
-  response.headers.set("cache-control", DOCUMENT_CACHE_CONTROL);
-};
-
-/**
- * The same for a locale redirect, but only when it is carrying a cookie.
- *
- * A `308` from `/en/discover` to `/discover` is a fact about URLs, identical for
- * every visitor, and permanently cacheable - which is most of the point of
- * answering with one. So it keeps that property by default.
- *
- * The exception is the redirect that also writes the locale cookie, which is
- * what `/pl/admin` produces: a stored copy of that would hand the next visitor
- * through the same shared cache a `Set-Cookie` chosen by somebody else, and
- * quietly switch their language. Shared caches are generally expected to refuse
- * a `Set-Cookie` response, but "generally expected" is not a property this
- * application can assert about somebody else's proxy, and one visitor's cookie
- * reaching another's browser is not the kind of thing to leave to convention.
- *
- * So the cookie-carrying case is forced, for the same reason the document is: a
- * `public` directive already on such a redirect is overwritten rather than
- * respected, because the thing that makes it unsafe to share is the `Set-Cookie`
- * beside it and not whatever the directive claims.
- *
- * The cookie-less case keeps its existing semantics untouched, directive and
- * all. It carries no private state, so there is nothing here to protect and
- * nothing to override.
- */
-export const applyRedirectCacheControl = (response: Response): void => {
-  if (!response.headers.has("set-cookie")) return;
-
-  response.headers.set("cache-control", DOCUMENT_CACHE_CONTROL);
-};

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

@@ -1,35 +0,0 @@
-import type { VitNodeConfig } from "@vitnode/core/vitnode.config";
-
-import { i18n } from "./i18n";
-
-/**
- * The VitNode config the browser is allowed to see.
- *
- * Everything in `VitNodeConfig` except `plugins`, and that omission is the whole
- * point. The plugin registry carries each plugin's translations as `import()`s
- * of JSON inside its `dist`, and eventually its AdminCP components - neither of
- * which a browser bundle should hold. In Next.js the boundary is drawn for you:
- * `vitnode.config.ts` is only ever read by Server Components, so none of it
- * reaches the client. TanStack Start has no such boundary - anything the root
- * route imports is in the browser bundle - so the split is made here instead, by
- * hand.
- *
- * `vitnode.config.ts` spreads this into `buildConfig` with the plugins added, so
- * there is one source for the metadata, the theme and the locales rather than
- * two that agree until they don't.
- *
- * Everything here is plain, serializable data. That is a rule, not a
- * coincidence: this module is imported by the document shell, which renders on
- * both sides of hydration.
- */
-export const vitNodeShellConfig = {
-  debug: false,
-  i18n,
-  metadata: {
-    shortTitle: "VitNode",
-    title: "VitNode",
-  },
-  theme: {
-    defaultTheme: "system",
-  },
-} satisfies Omit<VitNodeConfig, "plugins">;