@ingram-tech/nk-seo 0.9.0 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,7 +1,6 @@
1
1
  # @ingram-tech/nk-seo
2
2
 
3
- SEO primitives for Next.js sites, factored out of the patterns Next.js sites
4
- keep re-implementing:
3
+ SEO primitives for Next.js:
5
4
 
6
5
  1. **`<JsonLd>`** + **typed schema.org builders** — `faqPage`, `breadcrumbList`,
7
6
  `article`, `softwareApplication`, `organization`, `website`, `person`,
@@ -19,7 +18,7 @@ keep re-implementing:
19
18
  alternates (query-param or path-prefix strategy).
20
19
 
21
20
  The package root (`@ingram-tech/nk-seo`) is **pure** — builders and the metadata
22
- factory, no React — so `sitemap.ts` and route handlers can import it freely. The
21
+ factory, no React, so `sitemap.ts` and route handlers can import it freely. The
23
22
  components live at `@ingram-tech/nk-seo/components`.
24
23
 
25
24
  ## Install
@@ -28,9 +27,9 @@ components live at `@ingram-tech/nk-seo/components`.
28
27
  bun add @ingram-tech/nk-seo
29
28
  ```
30
29
 
31
- `next` and `react` are optional peers — the package root is runtime-free of
32
- both; the `/components` and `/og` entries need them (`/og` uses `next/og` and
33
- the React JSX runtime).
30
+ `next` and `react` are optional peers. The package root is runtime-free of both;
31
+ the `/components` and `/og` entries need them (`/og` uses `next/og` and the
32
+ React JSX runtime).
34
33
 
35
34
  ## Structured data
36
35
 
@@ -64,11 +63,10 @@ const seo = createSeo({
64
63
  <JsonLd data={seo.breadcrumbs([{ name: "Home", path: "/" }, { name: "Blog", path: "/blog" }, { name: title, path: `/blog/${slug}` }])} />
65
64
  ```
66
65
 
67
- `createSeo` resolves **nested** URL fields too — the organization's `url`/`logo`
68
- and `offers.url` may be site-relative, as in the example above. Already have
69
- absolute URLs and don't want the factory? The standalone builders (`faqPage`,
70
- `article`, `breadcrumbList`, …) take absolute URLs directly (they resolve
71
- nothing).
66
+ `createSeo` resolves **nested** URL fields too: the organization's `url`/`logo`
67
+ and `offers.url` may be site-relative, as in the example above. The standalone
68
+ builders (`faqPage`, `article`, `breadcrumbList`, …) take absolute URLs directly
69
+ and resolve nothing.
72
70
 
73
71
  Every builder returns a typed node (`FaqPageNode`, `ArticleNode`, …), so the
74
72
  shape survives past the call site. `<JsonLd data={...} />` accepts a single node
@@ -103,8 +101,8 @@ Values passed this way aren't reflected in the returned node type.
103
101
 
104
102
  For a node type no builder covers, `<JsonLd data={…} />` takes **any** object or
105
103
  array of objects. Hand-written nodes still get the `<` / U+2028 escaping, which
106
- is the security-relevant half of the package — worth preferring over
107
- `dangerouslySetInnerHTML` even with no builder involved.
104
+ is worth preferring over `dangerouslySetInnerHTML` even with no builder
105
+ involved.
108
106
 
109
107
  `article` covers `Article`, `BlogPosting`, `NewsArticle`, `ScholarlyArticle`,
110
108
  `TechArticle` (the right type for API/developer docs) and `Report` via `type`.
@@ -156,21 +154,35 @@ needed — each is merged into the generated object and wins on conflict. With
156
154
  `titleTemplate` set, `pageMetadata.root()` emits `title.template`, so plain page
157
155
  titles render as "Services | Acme" without every page appending the suffix.
158
156
 
