@nifrajs/web 2.9.1 → 2.11.0

package/src/index.ts

@@ -25,9 +25,13 @@ import {
 } from "./deferred.ts"
 import { isDraftEnabled } from "./draft.ts"
 import { trustedHeadAttributes } from "./internal/head-attributes.ts"
+// Head resolution/merging. Defined in an internal module so `@nifrajs/web/client` can export the same
+// two functions to the generated client entry without dragging THIS module (and its server code) into
+// the browser graph - see internal/head-merge.ts. Re-exported here so the public API is unchanged.
+import { mergeHeads, resolveMeta } from "./internal/head-merge.ts"
 import { jsStringLiteral } from "./internal/js-string.ts"
 import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./internal/script-types.ts"
-import { ISR_REVALIDATE_HEADER } from "./isr.ts"
+import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "./isr.ts"
 import { generateLlmsTxt } from "./llms-txt.ts"
 import type {
   LayoutEntry,
@@ -83,6 +87,7 @@ export {
   type CachedResponse,
   type CacheStore,
   ISR_REVALIDATE_HEADER,
+  ISR_REVALIDATE_TAGS_HEADER,
   ISR_STATUS_HEADER,
   type ISRApp,
   type ISROptions,
@@ -194,7 +199,7 @@ export {
   type SubmitOptions,
 } from "./router.ts"
 // Deferred loader data (`defer()` + the `Deferred<T>` type) - consumed by the adapter's `<Await>`.
-export { type Deferred, defer }
+export { type Deferred, defer, mergeHeads, resolveMeta }
 
 /** Phantom brand key for {@link ServerOnly}. A unique symbol so the brand can't be forged by a plain
  * object literal; `unique symbol` keys never appear in the emitted JS, so the brand is purely
@@ -310,6 +315,43 @@ export interface RenderAdapter {
   hydrationHead(nonce?: string): string
 }
 
+/**
+ * Loads a module through the DEV SERVER'S module graph rather than the runtime's. Takes an absolute
+ * file path or a bare specifier; resolution, compilation and caching are the dev server's.
+ */
+export type SsrModuleLoader = (id: string) => Promise<unknown>
+
+/* A `globalThis` singleton for the same reason `@nifrajs/web-react`'s router context is one: in dev
+ * this module is evaluated twice in one process (the CLI's copy under Bun, and the app's copy), and a
+ * module-level `let` would leave the adapter reading a slot the dev server set on the other copy. */
+const SSR_MODULE_LOADER_SLOT = Symbol.for("nifra.web.ssr-module-loader")
+/* Explicitly `| undefined`: clearing the slot is part of the contract (a dev server clears it on
+ * stop), and under `exactOptionalPropertyTypes` "absent" and "set to undefined" are separate types. */
+const loaderSlot = globalThis as { [SSR_MODULE_LOADER_SLOT]?: SsrModuleLoader | undefined }
+
+/**
+ * Publishes the dev server's SSR module loader. Called by a dev server that owns SSR resolution
+ * itself; pass `undefined` to clear it on shutdown.
+ */
+export function setSsrModuleLoader(load: SsrModuleLoader | undefined): void {
+  loaderSlot[SSR_MODULE_LOADER_SLOT] = load
+}
+
+/**
+ * The dev server's SSR module loader, or `undefined` when nothing owns SSR resolution but the runtime
+ * - the Bun dev pipeline, and every production build, where the adapter's assets are compiled ahead
+ * of time and a plain `import` is already the right thing.
+ *
+ * An adapter that must load a COMPILED asset at runtime (a `.svelte` component, say) has to prefer
+ * this over a bare `import`, and has to take the framework's SERVER RENDERER from it as well, not
+ * just the component. A component compiled by the dev server renders through the renderer the dev
+ * server resolved; mixing the two puts two copies of the framework runtime in one component tree,
+ * where context written by one half is invisible to the other.
+ */
+export function ssrModuleLoader(): SsrModuleLoader | undefined {
+  return loaderSlot[SSR_MODULE_LOADER_SLOT]
+}
+
 /** Global the server serializes loader data into; the client reads it to hydrate. */
 export const DATA_GLOBAL = "__NIFRA_DATA__"
 /** Per-layout loader data for hydration. Emitted ONLY when some layout in the chain has a loader, so
@@ -427,6 +469,8 @@ export interface RenderPageOptions {
   /** ISR: route freshness in seconds, emitted as the `x-nifra-isr-revalidate` header for a `withISR`
    * wrapper to read. Omit ⇒ no header (the wrapper's default TTL applies). */
   readonly revalidate?: number
+  /** ISR invalidation tags emitted as a bounded `x-nifra-isr-tags` header. */
+  readonly revalidateTags?: readonly string[]
   /** Matched route id; written to `window.__NIFRA_ROUTE__` so the client hydrates this chain. */
   readonly routeId?: string
   /** The matched route's decoded path params - surfaced to the page as `params` (via {@link RenderProps})
@@ -541,6 +585,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     styles = [],
     prerenderedPaths = [],
     revalidate,
+    revalidateTags = [],
     routeId,
     status = 200,
     title = "nifra",
@@ -695,6 +740,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // dedicated header (not the action-revalidation `x-nifra-revalidate`) so the TTL channel never aliases
   // the client's path-list channel.
   if (revalidate !== undefined) headers[ISR_REVALIDATE_HEADER] = String(revalidate)
+  const serializedTags = serializeISRTags(revalidateTags)
+  if (serializedTags !== undefined) headers[ISR_REVALIDATE_TAGS_HEADER] = serializedTags
   const renderProps: RenderProps = {
     data: forComponent,
     actionData: actionSplit?.forComponent,
@@ -1281,12 +1328,6 @@ function headTags(head: Meta | undefined): string {
   return out
 }
 
-/** Resolve a route's `meta` (static or a function of the loader data + params) to a {@link Meta}. */
-export function resolveMeta(meta: MetaInput | undefined, args: MetaArgs): Meta {
-  if (meta === undefined) return {}
-  return typeof meta === "function" ? meta(args) : meta
-}
-
 /**
  * A `<link rel="canonical">` descriptor for a route's `meta.link`. The canonical URL tells search
  * engines which URL is authoritative for a page (deduping query-string / tracking variants).
@@ -1373,68 +1414,6 @@ export function unsafeInlineScript(
   }
 }
 
-/**
- * Merge a route's `<head>` contributions from its layout chain + the page into one {@link Meta}.
- *
- * The head contract (see {@link CreateWebAppOptions} and `LayoutEntry`): a `_layout.tsx` may export
- * `meta` to put sitewide tags (`hreflang`, `preconnect`, a default `<title>`, …) on every page below
- * it. `heads` is passed **outermost layout → … → innermost layout → page** (the same order as the
- * render chain), and merges:
- *  - **`title`** - *nearest-wins*: the last defined value across the list, so the page overrides an
- *    inner layout, which overrides an outer one. A layout `title` is the section default; an undefined
- *    page `title` keeps it.
- *  - **`meta` / `link`** - *concatenated* in list order (outermost first, page last). Duplicate-tag
- *    de-duplication is the caller's concern; the framework emits exactly what's declared so a layout
- *    can ship N `<link rel="alternate" hreflang>` tags and a page can add its own canonical.
- *
- * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a
- * static (by-reference) `Meta` and there is exactly one - otherwise a new object each call. That is
- * fine: {@link headTags}'s memo is keyed on identity, so a per-request merge simply recomputes (its
- * content can vary with loader data anyway).
- */
-export function mergeHeads(heads: readonly Meta[]): Meta {
-  // Single-head fast path (a route with no layout `meta`, by far the common case) - return the
-  // resolved object by reference so headTags' identity-keyed memo hits across requests for static meta.
-  if (heads.length === 1) return heads[0] as Meta
-  let title: string | undefined
-  let lang: string | undefined
-  let dir: Meta["dir"]
-  const meta: MetaDescriptor[] = []
-  const link: LinkDescriptor[] = []
-  const script: ScriptDescriptor[] = []
-  const unsafeScript: UnsafeScriptDescriptor[] = []
-  for (const h of heads) {
-    if (h.title !== undefined) title = h.title // nearest-wins: later (more specific) overrides
-    if (h.lang !== undefined) lang = h.lang // nearest-wins, like title
-    if (h.dir !== undefined) dir = h.dir
-    if (h.meta !== undefined) meta.push(...h.meta)
-    if (h.link !== undefined) link.push(...h.link)
-    if (h.script !== undefined) script.push(...h.script) // concatenated like meta/link (outermost first)
-    if (h.unsafeScript !== undefined) unsafeScript.push(...h.unsafeScript)
-  }
-  // Build the result with only the fields that were actually contributed - an empty `meta`/`link`/
-  // `script` array would otherwise be a spurious (if harmless) key. A mutable local; the cast to `Meta`
-  // is sound because a key is assigned only when defined (so `exactOptionalPropertyTypes` never sees
-  // `undefined`).
-  const merged: {
-    title?: string
-    meta?: Meta["meta"]
-    link?: Meta["link"]
-    script?: Meta["script"]
-    unsafeScript?: Meta["unsafeScript"]
-    lang?: string
-    dir?: Meta["dir"]
-  } = {}
-  if (title !== undefined) merged.title = title
-  if (meta.length > 0) merged.meta = meta
-  if (link.length > 0) merged.link = link
-  if (script.length > 0) merged.script = script
-  if (unsafeScript.length > 0) merged.unsafeScript = unsafeScript
-  if (lang !== undefined) merged.lang = lang
-  if (dir !== undefined) merged.dir = dir
-  return merged as Meta
-}
-
 export interface CreateWebAppOptions {
   readonly adapter: RenderAdapter
   readonly manifest: Manifest
@@ -2225,6 +2204,7 @@ export function createWebApp<Env = unknown>(
           ...stylesOf(route.id),
           prerenderedPaths: options.prerenderedPaths ?? [],
           ...(mod.revalidate !== undefined ? { revalidate: mod.revalidate } : {}),
+          ...(mod.revalidateTags !== undefined ? { revalidateTags: mod.revalidateTags } : {}),
           ...(mod.islandScripts !== undefined ? { islandScripts: mod.islandScripts } : {}),
           ...titleOption,
           ...assemblyCacheFor(mod, chainLayoutModules),
@@ -2440,7 +2420,9 @@ export function generateClientEntry(
   }
 
   return `${[
-    'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web"',
+    // `/client`, never the root: the root's graph carries the server (renderPage, the static-file
+    // server), and Vite's dev server evaluates what it is given instead of tree-shaking it.
+    'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web/client"',
     'import { applyHead, installForms, installHistory, signalHydrated } from "@nifrajs/web/client"',
     // Namespace import: `errorBoundary` is optional (an adapter may not export it). A namespace member
     // access yields `undefined` if absent - unlike a named import, which would be a link error.
@@ -2457,6 +2439,16 @@ export function generateClientEntry(
         '`/client` entry (e.g. "@nifrajs/web-react/client"), or re-export mountRouter from it.',
     )})`,
     "const errorBoundary = __adapter.errorBoundary",
+    // A hot update that the framework cannot actually apply must end in a reload, not in nothing.
+    //
+    // Bun's dev server applies React Fast Refresh to JSX modules. For React that patches the component
+    // and preserves state. For Preact it does not - the module still LOOKS Fast-Refresh-able, so the
+    // update is accepted and then swallowed: `bun:beforeUpdate`/`bun:afterUpdate` both fire, the server
+    // logs a rebuild, and the page silently keeps rendering the old code. An edit that appears to do
+    // nothing is the worst failure mode in a dev loop - worse than a reload, because there is no signal
+    // to act on. An adapter that knows its framework is in that position says so, and the entry turns
+    // the swallowed update into an honest full reload.
+    'if (import.meta.hot && __adapter.hotUpdateNeedsReload) import.meta.hot.on("bun:afterUpdate", () => location.reload())',
     `const errorRouteIds = new Set(${JSON.stringify(errorRouteIds)})`,
     // Each route is a lazy loader: dynamic imports → Bun.build (splitting) emits one chunk per
     // route, shared layouts/deps deduped into shared chunks, so a route's code loads only when

package/src/internal/head-merge.ts

@@ -0,0 +1,80 @@
+/**
+ * Head resolution + merging, in its own module so the CLIENT can have it without the server.
+ *
+ * These two are pure functions over `Meta`, but they used to live in `index.ts` - the module that also
+ * carries `renderPage`, `createWebApp` and the static-file server. The generated client entry imported
+ * them from `@nifrajs/web`, which under a bundler was harmless (server code tree-shakes away) and under
+ * Vite's dev server was fatal: it serves each module as-is, so pulling `index.ts` into the browser graph
+ * executed `public-dir.ts` and the page died on `Module "node:fs/promises" has been externalized`
+ * before hydrating. Splitting them out means the client entry never names the server module at all,
+ * rather than relying on a bundler to remove it afterwards.
+ *
+ * `index.ts` and `client.ts` both re-export from here, so the public API is unchanged in both places.
+ */
+import type {
+  LinkDescriptor,
+  Meta,
+  MetaArgs,
+  MetaDescriptor,
+  MetaInput,
+  ScriptDescriptor,
+  UnsafeScriptDescriptor,
+} from "../manifest.ts"
+
+/** Resolve a route's `meta` export - a static object, or a function of the route's data/params. */
+export function resolveMeta(meta: MetaInput | undefined, args: MetaArgs): Meta {
+  if (meta === undefined) return {}
+  return typeof meta === "function" ? meta(args) : meta
+}
+
+/**
+ * Merge a layout chain's heads, outermost first: `title`/`lang`/`dir` are nearest-wins, and
+ * `meta`/`link`/`script` concatenate in chain order.
+ *
+ * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a
+ * static (by-reference) `Meta` and there is exactly one - otherwise a new object each call. That is
+ * fine: `headTags`'s memo is keyed on identity, so a per-request merge simply recomputes (its
+ * content can vary with loader data anyway).
+ */
+export function mergeHeads(heads: readonly Meta[]): Meta {
+  // Single-head fast path (a route with no layout `meta`, by far the common case) - return the
+  // resolved object by reference so headTags' identity-keyed memo hits across requests for static meta.
+  if (heads.length === 1) return heads[0] as Meta
+  let title: string | undefined
+  let lang: string | undefined
+  let dir: Meta["dir"]
+  const meta: MetaDescriptor[] = []
+  const link: LinkDescriptor[] = []
+  const script: ScriptDescriptor[] = []
+  const unsafeScript: UnsafeScriptDescriptor[] = []
+  for (const h of heads) {
+    if (h.title !== undefined) title = h.title // nearest-wins: later (more specific) overrides
+    if (h.lang !== undefined) lang = h.lang // nearest-wins, like title
+    if (h.dir !== undefined) dir = h.dir
+    if (h.meta !== undefined) meta.push(...h.meta)
+    if (h.link !== undefined) link.push(...h.link)
+    if (h.script !== undefined) script.push(...h.script) // concatenated like meta/link (outermost first)
+    if (h.unsafeScript !== undefined) unsafeScript.push(...h.unsafeScript)
+  }
+  // Build the result with only the fields that were actually contributed - an empty `meta`/`link`/
+  // `script` array would otherwise be a spurious (if harmless) key. A mutable local; the cast to `Meta`
+  // is sound because a key is assigned only when defined (so `exactOptionalPropertyTypes` never sees
+  // `undefined`).
+  const merged: {
+    title?: string
+    meta?: Meta["meta"]
+    link?: Meta["link"]
+    script?: Meta["script"]
+    unsafeScript?: Meta["unsafeScript"]
+    lang?: string
+    dir?: Meta["dir"]
+  } = {}
+  if (title !== undefined) merged.title = title
+  if (meta.length > 0) merged.meta = meta
+  if (link.length > 0) merged.link = link
+  if (script.length > 0) merged.script = script
+  if (unsafeScript.length > 0) merged.unsafeScript = unsafeScript
+  if (lang !== undefined) merged.lang = lang
+  if (dir !== undefined) merged.dir = dir
+  return merged as Meta
+}

package/src/internal/server-boundary.ts

@@ -3,8 +3,7 @@
  *
  * The client build must never ship server-only code, or server-only config, to a browser. Three
  * conventions enforce that, and each has to mean the SAME thing in every pipeline that builds the client
- * - the Bun client build, the Vite dev server, the Vite production build, and `nifra dev --bun`'s refusal
- * (which cannot transform, so it refuses to start instead):
+ * - the Bun client build, the Vite dev server, the Vite production build, and `nifra dev --bun`:
  *
  *   - `*.server` modules - emptied, so a secret / `node:` / native import subtree never reaches the client.
  *   - `*.fn` modules     - replaced with HTTP stubs, so the function bodies (and their imports) stay server-side.