Document head

head returns tags for title, meta, link, style and base. The tags of all matched routes, outermost first, are merged by identity: the last title wins, meta tags are keyed by name, property, http-equiv or charset, and a route that leaves removes its tags. script and noscript are refused so that nothing in the head can bypass a CSP nonce. Dusk adds charset and viewport meta tags by default; a route replaces them by declaring a meta with the same identity.

Annotate the return type as HeadTag[]. Without it TypeScript infers tag: string for a standalone export const head = () => [...], and the generated route tree no longer type-checks.

The <html> attributes are request state: set event.document.lang and event.document.dir in middleware before the page renders, or document.lang in the handler options for a fixed language. Extra markup for every page's <head> goes in document.head: trusted HTML, either a string (the same for every request; never put request data in it) or a function (event) => string that runs for every page response and receives the request event, so it can use event.nonce for an inline script under a Content-Security-Policy (the @shadow-js/ui no-flash theme script is the usual case, see the script and a Content Security Policy). A function that throws, or returns something other than a string, is reported to onError with phase "head" and the page renders without it.

import type { HandlerOptions, Middleware } from "@shadow-js/dusk/server";

/** Pages under /ar are right to left. */
const direction: Middleware = (event, next) => {
  if (event.url.pathname === "/ar" || event.url.pathname.startsWith("/ar/")) {
    event.document.lang = "ar";
    event.document.dir = "rtl";
  }
  return next();
};

const options: Omit<HandlerOptions, "manifest"> = {
  security: { allowedHosts: ["localhost"] },
  middleware: [direction],
};

export default options;

import type { JSX } from "@shadow-js/web";

export default function Arabic(): JSX.Element {
  return <h1>مرحبا</h1>;
}