nuxt-seo-utils 8.5.2 → 8.6.1

package/README.md

@@ -5,6 +5,14 @@
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
+<a href="https://skilld.dev/gh/harlan-zw/nuxt-seo-utils">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://skilld.dev/b/harlan-zw/nuxt-seo-utils?theme=dark">
+    <source media="(prefers-color-scheme: light)" srcset="https://skilld.dev/b/harlan-zw/nuxt-seo-utils?theme=light">
+    <img alt="Skill repository on skilld.dev" src="https://skilld.dev/b/harlan-zw/nuxt-seo-utils?theme=light">
+  </picture>
+</a>
+
 Nuxt SEO Utils is a collection of defaults and utilities to improve your Nuxt site's discoverability and shareability.
 
 While there are several features covering many aspects of SEO, it covers important defaults such as [automatic canonical URLs](https://nuxtseo.com/learn/controlling-crawlers/canonical-urls) and
@@ -40,10 +48,7 @@ npx nuxi@latest module add nuxt-seo-utils
 ```
 
 > [!TIP]
-> Generate an Agent Skill for this package using [skilld](https://github.com/harlan-zw/skilld):
-> ```bash
-> npx skilld add nuxt-seo-utils
-> ```
+> Using an AI agent? Get the nuxt-seo-utils Skill on [skilld.dev/gh/harlan-zw/nuxt-seo-utils](https://skilld.dev/gh/harlan-zw/nuxt-seo-utils).
 
 💡 Set up your meta tags? Check titles, descriptions and OG tags with a SERP preview using the free [Meta Tag Checker](https://nuxtseo.com/tools/meta-tag-checker), or monitor them across every page with [Nuxt SEO Pro](https://nuxtseo.com/pro).
 

package/dist/cli.mjs

@@ -9,7 +9,7 @@ import { p as pngToIco } from './shared/nuxt-seo-utils.NAV2YNQn.mjs';
 import 'node:buffer';
 
 const name = "nuxt-seo-utils";
-const version = "8.5.2";
+const version = "8.6.1";
 const description = "SEO utilities to improve your Nuxt sites discoverability and shareability";
 
 const ICON_SIZES = [

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.16.0"
   },
-  "version": "8.5.2",
+  "version": "8.6.1",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -14,6 +14,7 @@ import { c as classifyIconFilename, g as getIconRel, n as normalizeIconSizes, a
 import escapeRE from 'escape-string-regexp';
 import { readFile, readdir } from 'node:fs/promises';
 import { Buffer } from 'node:buffer';
+import { TWITTER_IMAGE_FALLBACK_KEY } from '../dist/runtime/shared/derivedTagKeys.js';
 import { JSON_TYPES, SKIP_JS_TYPES } from '../dist/runtime/shared/minify.js';
 import { setupDevToolsUI as setupDevToolsUI$1 } from 'nuxtseo-shared/devtools';
 
@@ -82,9 +83,15 @@ const MetaTagFileDeepGlobs = [
   "**/apple-*.{jpg,jpeg,png}",
   "**/*.apple-*.{jpg,jpeg,png}"
 ];
-const SOCIAL_IMAGE_RE = /^(?:og-image|opengraph-image|twitter-image)\.(?:png|jpe?g|gif)$/;
+const SOCIAL_IMAGE_RE = /^(og-image|opengraph-image|twitter-image)\.(?:png|jpe?g|gif)$/;
+function classifySocialImageFilename(filename) {
+  const keyword = SOCIAL_IMAGE_RE.exec(filename)?.[1];
+  if (!keyword)
+    return;
+  return keyword === "twitter-image" ? "twitterImage" : "ogImage";
+}
 function isMetaTagFile(filename) {
-  return SOCIAL_IMAGE_RE.test(filename) || classifyIconFilename(filename) !== void 0;
+  return classifySocialImageFilename(filename) !== void 0 || classifyIconFilename(filename) !== void 0;
 }
 
 const INDEX_SUFFIX_RE = /-index$/;
@@ -383,10 +390,9 @@ async function generateTagsFromPageDirImages(nuxt = useNuxt()) {
   const devMiddlewareMap = {};
   const nitroOutputMap = [];
   for (const pagesDir of pagesDirs) {
-    const files = (await glob(MetaTagFileDeepGlobs, { cwd: pagesDir, onlyFiles: true })).filter((file) => isMetaTagFile(basename(file)));
+    const files = (await glob(MetaTagFileDeepGlobs, { cwd: pagesDir, onlyFiles: true })).filter((file) => isMetaTagFile(basename(file))).sort();
     for (const file of files) {
       const fileName = basename(file);
-      const keyword = fileName.split(".")[0] || "";
       let { path } = generateNuxtPageFromFile(resolve(pagesDir, dirname(file)), pagesDir);
       if (path.endsWith("/_dir"))
         path = path.replace(DIR_SUFFIX_RE, "");
@@ -408,9 +414,10 @@ async function generateTagsFromPageDirImages(nuxt = useNuxt()) {
           media: meta.media ? String(meta.media) : void 0
         });
       } else {
-        const property = ["opengraph-image", "og-image"].includes(keyword) ? "ogImage" : "twitterImage";
-        routeRule.seoMeta[property] ||= [];
-        routeRule.seoMeta[property].push({ url: href, ...meta, sizes: void 0 });
+        const property = classifySocialImageFilename(fileName);
+        if (!property || routeRule.seoMeta[property])
+          continue;
+        routeRule.seoMeta[property] = { url: href, ...meta, alt: meta.alt || "", sizes: void 0 };
       }
       devMiddlewareMap[routeAssetPath] = resolve(pagesDir, file);
       nitroOutputMap.push({
@@ -539,7 +546,7 @@ async function generateTagsFromPublicFiles(nuxt = useNuxt()) {
   }
   let hasTwitterImage = hasMetaProperty(headConfig, "twitter:image");
   if (!hasTwitterImage) {
-    const twitterImageFiles = rootPublicFiles.filter((file) => file.startsWith("twitter-image.")).sort();
+    const twitterImageFiles = rootPublicFiles.filter((file) => classifySocialImageFilename(file) === "twitterImage").sort();
     if (twitterImageFiles.length) {
       headConfig.meta.push(
         ...(await Promise.all(twitterImageFiles.map(async (twitterImageFile) => {
@@ -557,25 +564,18 @@ async function generateTagsFromPublicFiles(nuxt = useNuxt()) {
     }
   }
   if (!hasMetaProperty(headConfig, "og:image")) {
-    const ogImageFiles = rootPublicFiles.filter((file) => file.startsWith("og-image.") || file.startsWith("og.")).sort();
+    const ogImageFiles = rootPublicFiles.filter((file) => classifySocialImageFilename(file) === "ogImage").sort();
     if (ogImageFiles.length) {
       headConfig.meta.push(
         ...(await Promise.all(ogImageFiles.map(async (src) => {
           const meta = await getImageMeta(fileEntries.find((e) => e.file === src).dir, src, false);
           delete meta.sizes;
-          const seoMeta = {
-            ogImage: {
-              url: src,
-              ...meta
-            }
-          };
+          const tags = unpackMeta({ ogImage: { url: src, ...meta } });
           if (!hasTwitterImage) {
-            seoMeta.twitterImage = {
-              url: src,
-              ...meta
-            };
+            const twitterTags = unpackMeta({ twitterImage: { url: src, ...meta } });
+            tags.push(...twitterTags.map((tag) => ({ ...tag, key: `${TWITTER_IMAGE_FALLBACK_KEY}:${src}` })));
           }
-          return unpackMeta(seoMeta);
+          return tags;
         }))).flat()
       );
     }
@@ -1034,6 +1034,9 @@ const module$1 = defineNuxtModule({
       }
     }
     const hasI18n = hasNuxtModule("@nuxtjs/i18n") || hasNuxtModule("nuxt-i18n-micro");
+    addPlugin({
+      src: resolve(runtimeDir, "./app/plugins/derivedTags")
+    });
     if (config.automaticDefaults) {
       if (hasI18n) {
         addPlugin({
@@ -1098,6 +1101,8 @@ const module$1 = defineNuxtModule({
       });
     }
     nuxt.options.alias["#seo-utils"] = runtimeDir;
+    const hasSchemaOrg = hasNuxtModule("nuxt-schema-org") && nuxt.options.schemaOrg?.enable !== false;
+    nuxt.options.alias["#seo-utils-schema"] = hasSchemaOrg ? resolve(runtimeDir, "./app/composables/schemaOrg") : resolve(runtimeDir, "./app/composables/polyfills");
     nuxt.options.runtimeConfig.public["nuxt-seo-utils-version"] = nuxt.options.runtimeConfig.public["nuxt-seo-utils-version"] || version || "";
     nuxt.options.runtimeConfig.public["seo-utils"] = defu(nuxt.options.runtimeConfig.public["seo-utils"] || {}, {
       canonicalQueryWhitelist: config.canonicalQueryWhitelist ?? [

package/dist/runtime/app/composables/schemaOrg.d.ts

@@ -0,0 +1,2 @@
+export { useSchemaOrg } from '#schema-org/app/composables/useSchemaOrg';
+export { defineBreadcrumb } from '@unhead/schema-org/vue';

package/dist/runtime/app/composables/schemaOrg.js

@@ -0,0 +1,2 @@
+export { useSchemaOrg } from "#schema-org/app/composables/useSchemaOrg";
+export { defineBreadcrumb } from "@unhead/schema-org/vue";

package/dist/runtime/app/composables/useBreadcrumbItems.js

@@ -1,6 +1,6 @@
 import { defu } from "defu";
 import { fixSlashes } from "nuxt-site-config/urls";
-import { useNuxtApp, useRoute, useRouter, useState } from "nuxt/app";
+import { useNuxtApp, useRoute, useRouter, useRuntimeConfig, useState } from "nuxt/app";
 import { withoutTrailingSlash } from "ufo";
 import {
   computed,
@@ -14,10 +14,12 @@ import {
   toValue,
   watch
 } from "vue";
-import { defineBreadcrumb, useI18n, useSchemaOrg } from "#imports";
+import { defineBreadcrumb, useSchemaOrg } from "#seo-utils-schema";
 import { useSiteConfig } from "#site-config/app/composables/useSiteConfig";
 import { createSitePathResolver } from "#site-config/app/composables/utils";
 import { pathBreadcrumbSegments, resolveBreadcrumbRoot } from "../../shared/breadcrumbs.js";
+import { normaliseCanonicalUrl } from "../../shared/canonicalUrl.js";
+import { useI18n as useI18nPolyfill } from "./polyfills.js";
 function withoutQuery(path) {
   return path.split("?")[0] || "";
 }
@@ -77,7 +79,7 @@ export function useBreadcrumbItems(_options = {}) {
   }
   const route = useRoute();
   const router = useRouter();
-  const i18n = useI18n();
+  const i18n = nuxtApp.$i18n || useI18nPolyfill();
   const siteResolver = createSitePathResolver({
     canonical: true,
     absolute: true
@@ -182,12 +184,17 @@ export function useBreadcrumbItems(_options = {}) {
   }, { immediate: true, flush: "sync" });
   const schemaOrgEnabled = typeof _options.schemaOrg === "undefined" ? true : _options.schemaOrg;
   if ((import.meta.server || import.meta.env?.NODE_ENV === "test") && schemaOrgEnabled) {
+    const { canonicalLowercase } = useRuntimeConfig().public["seo-utils"];
+    const schemaItemUrl = (to) => normaliseCanonicalUrl(toValue(siteResolver(to)), {
+      lowercase: canonicalLowercase,
+      locale: toValue(siteConfig.currentLocale) || toValue(siteConfig.defaultLocale)
+    });
     useSchemaOrg([
       defineBreadcrumb({
         "@id": `#${id}`,
         "itemListElement": computed(() => items.value.map((item) => ({
           name: item.label || item.ariaLabel,
-          item: item.to ? siteResolver(item.to) : void 0
+          item: item.to ? schemaItemUrl(String(item.to)) : void 0
         })))
       })
     ]);

