@antelopejs/dms-frontend 0.2.1 → 0.2.2

package/dist/config.js

@@ -39,6 +39,7 @@ exports.TEMPLATE_FILES = [
     ["frontend-module.ts", "frontend-module.ts"],
     ["globals.d.ts", "globals.d.ts"],
     ["compress-assets.mjs", "compress-assets.mjs"],
+    ["head-order.mjs", "head-order.mjs"],
     ["email-renderer.ts", "email-renderer.ts"],
     ["email-runtime.ts", "email-runtime.ts"],
     ["email-locales.ts", "email-locales.ts"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",

package/templates/vue/head-order.mjs

@@ -0,0 +1,39 @@
+// Restoring "paint before hydrate" in the built document.
+//
+// The source index.html marks the entry script `fetchpriority="low"` so the
+// browser spends its bandwidth on the render-blocking stylesheet first. Vite
+// rewrites that script tag when it builds and drops the attribute, and it emits
+// the script *before* the stylesheet — so the production document did the
+// opposite of what the template asked: it discovered a 250 kB hydration bundle
+// first and let it compete with the 27 kB the first paint actually waits on,
+// over the plain HTTP/1.1 the generated server speaks.
+//
+// Kept beside vite.config.ts rather than inside it so the transform can be
+// exercised on its own, the way client-manifest.mjs is.
+
+const SCRIPT = /<script[^>]*\stype="module"[^>]*><\/script>/;
+const STYLESHEET = /[ \t]*<link rel="stylesheet"[^>]*>\n?/;
+
+function deprioritize(html) {
+  return html.replace(SCRIPT, (tag) =>
+    tag.includes("fetchpriority")
+      ? tag
+      : tag.replace("<script ", '<script fetchpriority="low" '),
+  );
+}
+
+/**
+ * Give the entry script back its low fetch priority and move the stylesheet
+ * ahead of it. A document that already has them in that order is returned
+ * unchanged, so the transform is safe to run twice.
+ */
+export function orderHeadForFirstPaint(html) {
+  const prioritized = deprioritize(html);
+  const stylesheet = prioritized.match(STYLESHEET);
+  const script = prioritized.match(SCRIPT);
+  if (!stylesheet || !script || stylesheet.index < script.index)
+    return prioritized;
+  return prioritized
+    .replace(STYLESHEET, "")
+    .replace(SCRIPT, (tag) => `${stylesheet[0].trim()}\n    ${tag}`);
+}

package/templates/vue/main.ts

@@ -6,10 +6,47 @@ import { configureDmsApp, resolveDmsInertiaPage } from "./app-runtime";
 import { setupFrontendModules } from "./frontend-module";
 import { frontendModules } from "./frontend-modules.generated";
 
+const DEV_STYLE_ATTRIBUTE = "data-dms-dev-style";
+
+/**
+ * Hand each development stylesheet over to Vite.
+ *
+ * The development server puts the page's stylesheets in the document so it
+ * never paints unstyled (see `server/dev-styles.mjs`). Vite then injects its
+ * own copy of each one as a `<style data-vite-dev-id>`, and keeping both would
+ * make a later CSS edit look like it removed nothing: Vite rewrites its copy,
+ * ours keeps the deleted rules alive.
+ *
+ * We drop ours the moment Vite's appears, keyed by module id, rather than at a
+ * fixed point in the boot. A component reached through a dynamic import — most
+ * of them — has not been loaded when the app mounts, so removing its scoped
+ * rules then would flash exactly what this whole change exists to prevent.
+ */
+function adoptViteDevStyles(): void {
+  const pending = new Map<string, Element>();
+  for (const node of document.querySelectorAll(`[${DEV_STYLE_ATTRIBUTE}]`)) {
+    pending.set(node.getAttribute(DEV_STYLE_ATTRIBUTE) ?? "", node);
+  }
+  if (pending.size === 0) return;
+  const adopt = (): void => {
+    for (const style of document.querySelectorAll("style[data-vite-dev-id]")) {
+      const id = style.getAttribute("data-vite-dev-id") ?? "";
+      pending.get(id)?.remove();
+      pending.delete(id);
+    }
+    if (pending.size === 0) observer.disconnect();
+  };
+  const observer = new MutationObserver(adopt);
+  observer.observe(document.head, { childList: true });
+  adopt();
+}
+
 function markDmsReady(): void {
   document.documentElement.dataset.dmsReady = "true";
 }
 
+if (import.meta.env.DEV) adoptViteDevStyles();
+
 await setupFrontendModules(frontendModules);
 
 createInertiaApp({

package/templates/vue/server/dev-styles.mjs

@@ -0,0 +1,98 @@
+// Putting the page's stylesheets in the document the development server
+// returns, instead of letting the client entry inject them from JavaScript
+// once it has executed.
+//
+// Vite serves every stylesheet as a JavaScript module in development, so a
+// plain SSR document carries no styles at all and the browser paints raw HTML
+// until `/main.ts` and its module graph have run. Production has no such gap:
+// the built `index.html` already links the entry stylesheet, which is why this
+// module is development-only and lives beside client-manifest.mjs rather than
+// inside server.mjs, whose size the linter caps.
+//
+// Each tag carries the module id Vite will use for its own copy
+// (`data-vite-dev-id`), under our own attribute name. `main.ts` hands the
+// stylesheet over as soon as Vite injects that copy — see `adoptViteDevStyles`.
+// We deliberately do NOT reuse `data-vite-dev-id` itself: Vite's client adopts
+// any pre-existing link with that attribute and then skips `updateStyle` for
+// it, which would leave CSS edits stranded.
+
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pageModulePreloads } from "./client-manifest.mjs";
+
+const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
+const STYLE_ATTRIBUTE = "data-dms-dev-style";
+const SFC_STYLE = /[?&]vue&type=style/;
+const STYLE_EXTENSION =
+  /\.(?:css|less|pcss|postcss|sass|scss|styl|stylus)(?:$|\?)/;
+
+/**
+ * The workspace's generated entry stylesheet. `main.ts` is its only importer,
+ * so it never enters the SSR module graph, yet it carries Tailwind, Nuxt UI and
+ * one `@source` per materialized module — nearly every rule a page needs.
+ * Naming it is the one enumeration this module accepts, and the comment is the
+ * reason why.
+ */
+const ENTRY_STYLESHEET = "/dms-main.css";
+
+function ssrModuleGraph(devServer) {
+  return devServer.environments?.ssr?.moduleGraph ?? devServer.moduleGraph;
+}
+
+function directUrl(url) {
+  return `${url}${url.includes("?") ? "&" : "?"}direct`;
+}
+
+function styleModules(devServer) {
+  const graph = ssrModuleGraph(devServer);
+  if (!graph) return [];
+  return [...graph.urlToModuleMap.entries()]
+    .filter(([url]) => SFC_STYLE.test(url) || STYLE_EXTENSION.test(url))
+    .map(([url, module]) => ({ url, id: module?.id ?? url }));
+}
+
+function linkTag({ url, id }) {
+  return `<link rel="stylesheet" ${STYLE_ATTRIBUTE}="${id}" href="${directUrl(url)}">`;
+}
+
+/**
+ * A single-file component's `<style>` block is served with a JavaScript content
+ * type even when requested directly, so a browser would refuse it as a
+ * stylesheet. They are small; inline them instead. A block that could close its
+ * own tag is dropped rather than escaped — CSS has no escape that is valid in
+ * every position, and a scoped component rule is not worth the risk.
+ */
+async function inlineTag(devServer, { url, id }) {
+  const result = await devServer
+    .transformRequest(directUrl(url))
+    .catch(() => undefined);
+  const css = result?.code;
+  if (!css || /<\/style/i.test(css)) return "";
+  return `<style ${STYLE_ATTRIBUTE}="${id}">${css}</style>`;
+}
+
+/** Style tags for everything the development render touched, entry sheet first. */
+export async function developmentStyleTags(devServer) {
+  const modules = styleModules(devServer);
+  const links = [
+    { url: ENTRY_STYLESHEET, id: join(PROJECT_ROOT, "dms-main.css") },
+    ...modules.filter(({ url }) => !SFC_STYLE.test(url)),
+  ].map(linkTag);
+  const inlined = await Promise.all(
+    modules
+      .filter(({ url }) => SFC_STYLE.test(url))
+      .map((module) => inlineTag(devServer, module)),
+  );
+  return [...links, ...inlined].join("");
+}
+
+/**
+ * The style tags a document needs, whichever server is answering it: collected
+ * from the live module graph in development, read from the build manifest in
+ * production.
+ */
+export async function documentStyleTags(devServer, page, template) {
+  return devServer
+    ? developmentStyleTags(devServer)
+    : pageModulePreloads(page, template);
+}

package/templates/vue/server/homepage.mjs

@@ -0,0 +1,32 @@
+// Working out which page a visit to `/` means.
+//
+// The answer lives in the module registry the workspace was materialized with:
+// a module declares `homepage` somewhere in its options, at whatever depth its
+// own configuration shape puts it, and the highest-priority declaration wins —
+// the registry is already sorted. Read once at boot, because the registry is a
+// build artifact and cannot change while the server is up.
+//
+// Split out of server.mjs, whose size the linter caps.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
+const REGISTRY_PATH = join(PROJECT_ROOT, "generated-frontend-modules.json");
+const REGISTRY = existsSync(REGISTRY_PATH)
+  ? JSON.parse(readFileSync(REGISTRY_PATH, "utf8"))
+  : { modules: [] };
+
+function findHomepage(options) {
+  if (!options || typeof options !== "object") return undefined;
+  if (typeof options.homepage === "string") return options.homepage;
+  return Object.values(options)
+    .map(findHomepage)
+    .find((homepage) => homepage !== undefined);
+}
+
+export const HOMEPAGE =
+  REGISTRY.modules
+    .map((module) => findHomepage(module.options))
+    .find(Boolean) ?? "/";

package/templates/vue/server/inertia.mjs

@@ -7,6 +7,17 @@ const CLIENT_MANIFEST_PATH = fileURLToPath(
 );
 let productionAssetVersion;
 
+/**
+ * Every document and Inertia payload this server writes carries the visitor's
+ * own session: the user, the session, and the page tree their permissions
+ * allow. `private` is what keeps a shared cache from ever holding it;
+ * `no-cache` keeps the browser's own copy from being reused without asking us
+ * first, so a revoked session cannot resurface from disk. We stop short of
+ * `no-store`, which would additionally forfeit the back-forward cache on every
+ * page of a dashboard people navigate constantly.
+ */
+export const PRIVATE_CACHE_CONTROL = "private, no-cache";
+
 export function assetVersion() {
   if (process.env.DMS_DEV === "true" || !existsSync(CLIENT_MANIFEST_PATH))
     return "development";
@@ -32,6 +43,7 @@ export function createInertiaPage(url, props, version = assetVersion()) {
 
 export function inertiaHeaders(version = assetVersion()) {
   return {
+    "cache-control": PRIVATE_CACHE_CONTROL,
     "content-type": "application/json",
     "x-inertia": "true",
     vary: "X-Inertia",
@@ -39,6 +51,15 @@ export function inertiaHeaders(version = assetVersion()) {
   };
 }
 
+/** Headers for a rendered document: same cache stance as an Inertia payload. */
+export function htmlHeaders() {
+  return {
+    "cache-control": PRIVATE_CACHE_CONTROL,
+    "content-type": "text/html",
+    vary: "X-Inertia",
+  };
+}
+
 export function handleAssetVersionMismatch(request, response) {
   if (
     !request.headers["x-inertia"] ||

package/templates/vue/server.mjs

@@ -18,14 +18,14 @@ import {
   refreshSession,
 } from "./server/auth/routes.mjs";
 import { readSession } from "./server/auth/session.mjs";
-import {
-  pageModulePreloads,
-  productionHtmlTemplate,
-} from "./server/client-manifest.mjs";
+import { productionHtmlTemplate } from "./server/client-manifest.mjs";
+import { documentStyleTags } from "./server/dev-styles.mjs";
 import { handleEmailRender } from "./server/email.mjs";
+import { HOMEPAGE } from "./server/homepage.mjs";
 import { handleTester } from "./server/tester.mjs";
 import {
   createInertiaPage,
+  htmlHeaders,
   inertiaAppHtml,
   inertiaHeaders,
   redirectFrontendVisit,
@@ -36,13 +36,6 @@ export * from "./server/inertia.mjs";
 const INERTIA_HEADER = "x-inertia";
 const JSON_TYPE = "application/json";
 const PROJECT_ROOT = fileURLToPath(new URL(".", import.meta.url));
-const MODULE_REGISTRY_PATH = join(
-  PROJECT_ROOT,
-  "generated-frontend-modules.json",
-);
-const MODULE_REGISTRY = existsSync(MODULE_REGISTRY_PATH)
-  ? JSON.parse(readFileSync(MODULE_REGISTRY_PATH, "utf8"))
-  : { modules: [] };
 const MIME_TYPES = {
   ".css": "text/css",
   ".js": "text/javascript",
@@ -74,19 +67,6 @@ let vite;
 let vitePromise;
 let frontendHttpServer;
 
-function findHomepage(options) {
-  if (!options || typeof options !== "object") return undefined;
-  if (typeof options.homepage === "string") return options.homepage;
-  return Object.values(options)
-    .map(findHomepage)
-    .find((homepage) => homepage !== undefined);
-}
-
-const HOMEPAGE =
-  MODULE_REGISTRY.modules
-    .map((module) => findHomepage(module.options))
-    .find(Boolean) ?? "/";
-
 class BackendResponseError extends Error {
   constructor(status) {
     super(`DMS backend returned ${status}`);
@@ -358,7 +338,7 @@ export async function renderHtml(page, requestUrl, serverFetch) {
   }
   if (rendered.redirect)
     return { html: "", status: 200, redirect: rendered.redirect };
-  const preloads = devServer ? "" : pageModulePreloads(page, template);
+  const preloads = await documentStyleTags(devServer, page, template);
   const html = template
     .replace("<title>Antelope DMS</title>", rendered.head.headTags)
     .replace("<html", `<html ${rendered.head.htmlAttrs}`)
@@ -410,13 +390,7 @@ async function writeBackendError(error, request, response) {
       request.url,
       serverComponentFetch(request),
     );
-    return writeContent(
-      request,
-      response,
-      status,
-      { "content-type": "text/html", vary: "X-Inertia" },
-      html,
-    );
+    return writeContent(request, response, status, htmlHeaders(), html);
   }
   const payload =
     error instanceof UpstreamError || error instanceof RequestBodyError
@@ -481,7 +455,7 @@ export async function handleRequest(request, response) {
     request,
     response,
     rendered.status,
-    { "content-type": "text/html", vary: "X-Inertia" },
+    htmlHeaders(),
     rendered.html,
   );
 }

package/templates/vue/vite.config.ts

@@ -2,7 +2,8 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import ui from "@nuxt/ui/vite";
 import vue from "@vitejs/plugin-vue";
-import { defineConfig } from "vite";
+import { defineConfig, type Plugin } from "vite";
+import { orderHeadForFirstPaint } from "./head-order.mjs";
 
 interface FrontendModuleRegistryEntry {
   id: string;
@@ -66,6 +67,38 @@ const optimizedDependencies = [
   "json-schema-to-zod",
   "striptags",
 ];
+
+/**
+ * Entry points the dependency optimizer crawls at startup.
+ *
+ * Every materialized module brings its own dependency set — subpath exports and
+ * transitive CommonJS included — and none of it can be listed in
+ * `optimizedDependencies` by hand, because the modules are only known at
+ * materialization time. Leaving the crawl off and letting Vite discover them as
+ * pages load meant the first visit to a cold page re-ran the optimizer
+ * mid-request: the chunks already in flight answered 504 and the client was
+ * told to reload the whole document. Crawling the module sources once, at
+ * startup, pays that cost a single time and in a place where it reads as
+ * startup rather than as a crash.
+ */
+const optimizerEntries = [
+  resolve(__dirname, "main.ts"),
+  ...moduleRoots.map((root) => resolve(root, "dms.frontend.ts")),
+  ...frontendSourceRoots.flatMap((root) => [
+    resolve(root, "app/**/*.vue"),
+    resolve(root, "app/**/*.ts"),
+  ]),
+];
+
+function paintBeforeHydrate(): Plugin {
+  return {
+    name: "dms-paint-before-hydrate",
+    apply: "build",
+    enforce: "post",
+    transformIndexHtml: { order: "post", handler: orderHeadForFirstPaint },
+  };
+}
+
 const uiLinkImport = "@nuxt/ui/components/Link.vue";
 const uiInertiaLinkImport = resolve(
   __dirname,
@@ -131,6 +164,7 @@ export default defineConfig({
         vueTemplate: true,
       },
     }),
+    paintBeforeHydrate(),
   ],
   resolve: {
     dedupe: ["vue", "reka-ui", "@nuxt/ui"],
@@ -152,8 +186,7 @@ export default defineConfig({
   },
   optimizeDeps: {
     include: optimizedDependencies,
-    // Avoid crawling every module page at startup, but optimize dependencies as pages load.
-    entries: [],
+    entries: optimizerEntries,
   },
   ssr: { noExternal: ["@nuxt/icon", "@nuxt/ui"] },
   server: { strictPort: true, allowedHosts: [".onamp.dev"] },