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

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

@@ -7,49 +7,7 @@ import {
 
 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,

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

@@ -5,17 +5,4 @@ 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

@@ -2,23 +2,4 @@ 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/vitnode.config.ts

@@ -1,66 +1,10 @@
 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",

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

@@ -5,17 +5,6 @@ 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,

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

@@ -8,92 +8,8 @@ import { defineConfig } from "vite";
 
 const config = defineConfig({
   resolve: { tsconfigPaths: true },
-  /**
-   * A second dev server has to fail rather than quietly move.
-   *
-   * `tanstackStart()` runs the route generator and *writes*
-   * `src/routeTree.gen.ts`. Two servers means two generators owning one file: if
-   * their route lists ever differ - which is precisely what happens when one was
-   * started before a route file existed - they overwrite each other forever, and
-   * every write is a full page reload. Without `strictPort` the second `pnpm dev`
-   * says "Port 3000 is in use, trying another one" and succeeds, so the fight
-   * starts silently and looks like an inexplicable refresh loop on the first
-   * server.
-   */
   server: { strictPort: true },
-  ssr: {
-    /**
-     * The VitNode API packages mounted at `/api/*`, kept out of the SSR pass.
-     *
-     * They are Node libraries rather than app source: `@vitnode/core` loads its
-     * locale files with a runtime `import("./en.json", { with: { type: "json" } })`
-     * relative to its own `dist`. Bundling them in this pass moves that chunk
-     * and the JSON stops resolving, which fails the build outright. Left
-     * external here, Nitro resolves them from the package itself.
-     *
-     * Every VitNode package the app installs belongs on this list - add a
-     * plugin's package name here when you install one.
-     *
-     * This is also what decides the shape of `@vitnode/core/tanstack/*`, so it is
-     * worth naming the consequence rather than leaving it to be rediscovered.
-     * Externalised here, the package skips this pass entirely and Nitro's own
-     * Rollup run inlines its `dist` afterwards - and nothing in that path runs
-     * the TanStack Start compiler. The *client* build has no such gap: it inlines
-     * the package, so the compiler transforms it there. So package code reaches
-     * the browser compiled and the server un-compiled, which is exactly why the
-     * package may declare `createIsomorphicFn` (its stub falls back to the
-     * `.server()` branch, which is what a server wants) and may never declare
-     * `createServerFn` (un-compiled, its handler resolves to `undefined` with no
-     * error at all). `packages/vitnode/src/tanstack/boundary.test.ts` holds the
-     * package to that.
-     *
-     * Removing `@vitnode/core` from this list to close the gap was measured and
-     * does not work: the SSR pass then reaches the locale barrel above and the
-     * build fails on `Could not resolve './en.json'`.
-     *
-     * ## `tslib` is here for an entirely different reason
-     *
-     * It is not a VitNode package and it is not a Node library. It is here
-     * because bundling it is broken, in a way that only appears in a production
-     * build and only once a page renders.
-     *
-     * The Radix scroll-lock stack that every modal in a VitNode page pulls in -
-     * `react-remove-scroll`, `use-sidecar`, `aria-hidden` - does
-     * `import { __extends } from "tslib"`. Under the `node` condition that
-     * resolves to `tslib/modules/index.js`, a two-line ESM shim around the
-     * **CommonJS** `tslib.js`:
-     *
-     *     import tslib from "../tslib.js";
-     *     const { __extends, … } = tslib;
-     *
-     * `tslib.js` defines `__esModule` on its exports, so Rolldown's CJS interop
-     * helper does not synthesise a `default` - while the call site it generated
-     * still reads `.default`. Every page that renders a dialog then throws
-     * `Cannot destructure property '__extends' of undefined`.
-     *
-     * Externalised, the file is never bundled: Nitro traces the package into the
-     * output and Node loads it with Node's own interop, which is correct. An
-     * alias to `tslib/tslib.es6.mjs` was tried first and is worse - it fixes
-     * Vite's copy and not Nitro's, because Nitro re-resolves externals itself,
-     * and the tracer then copies only the file the alias named.
-     */
-    external: ["@vitnode/core", "tslib"],
-  },
   plugins: [
-    /**
-     * Environment handling, the dev server's dependency pre-bundling and the
-     * plugin route registry, in the order they have to run.
-     *
-     * `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.
-     *
-     * `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 a key is added only when
-     * something in the browser genuinely reads it.
-     */
     vitnode({ appRoot: import.meta.dirname }),
     devtools(),
     nitro({ rollupConfig: { external: [/^@sentry\//] } }),

package/dist/src/plugin/create/route-templates.js

@@ -31,30 +31,7 @@ export const routes = definePluginRoutes([
 };
 export const pluginRouteModuleTemplate = (pluginName) => `import { useTranslations } from "use-intl";
 
-/**
- * The page \`routes.ts\` declares.
- *
- * Keep it framework-neutral. This module is compiled into the package's own
- * \`dist\` and imported by whichever app installed the plugin, so anything from
- * a router or a host-bound i18n package pins the plugin to one kind of host.
- * \`use-intl\` - which is what VitNode itself renders through - and plain JSX are
- * pinned to neither.
- *
- * No \`<main>\`: the application 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.
- *
- * To give this route a loader, page metadata or a breadcrumb, add a \`route\`
- * export beside the default one:
- *
- *     import { definePluginRoute } from "@vitnode/core/routing";
- *
- *     export const route = definePluginRoute({
- *       load: ({ context, params }) => fetchThing(context.locale, params.id),
- *       head: ({ loaderData }) => ({ title: loaderData?.title }),
- *     });
- */
+
 const HomePage = () => {
   const t = useTranslations("${pluginName}");
 
@@ -83,11 +60,7 @@ export const pluginMessagesTemplate = (pluginName) => `${JSON.stringify({
 }, null, 2)}\n`;
 export const pluginMessagesBarrelTemplate = () => `import type { LocaleMessagesMap } from "@vitnode/core/lib/i18n/types";
 
-/**
- * Every language this plugin ships. Add a file next to this one and a line here
- * to add another; apps pick it up with no copy step, because they read this
- * package's own \`dist\` rather than a copy of it.
- */
+
 const messages: LocaleMessagesMap = {
   en: async () => await import("./en.json", { with: { type: "json" } }),
 };
@@ -109,17 +82,7 @@ export const pluginConfigTemplate = (pluginName) => `import { buildPlugin } from
 import messages from "./locales";
 import { routes } from "./routes";
 
-/**
- * This plugin, as an application registers it.
- *
- * \`pluginId\` is the package name, and that is not a convention - it is how this
- * plugin's route tree is imported (\`${pluginName}/routes\`) and how its messages
- * are namespaced. The two cannot drift because they are one string.
- *
- * Add this to an app's \`src/vitnode.config.ts\` \`plugins\` array. A plugin that
- * is installed but not listed there contributes nothing - no directory is ever
- * scanned - so this is the only switch.
- */
+
 export const ${pluginVariableName(pluginName)} = () =>
   buildPlugin({
     pluginId: "${pluginName}",