package/dist/runtime/app/composables/useFallbackTitle.js

@@ -2,7 +2,6 @@ import { useError, useNuxtApp, useRoute } from "nuxt/app";
 import { titleCase } from "scule";
 import { withoutTrailingSlash } from "ufo";
 import { computed } from "vue";
-import { useI18n } from "#imports";
 export function useFallbackTitle() {
   const route = useRoute();
   const err = useError();
@@ -11,13 +10,6 @@ export function useFallbackTitle() {
     i18n = useNuxtApp().$i18n;
   } catch {
   }
-  if (!i18n) {
-    try {
-      i18n = useI18n();
-    } catch {
-      console.warn("[nuxt-seo-utils] useFallbackTitle: could not resolve the i18n instance. Titles will not be resolved from i18n messages.");
-    }
-  }
   return computed(() => {
     if (err.value?.statusCode && [404, 500].includes(err.value.statusCode)) {
       return `${err.value.statusCode} - ${err.value.message}`;

package/dist/runtime/app/composables/useShareLinks.js

@@ -1,8 +1,9 @@
 import { useRoute, useRuntimeConfig } from "nuxt/app";
-import { stringifyQuery, withQuery } from "ufo";
+import { withQuery } from "ufo";
 import { computed, toValue } from "vue";
 import { useSiteConfig } from "#site-config/app/composables/useSiteConfig";
 import { createSitePathResolver } from "#site-config/app/composables/utils";
+import { resolveCanonicalUrl } from "../../shared/canonicalUrl.js";
 function buildShareUrl(platform, url, title, options) {
   const encodedUrl = encodeURIComponent(url);
   const encodedTitle = encodeURIComponent(title);
@@ -53,14 +54,11 @@ export function useShareLinks(options = {}) {
     if (customUrl) {
       canonicalUrl = customUrl;
     } else {
-      let url = resolveUrl(route.path || "/").value || route.path;
-      if (canonicalLowercase) {
-        url = url.toLowerCase();
-      }
-      const filteredQuery = Object.fromEntries(
-        Object.entries(route.query).filter(([key]) => canonicalQueryWhitelist.includes(key)).sort(([a], [b]) => a.localeCompare(b))
-      );
-      canonicalUrl = Object.keys(filteredQuery).length ? `${url}?${stringifyQuery(filteredQuery)}` : url;
+      canonicalUrl = resolveCanonicalUrl(resolveUrl(route.path || "/").value || route.path, route.query, {
+        lowercase: canonicalLowercase,
+        locale: toValue(siteConfig.currentLocale) || toValue(siteConfig.defaultLocale),
+        queryWhitelist: canonicalQueryWhitelist
+      });
     }
     const utm = toValue(options.utm) ?? true;
     const title = toValue(options.title) || siteConfig.name || "";

package/dist/runtime/app/logic/applyDefaults.js

@@ -1,10 +1,10 @@
-import { injectHead, useHead, useSeoMeta } from "@unhead/vue";
 import { TemplateParamsPlugin } from "@unhead/vue/plugins";
-import { useError, useRoute, useRuntimeConfig } from "nuxt/app";
-import { stringifyQuery } from "ufo";
+import { injectHead, useError, useHead, useRoute, useRuntimeConfig, useSeoMeta } from "nuxt/app";
 import { computed, toValue } from "vue";
 import { useSiteConfig } from "#site-config/app/composables/useSiteConfig";
 import { createSitePathResolver } from "#site-config/app/composables/utils";
+import { resolveCanonicalUrl } from "../../shared/canonicalUrl.js";
+import { OG_URL_KEY } from "../../shared/derivedTagKeys.js";
 const LOCALE_UNDERSCORE_RE = /_/g;
 export function applyDefaults() {
   const siteConfig = useSiteConfig({
@@ -26,20 +26,12 @@ export function applyDefaults() {
     if (err.value) {
       return false;
     }
-    const { query } = route;
-    let url = resolveUrl(route.path || "/").value || route.path;
-    if (canonicalLowercase) {
-      try {
-        url = url.toLocaleLowerCase(resolveCurrentLocale());
-      } catch {
-        url = url.toLowerCase();
-      }
-    }
-    const filteredQuery = Object.fromEntries(
-      Object.entries(query).filter(([key]) => canonicalQueryWhitelist.includes(key)).sort(([a], [b]) => a.localeCompare(b))
-      // Sort params
-    );
-    const href = Object.keys(filteredQuery).length ? `${url}?${stringifyQuery(filteredQuery)}` : url;
+    const url = resolveUrl(route.path || "/").value || route.path;
+    const href = resolveCanonicalUrl(url, route.query, {
+      lowercase: canonicalLowercase,
+      locale: resolveCurrentLocale(),
+      queryWhitelist: canonicalQueryWhitelist
+    });
     return { rel: "canonical", href };
   });
   const minimalPriority = {
@@ -74,10 +66,6 @@ export function applyDefaults() {
   }, minimalPriority);
   const seoMeta = {
     ogType: "website",
-    ogUrl: () => {
-      const url = canonicalUrl.value;
-      return url ? url.href : false;
-    },
     ogSiteName: siteConfig.name
   };
   if (import.meta.server && siteConfig.description)
@@ -88,4 +76,14 @@ export function applyDefaults() {
     seoMeta.twitterSite = id;
   }
   useSeoMeta(seoMeta, seoMetaPriority);
+  useHead({
+    meta: [{
+      property: "og:url",
+      content: () => {
+        const url = canonicalUrl.value;
+        return url ? url.href : false;
+      },
+      key: OG_URL_KEY
+    }]
+  }, seoMetaPriority);
 }

package/dist/runtime/app/logic/syncDerivedTags.d.ts

@@ -0,0 +1,14 @@
+import type { HeadTag } from '@unhead/vue/types';
+/**
+ * Returns the entries whose tags hold an `og:image`, before deduplication.
+ */
+export declare function ogImageEntryIds(entryTags: Iterable<HeadTag[]>): Set<number>;
+/**
+ * Keeps tags that describe another tag consistent with the tag that won deduplication.
+ *
+ * - `og:image:*` tags from an entry whose `og:image` lost are dropped, so a page `ogImage`
+ *   does not keep the width, height, or type of the `public/` image.
+ * - `twitter:image` tags copied from a `public/` og-image follow the same rule.
+ * - The default `og:url` takes the href of the resolved canonical link.
+ */
+export declare function syncDerivedTags(tags: HeadTag[], entriesWithOgImage: Set<number>): HeadTag[];

package/dist/runtime/app/logic/syncDerivedTags.js

@@ -0,0 +1,43 @@
+import { OG_URL_KEY, TWITTER_IMAGE_FALLBACK_KEY } from "../../shared/derivedTagKeys.js";
+function entryOf(tag) {
+  return tag._p === void 0 ? void 0 : tag._p >> 10;
+}
+function metaKey(tag) {
+  const key = tag.props.property ?? tag.props.name;
+  return typeof key === "string" ? key : void 0;
+}
+function isOgImage(tag) {
+  return tag.tag === "meta" && metaKey(tag) === "og:image";
+}
+export function ogImageEntryIds(entryTags) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const tags of entryTags) {
+    const tag = tags.find(isOgImage);
+    const id = tag && entryOf(tag);
+    if (id !== void 0)
+      ids.add(id);
+  }
+  return ids;
+}
+export function syncDerivedTags(tags, entriesWithOgImage) {
+  const winningOgImageEntries = new Set(tags.filter(isOgImage).map(entryOf));
+  const canonicalHref = tags.find((tag) => tag.tag === "link" && tag.props.rel === "canonical")?.props.href;
+  const lostOgImage = (tag) => {
+    const entry = entryOf(tag);
+    return entry !== void 0 && entriesWithOgImage.has(entry) && !winningOgImageEntries.has(entry);
+  };
+  return tags.flatMap((tag) => {
+    if (tag.tag !== "meta")
+      return [tag];
+    if (metaKey(tag)?.startsWith("og:image:") && lostOgImage(tag))
+      return [];
+    if (tag.key?.startsWith(TWITTER_IMAGE_FALLBACK_KEY) && lostOgImage(tag))
+      return [];
+    if (tag.key === OG_URL_KEY) {
+      if (typeof canonicalHref !== "string" || !canonicalHref)
+        return [];
+      return [{ ...tag, props: { ...tag.props, content: canonicalHref } }];
+    }
+    return [tag];
+  });
+}

package/dist/runtime/app/plugins/0.routeRules.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/app/plugins/0.routeRules.js

@@ -1,4 +1,4 @@
-import { defineNuxtPlugin, useHead, useRequestEvent, useRuntimeConfig, useSeoMeta, useState } from "#imports";
+import { defineNuxtPlugin, useHead, useRequestEvent, useSeoMeta, useState } from "nuxt/app";
 function parseRouteRuleState(context) {
   const rules = context._nitro?.routeRules;
   return {
@@ -10,7 +10,6 @@ export default defineNuxtPlugin({
   enforce: "post",
   env: { islands: false },
   setup() {
-    const { tagPriority } = useRuntimeConfig().public["seo-utils"];
     const routeRuleState = useState("nuxt-seo-utils:routeRules", () => null);
     if (import.meta.server) {
       const event = useRequestEvent();
@@ -21,7 +20,7 @@ export default defineNuxtPlugin({
       if (headInput)
         useHead(headInput);
       if (seoMeta)
-        useSeoMeta(seoMeta, { tagPriority });
+        useSeoMeta(seoMeta);
     }
   }
 });

package/dist/runtime/app/plugins/1.absoluteImageUrls.server.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/app/plugins/1.absoluteImageUrls.server.js

@@ -1,5 +1,4 @@
-import { injectHead } from "@unhead/vue";
-import { defineNuxtPlugin } from "nuxt/app";
+import { defineNuxtPlugin, injectHead } from "nuxt/app";
 import { unref } from "vue";
 import { createSitePathResolver } from "#site-config/app/composables/utils";
 export default defineNuxtPlugin({

package/dist/runtime/app/plugins/colorModeIcons.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/app/plugins/colorModeIcons.js

@@ -1,4 +1,4 @@
-import { defineNuxtPlugin, useHead, useNuxtApp, useRuntimeConfig } from "#imports";
+import { defineNuxtPlugin, useHead, useNuxtApp, useRuntimeConfig } from "nuxt/app";
 import { selectColorModeIconLinks } from "../logic/colorModeIcons.js";
 export default defineNuxtPlugin({
   name: "nuxt-seo-utils:color-mode-icons",

package/dist/runtime/app/plugins/defaults.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/app/plugins/defaultsWaitI18n.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/app/plugins/derivedTags.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/app/plugins/derivedTags.js

@@ -0,0 +1,17 @@
+import { defineNuxtPlugin, injectHead } from "nuxt/app";
+import { ogImageEntryIds, syncDerivedTags } from "../logic/syncDerivedTags.js";
+export default defineNuxtPlugin({
+  name: "nuxt-seo:derived-tags",
+  setup() {
+    const head = injectHead();
+    head.use({
+      key: "nuxt-seo-utils:derived-tags",
+      hooks: {
+        "tags:beforeResolve": (ctx) => {
+          const entryTags = [...head.entries.values()].map((entry) => entry._tags || entry._precomputedTags || []);
+          ctx.tags = syncDerivedTags(ctx.tags, ogImageEntryIds(entryTags));
+        }
+      }
+    });
+  }
+});

package/dist/runtime/app/plugins/inferSeoMetaPlugin.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/app/plugins/inferSeoMetaPlugin.js

@@ -1,6 +1,5 @@
-import { injectHead } from "@unhead/vue";
 import { InferSeoMetaPlugin, TemplateParamsPlugin } from "@unhead/vue/plugins";
-import { defineNuxtPlugin, useRuntimeConfig } from "nuxt/app";
+import { defineNuxtPlugin, injectHead, useRuntimeConfig } from "nuxt/app";
 const disabledTwitterCard = "x-nuxt-seo-utils-disabled-twitter-card";
 export default defineNuxtPlugin(() => {
   const head = injectHead();

package/dist/runtime/app/plugins/minifyScripts.server.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/app/plugins/minifyScripts.server.js

@@ -1,5 +1,4 @@
-import { injectHead } from "@unhead/vue";
-import { defineNuxtPlugin } from "nuxt/app";
+import { defineNuxtPlugin, injectHead } from "nuxt/app";
 import { JSON_TYPES, minifyCSS, minifyJS, minifyJSON, SKIP_JS_TYPES } from "../../shared/minify.js";
 export default defineNuxtPlugin({
   enforce: "post",

package/dist/runtime/app/plugins/siteConfig.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/app/plugins/siteConfig.js

@@ -1,5 +1,4 @@
-import { injectHead } from "@unhead/vue";
-import { defineNuxtPlugin, useRuntimeConfig } from "nuxt/app";
+import { defineNuxtPlugin, injectHead, useRuntimeConfig } from "nuxt/app";
 import { useSiteConfig } from "#site-config/app/composables/useSiteConfig";
 export default defineNuxtPlugin(() => {
   const head = injectHead();

package/dist/runtime/app/plugins/titles.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/app/plugins/titles.js

@@ -1,5 +1,4 @@
-import { useHead } from "@unhead/vue";
-import { defineNuxtPlugin } from "nuxt/app";
+import { defineNuxtPlugin, useHead } from "nuxt/app";
 import { useFallbackTitle } from "../composables/useFallbackTitle.js";
 export default defineNuxtPlugin({
   name: "nuxt-seo:fallback-titles",

package/dist/runtime/app/plugins/titlesWaitI18n.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/app/plugins/titlesWaitI18n.js

@@ -1,5 +1,4 @@
-import { useHead } from "@unhead/vue";
-import { defineNuxtPlugin } from "nuxt/app";
+import { defineNuxtPlugin, useHead } from "nuxt/app";
 import { useFallbackTitle } from "../composables/useFallbackTitle.js";
 export default defineNuxtPlugin({
   name: "nuxt-seo:fallback-titles",

package/dist/runtime/shared/canonicalUrl.d.ts

@@ -0,0 +1,17 @@
+import type { QueryObject } from 'ufo';
+export interface CanonicalUrlOptions {
+    lowercase: boolean;
+    /** BCP 47 or underscore locale. Lowercasing follows its rules, for example Turkish dotless ı. */
+    locale?: string;
+}
+/**
+ * The one normaliser for absolute URLs that name the page: the canonical link, og:url,
+ * share links, and Schema.org breadcrumb items. Navigation links never pass through it.
+ */
+export declare function normaliseCanonicalUrl(url: string, { lowercase, locale }: CanonicalUrlOptions): string;
+/**
+ * Normalises the page URL and keeps only whitelisted query keys, sorted.
+ */
+export declare function resolveCanonicalUrl(url: string, query: QueryObject, options: CanonicalUrlOptions & {
+    queryWhitelist: string[];
+}): string;

package/dist/runtime/shared/canonicalUrl.js

@@ -0,0 +1,26 @@
+import { parseURL, stringifyParsedURL, stringifyQuery } from "ufo";
+const LOCALE_UNDERSCORE_RE = /_/g;
+const DEFAULT_LOCALE = "en";
+export function normaliseCanonicalUrl(url, { lowercase, locale }) {
+  if (!lowercase)
+    return url;
+  const parsed = parseURL(url);
+  if (parsed.host)
+    parsed.host = parsed.host.toLowerCase();
+  parsed.pathname = lowercasePath(parsed.pathname, locale);
+  return stringifyParsedURL(parsed);
+}
+function lowercasePath(path, locale) {
+  try {
+    return path.toLocaleLowerCase(locale ? locale.replace(LOCALE_UNDERSCORE_RE, "-") : DEFAULT_LOCALE);
+  } catch {
+    return path.toLowerCase();
+  }
+}
+export function resolveCanonicalUrl(url, query, options) {
+  const normalised = normaliseCanonicalUrl(url, options);
+  const filteredQuery = Object.fromEntries(
+    Object.entries(query).filter(([key]) => options.queryWhitelist.includes(key)).sort(([a], [b]) => a.localeCompare(b))
+  );
+  return Object.keys(filteredQuery).length ? `${normalised}?${stringifyQuery(filteredQuery)}` : normalised;
+}

package/dist/runtime/shared/derivedTagKeys.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Marks the `twitter:image` tags copied from a `public/` og-image.
+ * They are dropped when another entry's `og:image` replaces that image.
+ * Keys start with this prefix and end with the file name, so two files never merge.
+ */
+export declare const TWITTER_IMAGE_FALLBACK_KEY = "nuxt-seo-utils:twitter-image-fallback";
+/**
+ * Marks the default `og:url`. It takes the href of the resolved canonical link.
+ */
+export declare const OG_URL_KEY = "nuxt-seo-utils:og-url";

package/dist/runtime/shared/derivedTagKeys.js

@@ -0,0 +1,2 @@
+export const TWITTER_IMAGE_FALLBACK_KEY = "nuxt-seo-utils:twitter-image-fallback";
+export const OG_URL_KEY = "nuxt-seo-utils:og-url";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-seo-utils",
   "type": "module",
-  "version": "8.5.2",
+  "version": "8.6.1",
   "description": "SEO utilities to improve your Nuxt sites discoverability and shareability",
   "license": "MIT",
   "funding": "https://github.com/sponsors/harlan-zw",
@@ -25,7 +25,8 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "skills"
   ],
   "build": {
     "externals": [

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

@@ -0,0 +1,144 @@
+---
+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.
+---
+
+# nuxt-seo-utils
+
+Tested against `nuxt-seo-utils` 8.5.2 on Nuxt 4.5.2 with Unhead v3 (requires Nuxt `>=3.16.0`).
+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
+
+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.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-seo-utils'],
+  site: { url: 'https://example.com', name: 'Acme', description: 'Default description', twitter: 'acme', defaultLocale: 'en-US' },
+})
+```
+
+Crawlers read only the SSR response. The defaults render on the server.
+
+## Automatic behaviour
+
+With the defaults, every page gets:
+
+- `<title>` from the template `%s %separator %siteName`. The separator is `|`. Change it with `site.separator`.
+- A fallback title from the last path segment, title cased: `/blog/my-post` becomes `My Post`. `definePageMeta({ title })` sets it with a static string.
+- `<link rel="canonical">` from `site.url` and the route path, lowercased, with only these query keys kept: `page`, `sort`, `filter`, `search`, `q`, `category`, `tag`.
+- `og:url` (the resolved canonical, including one a page sets), `og:type` (`website`), `og:site_name` (`site.name`), and `description` from `site.description`.
+- `og:title`, `og:description`, and `twitter:card` (`summary_large_image`), inferred from the title and description.
+- `twitter:site` and `twitter:creator` from `site.twitter`. The `@` is added.
+- `<html lang>` from `site.currentLocale` or `site.defaultLocale`, else `en`.
+- `og:locale` only when the locale has a region. `en-US` renders `en_US`. `en` renders no tag.
+- Relative `og:image` and `twitter:image` values become absolute against `site.url`.
+
+Module tags use `tagPriority: 'low'`, so a page `useSeoMeta()` or `useHead()` call replaces them.
+A page `ogImage` also drops the default image's width, height, type, and copied `twitter:image`. A page `ogImageAlt` alone keeps the default image.
+A page canonical needs no extra priority:
+
+```ts
+useHead({ link: [{ rel: 'canonical', href: 'https://example.com/preferred' }] })
+```
+
+Set `seo: { automaticDefaults: false }` to drop the canonical, title template, `lang`, and Open Graph defaults together. No option drops only one of them.
+
+## Metadata files
+
+Files in `public/` become site-wide head tags at build time:
+
+- `favicon.{ico,png,svg}`, `icon*.{ico,png,jpg,svg}`, `apple-icon*.png`, `apple-touch-icon*.png`: `<link rel="icon">` or `apple-touch-icon`, with `type` and `sizes` read from the file.
+- `og-image.{png,jpg,jpeg,gif}` or `opengraph-image.*`: `og:image` with width, height, and type. It also fills `twitter:image` when no `twitter-image.*` file exists. The name must match exactly; `blog-og-image.png` is ignored.
+- `<name>.alt.txt` next to an image sets `og:image:alt`.
+- `-dark` or `-light` in an icon name adds a `prefers-color-scheme` media query.
+
+The same file names inside `pages/<route>/` or `pages/<route>/_dir/` apply to that route and its children. They replace a `public/` image there.
+An icon link in `app.head.link` with the same `rel` wins over the files.
+Set `seo: { metaDataFiles: false }` to turn this off.
+
+Generate icon files from one source image in `public/`:
+
+```bash
+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.
+
+## Site-wide and per-route meta
+
+`seo.meta` takes `useSeoMeta()` input and renders on every page:
+
+```ts
+export default defineNuxtConfig({
+  seo: { meta: { author: 'Acme Team', themeColor: '#18181b' } },
+})
+```
+
+`routeRules` accept `seoMeta` and `head`:
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/blog/**': { seoMeta: { author: 'Blog Team' }, head: { meta: [{ name: 'x-section', content: 'blog' }] } },
+  },
+})
+```
+
+Route rule tags override `seo.meta` and `app.head`. A page `useSeoMeta()` or `useHead()` call overrides them. The `tagPriority` option does not change this.
+Route rule tags render on the server only. They do not update on client navigation.
+
+## Breadcrumbs
+
+`useBreadcrumbItems()` is auto-imported. It returns a ref of items from the route path, ready for Nuxt UI `<UBreadcrumb :items>`.
+
+```ts
+const items = useBreadcrumbItems({
+  overrides: [undefined, undefined, { label: post.value.title }], // index matches the path segment; false removes it
+})
+```
+
+- With `nuxt-schema-org` installed, it also adds a `BreadcrumbList` node. Without it, no JSON-LD renders and there is no warning.
+- Labels come from `definePageMeta({ breadcrumb: { label } })`, then `title` in page meta, then the title-cased segment. The index route is `Home`.
+- Call it in the page component, not the layout. The page has the data for the last items. Calls in parent components with the same `id` merge their options.
+
+## Share links
+
+```ts
+const share = useShareLinks({ title: post.value.title, utm: { source: 'auto', campaign: 'launch' } })
+// share.value.twitter, .facebook, .linkedin, .whatsapp, .telegram, .reddit, .pinterest, .email, .canonicalUrl
+```
+
+`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`.
+
+## 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.
+
+## Version 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.
+- `automaticOgAndTwitterTags` (`true`): the `og:title`, `og:description`, and `twitter:card` inference.
+- Other options: https://nuxtseo.com/docs/seo-utils/api/config
+
+## Debug
+
+- 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.