159
- On a localized site the per-page `alternates` and `locale` are what make the
160
- factory usable — `alternates.languages` is what Next renders as
161
- `<link rel="alternate" hreflang>`, and `og:locale` has to vary per page:
157
+ On a localized site give the factory the locale cluster once and every page
158
+ emits its `alternates.languages` (what Next renders as
159
+ `<link rel="alternate" hreflang>`, `x-default` included) and a canonical that
160
+ follows the address. `@ingram-tech/nk-i18n`'s routing object fits as-is:
162
161
 
163
162
  ```ts
164
- import { hreflangAlternates } from "@ingram-tech/nk-seo";
163
+ export const pageMetadata = createMetadata({
164
+ baseUrl: routing.baseUrl,
165
+ siteName: "Acme",
166
+ hreflang: routing, // or { locales, strategy, param, hrefLangTags }
167
+ });
165
168
 
166
- const { languages } = hreflangAlternates(HREFLANG_CONFIG, `/${locale}/about`);
169
+ // A dynamic page: the URL locale makes the canonical self-reference /fr/about.
167
170
  return pageMetadata({
168
- title, description, path: `/${locale}/about`,
169
- alternates: { languages },
170
- locale: "fr_BE", // overrides the site-wide `locale`
171
+ title, description, path: "/about",
172
+ urlLocale: await getUrlLocale(routing), // from "@ingram-tech/nk-i18n/next"
173
+ locale: "fr_BE", // og:locale, overrides the site-wide one
171
174
  });
175
+
176
+ // A static page (`force-static`): one document for every visitor, so no
177
+ // `urlLocale` — it canonicalizes to the bare, x-default address.
178
+ return pageMetadata({ title, description, path: `/posts/${slug}` });
172
179
  ```
173
180
 
181
+ This is the wiring to prefer over `<HreflangLinks>`: it needs no request
182
+ header, so it works on statically rendered routes, and there is nothing to
183
+ forget in middleware. Reach for the component, or the pure `hreflangAlternates`,
184
+ only on pages that don't go through `pageMetadata`.
185
+
174
186
  ## Sitemap & robots
175
187
 
176
188
  ```ts
@@ -204,9 +216,9 @@ export default () =>
204
216
  });
205
217
  ```
206
218
 
207
- When `isProduction` is false the whole site is disallowed — the one SEO
208
- safeguard everyone forgets on Vercel, where preview and branch deployments are
209
- otherwise crawlable and compete with the production domain for the same content.
219
+ When `isProduction` is false the whole site is disallowed. Without it, Vercel
220
+ preview and branch deployments are crawlable and compete with the production
221
+ domain for the same content.
210
222
 
211
223
  ## Open Graph image
212
224
 
@@ -232,8 +244,8 @@ export default () =>
232
244
  ```
233
245
 
234
246
  Pass `logo` (absolute URL or data URI) to replace the accent-square mark with
235
- your logo, and `fonts` + `fontFamily` to render with the brand typeface —
236
- `fonts` is forwarded to `ImageResponse`, which takes raw TTF/OTF/WOFF data.
247
+ your logo, and `fonts` + `fontFamily` to render with your own typeface. `fonts`
248
+ is forwarded to `ImageResponse`, which takes raw TTF/OTF/WOFF data.
237
249
 
238
250
  ### Two ways the generated card silently doesn't reach your pages
239
251
 
@@ -261,13 +273,12 @@ either at the image route and every page it builds carries the card.
261
273
  **Locale-negotiating middleware eats the image route.** A site that redirects
262
274
  any path lacking a locale prefix also redirects `/opengraph-image`, so the card
263
275
  URL never resolves. Put the file at `app/[locale]/opengraph-image.tsx` instead:
264
- it dodges the redirect and gives per-locale cards from `params`. That is the
265
- better default for any localized site.
276
+ it dodges the redirect and gives per-locale cards from `params`.
266
277
 
267
- The template encodes the Satori rule that trips everyone up: every node with
268
- more than one child sets `display: flex`, and text nodes are never mixed with
269
- sibling elements — so the headline stays a plain string and the accent rides on
270
- the mark, not a coloured `<span>` inside the title.
278
+ The template follows the two Satori structural rules: every node with more than
279
+ one child sets `display: flex`, and text nodes are never mixed with sibling
280
+ elements. That is why the headline stays a plain string and the accent rides on
281
+ the mark rather than a coloured `<span>` inside the title.
271
282
 
272
283
  Type-check won't help here: `ImageResponse` accepts all of
273
284
  `React.CSSProperties` and Satori silently drops what it doesn't know. Two guards
@@ -276,7 +287,7 @@ which flags unsupported style properties, `calc()`, and the two structural rules
276
287
  in files that import `next/og` or are an `opengraph-image`/`twitter-image`
277
288
  convention. And rendering remains the final validator: this package renders its
278
289
  template through the real satori + resvg pipeline in its own tests, so a site
279
- hand-rolling extra cards should add the same guard — a vitest file (node
290
+ hand-rolling extra cards should add the same guard: a vitest file (node
280
291
  environment) that renders each `opengraph-image.tsx` and asserts a valid PNG
281
292
  comes out.
282
293
 
@@ -295,9 +306,14 @@ return NextResponse.next({ request: { headers: requestHeaders } });
295
306
  ```
