Skip to content

Private previewMost of the architecture is written. First public release in 2027.

SEO

Hamur gives a site its address, its search tags, a robots.txt, a sitemap, icons, a web app manifest and feeds from a few config keys and files. The core holds site, the head defaults, the manifest and feed; @hamur/seo adds /robots.txt and /sitemap.xml.

ts
import type { SeoConfig } from "@hamur/seo";
import { defineConfig } from "hamur";

const seo = {
  robots: { groups: [{ userAgent: "*", disallow: ["/drafts/"] }], blockAiBots: true },
  sitemap: { sources: ["/_sitemap/posts"], exclude: ["/legal/**"] },
} satisfies SeoConfig;

export default defineConfig({
  framework: "react",
  modules: ["@hamur/seo"],
  site: {
    url: "https://example.com",
    name: "Example",
    description: "Notes on building for the web",
    canonicalQuery: ["page"],
  },
  seo,
  routeRules: { "/admin/**": { noindex: true } },
  app: {
    head: { link: [{ rel: "alternate", type: "application/rss+xml", title: "Blog", href: "/feed.xml" }] },
    manifest: {
      short_name: "Example",
      display: "standalone",
      theme_color: "#0b5fff",
      icons: [{ src: "/icon-192.png", sizes: "192x192", type: "image/png" }],
    },
  },
});

Site config

site says what the site is. It is a core key and needs no module.

KeyDefault
site.urlunsetthe canonical origin, such as https://example.com, with no path; app.baseURL adds the path. HAMUR_SITE_URL sets it at run time
site.nameunsetthe site's name: og:site_name, the title template, %site.name, the manifest's name. HAMUR_SITE_NAME sets it at run time
site.descriptionunsetthe default description meta, a feed's default description and the manifest's description
site.envthe mode: development under hamur dev, production under hamur build, staging with --mode stagingthe deploy environment. HAMUR_SITE_ENV sets it at run time, then VERCEL_ENV on vercel presets or CONTEXT on netlify presets (deploy-preview reads preview, dev reads development)
site.indexablesite.env === "production"whether crawlers may index the site
site.canonicalQuery[]the query parameter names that stay in canonical links and og:url; every other parameter is dropped
site.headDefaultstruefalse pushes no site defaults to the head

The server resolves HAMUR_SITE_URL, HAMUR_SITE_NAME and HAMUR_SITE_ENV when it starts, so one build deployed as a preview is not indexable and the same build promoted to production is, with no rebuild. A prerendered page keeps the values of the build. A HAMUR_SITE_URL that is not an origin stops the server with HAMUR_SITE_URL "example.com" must be an origin such as "https://example.com"; a bad site.url fails the config the same way (site.url "example.com" must be an origin such as "https://example.com" (app.baseURL adds the path)). A runtimeConfig key that reads one of the three variables fails at load.

useSiteConfig() of every adapter returns the resolved value, frozen: url, name, description, env, indexable, canonicalQuery and headDefaults. The server reads it with useSiteConfig(event) of hamur/server. The document carries it, so the browser reads what the server rendered. site.url is the address search engines see; it is not where the server is reached.

What the site gives the head

With headDefaults on, every page gets these tags, below app.head and every useHead, so any of them can be replaced:

TagWhen
<link rel="canonical"> and og:urlsite.url is set and the page is not the error page. The value is site.url, app.baseURL and the path, the query cut to canonicalQuery, in the form app.trailingSlash answers with
og:site_namesite.name is set
og:typealways website
descriptionsite.description is set
the title template %s %separator %site.namesite.name is set: a page titled Anvil gets Anvil | Example, and a page with no title gets Example
twitter:card summary_large_imagean og:image tag exists

A relative og:image, twitter:image, og:url, canonical or alternate URL is made absolute against site.url and app.baseURL, as a browser resolves it, with or without headDefaults. An asset you import is already a path under app.buildAssetsDir and stays on it. Without site.url a relative value stays as written, and crawlers need an absolute one.

site.indexable is false outside production. Then /robots.txt answers User-agent: * and Disallow: /, whatever its config says. A route rule with noindex: true keeps one set of paths out: the sitemap leaves them out and the robots file adds a Disallow: line for them.

Robots

Add the module and set seo.robots:

sh
bun add @hamur/seo

With the module and no options, /robots.txt allows everything and ends with Sitemap: <site.url><app.baseURL>sitemap.xml when site.url is set. Options:

  • groups: a list of { userAgent, allow?, disallow?, crawlDelay? } that replaces the default group.
  • blockAiBots: true adds one Disallow: / group for each name of a fixed list of AI crawlers.
  • fromRules (default true): each route rule pattern with noindex: true adds a Disallow: line to every group.

robots: false serves no file. A public/robots.txt, or a handler whose route is /robots.txt, wins: the module drops its own route and logs it. Every option, its default and its error message is in the @hamur/seo reference.

Sitemap

/sitemap.xml lists each page route without params (with the copies @hamur/i18n makes), each prerender.routes entry and each route rule pattern with prerender: true, once each. A path with noindex: true or a redirect rule, and a path that matches seo.sitemap.exclude, is left out. Every loc is absolute from site.url. Without site.url the build warns, and the answer is a 500 that says what to set.

