document

document declares what all application HTML documents share: <html>'s lang and a head with a title, title template, meta, link, script, style and <html> and <body> attributes. It renders in SSR, "stream", "prerender", error pages and the shell for "client" routes, with the lowest priority: useHead, useSeoMeta and each page's head override it.

In addition, document.seo (since 1.3) adds each page's <link rel="canonical"> and its og:url, og:title and og:description, and document.idPrefix (since 1.5) changes the prefix of IDs from useId and form.field.

Usage#

// meeko.config.ts
import { defineMeekoConfig } from "@meekojs/meeko/framework";

export default defineMeekoConfig({
  site: "https://example.com",
  document: {
    lang: "es",
    head: {
      title: "My store",            // pages without their own title
      titleTemplate: "%s · My store",
      link: [{ rel: "icon", href: "/favicon.svg", type: "image/svg+xml" }],
      meta: [{ name: "theme-color", content: "#0f172a" }],
    },
    seo: true,
  },
});

Type#

readonly document?: DocumentConfig

interface DocumentConfig {
	lang?: string
	head?: DocumentHead
	seo?: boolean | DocumentSeo
	theme?: ThemeConfig
	idPrefix?: string
}

interface DocumentSeo {
	canonical?: boolean
	ogUrl?: boolean
	ogTitle?: boolean
	ogDescription?: boolean
	origin?: string
}

Options#

Result#

With seo: true and site: "https://example.com", a /docs/api page titled “API” receives:

<title>API · My store</title>
<link rel="canonical" href="https://example.com/docs/api">
<meta property="og:url" content="https://example.com/docs/api">
<meta property="og:title" content="API · My store">

canonical does not include the query string, and error pages receive neither canonical nor og:url.

Examples#

A script before rendering, compatible with CSP#

import { defineMeekoConfig } from "@meekojs/meeko/framework";

export default defineMeekoConfig({
  document: {
    head: { script: [{ children: "document.documentElement.dataset.js = 'on'" }] },
  },
});

With server.contentSecurityPolicy (since 1.7), the script carries each SSR response's nonce and its hash in prerendered pages, without 'unsafe-inline'.

Only the canonical tag#

import { defineMeekoConfig } from "@meekojs/meeko/framework";

export default defineMeekoConfig({
  site: "https://example.com",
  document: { seo: { ogUrl: false, ogTitle: false, ogDescription: false } },
});

Two Meeko applications on the same page#

import { defineMeekoConfig } from "@meekojs/meeko/framework";

export default defineMeekoConfig({ document: { idPrefix: "shop" } });

Common mistakes#

A function in titleTemplate#

export default defineMeekoConfig({ document: { head: { titleTemplate: (title: string) => `${title} · My store` } } as never });

document is fixed at build time and ends up in HTML: meeko check reports a type error and meeko dev, meeko build and meeko routes stop with …/meeko.config.ts: document.head: titleTemplate must be a string here, since it is serialized.

import { defineMeekoConfig } from "@meekojs/meeko/framework";
export default defineMeekoConfig({ document: { head: { titleTemplate: "%s · My store" } } });

The theme inside document#

export default defineMeekoConfig({ document: { theme: { themes: ["light", "dark"] } } as never });

…/meeko.config.ts: document.theme no es una opción de meeko.config.ts; use theme en el nivel superior.

import { defineMeekoConfig } from "@meekojs/meeko/framework";
export default defineMeekoConfig({ theme: { themes: ["light", "dark"] } });

seo without an origin#

export default defineMeekoConfig({ document: { seo: true } }); // without site or MEEKO_PUBLIC_ORIGIN

meeko build stops before compilation with document.seo (canonical y og:url) necesita la URL pública del sitio: declara site en meeko.config.ts (site: "https://example.com") o define MEEKO_PUBLIC_ORIGIN al construir. In meeko dev without an origin, those two tags are not written.

import { defineMeekoConfig } from "@meekojs/meeko/framework";
export default defineMeekoConfig({ site: "https://example.com", document: { seo: true } });

Notes#

• Public. document reaches the browser bundle because it ends up in HTML: do not put secrets in it.
• Security. script and style are written as is in <head>: do not interpolate user or request data.
• Development. Changing meeko.config.ts requires restarting meeko dev.

Related#

• useHeadAdds title, meta, link, script and style tags and html and body attributes to the document while the component is mounted.
• useSeoMetaTyped useHead shortcut for SEO that converts each field (description, Open Graph, Twitter, canonical) to the correct tag.
• useIdReturns an ID unique to each instance and call, identical in server HTML and during hydration, to link labels, controls and help text.
• siteThe site's public URL, of which only the origin is used, for absolute URLs in sitemap.xml, robots.txt and document.seo.
• themeFlicker-free light, dark or custom application themes, with the choice in a cookie, the theme on html from the first byte and useTheme in components.
• Document head: document, useHead and useSeoMetaMeeko as a full-stack framework
• Per-page canonical URL and Open GraphMeeko as a full-stack framework