Skip to content

Document

The page's root, giving its family and site layer from the first byte and routing hydration.

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import { documentAttrs, startSite } from "capsomer/behavior/document";

Usage

// app/root.tsx
import { Document, routeHydrates } from "capsomer/react/document";
import { ThemeColor } from "capsomer/react/theme-switch";

export function Layout({ children }: { children: React.ReactNode }) {
  const hydrate = routeHydrates(useMatches());
  return (
    <Document family="navy" site="txasm" hydrate={hydrate} script="/site.js" head={<ThemeColor ground={GROUND} />}>
      {children}
    </Document>
  );
}
// app/site.ts, bundled to /site.js
import { startPage } from "@dustinedwards/site-runtime/page-client";
import { startSite } from "capsomer/behavior/document";
import { enhance as enhanceHeader } from "capsomer/behavior/site-header";
import { enhance as enhanceTabs } from "capsomer/behavior/tabs";

startPage();
startSite([enhanceHeader, enhanceTabs, startIslands]);

API reference

Document

PropTypeRequiredDoes
childrenReactNodeYes
langstring
headReactNodeMore of the head: ThemeColor, the theme script, preloads.
hydratebooleanTrue on a page whose routes hydrate (site-runtime's routeHydrates(useMatches())): React Router's scripts. Otherwise script.
scriptstringThe script a page that does not hydrate loads ("/site.js"): same-origin, deferred, so it needs no nonce.
endReactNodeAfter the content and the scripts: an analytics beacon.
familystringA Capsomer family (data-family): purple, fox, teal, navy, forest, amber and the rest.
sitestringA site layer (data-cap-site), from SITES in tokens/sites.mjs.
theme"light" | "dark" | nullA pinned theme (data-theme), or none to follow the system.

SiteScope

PropTypeRequiredDoes
childrenReactNodeYes
as"div" | "section" | "main" | "article"
classNamestring
familystringA Capsomer family (data-family): purple, fox, teal, navy, forest, amber and the rest.
sitestringA site layer (data-cap-site), from SITES in tokens/sites.mjs.
theme"light" | "dark" | nullA pinned theme (data-theme), or none to follow the system.

Functions

FunctionSignatureDoes
documentAttrs({ family, site, theme }: DocumentScope): Record<string, string>The attributes for <html> or a wrapper. Undefined values are left out, so a spread writes only what is set.
startSite(parts: readonly Starter[], report?: (error: unknown) => void): Promise<number>Starts a page that does not hydrate: runs each part (Capsomer's enhance functions, the site's islands) in order, each on its own, so one that throws never stops the rest, and reports what failed. Answers, once every part that returned a promise has settled, how many failed, thrown or rejected. Call it after site-runtime's startPage() (./page-client), which installs the Trusted Types policy every part writes through.