296
307
 
297
308
  Copying `req.headers` first also overwrites any client-spoofed `x-pathname`.
298
- Note that reading the header (`headers()`) opts the page into dynamic
299
- rendering — pass `pathname` explicitly (e.g. from route params) on pages that
300
- must stay static.
309
+ Reading the header (`headers()`) opts the page into dynamic rendering, and on a
310
+ route that is already static (`force-static`, no request-time reads) the header
311
+ is simply empty — so a `<HreflangLinks>` in the root layout **throws under any
312
+ static page**. Sites with static routes should emit hreflang from metadata
313
+ instead (`createMetadata({ hreflang })`, above), which needs no header at all;
314
+ short of that, pass `pathname` explicitly from route params on the page itself
315
+ (React hoists `<link>` into `<head>` from anywhere in the tree) and keep the
316
+ header-reading instance out of layouts that static routes share.
301
317
 
302
318
  ```tsx
303
319
  import { HreflangLinks } from "@ingram-tech/nk-seo/components";
@@ -328,7 +344,7 @@ neither is available the component **throws** instead of guessing — a silent
328
344
  fallback would canonicalize every page to the homepage, the kind of site-wide
329
345
  SEO bug nobody notices for months.
330
346
 
331
- Two rules of the road:
347
+ Two rules:
332
348
 
333
349
  - **One canonical per page.** If your pages already set `alternates.canonical`
334
350
  (e.g. via `createMetadata`), render `<HreflangLinks canonical={false} />`.
@@ -342,18 +358,18 @@ Two rules of the road:
342
358
  strategy can't see the query string server-side, so
343
359
  [`hreflangConfigFor(routing)`](../nk-i18n/README.md) from
344
360
  `@ingram-tech/nk-i18n/next` is the wiring that gets this right for you.
345
- - Building metadata instead of rendering links? The pure `hreflangAlternates`
346
- (package root) returns the same links for use in `generateMetadata`:
361
+ - Building metadata instead of rendering links? `createMetadata({ hreflang })`
362
+ does it on every page; the pure `hreflangAlternates` (package root) returns
363
+ the same links for a hand-rolled `generateMetadata`:
347
364
  `{ canonical, links, languages }`, where `languages` is already keyed by
348
- hreflang for `Metadata.alternates.languages` (or `createMetadata`'s
349
- per-page `alternates`).
365
+ hreflang for `Metadata.alternates.languages`.
350
366
 
351
367
  ## Verifying the cluster (`/verify`)
352
368
 
353
369
  hreflang is a set of promises about **other** URLs, and nothing local can tell
354
- you whether they hold. A site can emit a flawless cluster while its middleware
355
- redirects every URL in it away, or while each variant quietly canonicalizes to
356
- the default language. Both delete the non-default languages from search, neither
370
+ you whether they hold. A site can emit a correct cluster while its middleware
371
+ redirects every URL in it away, or while each variant canonicalizes to the
372
+ default language. Both delete the non-default languages from search, neither
357
373
  raises an error, and Search Console reports them as ordinary redirects and
358
374
  duplicates months later. Fetch them:
359
375
 
@@ -369,5 +385,6 @@ canonicalizes elsewhere, a missing or duplicated canonical, a non-reciprocal
369
385
  cluster, and an `<html lang>` contradicting the `hreflang` it's advertised under.
370
386
  `verifyHreflangCluster` returns the problems instead of throwing.
371
387
 
372
- Run it against a real deployment — it is the only check that sees what a crawler
373
- sees. A `LocaleRouting` from `@ingram-tech/nk-i18n` is a valid config for it.
388
+ Run it against a real deployment: it is the only check here that sees what a
389
+ crawler sees. A `LocaleRouting` from `@ingram-tech/nk-i18n` is a valid config
390
+ for it.
@@ -11,9 +11,12 @@ export interface HreflangLinksProps extends HreflangConfig {
11
11
  * return NextResponse.next({ request: { headers: requestHeaders } });
12
12
  * ```
