@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 +63 -46
- package/dist/hreflang.d.ts +6 -3
- package/dist/hreflang.d.ts.map +1 -1
- package/dist/hreflang.js.map +1 -1
- package/dist/metadata.d.ts +22 -2
- package/dist/metadata.d.ts.map +1 -1
- package/dist/metadata.js +16 -2
- package/dist/metadata.js.map +1 -1
- package/package.json +3 -3
- package/src/hreflang.tsx +6 -3
- package/src/metadata.ts +40 -4
package/README.md
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
# @ingram-tech/nk-seo
|
|
2
2
|
|
|
3
|
-
SEO primitives for Next.js
|
|
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
|
|
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
|
|
32
|
-
|
|
33
|
-
|
|
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
|
|
68
|
-
and `offers.url` may be site-relative, as in the example above.
|
|
69
|
-
|
|
70
|
-
|
|
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
|
|
107
|
-
|
|
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
|
|
160
|
-
|
|
161
|
-
`<link rel="alternate" hreflang>`,
|
|
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
|
-
|
|
163
|
+
export const pageMetadata = createMetadata({
|
|
164
|
+
baseUrl: routing.baseUrl,
|
|
165
|
+
siteName: "Acme",
|
|
166
|
+
hreflang: routing, // or { locales, strategy, param, hrefLangTags }
|
|
167
|
+
});
|
|
165
168
|
|
|
166
|
-
|
|
169
|
+
// A dynamic page: the URL locale makes the canonical self-reference /fr/about.
|
|
167
170
|
return pageMetadata({
|
|
168
|
-
title, description, path:
|
|
169
|
-
|
|
170
|
-
locale: "fr_BE",
|
|
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
|
|
208
|
-
|
|
209
|
-
|
|
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
|
|
236
|
-
|
|
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`.
|
|
265
|
-
better default for any localized site.
|
|
276
|
+
it dodges the redirect and gives per-locale cards from `params`.
|
|
266
277
|
|
|
267
|
-
The template
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
the mark
|
|
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
|
|
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
|
-
|
|
299
|
-
|
|
300
|
-
|
|
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
|
|
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?
|
|
346
|
-
|
|
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
|
|
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
|
|
355
|
-
redirects every URL in it away, or while each variant
|
|
356
|
-
|
|
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
|
|
373
|
-
sees. A `LocaleRouting` from `@ingram-tech/nk-i18n` is a valid config
|
|
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.
|
package/dist/hreflang.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
16
|
-
*
|
|
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
|
/**
|
package/dist/hreflang.d.ts.map
CHANGED
|
@@ -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
|
|
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"}
|
package/dist/hreflang.js.map
CHANGED
|
@@ -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;
|
|
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"}
|
package/dist/metadata.d.ts
CHANGED
|
@@ -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
|
-
* `
|
|
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). */
|
package/dist/metadata.d.ts.map
CHANGED
|
@@ -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;
|
|
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
|
-
|
|
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: {
|
|
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 } } : {}),
|
package/dist/metadata.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
*
|
|
18
|
-
*
|
|
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
|
-
* `
|
|
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
|
-
|
|
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: {
|
|
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 } } : {}),
|