Sources

Pages are not the only URLs of a site. A sitemap source is a GET handler that answers a list of SitemapEntry; name its literal route in seo.sitemap.sources. Its entries come after the pages, in the order of the list, and an entry with the loc of an earlier one replaces it.

ts
import type { SitemapEntry } from "@hamur/seo";
import { defineHandler } from "hamur/server";

interface Post {
  slug: string;
  updatedAt: string;
}

async function listPosts(): Promise<Post[]> {
  return [{ slug: "hello", updatedAt: "2026-03-07" }];
}

export const postEntries = defineHandler({
  route: "/_sitemap/posts",
  method: "GET",
  async handler() {
    const posts = await listPosts();
    return posts.map((post): SitemapEntry => ({ loc: `/blog/${post.slug}`, lastmod: post.updatedAt, changefreq: "weekly" }));
  },
});

A SitemapEntry has loc, and lastmod (a Date or a W3C datetime string), changefreq, priority (0 to 1), images, videos and alternates. A relative loc is resolved against site.url. A source that fails, or answers something that is not a list of entries, makes /sitemap.xml answer 500, so a crawler retries and never keeps a sitemap that lost half its pages. A field that is wrong is left out and logged once.

Index and parts

With more than seo.sitemap.chunkSize URLs (the default, and the most it may be, is 50000), /sitemap.xml is a sitemap index of /sitemap-<n>.xml parts. On the static preset the module passes each part to prerenderRoutes, so every file is written.

Alternates

With @hamur/i18n, each page's <url> holds one xhtml:link rel="alternate" per locale and an x-default, the same set as the head's hreflang links.

Prerendering paths a handler knows

A handler that answers a prerender request may name pages for the crawl with prerenderRoutes(event, ...paths) of hamur/server. The paths join the queue once, under the same rules as links (prerender.ignore and prerender: false apply). Outside a prerender the call does nothing.

ts
import { defineHandler, prerenderRoutes } from "hamur/server";

export const hiddenList = defineHandler({
  route: "/hidden-list.json",
  method: "GET",
  handler(_, { event }) {
    prerenderRoutes(event, "/hidden/1", "/hidden/2");
    return ["/hidden/1", "/hidden/2"];
  },
});

Metadata files

Files in app/ become head tags with no code. See Head for the rules.

FileGives
favicon.ico, icon.*, apple-icon.*the icon links, with sizes read from the file
opengraph-image.*, twitter-image.*og:image with type, width, height and og:image:alt, and twitter:image, per route folder

A file that is not what its extension says fails the build with its path. A page file named opengraph-image or twitter-image fails it too: a generated image is a handler route whose URL a page sets with useSeoMeta({ ogImage }).

Web app manifest

app.manifest is an object of W3C manifest members (the WebAppManifest type of hamur). Hamur serves it at <baseURL>manifest.webmanifest as application/manifest+json and links it from every document. name, description and start_url default to site.name, site.description and app.baseURL. The static preset writes the file. false serves none, and a public/manifest.webmanifest together with app.manifest fails the build with public/manifest.webmanifest and app.manifest both define the manifest; keep one. An app.head that already links a manifest keeps its link.

Structured data

useHead({ jsonLd }) writes one <script type="application/ld+json"> for each object and adds "@context": "https://schema.org" when the object has none. Objects with the same @id keep one tag, the later. The text is escaped, so no value can close the element, and the tag takes the request's CSP nonce. See Head.

Feeds

feed of hamur/server is the body of a raw handler that answers RSS 2.0, Atom 1.0 or JSON Feed 1.1. format is "rss" (default), "atom" or "json".

ts
import { defineHandler, feed } from "hamur/server";

interface Post {
  slug: string;
  title: string;
  summary: string;
  date: Date;
}

async function listPosts(): Promise<Post[]> {
  return [{ slug: "hello", title: "Hello", summary: "First post", date: new Date("2026-03-07") }];
}

export const rss = defineHandler({
  route: "/feed.xml",
  method: "GET",
  raw: true,
  handler: feed(async () => ({
    title: "Example blog",
    items: (await listPosts()).map((post) => ({
      title: post.title,
      link: `/blog/${post.slug}`,
      published: post.date,
      description: post.summary,
    })),
  })),
});

export const atom = defineHandler({
  route: "/feed.atom",
  method: "GET",
  raw: true,
  handler: feed(async () => ({
    format: "atom",
    title: "Example blog",
    updated: new Date("2026-03-07"),
    items: [],
  })),
});

Relative links resolve against site.url. description defaults to site.description, link to the site's address and an item's id to its absolute link. Content that XML cannot hold is removed or escaped for you. The mistakes are thrown in the handler and logged, for example feed: item link "/a" is relative and site.url is not set and feed: atom item "A" needs published or updated. On a preset that prerenders, a route without params whose handler is feed(…) is written as a file. Readers find the feed through app.head.link with rel: "alternate", as the config above does.