13
13
  *
14
- * Pass explicitly if you don't use that header (e.g. from route params) —
15
- * also the only way to keep the page statically renderable, since reading
16
- * `headers()` opts the page into dynamic rendering.
14
+ * Pass explicitly if you don't use that header (e.g. from route params).
15
+ * On a statically rendered route the header is empty (and reading it would
16
+ * otherwise opt the page into dynamic rendering), so a header-reading
17
+ * instance cannot sit in a layout shared with static pages — prefer
18
+ * `createMetadata({ hreflang })`, which emits the same cluster from metadata
19
+ * without any request header.
17
20
  */
18
21
  pathname?: string;
19
22
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"hreflang.d.ts","sourceRoot":"","sources":["../src/hreflang.tsx"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE1E,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,EACnC,QAAQ,EACR,SAAgB,EAChB,GAAG,MAAM,EACT,EAAE,kBAAkB,wCA4BpB"}
1
+ {"version":3,"file":"hreflang.d.ts","sourceRoot":"","sources":["../src/hreflang.tsx"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE1E,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,EACnC,QAAQ,EACR,SAAgB,EAChB,GAAG,MAAM,EACT,EAAE,kBAAkB,wCA4BpB"}
@@ -1 +1 @@
1
- {"version":3,"file":"hreflang.js","sourceRoot":"","sources":["../src/hreflang.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAuB,MAAM,iBAAiB,CAAC;AA2B1E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EACnC,QAAQ,EACR,SAAS,GAAG,IAAI,EAChB,GAAG,MAAM,EACW;IACpB,MAAM,IAAI,GAAG,QAAQ,IAAI,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC7D,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACd,wEAAwE;YACvE,kDAAkD;YAClD,kFAAkF;YAClF,4DAA4D;YAC5D,iFAAiF,CAClF,CAAC;IACH,CAAC;IACD,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5E,OAAO,CACN,8BACE,SAAS,CAAC,CAAC,CAAC,eAAM,GAAG,EAAC,WAAW,EAAC,IAAI,EAAE,YAAY,GAAI,CAAC,CAAC,CAAC,IAAI,EAC/D,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CACpB,eAIC,GAAG,EAAC,WAAW,EACf,QAAQ,EAAE,IAAI,CAAC,QAAQ,EACvB,IAAI,EAAE,IAAI,CAAC,IAAI,IAHV,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAInC,CACF,CAAC,IACA,CACH,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"hreflang.js","sourceRoot":"","sources":["../src/hreflang.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAuB,MAAM,iBAAiB,CAAC;AA8B1E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EACnC,QAAQ,EACR,SAAS,GAAG,IAAI,EAChB,GAAG,MAAM,EACW;IACpB,MAAM,IAAI,GAAG,QAAQ,IAAI,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC7D,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACd,wEAAwE;YACvE,kDAAkD;YAClD,kFAAkF;YAClF,4DAA4D;YAC5D,iFAAiF,CAClF,CAAC;IACH,CAAC;IACD,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5E,OAAO,CACN,8BACE,SAAS,CAAC,CAAC,CAAC,eAAM,GAAG,EAAC,WAAW,EAAC,IAAI,EAAE,YAAY,GAAI,CAAC,CAAC,CAAC,IAAI,EAC/D,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CACpB,eAIC,GAAG,EAAC,WAAW,EACf,QAAQ,EAAE,IAAI,CAAC,QAAQ,EACvB,IAAI,EAAE,IAAI,CAAC,IAAI,IAHV,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAInC,CACF,CAAC,IACA,CACH,CAAC;AACH,CAAC"}
@@ -1,4 +1,5 @@
1
1
  import type { Metadata } from "next";
2
+ import { type HreflangConfig } from "./alternates.js";
2
3
  /**
3
4
  * Per-site defaults for {@link createMetadata}. Set once, reuse on every page.
4
5
  */
@@ -25,6 +26,15 @@ export interface MetadataSiteConfig {
25
26
  twitterSite?: string;
26
27
  /** Twitter `@handle` for `creator`. */
27
28
  twitterCreator?: string;
29
+ /**
30
+ * Locale cluster for the site. When set, every `pageMetadata()` call emits
31
+ * the per-locale `alternates.languages` (plus `x-default`) and a canonical
32
+ * that follows the address — the same links `<HreflangLinks>` renders, but
33
+ * from metadata, so it works on statically rendered routes too (there is no
34
+ * request header to read there) and needs no middleware wiring.
35
+ * `@ingram-tech/nk-i18n`'s routing object fits directly: `hreflang: routing`.
36
+ */
37
+ hreflang?: Omit<HreflangConfig, "baseUrl" | "currentLocale">;
28
38
  }
29
39
  /** Per-page inputs for the bound `pageMetadata` function. */
30
40
  export interface PageMetadataInput {
@@ -42,11 +52,21 @@ export interface PageMetadataInput {
42
52
  * on a multilingual site `og:locale` has to vary per page.
43
53
  */
44
54
  locale?: string;
55
+ /**
56
+ * With `site.hreflang` set: the locale **the URL names** (not the one that
57
+ * rendered), so the canonical self-references the localized address. Get it
58
+ * from `getUrlLocale(routing)` (`@ingram-tech/nk-i18n/next`) on dynamic
59
+ * pages; leave it unset on the bare path and on static routes, which serve
60
+ * one document for every visitor and so canonicalize to the bare, `x-default`
61
+ * address. Under the prefix strategy a `/fr/…`-prefixed `path` implies it.
62
+ */
63
+ urlLocale?: string;
45
64
  /**
46
65
  * Merged into the generated `alternates` (wins on conflict). The reason it
47
66
  * exists: `alternates.languages` is per-page on a localized site, and
48
- * spreading the result to bolt it on drops the rest of the object.
49
- * `hreflangAlternates()` returns a ready-made `languages` map.
67
+ * spreading the result to bolt it on drops the rest of the object. Prefer
68
+ * `site.hreflang`, which fills it in on every page; `hreflangAlternates()`
69
+ * returns a ready-made `languages` map for the hand-rolled case.
50
70
  */
51
71
  alternates?: Partial<NonNullable<Metadata["alternates"]>>;
52
72
  /** Merged into the generated `openGraph` (wins on conflict). */
@@ -1 +1 @@
1
- {"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAGrC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC1D,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACxD,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB;YAGzB,iBAAiB,GAAG,QAAQ;mBAgDR,iBAAiB,KAAQ,QAAQ;EAalF;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB;;;;;IAS1D"}
1
+ {"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG1E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,eAAe,CAAC,CAAC;CAC7D;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC1D,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACxD,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB;YAGzB,iBAAiB,GAAG,QAAQ;mBAgER,iBAAiB,KAAQ,QAAQ;EAalF;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB;;;;;IAS1D"}
package/dist/metadata.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { hreflangAlternates } from "./alternates.js";
1
2
  import { absoluteUrl } from "./url.js";
2
3
  /**
3
4
  * Returns a `pageMetadata(input)` builder that produces a Next `Metadata`
@@ -26,14 +27,27 @@ export function createMetadata(site) {
26
27
  function pageMetadata(input) {
27
28
  const imagePath = input.image ?? site.defaultImage;
28
29
  const imageUrl = imagePath ? absolute(imagePath) : undefined;
29
- const url = absolute(input.path);
30
+ // With a locale cluster the canonical is the current variant's own address
31
+ // (and og:url must agree with it); otherwise the path as given.
32
+ const hreflang = site.hreflang
33
+ ? hreflangAlternates({
34
+ ...site.hreflang,
35
+ baseUrl: site.baseUrl,
36
+ currentLocale: input.urlLocale,
37
+ }, input.path)
38
+ : undefined;
39
+ const url = hreflang?.canonical ?? absolute(input.path);
30
40
  const locale = input.locale ?? site.locale;
31
41
  return {
32
42
  metadataBase: new URL(site.baseUrl),
33
43
  title: input.title,
34
44
  description: input.description,
35
45
  ...(input.keywords ? { keywords: input.keywords } : {}),
36
- alternates: { canonical: url, ...input.alternates },
46
+ alternates: {
47
+ canonical: url,
48
+ ...(hreflang ? { languages: hreflang.languages } : {}),
49
+ ...input.alternates,
50
+ },
37
51
  // noindex but follow: keep link equity flowing through the page. Use a
38
52
  // full robots override in the page's own metadata for nofollow too.
39
53
  ...(input.noIndex ? { robots: { index: false, follow: true } } : {}),
@@ -1 +1 @@
1
- {"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ingram-tech/nk-seo",
3
- "version": "0.9.0",
3
+ "version": "0.10.1",
4
4
  "description": "SEO primitives for Next.js sites: typed schema.org JSON-LD builders, a <JsonLd> tag, a Metadata factory (canonical + OG + Twitter), and configurable hreflang alternates.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -43,14 +43,14 @@
43
43
  "test": "vitest run"
44
44
  },
45
45
  "devDependencies": {
46
- "@ingram-tech/nk-dev": "0.13.0",
46
+ "@ingram-tech/nk-dev": "0.13.1",
47
47
  "@types/node": "^26.2.0",
48
48
  "@types/react": "^19.2.18",
49
49
  "next": "^16.3.1",
50
50
  "react": "^19.2.8",
51
51
  "typescript": "^7.0.2",
52
52
  "vitest": "^4.1.10",
53
- "@ingram-tech/nk-i18n": "0.5.0"
53
+ "@ingram-tech/nk-i18n": "0.5.2"
54
54
  },
55
55
  "peerDependencies": {
56
56
  "next": ">=14.0.0",
package/src/hreflang.tsx CHANGED
@@ -13,9 +13,12 @@ export interface HreflangLinksProps extends HreflangConfig {
13
13
  * return NextResponse.next({ request: { headers: requestHeaders } });
14
14
  * ```
15
15
  *
16
- * Pass explicitly if you don't use that header (e.g. from route params) —
17
- * also the only way to keep the page statically renderable, since reading
18
- * `headers()` opts the page into dynamic rendering.
16
+ * Pass explicitly if you don't use that header (e.g. from route params).
17
+ * On a statically rendered route the header is empty (and reading it would
18
+ * otherwise opt the page into dynamic rendering), so a header-reading
19
+ * instance cannot sit in a layout shared with static pages — prefer
20
+ * `createMetadata({ hreflang })`, which emits the same cluster from metadata
21
+ * without any request header.
19
22
  */
20
23
  pathname?: string;
21
24
  /**
package/src/metadata.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { Metadata } from "next";
2
+ import { hreflangAlternates, type HreflangConfig } from "./alternates.js";
2
3
  import { absoluteUrl } from "./url.js";
3
4
 
4
5
  /**
@@ -27,6 +28,15 @@ export interface MetadataSiteConfig {
27
28
  twitterSite?: string;
28
29
  /** Twitter `@handle` for `creator`. */
29
30
  twitterCreator?: string;
31
+ /**
32
+ * Locale cluster for the site. When set, every `pageMetadata()` call emits
33
+ * the per-locale `alternates.languages` (plus `x-default`) and a canonical
34
+ * that follows the address — the same links `<HreflangLinks>` renders, but
35
+ * from metadata, so it works on statically rendered routes too (there is no
36
+ * request header to read there) and needs no middleware wiring.
37
+ * `@ingram-tech/nk-i18n`'s routing object fits directly: `hreflang: routing`.
38
+ */
39
+ hreflang?: Omit<HreflangConfig, "baseUrl" | "currentLocale">;
30
40
  }
31
41
 
32
42
  /** Per-page inputs for the bound `pageMetadata` function. */
@@ -45,11 +55,21 @@ export interface PageMetadataInput {
45
55
  * on a multilingual site `og:locale` has to vary per page.
46
56
  */
47
57
  locale?: string;
58
+ /**
59
+ * With `site.hreflang` set: the locale **the URL names** (not the one that
60
+ * rendered), so the canonical self-references the localized address. Get it
61
+ * from `getUrlLocale(routing)` (`@ingram-tech/nk-i18n/next`) on dynamic
62
+ * pages; leave it unset on the bare path and on static routes, which serve
63
+ * one document for every visitor and so canonicalize to the bare, `x-default`
64
+ * address. Under the prefix strategy a `/fr/…`-prefixed `path` implies it.
65
+ */
66
+ urlLocale?: string;
48
67
  /**
49
68
  * Merged into the generated `alternates` (wins on conflict). The reason it
50
69
  * exists: `alternates.languages` is per-page on a localized site, and
51
- * spreading the result to bolt it on drops the rest of the object.
52
- * `hreflangAlternates()` returns a ready-made `languages` map.
70
+ * spreading the result to bolt it on drops the rest of the object. Prefer
71
+ * `site.hreflang`, which fills it in on every page; `hreflangAlternates()`
72
+ * returns a ready-made `languages` map for the hand-rolled case.
53
73
  */
54
74
  alternates?: Partial<NonNullable<Metadata["alternates"]>>;
55
75
  /** Merged into the generated `openGraph` (wins on conflict). */
@@ -95,7 +115,19 @@ export function createMetadata(site: MetadataSiteConfig) {
95
115
  function pageMetadata(input: PageMetadataInput): Metadata {
96
116
  const imagePath = input.image ?? site.defaultImage;
97
117
  const imageUrl = imagePath ? absolute(imagePath) : undefined;
98
- const url = absolute(input.path);
118
+ // With a locale cluster the canonical is the current variant's own address
119
+ // (and og:url must agree with it); otherwise the path as given.
120
+ const hreflang = site.hreflang
121
+ ? hreflangAlternates(
122
+ {
123
+ ...site.hreflang,
124
+ baseUrl: site.baseUrl,
125
+ currentLocale: input.urlLocale,
126
+ },
127
+ input.path,
128
+ )
129
+ : undefined;
130
+ const url = hreflang?.canonical ?? absolute(input.path);
99
131
  const locale = input.locale ?? site.locale;
100
132
 
101
133
  return {
@@ -103,7 +135,11 @@ export function createMetadata(site: MetadataSiteConfig) {
103
135
  title: input.title,
104
136
  description: input.description,
105
137
  ...(input.keywords ? { keywords: input.keywords } : {}),
106
- alternates: { canonical: url, ...input.alternates },
138
+ alternates: {
139
+ canonical: url,
140
+ ...(hreflang ? { languages: hreflang.languages } : {}),
141
+ ...input.alternates,
142
+ },
107
143
  // noindex but follow: keep link equity flowing through the page. Use a
108
144
  // full robots override in the page's own metadata for nofollow too.
109
145
  ...(input.noIndex ? { robots: { index: false, follow: true } } : {}),