layout()

layout() creates a route-scoped shell. MiniFW composes every layout whose pattern matches a requested page(), then places the result inside the document generated by mini(). Document markup, global assets, HTMX, and the browser runtime are configured through mini().

Define A Shell

The page argument contains a rendered nested layout or leaf page. Set pageTarget to a stable selector in the returned markup; MiniFW targets it for compatible boosted navigation.

import { layout } from "@calvinbonner/minifw/core";
import { html } from "@calvinbonner/minifw/helpers";

const appLayout = layout(
  ({ page }) => html`<main id="app-page">${page}</main>`,
  { pageTarget: "#app-page" },
);

The default target is body. Provide an explicit target whenever the layout has persistent markup around its nested page content.

Nested Route Layouts

Register layouts through mini({ layouts }). Every matching pattern applies, from least to most specific:

const docsLayout = layout(
  ({ page }) => html`
    <aside>${documentationTree()}</aside>
    <section id="docs-page">${page}</section>
  `,
  { pageTarget: "#docs-page" },
);

mini({
  layouts: {
    "*": appLayout,
    "/docs/*": docsLayout,
  },
  routes: { "/docs/*": documentation },
});

A request to /docs/core/page renders the page inside docsLayout, then wraps that result in appLayout. A trailing /* layout matches both its base route and descendants, so /docs/* covers /docs and /docs/core/page.

Boosted Navigation

MiniFW compares the destination layout chain with the browser's current chain for boosted HTMX navigation. When both chains match, it returns only the leaf page and sends HX-Retarget for the innermost layout's pageTarget. Persistent outer markup, such as a documentation navigation tree, stays in the browser.

When the chains differ, such as navigating from / to /docs/core/page, MiniFW sends HX-Redirect and HTMX performs a full page load. This ensures the server can render the correct document and layout structure.

Use fragment() for reusable context-free markup, and partial() for a separately requested HTMX endpoint.