@ingram-tech/nk-seo 0.10.0 → 0.10.2

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.
Files changed (2) hide show
  1. package/README.md +29 -31
  2. package/package.json +8 -8
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`.
@@ -218,9 +216,9 @@ export default () =>
218
216
  });
219
217
  ```
220
218
 
221
- When `isProduction` is false the whole site is disallowed — the one SEO
222
- safeguard everyone forgets on Vercel, where preview and branch deployments are
223
- 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.
224
222
 
225
223
  ## Open Graph image
226
224
 
@@ -246,8 +244,8 @@ export default () =>
246
244
  ```
247
245
 
248
246
  Pass `logo` (absolute URL or data URI) to replace the accent-square mark with
249
- your logo, and `fonts` + `fontFamily` to render with the brand typeface —
250
- `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.
251
249
 
252
250
  ### Two ways the generated card silently doesn't reach your pages
253
251
 
@@ -275,13 +273,12 @@ either at the image route and every page it builds carries the card.
275
273
  **Locale-negotiating middleware eats the image route.** A site that redirects
276
274
  any path lacking a locale prefix also redirects `/opengraph-image`, so the card
277
275
  URL never resolves. Put the file at `app/[locale]/opengraph-image.tsx` instead:
278
- it dodges the redirect and gives per-locale cards from `params`. That is the
279
- better default for any localized site.
276
+ it dodges the redirect and gives per-locale cards from `params`.
280
277
 
281
- The template encodes the Satori rule that trips everyone up: every node with
282
- more than one child sets `display: flex`, and text nodes are never mixed with
283
- sibling elements — so the headline stays a plain string and the accent rides on
284
- 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.
285
282
 
286
283
  Type-check won't help here: `ImageResponse` accepts all of
287
284
  `React.CSSProperties` and Satori silently drops what it doesn't know. Two guards
@@ -290,7 +287,7 @@ which flags unsupported style properties, `calc()`, and the two structural rules
290
287
  in files that import `next/og` or are an `opengraph-image`/`twitter-image`
291
288
  convention. And rendering remains the final validator: this package renders its
292
289
  template through the real satori + resvg pipeline in its own tests, so a site
293
- 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
294
291
  environment) that renders each `opengraph-image.tsx` and asserts a valid PNG
295
292
  comes out.
296
293
 
@@ -347,7 +344,7 @@ neither is available the component **throws** instead of guessing — a silent
347
344
  fallback would canonicalize every page to the homepage, the kind of site-wide
348
345
  SEO bug nobody notices for months.
349
346
 
350
- Two rules of the road:
347
+ Two rules:
351
348
 
352
349
  - **One canonical per page.** If your pages already set `alternates.canonical`
353
350
  (e.g. via `createMetadata`), render `<HreflangLinks canonical={false} />`.
@@ -370,9 +367,9 @@ Two rules of the road:
370
367
  ## Verifying the cluster (`/verify`)
371
368
 
372
369
  hreflang is a set of promises about **other** URLs, and nothing local can tell
373
- you whether they hold. A site can emit a flawless cluster while its middleware
374
- redirects every URL in it away, or while each variant quietly canonicalizes to
375
- 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
376
373
  raises an error, and Search Console reports them as ordinary redirects and
377
374
  duplicates months later. Fetch them:
378
375
 
@@ -388,5 +385,6 @@ canonicalizes elsewhere, a missing or duplicated canonical, a non-reciprocal
388
385
  cluster, and an `<html lang>` contradicting the `hreflang` it's advertised under.
389
386
  `verifyHreflangCluster` returns the problems instead of throwing.
390
387
 
391
- Run it against a real deployment — it is the only check that sees what a crawler
392
- 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ingram-tech/nk-seo",
3
- "version": "0.10.0",
3
+ "version": "0.10.2",
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",
47
- "@types/node": "^26.2.0",
48
- "@types/react": "^19.2.18",
49
- "next": "^16.3.1",
50
- "react": "^19.2.8",
46
+ "@ingram-tech/nk-dev": "0.17.0",
47
+ "@ingram-tech/nk-i18n": "0.6.0",
48
+ "@types/node": "^26.5.1",
49
+ "@types/react": "^19.3.0",
50
+ "next": "^16.3.5",
51
+ "react": "^19.3.0",
51
52
  "typescript": "^7.0.2",
52
- "vitest": "^4.1.10",
53
- "@ingram-tech/nk-i18n": "0.5.1"
53
+ "vitest": "^5.0.0"
54
54
  },
55
55
  "peerDependencies": {
56
56
  "next": ">=14.0.0",