@kitr/seo 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -18,10 +18,15 @@ export interface SeoConfig {
   site?: SeoSite;
   /** Default rendering for routes that set no `ssr` of their own (the router's `defaultSsr`). `ssrRoute()` overrides it per route. */
   ssr?: boolean | 'data-only';
-  /** Routes to prerender at build time; `crawlLinks` follows links from them. A `static` web platform prerenders everything. */
+  /**
+   * Routes to prerender at build time; `crawlLinks` follows links from them. A `static` web platform
+   * prerenders everything. A listed route that fails to render fails the build; a crawled link only
+   * warns, unless `failOnError` is `true`.
+   */
   prerender?: string[] | {
     routes: string[];
     crawlLinks?: boolean;
+    failOnError?: boolean;
   };
   /** Rules for `robotsTxt()`, which the build writes to `robots.txt` unless `public/robots.txt` exists. `false` writes none. */
   robots?: false | {
@@ -43,13 +48,13 @@ declare module '@kitr/core' {
 export declare const defineConfig: <const C extends SeoConfig>(config: C) => C;
 /** What one page passes to `seo()`. Every field is optional; `site` supplies the defaults. */
 export interface SeoInput {
-  /** The page title, without the site name. */
+  /** The page title, without the site name. Default: `title` from the route's loader data. */
   title?: string;
-  /** The page summary for search results and share cards. */
+  /** The page summary for search results and share cards. Default: `description` from the route's loader data. */
   description?: string;
   /** Share image for this page; replaces `site.image`. Use an absolute URL. */
   image?: string;
-  /** The page's canonical URL; falls back to `site.url`, so pass it on every page. */
+  /** The page's canonical URL. Default: `site.url` plus the matched path from the `head` argument, else `site.url`. */
   url?: string;
   /** `og:type`. Default `website`. */
   type?: 'website' | 'article' | 'product';
@@ -70,7 +75,9 @@ export type SeoContext = object;
  * Meta tags for a route's `head()`: `head: (ctx) => seo({ title, description }, ctx)`.
  * Covers title, description, Open Graph, Twitter cards, canonical and robots. Pass the `head`
  * argument (or the app) as the second argument so the site name, image and origin from
- * `config/seo.ts` apply; without it only `input.site` does.
+ * `config/seo.ts` apply; without it only `input.site` does. From the `head` argument it also
+ * takes the canonical URL (`site.url` plus the matched path) and, when the loader returned
+ * them, `title` and `description`: `head: (ctx) => seo({}, ctx)`.
  */
 export declare function seo(input: SeoInput, context?: SeoContext): {
   meta: Record<string, string>[];

package/dist/index.js

@@ -19,18 +19,42 @@ function appOf(context) {
 	};
 	return candidates(context).find(isApp);
 }
+/** The matched path from a `head` argument (`match.pathname`), or a `location`'s. */
+function pathOf(context) {
+	const v = context;
+	const path = v?.match?.pathname ?? v?.location?.pathname;
+	return typeof path === "string" && path.startsWith("/") ? path : void 0;
+}
+/** `title` and `description` from a `head` argument's `loaderData`, when the loader returned them. */
+function fromLoader(context) {
+	const data = context?.loaderData;
+	if (!data || typeof data !== "object") return {};
+	return {
+		...typeof data.title === "string" ? { title: data.title } : {},
+		...typeof data.description === "string" ? { description: data.description } : {}
+	};
+}
 /**
 * Meta tags for a route's `head()`: `head: (ctx) => seo({ title, description }, ctx)`.
 * Covers title, description, Open Graph, Twitter cards, canonical and robots. Pass the `head`
 * argument (or the app) as the second argument so the site name, image and origin from
-* `config/seo.ts` apply; without it only `input.site` does.
+* `config/seo.ts` apply; without it only `input.site` does. From the `head` argument it also
+* takes the canonical URL (`site.url` plus the matched path) and, when the loader returned
+* them, `title` and `description`: `head: (ctx) => seo({}, ctx)`.
 */
 function seo(input, context) {
 	const configured = appOf(context)?.config.get("seo", {});
 	const site = input.site ?? configured?.site ?? {};
+	const loaded = fromLoader(context);
+	input = {
+		...input,
+		title: input.title ?? loaded.title,
+		description: input.description ?? loaded.description
+	};
 	const title = input.title ? site.name && input.title !== site.name ? `${input.title} · ${site.name}` : input.title : site.name;
 	const image = input.image ?? site.image;
-	const url = input.url ?? site.url;
+	const path = pathOf(context);
+	const url = input.url ?? (site.url && path ? `${site.url.replace(/\/+$/, "")}${path}` : site.url);
 	const meta = [];
 	if (title) meta.push({ title }, {
 		property: "og:title",

package/docs/api.md

@@ -69,7 +69,9 @@ function seo(input: SeoInput, context?: SeoContext): {
 Meta tags for a route's `head()`: `head: (ctx) => seo({ title, description }, ctx)`.
 Covers title, description, Open Graph, Twitter cards, canonical and robots. Pass the `head`
 argument (or the app) as the second argument so the site name, image and origin from
-`config/seo.ts` apply; without it only `input.site` does.
+`config/seo.ts` apply; without it only `input.site` does. From the `head` argument it also
+takes the canonical URL (`site.url` plus the matched path) and, when the loader returned
+them, `title` and `description`: `head: (ctx) => seo({}, ctx)`.
 
 ### ssrRoute
 
@@ -104,10 +106,15 @@ interface SeoConfig {
   site?: SeoSite;
   /** Default rendering for routes that set no `ssr` of their own (the router's `defaultSsr`). `ssrRoute()` overrides it per route. */
   ssr?: boolean | 'data-only';
-  /** Routes to prerender at build time; `crawlLinks` follows links from them. A `static` web platform prerenders everything. */
+  /**
+   * Routes to prerender at build time; `crawlLinks` follows links from them. A `static` web platform
+   * prerenders everything. A listed route that fails to render fails the build; a crawled link only
+   * warns, unless `failOnError` is `true`.
+   */
   prerender?: string[] | {
     routes: string[];
     crawlLinks?: boolean;
+    failOnError?: boolean;
   };
   /** Rules for `robotsTxt()`, which the build writes to `robots.txt` unless `public/robots.txt` exists. `false` writes none. */
   robots?: false | {
@@ -124,13 +131,13 @@ Options for `config/seo.ts`. The build reads `prerender`, `site.url` and `robots
 
 ```ts
 interface SeoInput {
-  /** The page title, without the site name. */
+  /** The page title, without the site name. Default: `title` from the route's loader data. */
   title?: string;
-  /** The page summary for search results and share cards. */
+  /** The page summary for search results and share cards. Default: `description` from the route's loader data. */
   description?: string;
   /** Share image for this page; replaces `site.image`. Use an absolute URL. */
   image?: string;
-  /** The page's canonical URL; falls back to `site.url`, so pass it on every page. */
+  /** The page's canonical URL. Default: `site.url` plus the matched path from the `head` argument, else `site.url`. */
   url?: string;
   /** `og:type`. Default `website`. */
   type?: 'website' | 'article' | 'product';

package/docs/index.md

@@ -88,6 +88,7 @@ export default defineConfig({
 | `prerender` | `[]` | Routes the build renders to HTML files. An array of paths, or `{ routes, crawlLinks }`. |
 | `prerender.routes` | `[]` | The paths to prerender, such as `['/', '/pricing']`. |
 | `prerender.crawlLinks` | `false` | Also prerender every page linked from those routes. |
+| `prerender.failOnError` | `false` | Fail the build when a crawled page fails to render, not only a listed one. |
 | `robots` | `{}` | Rules for the `robots.txt` the build writes (see [Write robots.txt](#write-robotstxt)). `false` writes none. |
 | `robots.allow` | `['/']` | `Allow:` lines. |
 | `robots.disallow` | `[]` | `Disallow:` lines. |
@@ -137,24 +138,17 @@ View the page source of `/pricing`. The root route's `<HeadContent />` renders t
 
 ## Use your site defaults on every page
 
-`seo()` takes the site name, share image, handle and locale from `site`, so every title gets the site name once you pass `ctx`. Give each page its own URL:
+`seo()` takes the site name, share image, handle and locale from `site`, so every title gets the site name once you pass `ctx`. It also builds the page's URL from `site.url` and the matched path in `ctx`, so a page needs only its title and description:
 
 ```ts
 // app/routes.ts
 import { seo } from '@kitr/seo'
 
 r.page('/pricing', {
-  head: (ctx) =>
-    seo(
-      {
-        title: 'Pricing',
-        description: 'Plans for every team size.',
-        url: 'https://acme.com/pricing',
-      },
-      ctx,
-    ),
+  head: (ctx) => seo({ title: 'Pricing', description: 'Plans for every team size.' }, ctx),
   lazy: () => import('./pages/pricing'),
 })
+// => canonical and og:url: https://acme.com/pricing
 ```
 
 With the config from [Configure](#configure), the title becomes `Pricing · Acme`, and `og:site_name`, `og:locale`, `og:url`, `og:image`, `twitter:site` and a canonical link are filled in. A `site` passed to `seo()` replaces the config's, for a page that belongs to another brand. How the values combine:
@@ -162,15 +156,33 @@ With the config from [Configure](#configure), the title becomes `Pricing · Acme
 | Tag | Comes from |
 | --- | --- |
 | `<title>` | `title · site.name`; `title` alone when it equals `site.name`; `site.name` when there is no `title`. |
+| `title`, `description` | The options, else `title` and `description` from the loader's data. |
 | `og:title`, `twitter:title` | `title` without the site name. |
 | `description`, `og:description`, `twitter:description` | `description`, only when set. |
-| `og:url`, canonical link | `url`, else `site.url`. |
+| `og:url`, canonical link | `url`, else `site.url` plus the matched path from `ctx`, else `site.url`. |
 | `og:image`, `twitter:image` | `image`, else `site.image`. |
 | `twitter:card` | `summary_large_image` when there is an image, else `summary`. |
 | `og:type` | `type`, default `'website'`. |
 
-> [!WARNING] Pass url on every page
-> Without it, `og:url` and the canonical link fall back to `site.url`, so the page tells search engines it is a copy of your home page and they may drop it.
+> [!WARNING] Pass ctx on every page
+> Without `ctx` (or `url`), `og:url` and the canonical link fall back to `site.url`, so the page tells search engines it is a copy of your home page and they may drop it.
+
+When the loader returns `title` and `description`, `seo()` reads them from `ctx.loaderData`, so a page with data needs no options at all:
+
+```ts
+// app/routes.ts
+import { seo } from '@kitr/seo'
+import { getDoc } from '#app/content/docs'
+
+r.page('/docs/$slug', {
+  loader: ({ params }) => getDoc(params.slug), // => { title: 'Agents', description: '...', html: '...' }
+  head: (ctx) => seo({}, ctx),
+  lazy: () => import('./pages/docs/slug'),
+})
+// => <title>Agents · Acme</title>, canonical https://acme.com/docs/agents
+```
+
+Options you pass win over the loader's values and over the derived URL.
 
 ## Set defaults in the root route
 
@@ -259,9 +271,7 @@ r.page('/blog/$slug', {
   head: (ctx) =>
     seo(
       {
-        title: ctx.loaderData?.title,
         description: ctx.loaderData?.excerpt,
-        url: `https://acme.com/blog/${ctx.params.slug}`,
         type: 'article',
         keywords: ctx.loaderData?.tags,
       },
@@ -283,7 +293,7 @@ export default function PostPage() {
 }
 ```
 
-`head` runs after the loader, on the server for the first request and on the client after each navigation. Search engines ignore `keywords`; it only helps your own site search.
+The title comes from the post's `title` and the URL from the path. `head` runs after the loader, on the server for the first request and on the client after each navigation. Search engines ignore `keywords`; it only helps your own site search.
 
 ## Keep a page out of search results
 
@@ -380,6 +390,13 @@ What the build does with `prerender` in each web mode:
 > [!WARNING] No computed lists
 > `prerender: posts.map(...)` is not seen. Write each path as a string, or list a page that links to all of them with `crawlLinks: true`.
 
+A page that fails to render prints one line and stays out of the sitemap. A listed route fails the build; a crawled link only warns, unless `failOnError: true`:
+
+```sh
+kitr build site
+# [prerender] 404 at /blog/draft, linked from /blog
+```
+
 ## Generate a sitemap
 
 Set `site.url` to a string literal, as in the config above, and the build turns on [TanStack Start's sitemap](https://tanstack.com/start/latest/docs/framework/react/guide/static-prerendering) with that host. It writes `sitemap.xml` from the pages it prerenders, so prerender (or crawl to) every page you want listed. `robotsTxt()` points crawlers at `<site.url>/sitemap.xml`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitr/seo",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "@kitr/seo: meta and Open Graph tags per route, prerender list, sitemap and robots, cache headers. Works for SSR, static sites, SPAs and PWAs.",
   "kitr": {
     "name": "seo",
@@ -41,7 +41,7 @@
     "docs"
   ],
   "dependencies": {
-    "@kitr/core": "0.3.0"
+    "@kitr/core": "0.3.2"
   },
   "peerDependencies": {},
   "peerDependenciesMeta": {},