nuxt-seo-utils 8.6.0 → 9.0.0

package/dist/runtime/shared/redirects.js

@@ -0,0 +1,59 @@
+import { joinURL, withoutTrailingSlash } from "ufo";
+export const REDIRECT_CACHE_CONTROL = "public, max-age=3600";
+export function normalizePath(path) {
+  return path === "/" ? path : withoutTrailingSlash(path);
+}
+export function isAbsoluteUrl(to) {
+  return /^https?:\/\//i.test(to);
+}
+export function parseSourcePattern(source) {
+  if (!source.startsWith("/") || source.startsWith("//"))
+    return "it must be a path that starts with `/`";
+  if (/[?#]/.test(source))
+    return "route matching ignores the query string and hash, so remove them";
+  const wildcard = source.endsWith("/**");
+  const base = wildcard ? source.slice(0, -3) : source;
+  if (/\*|\/:/.test(base))
+    return "only a trailing `/**` is supported";
+  if (wildcard) {
+    const prefix = normalizePath(base || "/");
+    return { _tag: "Prefix", prefix: prefix === "/" ? "" : prefix };
+  }
+  return { _tag: "Exact", path: normalizePath(base) };
+}
+export function matchesSource(pattern, path) {
+  const normalized = normalizePath(path);
+  if (pattern._tag === "Exact")
+    return pattern.path === normalized;
+  return normalized === (pattern.prefix || "/") || normalized.startsWith(`${pattern.prefix}/`);
+}
+export function createRedirectMatcher(entries) {
+  const exact = /* @__PURE__ */ new Map();
+  const prefixes = [];
+  for (const entry of entries) {
+    if (entry.pattern._tag === "Exact")
+      exact.set(entry.pattern.path, entry);
+    else
+      prefixes.push(entry);
+  }
+  const prefixLength = (entry) => entry.pattern._tag === "Prefix" ? entry.pattern.prefix.length : 0;
+  prefixes.sort((a, b) => prefixLength(b) - prefixLength(a));
+  return (path) => {
+    const normalized = normalizePath(path);
+    return exact.get(normalized) ?? prefixes.find((entry) => matchesSource(entry.pattern, normalized));
+  };
+}
+export function resolveTarget(rule, path) {
+  if (!rule.to.endsWith("/**"))
+    return rule.to;
+  const rest = rule.pattern._tag === "Prefix" ? normalizePath(path).slice(rule.pattern.prefix.length) : "";
+  return joinURL(rule.to.slice(0, -3) || "/", rest);
+}
+export function appendSearch(target, search) {
+  if (!search || search === "?")
+    return target;
+  const hashIndex = target.indexOf("#");
+  const base = hashIndex === -1 ? target : target.slice(0, hashIndex);
+  const hash = hashIndex === -1 ? "" : target.slice(hashIndex);
+  return `${base}${base.includes("?") ? "&" : "?"}${search.replace(/^\?/, "")}${hash}`;
+}

package/dist/runtime/types.d.ts

@@ -1,4 +1,19 @@
+import type { UseHeadOptions } from '@unhead/vue';
 import type { Head, Link, MetaFlat, RawInput } from '@unhead/vue/types';
+export interface SeoUtilsRuntimeConfig {
+    canonicalQueryWhitelist: string[];
+    canonicalLowercase: boolean;
+    automaticTwitterTags: boolean;
+    tagPriority: UseHeadOptions['tagPriority'];
+    separator?: string;
+    titleSeparator?: string;
+    colorModeIcons?: ColorModeIconLinks;
+}
+declare module 'nuxt/schema' {
+    interface PublicRuntimeConfig {
+        'seo-utils': SeoUtilsRuntimeConfig;
+    }
+}
 export interface ColorModeIconLinks {
     dark: Link[];
     light: Link[];

package/dist/types.d.mts

@@ -1,3 +1,3 @@
 export { default } from './module.mjs'
 
-export { type ModuleOptions } from './module.mjs'
+export { type GoneUrl, type ModuleOptions, type MovedUrl, type RedirectDate, type RedirectInput, type Redirects } from './module.mjs'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-seo-utils",
   "type": "module",
-  "version": "8.6.0",
+  "version": "9.0.0",
   "description": "SEO utilities to improve your Nuxt sites discoverability and shareability",
   "license": "MIT",
   "funding": "https://github.com/sponsors/harlan-zw",
@@ -30,6 +30,7 @@
   ],
   "build": {
     "externals": [
+      "nuxt/server",
       "unhead",
       "@unhead/vue",
       "@unhead/vue/plugins",
@@ -37,13 +38,17 @@
       "@unhead/vue/vite"
     ]
   },
+  "engines": {
+    "node": "^22.22.3 || ^24.15.0 || >=26.0.0"
+  },
   "peerDependencies": {
-    "@unhead/vue": "^2.0.7 || ^3.0.0",
+    "@unhead/vue": "^3.4.2",
     "esbuild": ">=0.17.0",
     "lightningcss": ">=1.20.0",
-    "nuxt": "^3.0.0 || ^4.0.0 || ^5.0.0",
+    "nuxt": "^4.6.0 || ^5.0.0",
     "rolldown": ">=1.0.0-beta.0",
-    "unhead": "^2.0.7 || ^3.0.0"
+    "sharp": "^0.35.5",
+    "unhead": "^3.4.2"
   },
   "peerDependenciesMeta": {
     "@unhead/vue": {
@@ -58,59 +63,60 @@
     "rolldown": {
       "optional": true
     },
+    "sharp": {
+      "optional": true
+    },
     "unhead": {
       "optional": true
     }
   },
   "dependencies": {
-    "@nuxt/kit": "^4.5.2",
+    "@nuxt/kit": "^4.6.0",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "defu": "^6.1.7",
     "escape-string-regexp": "^5.0.0",
-    "exsolve": "^1.1.1",
-    "nuxt-site-config": "^4.2.3",
-    "nuxtseo-shared": "^5.3.14",
+    "exsolve": "^1.1.3",
+    "nuxt-site-config": "^5.0.0",
+    "nuxtseo-shared": "^6.0.0",
     "pathe": "^2.0.3",
-    "pkg-types": "^2.3.1",
     "scule": "^1.3.0",
     "tinyglobby": "^0.2.17",
     "ufo": "^1.6.4"
   },
-  "optionalDependencies": {
-    "sharp": "^0.35.4"
-  },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.3.0",
-    "@nuxt/devtools-kit": "4.0.0-alpha.9",
+    "@antfu/eslint-config": "^9.5.1",
+    "@nuxt/devtools-kit": "4.0.0-beta.4",
     "@nuxt/module-builder": "^1.0.3",
-    "@nuxt/schema": "^4.5.2",
-    "@nuxt/test-utils": "^4.2.0",
-    "@nuxt/ui": "^4.11.0",
+    "@nuxt/schema": "^4.6.0",
+    "@nuxt/test-utils": "^4.3.3",
+    "@nuxt/ui": "^4.11.3",
     "@nuxtjs/i18n": "^10.6.0",
-    "@types/node": "^26.4.0",
-    "@unhead/vue": "3.2.3",
-    "@vue/test-utils": "^2.5.0",
-    "bumpp": "^12.2.2",
+    "@nuxtjs/sitemap": "^9.0.0",
+    "@types/node": "^26.6.4",
+    "@unhead/vue": "^3.4.2",
+    "@vue/test-utils": "^2.5.1",
+    "bumpp": "^12.3.0",
     "case-police": "^2.2.1",
     "cheerio": "^1.2.0",
-    "eslint": "^10.9.1",
-    "eslint-plugin-harlanzw": "^0.20.0",
-    "happy-dom": "^20.12.0",
-    "lint-staged": "^17.4.1",
+    "eslint": "^10.12.0",
+    "eslint-plugin-harlanzw": "^0.23.0",
+    "happy-dom": "^20.14.5",
+    "lint-staged": "^17.6.0",
     "markdownlint-cli": "^0.49.1",
-    "nuxt": "^4.5.2",
+    "nuxt": "4.6.0",
     "nuxt-security": "^2.6.0",
-    "nuxtseo-layer-devtools": "^5.3.14",
-    "playwright-core": "^1.62.1",
-    "sass": "^1.103.1",
+    "nuxtseo-layer-devtools": "^5.3.16",
+    "playwright-core": "^1.63.0",
+    "sass": "^1.105.1",
+    "sharp": "^0.35.5",
     "typescript": "6.0.3",
     "ultrahtml": "^1.7.0",
     "unbuild": "^3.6.1",
-    "unhead": "3.2.3",
-    "vitest": "^4.1.11",
-    "vue": "^3.5.42",
-    "vue-tsc": "^3.3.11"
+    "unhead": "^3.4.2",
+    "vitest": "^5.0.3",
+    "vue": "^3.5.43",
+    "vue-tsc": "^3.3.12"
   },
   "scripts": {
     "client:build": "node -e \"require('fs').cpSync('devtools','dist/devtools',{recursive:true})\"",
@@ -123,14 +129,13 @@
     "typecheck": "nuxt typecheck",
     "prepare:fixtures": "nuxt prepare test/fixtures/basic && nuxt prepare test/fixtures/i18n && nuxt prepare test/fixtures/csp",
     "test": "vitest && pnpm test:nuxt5",
-    "test:run": "vitest run --exclude '**/\\_\\_runtime\\_\\_/**'",
+    "test:run": "vitest run --exclude '**/\\_\\_runtime\\_\\_/**' && pnpm test:nuxt5",
     "test:runtime": "pnpm test:runtime:basic && pnpm test:runtime:i18n",
     "test:runtime:basic": "cd test/fixtures/basic && vitest --run",
     "test:runtime:i18n": "cd test/fixtures/i18n && vitest --run",
-    "test:nuxt5": "pnpm pack --out test/fixtures/nuxt5/module.tgz && node test/fixtures/nuxt5/run.mjs",
+    "test:nuxt5": "pnpm build && pnpm --dir test/fixtures/nuxt5 install --frozen-lockfile && pnpm --dir test/fixtures/nuxt5 test",
     "release": "pnpm build && bumpp -x \"npx changelogen --output=CHANGELOG.md\"",
     "lint:docs": "markdownlint ./docs/content && case-police 'docs/content/**/*.md' *.md",
-    "lint:docs:fix": "markdownlint ./docs/content --fix && case-police 'docs/content/**/*.md' *.md --fix",
-    "test:compat-v2": "node test/compat-v2/run.mjs"
+    "lint:docs:fix": "markdownlint ./docs/content --fix && case-police 'docs/content/**/*.md' *.md --fix"
   }
 }

package/skills/nuxt-seo-utils/SKILL.md

@@ -1,16 +1,20 @@
 ---
 name: nuxt-seo-utils
-description: Set up, override, and debug the default SEO head tags in a Nuxt app with the nuxt-seo-utils module. Use when a task mentions canonical URLs, the title template or separator, fallback titles, og:image or twitter:image files, favicons and app icons, seo.meta, seoMeta or head in routeRules, useBreadcrumbItems, useShareLinks, the nuxt-seo-utils icons CLI, or the seo config key. Also use when a page tag does not override a default, html lang ignores useHead, or og:image renders twice.
+description: Set up, override, and debug the default SEO head tags in a Nuxt app with the nuxt-seo-utils module. Use when a task mentions canonical URLs, the title template or separator, fallback titles, og:image or twitter:image files, favicons and app icons, seo.meta, seoMeta or head in routeRules, useBreadcrumbItems, useShareLinks, the nuxt-seo-utils icons CLI, seo.redirects, moved or deleted URLs, 301 or 410 responses, or the seo config key. Also use when a page tag does not override a default, html lang ignores useHead, or og:image renders twice.
+license: MIT
+compatibility: "Requires Node.js ^22.22.3 || ^24.15.0 || >=26.0.0. Requires Nuxt ^4.6.0 || ^5.0.0. Requires Unhead ^3.4.2."
 ---
 
 # nuxt-seo-utils
 
-Tested against `nuxt-seo-utils` 8.5.2 on Nuxt 4.5.2 with Unhead v3 (requires Nuxt `>=3.16.0`).
+Requires Nuxt `^4.6.0 || ^5.0.0` and Unhead 3.4.2 or newer.
 The module adds default head tags from site config, reads icon and social image files, and ships breadcrumb and share link composables.
 Docs: https://nuxtseo.com/docs/seo-utils
 
 ## Setup
 
+Install with `npx nuxt module add nuxt-seo-utils`.
+Included in `@nuxtjs/seo` v6. If the app uses `@nuxtjs/seo`, configure the `seo` key and do not add the module again.
 The config key is `seo`. `seoUtils` does nothing.
 Set `site.url` and `site.name`. The canonical URL, `og:url`, the title template, and absolute image URLs read them.
 
@@ -66,7 +70,7 @@ Generate icon files from one source image in `public/`:
 pnpm exec nuxt-seo-utils icons --source logo.svg
 ```
 
-It writes `favicon.ico`, `apple-touch-icon.png`, and `icon-{16,32,192,512}` PNGs to `public/`. It needs `sharp`, which installs as an optional dependency.
+It writes `favicon.ico`, `apple-touch-icon.png`, and `icon-{16,32,192,512}` PNGs to `public/`. Install the optional peer with `pnpm add -D sharp` before generating icons.
 
 ## Site-wide and per-route meta
 
@@ -115,25 +119,66 @@ const share = useShareLinks({ title: post.value.title, utm: { source: 'auto', ca
 `title` defaults to `site.name`, not the page title. Pass it.
 UTM defaults to `utm_source=<platform>` and `utm_medium=social` (or `email`). An object without `source: 'auto'` switches to manual mode: `{ campaign: 'launch' }` sends only `utm_campaign`.
 
+## Redirects and gone URLs
+
+`seo.redirects` lists old URLs, keyed by path without `app.baseURL`. Every entry needs `addedAt`.
+
+```ts
+export default defineNuxtConfig({
+  seo: {
+    redirects: {
+      '/blog/old-post': { to: '/blog/new-post', addedAt: '2026-10-13' }, // 301; set statusCode: 308 to keep the method
+      '/docs/v1/**': { to: '/docs/**', addedAt: '2026-10-13' }, // /docs/v1/setup -> /docs/setup
+      '/spring-sale': { statusCode: 410, addedAt: '2026-10-13', reason: 'Sale ended' }, // error page with 410
+    },
+  },
+})
+```
+
+- A moved URL has `to` (a path or an absolute URL) and `statusCode` 301 (default) or 308. A gone URL has no `to` and `statusCode` 410 or 404.
+- The request query string is kept. A trailing slash does not change the match. An exact key beats a `/**` key.
+- `reason` is a private note. Visitors never see it.
+- Nothing expires. After `redirectReviewAfterDays` (365) from `addedAt` or `reviewedAt`, `nuxt dev` and `nuxt build` list the entry for review. To keep it, set `reviewedAt` to today. Delete it only when the old URL gets no visits and no backlinks.
+- Chains flatten at build: `/a` to `/b` and `/b` to `/c` serve `/a` to `/c`. A loop or an invalid entry stops the build. A redirect to a gone URL warns.
+- With an i18n prefix strategy, each unprefixed entry also applies under each locale prefix. A translated path needs its own entry.
+- For a long list, import a file typed with `satisfies Redirects` (`import type { Redirects } from 'nuxt-seo-utils'`).
+- Do not redirect deleted pages to the home page. Google can treat that as a soft 404. Use a gone URL.
+- Use `routeRules` `redirect` for temporary 302 or 307 redirects. `seo.redirects` accepts only permanent ones.
+
 ## Traps
 
 - **`htmlAttrs.lang` in `useHead()` or `app.head` is ignored.** The module sets `lang` from site config. Set `site.defaultLocale`, or use `@nuxtjs/i18n`.
 - **Before nuxt-schema-org 6.4.1, the Schema.org WebPage URL keeps the route case.** `canonicalLowercase` lowercases the canonical, `og:url`, `useShareLinks()` URLs, and `BreadcrumbList` item URLs. nuxt-schema-org before 6.4.1 builds the WebPage `url` from the route path. There, `/blog/My-Post` gets a canonical of `/blog/my-post` and a WebPage URL of `/blog/My-Post`. From 6.4.1, the WebPage `url` follows the canonical. On an older version, upgrade nuxt-schema-org, use lowercase route paths, or set `canonicalLowercase: false`. Breadcrumb `to` links keep their case on purpose.
 - **`definePageMeta({ title })` takes a static string only.** Use `useSeoMeta({ title })` for data.
+- **Only some static presets get native redirects.** `nuxt generate` writes host rules for `netlify-static` (`_redirects`, 308 becomes 301), `vercel-static` (`config.json` routes), and `cloudflare-pages-static` (`_redirects`, no 410: gone URLs get the host 404 page). With `netlify-static` and an `app.baseURL`, and with every other preset, each exact moved URL becomes an instant meta refresh page, and gone URLs and `/**` keys need host rules. The build lists each entry the host cannot serve.
+- **A catch-all page skips client-side redirects.** `seo.redirects` runs on the server. A `NuxtLink` to an old URL that a `[...slug].vue` page matches renders that page. Fix the link. Nuxt Link Checker flags a link to a 301 entry.
 
 ## Version limits
 
+v9 breaking changes and their fixes:
+
+- Nuxt `^4.6.0 || ^5.0.0`, Node `^22.22.3 || ^24.15.0 || >=26.0.0`, and Unhead `^3.4.2` are required. Upgrade Nuxt and Node first.
+- Unhead v2 is not supported. Remove any `@unhead/vue` 2 pin or override.
+- `nuxt-site-config` 5 is required. Change a pinned `nuxt-site-config` to `^5.0.0`.
+- The module no longer installs Sharp. Run `pnpm add -D sharp` before `nuxt-seo-utils icons`.
+- Runtime and prerender minification keep inline JavaScript unchanged. Put scripts that need minification in `app.head`.
+- Only `#seo-utils/app` resolves. Replace `#seo-utils/types`, `#seo-utils/server/`, and `#seo-utils/shared/` imports with `#seo-utils/app` exports.
+- The DevTools panel needs `nuxtseo-devtools-host` as a dev dependency.
+
+Older limits:
+
 - 8.5.2 and earlier: a page `ogImage` keeps the default image's dimensions and `twitter:image`, a page canonical leaves `og:url` on the route URL, a `pages/<route>/og-image.png` renders `og:image:alt` twice, and `public/opengraph-image.*` is ignored.
 - 8.5.2 and earlier: `BreadcrumbList` item URLs keep the route case, and `useShareLinks()` lowercases without the site locale.
 - 8.5.2 and earlier: `seo.meta` and `public/og-image.png` beat route rule `seoMeta` and `pages/**/og-image.png`. Put the route value in the page with `useSeoMeta()`.
-- `treeShakeUseSeoMeta` needs Unhead v3. On Unhead v2 the module skips it with a warning.
 - `automaticTwitterTags: false` (removes `twitter:card`) arrived in 8.5.0.
 
 ## Config
 
 - `redirectToCanonicalSiteUrl` (`false`): in production, send a 301 from other hosts to the `site.url` host.
 - `canonicalQueryWhitelist`: replaces the default list. It does not extend it.
-- `minify` (`{ build: true, runtime: false }`): minify inline scripts and styles in `app.head` and prerendered HTML. `runtime: true` minifies on every SSR request.
+- `redirects`: moved and gone URLs. See the section above.
+- `redirectReviewAfterDays` (`365`): days until an entry is due for review. `false` turns the review off.
+- `minify` (`{ build: true, runtime: false }`): minify static `app.head` JavaScript/CSS with parser-based tooling. Compact JSON/CSS in prerendered HTML. `runtime: true` compacts JSON/CSS per SSR request. Dynamic JavaScript and custom script types remain unchanged.
 - `automaticOgAndTwitterTags` (`true`): the `og:title`, `og:description`, and `twitter:card` inference.
 - Other options: https://nuxtseo.com/docs/seo-utils/api/config
 
@@ -141,4 +186,5 @@ UTM defaults to `utm_source=<platform>` and `utm_medium=social` (or `email`). An
 
 - On `nuxt dev` and `nuxt build`, the module warns about conflicts in `app.head`, such as a static `lang` or an `og:site_name` that differs from `site.name`. Fix the site config, not the head. Set `validateAppHead: false` to hide the check.
 - `/__nuxt-seo-utils/debug.json` in dev, or in production with `seo: { debug: true }`.
-- Nuxt DevTools has an SEO Utils tab.
+- On `nuxt dev` and `nuxt build`, the module warns when SSR is off for indexable pages. Turn SSR on for public routes. For private routes, set `robots: false` with `@nuxtjs/robots`.
+- Nuxt DevTools has an SEO Utils tab. The panel needs `nuxtseo-devtools-host` as a dev dependency.