@hamur/seo
The first-party seo module. Add it to modules and set its options under the seo config key. It serves /robots.txt and /sitemap.xml and, with site.indexable false, tells every crawler to stay away.
// hamur.config.ts
export default defineConfig({
modules: ["@hamur/seo"],
site: { url: "https://example.com" },
seo: { robots: { groups: [{ userAgent: "*", disallow: ["/drafts/"] }], blockAiBots: true }, sitemap: { exclude: ["/legal/**"] } },
routeRules: { "/admin/**": { noindex: true } },
});
default
The module, as defineModule({ meta: { name: "seo", configKey: "seo" } }). Its setup checks seo.robots and seo.sitemap (a wrong value is a build error naming the key), adds the server routes GET /robots.txt, GET /sitemap.xml and GET /sitemap-:n.xml (the parts of a sitemap index), /robots.txt with the route rule swr: 600 (the app's own rule wins) and the sitemap with a cached URL list, and on the static preset adds the first two to the prerender routes, so .output/public/robots.txt and .output/public/sitemap.xml are written, and the sitemap hands its parts to prerenderRoutes.
The app's own answer wins. A public/robots.txt, or a handler whose literal route is /robots.txt, makes the module drop its route in server:extend and log public/robots.txt exists; @hamur/seo serves no /robots.txt (or server/robots.ts#robots answers /robots.txt; @hamur/seo serves none); the build does not fail. /sitemap.xml follows the same rule, and the part route goes with it. With app.baseURL other than / the build warns that crawlers read robots.txt only at the origin's root.
SeoConfig
| Key | Type | Default |
|---|---|---|
robots | boolean | RobotsConfig | true: one group User-agent: * / Allow: /; false serves no robots file |
sitemap | boolean | SitemapConfig | true: /sitemap.xml from the route table and the prerender list; false serves none and drops the Sitemap: line of /robots.txt |
RobotsConfig
| Key | Type | Default |
|---|---|---|
groups | RobotsGroup[] | one * group allowing /; a list replaces it |
blockAiBots | boolean | false: true adds one Disallow: / group per name of a fixed list (GPTBot, ClaudeBot, anthropic-ai, CCBot, Google-Extended, Applebot-Extended, PerplexityBot, Bytespider, meta-externalagent, Amazonbot, cohere-ai) |
fromRules | boolean | true: each route rule pattern with noindex: true adds a Disallow: line to every configured group (/admin/** and /admin/* give /admin/, /admin gives /admin$, a * inside stays * and the line ends in $), with the locale-prefixed copies when @hamur/i18n is installed |
When site.indexable is false (a staging deploy, HAMUR_SITE_ENV=staging) the answer is User-agent: * / Disallow: /, whatever the config says.
SitemapConfig
| Key | Type | Default |
|---|---|---|
sources | string[] | []: the literal routes of GET handlers that answer SitemapEntry[]; their entries follow the pages, in this order |
exclude | string[] | []: route rule patterns (/legal/**, /blog/*) whose paths are left out |
chunkSize | number | 50000: an integer from 1 to 50000; more URLs than this make /sitemap.xml an index of /sitemap-<n>.xml parts |
GET /sitemap.xml answers 200, application/xml; charset=utf-8 and a <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> with one <url><loc> for each page route without params (the copies of @hamur/i18n included), each prerender.routes entry and each routeRules pattern with prerender: true, in that order and each once. A path whose merged route rule has noindex: true or redirect, and a path matching exclude, is left out. Each loc is absolute from site.url and app.baseURL, and &, <, >, ' and " are escaped. Paths that only the prerender:routes hook adds are not listed; each sitemap source then adds its entries.
Without site.url the build warns site.url is not set; /sitemap.xml needs HAMUR_SITE_URL at run time, and the answer is 500 with the log line @hamur/seo: sitemap needs site.url (set site.url or HAMUR_SITE_URL); a preset that prerenders fails on that answer. With site.url, /robots.txt ends with Sitemap: <site.url><app.baseURL>sitemap.xml. The load errors are seo.sitemap must be a boolean or an object (got "yes"), seo.sitemap.<key> is not an option, seo.sitemap.exclude must be an array of route rule patterns (got "/a") and seo.sitemap.exclude[0] must be a route rule pattern starting with "/", seo.sitemap.sources[0] "posts" must be a path starting with "/" and seo.sitemap.chunkSize must be an integer from 1 to 50000 (got 60000). After the server routes are known, a source that is no GET handler route fails the build: seo.sitemap.sources[0] "/_sitemap/posts" is not the route of a GET handler.
Sitemap sources
A source is a GET handler whose answer is a JSON array of SitemapEntry, named in seo.sitemap.sources; the sitemap calls it in process, with no cookie or authorization, so the route needs no extra auth (give it a route rule to keep it from the public if you want). A source path is a literal route: /sitemap.xml, a part route and a path with a param or wildcard fail the build (seo.sitemap.sources[0] "/sitemap.xml" is a route of the sitemap itself). A relative loc, image, video or alternate URL resolves against site.url and app.baseURL as a browser resolves it; an absolute one is kept. A loc must be an http(s) URL on site.url's origin (else the entry is left out and logged), the other URLs must be http(s), and lastmod a W3C datetime (2026-03-07, 2026-03-07T10:00:00Z; March 7, 2024 is left out). Entries come after the pages, and an entry with the loc of an earlier one replaces it.
// server/sitemap.ts, exported from server/index.ts
export const postEntries = defineHandler({
route: "/_sitemap/posts",
method: "GET",
async handler() {
return (await listPosts()).map((post) => ({ loc: `/blog/${post.slug}`, lastmod: post.updatedAt })) satisfies SitemapEntry[];
},
});
// hamur.config.ts
seo: { sitemap: { sources: ["/_sitemap/posts"] } }
A source that answers a status other than 2xx, throws, or answers a value that is not an array of objects with a string loc makes /sitemap.xml answer 500 with the body @hamur/seo: sitemap source /_sitemap/posts failed and the log line sitemap source /_sitemap/posts failed: 503 (or … answered a value that is not an array of entries): a crawler retries a 500 and keeps a sitemap that silently lost half its pages. A field that is wrong is left out and logged once per source and field, for example sitemap entry /blog/a: priority 2 is outside 0 to 1; left out and sitemap entry /blog/a: a video needs content_loc or player_loc; left out.
Index, parts and the static preset
With more than chunkSize URLs GET /sitemap.xml answers a <sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> with one <sitemap><loc> per part, and each part is GET <app.baseURL>sitemap-<n>.xml, n from 1, holding URLs (n-1)·chunkSize + 1 to n·chunkSize. A part past the end, or a name that is not a positive integer, answers 404. A document over 50 MiB is still answered and logs /sitemap-2.xml is 53 MB, over the 50 MB a sitemap may hold; lower seo.sitemap.chunkSize. The URL list is cached for 600 seconds (one run), and /sitemap.xml and its parts read it, so a part number outside that run is 404. On the static preset the sitemap hands every part to prerenderRoutes, so .output/public/sitemap-<n>.xml is written beside sitemap.xml.
Images, videos and alternates
images and videos add xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" and xmlns:video="http://www.google.com/schemas/sitemap-video/1.1" to the root when any entry has them, and one <image:image><image:loc> or <video:video> per item. With @hamur/i18n, the root gains xmlns:xhtml="http://www.w3.org/1999/xhtml" and each page's <url> holds one <xhtml:link rel="alternate" hreflang="<language>" href> per locale plus hreflang="x-default" for the default locale's URL, the set of the head's hreflang links, for a route and each of its copies. A source's entry gets exactly the alternates it gives.
SitemapEntry, SitemapVideo, SitemapChangeFrequency
interface SitemapEntry {
loc: string;
lastmod?: string | Date; // a Date is written as toISOString(), a string only when it is a W3C datetime
changefreq?: SitemapChangeFrequency;
priority?: number; // 0.0 – 1.0
images?: Array<{ loc: string }>;
videos?: SitemapVideo[];
alternates?: Array<{ hreflang: string; href: string }>;
}
interface SitemapVideo {
thumbnail_loc: string;
title: string;
description: string;
content_loc?: string; // one of content_loc and player_loc is required
player_loc?: string;
duration?: number; // seconds
}
type SitemapChangeFrequency = "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
RobotsGroup
interface RobotsGroup {
userAgent: string | string[];
allow?: string[];
disallow?: string[];
crawlDelay?: number;
}
Each group writes one User-agent: line per agent, then Allow:, Disallow: and Crawl-delay:. A path starts with / or * and holds no line break; crawlDelay is a positive number. The load errors are seo.robots must be a boolean or an object (got "yes"), seo.robots.<key> is not an option, seo.robots.groups[0].userAgent must be a non-empty string or an array of them (got ""), seo.robots.groups[0].disallow[1] "admin" must be a path starting with "/" or "*", seo.robots.groups[0].allow[0] cannot contain a line break and seo.robots.groups[0].crawlDelay must be a positive number (got 0).
@hamur/seo/server
Nothing is exported yet; the module's handlers are reached through its own door.