nuxt-seo-utils 8.4.3 → 8.5.0

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.4.3";
+const version = "8.5.0";
 const description = "SEO utilities to improve your Nuxt sites discoverability and shareability";
 
 const ICON_SIZES = [

package/dist/module.d.mts

@@ -25,6 +25,12 @@ interface ModuleOptions {
      * @default true
      */
     automaticOgAndTwitterTags: boolean;
+    /**
+     * Whether to infer Twitter metadata from Open Graph metadata.
+     *
+     * @default true
+     */
+    automaticTwitterTags: boolean;
     /**
      * Attempts to treeshake the `useSeoMeta` function. Can save around 5kb in the client bundle.
      *
@@ -127,6 +133,13 @@ interface ModuleOptions {
         build?: boolean;
         runtime?: boolean;
     };
+    /**
+     * Checks the `app.head` in your Nuxt config for conflicts, redundant tags, and dead tags.
+     * Warnings print on dev server start and on build.
+     *
+     * @default true
+     */
+    validateAppHead: boolean;
     /**
      * Enables debug logs and a debug endpoint.
      *

package/dist/module.d.ts

@@ -25,6 +25,12 @@ interface ModuleOptions {
      * @default true
      */
     automaticOgAndTwitterTags: boolean;
+    /**
+     * Whether to infer Twitter metadata from Open Graph metadata.
+     *
+     * @default true
+     */
+    automaticTwitterTags: boolean;
     /**
      * Attempts to treeshake the `useSeoMeta` function. Can save around 5kb in the client bundle.
      *
@@ -127,6 +133,13 @@ interface ModuleOptions {
         build?: boolean;
         runtime?: boolean;
     };
+    /**
+     * Checks the `app.head` in your Nuxt config for conflicts, redundant tags, and dead tags.
+     * Warnings print on dev server start and on build.
+     *
+     * @default true
+     */
+    validateAppHead: boolean;
     /**
      * Enables debug logs and a debug endpoint.
      *

package/dist/module.json

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

package/dist/module.mjs

@@ -1,13 +1,13 @@
 import fs, { existsSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { useNuxt, addTypeTemplate, useLogger, defineNuxtModule, createResolver, addServerHandler, hasNuxtModule, addPlugin, addImports, hasNuxtCompatibility, directoryToURL, addVitePlugin } from '@nuxt/kit';
+import { unpackMeta } from '@unhead/vue/utils';
 import { defu } from 'defu';
 import { resolveModulePath } from 'exsolve';
-import { installNuxtSiteConfig } from 'nuxt-site-config/kit';
+import { installNuxtSiteConfig, useSiteConfig } from 'nuxt-site-config/kit';
 import { useModuleLogger, setupNitroRuntimeCompatibility, renderNitroTypeAugmentations, resolveHostUnheadMajor } from 'nuxtseo-shared/kit';
 import { resolve, extname, relative, dirname, basename } from 'pathe';
 import { readPackageJSON, resolvePackageJSON } from 'pkg-types';
-import { unpackMeta } from '@unhead/vue/utils';
 import { glob } from 'tinyglobby';
 import { encodePath, joinURL } from 'ufo';
 import { c as classifyIconFilename, g as getIconRel, n as normalizeIconSizes, a as partitionColorModeIconLinks } from './shared/nuxt-seo-utils.NAV2YNQn.mjs';
@@ -703,6 +703,249 @@ function setupNuxtConfigAppHeadWithMoreDefaults(nuxt = useNuxt()) {
   nuxt.options.app.head = headConfig;
 }
 
+const NUXT_DEFAULT_VIEWPORT = "width=device-width, initial-scale=1";
+const UNDERSCORE_RE = /_/g;
+const HYPHEN_RE = /-/g;
+const WS_RE = /\s+/g;
+const ABSOLUTE_SRC_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+const NOOP_ROBOTS = /* @__PURE__ */ new Set(["index", "follow", "all", "index,follow", "follow,index"]);
+const META_TAGS_ARRAYABLE = /* @__PURE__ */ new Set([
+  "theme-color",
+  "google-site-verification",
+  "author",
+  "og:locale:alternate",
+  "og:image",
+  "og:video",
+  "og:audio",
+  "article:author",
+  "article:tag",
+  "book:author",
+  "book:tag",
+  "twitter:image"
+]);
+function isMetaArrayable(key) {
+  const dedupeKey = `meta:${key}`;
+  const suffix = dedupeKey.slice(dedupeKey.indexOf(":") + 1);
+  return META_TAGS_ARRAYABLE.has(suffix) || suffix.startsWith("og:image:") || suffix.startsWith("og:video:") || suffix.startsWith("og:audio:") || suffix.startsWith("twitter:image:");
+}
+function normalizeWhitespace(value) {
+  return value.trim().replace(WS_RE, " ");
+}
+function asString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function metaTagKey(entry) {
+  if (asString(entry.charset))
+    return "charset";
+  const key = asString(entry.name) || asString(entry.property) || asString(entry["http-equiv"]);
+  return key?.toLowerCase();
+}
+function findMeta(meta, key) {
+  return meta.find((entry) => metaTagKey(entry) === key);
+}
+function metaContent(entry) {
+  return entry ? asString(entry.content) : void 0;
+}
+function baseLanguage(locale) {
+  return locale.toLowerCase().replace(UNDERSCORE_RE, "-").split("-")[0];
+}
+function checkLocale(ctx, meta, diagnostics) {
+  const lang = asString(ctx.head.htmlAttrs?.lang);
+  const ogLocale = metaContent(findMeta(meta, "og:locale"));
+  if (ogLocale && ogLocale.includes("-")) {
+    diagnostics.push({
+      _tag: "OgLocaleNotUnderscored",
+      level: "warn",
+      content: ogLocale,
+      resolved: ogLocale.replace(HYPHEN_RE, "_")
+    });
+  }
+  if (!lang)
+    return;
+  if (lang.includes("_")) {
+    diagnostics.push({
+      _tag: "LangNotBcp47",
+      level: "warn",
+      lang,
+      resolved: lang.replace(UNDERSCORE_RE, "-")
+    });
+  }
+  if (ctx.hasI18n) {
+    diagnostics.push({ _tag: "StaticLangWithI18n", level: "warn", lang });
+    return;
+  }
+  const configured = asString(ctx.siteConfig?.defaultLocale);
+  const defaultLocale = configured || "en";
+  if (baseLanguage(lang) !== baseLanguage(defaultLocale)) {
+    diagnostics.push({
+      _tag: "LocaleMismatch",
+      level: "warn",
+      lang,
+      defaultLocale,
+      configured: Boolean(configured)
+    });
+  }
+}
+function renderedIndexes(groups) {
+  const rendered = /* @__PURE__ */ new Map();
+  let index = -1;
+  for (const group of groups) {
+    for (const entry of group) {
+      index++;
+      const key = metaTagKey(entry);
+      if (key && !isMetaArrayable(key))
+        rendered.set(key, index);
+    }
+  }
+  return rendered;
+}
+function checkMeta(ctx, groups, diagnostics) {
+  const rendered = renderedIndexes(groups);
+  let index = -1;
+  for (const group of groups) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const entry of group) {
+      index++;
+      const key = metaTagKey(entry);
+      if (!key) {
+        diagnostics.push({ _tag: "MalformedTag", level: "warn", index, layered: groups.length > 1 });
+        continue;
+      }
+      const content = key === "charset" ? asString(entry.charset) : metaContent(entry);
+      if (seen.has(key) && seen.get(key) !== content && !isMetaArrayable(key))
+        diagnostics.push({ _tag: "DuplicateTag", level: "warn", tag: key });
+      seen.set(key, content);
+      if (!isMetaArrayable(key) && rendered.get(key) !== index)
+        continue;
+      if (key === "charset" && content?.toLowerCase() === "utf-8")
+        diagnostics.push({ _tag: "RedundantTag", level: "info", tag: "charset", reason: "Nuxt sets it by default." });
+      if (key === "viewport" && content && normalizeWhitespace(content) === NUXT_DEFAULT_VIEWPORT)
+        diagnostics.push({ _tag: "RedundantTag", level: "info", tag: "viewport", reason: "Nuxt sets the same value by default." });
+      if (key === "og:type" && content === "website" && ctx.defaultsActive !== false)
+        diagnostics.push({ _tag: "RedundantTag", level: "info", tag: "og:type", reason: "nuxt-seo-utils sets it by default." });
+      if (key === "og:url" && ctx.defaultsActive !== false)
+        diagnostics.push({ _tag: "GlobalPageTag", level: "warn", tag: "og:url", reason: "It applies the same URL to every page. nuxt-seo-utils sets it per route." });
+      if (key === "robots" && content) {
+        if (ctx.hasRobotsModule)
+          diagnostics.push({ _tag: "RobotsModuleConflict", level: "warn", content });
+        else if (NOOP_ROBOTS.has(content.toLowerCase().replace(WS_RE, "")))
+          diagnostics.push({ _tag: "RedundantTag", level: "info", tag: "robots", reason: "Crawlers index and follow by default." });
+      }
+      if (key === "og:site_name" && content && ctx.defaultsActive !== false) {
+        const siteName = asString(ctx.siteConfig?.name);
+        if (!siteName) {
+          diagnostics.push({ _tag: "SiteNameMismatch", level: "warn", head: content });
+        } else if (siteName === content) {
+          diagnostics.push({ _tag: "RedundantTag", level: "info", tag: "og:site_name", reason: "nuxt-seo-utils sets it from your site config." });
+        } else {
+          diagnostics.push({ _tag: "SiteNameMismatch", level: "warn", head: content, site: siteName });
+        }
+      }
+      if (key === "description" && content && ctx.mergeWithSiteConfig !== false && content === asString(ctx.siteConfig?.description))
+        diagnostics.push({ _tag: "RedundantTag", level: "info", tag: "description", reason: "nuxt-seo-utils sets it from your site config." });
+      if ((key === "og:image" || key === "twitter:image") && content && !ABSOLUTE_SRC_RE.test(content) && !asString(ctx.siteConfig?.url))
+        diagnostics.push({ _tag: "RelativeSocialImage", level: "warn", tag: key, src: content });
+    }
+  }
+}
+function checkShorthand(ctx, diagnostics) {
+  const charset = asString(ctx.head.charset);
+  if (charset?.toLowerCase() === "utf-8")
+    diagnostics.push({ _tag: "RedundantTag", level: "info", tag: "app.head.charset", reason: "Nuxt sets `utf-8` by default." });
+  const viewport = asString(ctx.head.viewport);
+  if (viewport && normalizeWhitespace(viewport) === NUXT_DEFAULT_VIEWPORT)
+    diagnostics.push({ _tag: "RedundantTag", level: "info", tag: "app.head.viewport", reason: "Nuxt sets the same value by default." });
+  const titleTemplate = ctx.head.titleTemplate;
+  if (typeof titleTemplate === "string" && !titleTemplate.includes("%s")) {
+    diagnostics.push({ _tag: "TitleTemplateMissingPlaceholder", level: "warn", titleTemplate });
+  }
+}
+function checkLinks(ctx, diagnostics) {
+  for (const link of ctx.head.link || []) {
+    const rel = asString(link.rel)?.toLowerCase();
+    if (rel === "canonical") {
+      if (ctx.defaultsActive !== false) {
+        diagnostics.push({
+          _tag: "GlobalPageTag",
+          level: "error",
+          tag: 'link[rel="canonical"]',
+          reason: "It points every page at one URL. nuxt-seo-utils sets a canonical per route."
+        });
+      }
+    } else if (rel === "alternate" && asString(link.hreflang)) {
+      diagnostics.push({
+        _tag: "GlobalPageTag",
+        level: "warn",
+        tag: 'link[rel="alternate"][hreflang]',
+        reason: "It repeats the same alternate URL on every page. Let @nuxtjs/i18n generate it."
+      });
+    }
+  }
+}
+function validateAppHead(ctx) {
+  const diagnostics = [];
+  const groups = ctx.head.metaByLayer ?? (ctx.head.meta ? [ctx.head.meta] : []);
+  checkLocale(ctx, groups.flat(), diagnostics);
+  checkShorthand(ctx, diagnostics);
+  checkMeta(ctx, groups, diagnostics);
+  checkLinks(ctx, diagnostics);
+  return diagnostics;
+}
+function formatAppHeadDiagnostic(diagnostic) {
+  switch (diagnostic._tag) {
+    case "LocaleMismatch":
+      return diagnostic.configured ? `\`app.head.htmlAttrs.lang\` is "${diagnostic.lang}" but site \`defaultLocale\` is "${diagnostic.defaultLocale}". og:locale, canonical casing, and Schema.org will use "${diagnostic.defaultLocale}". Set \`site.defaultLocale\` to "${diagnostic.lang}".` : `\`app.head.htmlAttrs.lang\` is "${diagnostic.lang}" but no site \`defaultLocale\` is set, so it falls back to "en". og:locale, canonical casing, and Schema.org will use "en". Add \`site: { defaultLocale: '${diagnostic.lang}' }\` to your Nuxt config.`;
+    case "LangNotBcp47":
+      return `\`app.head.htmlAttrs.lang\` is "${diagnostic.lang}". The HTML lang attribute needs a hyphen. Use "${diagnostic.resolved}".`;
+    case "OgLocaleNotUnderscored":
+      return `\`og:locale\` is "${diagnostic.content}". Open Graph needs an underscore. Use "${diagnostic.resolved}".`;
+    case "StaticLangWithI18n":
+      return `\`app.head.htmlAttrs.lang\` is "${diagnostic.lang}" while an i18n module is installed. It pins every locale to one language. Remove it and set the locale in your i18n config.`;
+    case "RedundantTag":
+      return `\`${diagnostic.tag}\` repeats a default. ${diagnostic.reason} You can remove it.`;
+    case "GlobalPageTag":
+      return `\`${diagnostic.tag}\` is set in \`app.head\`. ${diagnostic.reason}`;
+    case "DuplicateTag":
+      return `\`${diagnostic.tag}\` is set more than once with different content. Only the last value renders.`;
+    case "MalformedTag":
+      return diagnostic.layered ? `An \`app.head.meta\` entry has no \`name\`, \`property\`, \`http-equiv\`, or \`charset\`. It renders an empty tag.` : `\`app.head.meta[${diagnostic.index}]\` has no \`name\`, \`property\`, \`http-equiv\`, or \`charset\`. It renders an empty tag.`;
+    case "TitleTemplateMissingPlaceholder":
+      return `\`titleTemplate\` is "${diagnostic.titleTemplate}" and has no \`%s\`. Every page renders the same title. Add \`%s\` where the page title belongs.`;
+    case "SiteNameMismatch":
+      return diagnostic.site ? `\`og:site_name\` is "${diagnostic.head}" but site \`name\` is "${diagnostic.site}". Keep one source of truth. Set \`site.name\` and remove the meta tag.` : `\`og:site_name\` is "${diagnostic.head}" but no site \`name\` is set. Set \`site.name\` to "${diagnostic.head}" and remove the meta tag, nuxt-seo-utils then sets it from your site config.`;
+    case "RelativeSocialImage":
+      return `\`${diagnostic.tag}\` is "${diagnostic.src}" and no site \`url\` is set. Crawlers need an absolute URL. Set \`site.url\`.`;
+    case "RobotsModuleConflict":
+      return `\`robots\` is "${diagnostic.content}" in \`app.head\` while @nuxtjs/robots is installed. The two fight over the tag. Configure it through the robots module instead.`;
+  }
+}
+function collectUserAppHead(nuxt) {
+  const head = { metaByLayer: [], link: [] };
+  const layers = nuxt.options._layers || [];
+  for (let i = layers.length - 1; i >= 0; i--) {
+    const layerHead = layers[i]?.config?.app?.head;
+    if (!layerHead)
+      continue;
+    if (layerHead.meta?.length)
+      head.metaByLayer.push(layerHead.meta);
+    const seoMeta = layerHead.seoMeta;
+    if (seoMeta && Object.keys(seoMeta).length)
+      head.metaByLayer.push(unpackMeta(seoMeta));
+    head.link.push(...layerHead.link || []);
+  }
+  for (const layer of layers) {
+    const layerHead = layer.config?.app?.head;
+    if (!layerHead)
+      continue;
+    head.charset ??= layerHead.charset;
+    head.viewport ??= layerHead.viewport;
+    head.titleTemplate ??= layerHead.titleTemplate;
+    if (layerHead.htmlAttrs)
+      head.htmlAttrs = { ...layerHead.htmlAttrs, ...head.htmlAttrs };
+  }
+  return head;
+}
+
 function setupDevToolsUI(resolve, nuxt = useNuxt()) {
   setupDevToolsUI$1({
     route: "/__nuxt-seo-utils",
@@ -748,7 +991,9 @@ const module$1 = defineNuxtModule({
     extendNuxtConfigAppHeadTypes: true,
     setupNuxtConfigAppHeadWithMoreDefaults: true,
     automaticOgAndTwitterTags: true,
+    automaticTwitterTags: true,
     canonicalLowercase: true,
+    validateAppHead: true,
     tagPriority: "low",
     minify: { build: true, runtime: false }
   },
@@ -865,6 +1110,7 @@ const module$1 = defineNuxtModule({
         "tag"
       ],
       canonicalLowercase: config.canonicalLowercase,
+      automaticTwitterTags: config.automaticTwitterTags,
       tagPriority: config.tagPriority,
       separator: headTemplateParams?.separator,
       titleSeparator: headTemplateParams?.titleSeparator
@@ -1008,6 +1254,43 @@ export {}
         handler: resolve("./runtime/server/routes/__nuxt-seo-utils/debug")
       });
     }
+    if (config.validateAppHead) {
+      nuxt.hook("modules:done", () => {
+        try {
+          const userHead = collectUserAppHead(nuxt);
+          const seoMeta = unpackMeta(config.meta || {});
+          if (seoMeta.length)
+            userHead.metaByLayer.push(seoMeta);
+          const siteConfig = useSiteConfig(nuxt);
+          const hasUserI18n = hasI18n && (nuxt.options._layers || []).some((layer) => Boolean(layer.config?.i18n));
+          const diagnostics = validateAppHead({
+            head: userHead,
+            siteConfig: {
+              name: siteConfig.name,
+              url: siteConfig.url,
+              description: siteConfig.description,
+              defaultLocale: siteConfig.defaultLocale
+            },
+            hasI18n: hasUserI18n,
+            hasRobotsModule: hasNuxtModule("@nuxtjs/robots", nuxt),
+            defaultsActive: config.automaticDefaults,
+            mergeWithSiteConfig: config.mergeWithSiteConfig
+          });
+          if (!diagnostics.length)
+            return;
+          const lines = diagnostics.map((d) => `  ${d.level === "info" ? "\xB7" : "\u2716"} ${formatAppHeadDiagnostic(d)}`);
+          const message = `Found ${diagnostics.length} issue${diagnostics.length > 1 ? "s" : ""} in your Nuxt config head.
+${lines.join("\n")}
+  Set \`seo: { validateAppHead: false }\` to turn off this check.`;
+          if (diagnostics.some((d) => d.level !== "info"))
+            logger.warn(message);
+          else
+            logger.info(message);
+        } catch (e) {
+          logger.warn(`Skipped the head config check. ${e}`);
+        }
+      });
+    }
     if (nuxt.options.dev) {
       setupDevToolsUI(resolve, nuxt);
     }

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

@@ -1,10 +1,28 @@
 import { injectHead } from "@unhead/vue";
 import { InferSeoMetaPlugin, TemplateParamsPlugin } from "@unhead/vue/plugins";
-import { defineNuxtPlugin } from "nuxt/app";
+import { defineNuxtPlugin, useRuntimeConfig } from "nuxt/app";
+const disabledTwitterCard = "x-nuxt-seo-utils-disabled-twitter-card";
 export default defineNuxtPlugin(() => {
   const head = injectHead();
   if (!head)
     return;
+  const { automaticTwitterTags } = useRuntimeConfig().public["seo-utils"];
   head.use(TemplateParamsPlugin);
-  head.use(InferSeoMetaPlugin());
+  if (automaticTwitterTags === false) {
+    head.use(InferSeoMetaPlugin({ twitterCard: disabledTwitterCard }));
+    head.use({
+      key: "nuxt-seo-utils:twitter-card-suppression",
+      hooks: {
+        "tags:beforeResolve": ({ tags }) => {
+          for (let i = tags.length - 1; i >= 0; i--) {
+            const tag = tags[i];
+            if (tag.tag === "meta" && tag.props.name === "twitter:card" && tag.props.content === disabledTwitterCard)
+              tags.splice(i, 1);
+          }
+        }
+      }
+    });
+  } else {
+    head.use(InferSeoMetaPlugin());
+  }
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-seo-utils",
   "type": "module",
-  "version": "8.4.3",
+  "version": "8.5.0",
   "description": "SEO utilities to improve your Nuxt sites discoverability and shareability",
   "license": "MIT",
   "funding": "https://github.com/sponsors/harlan-zw",
@@ -68,8 +68,8 @@
     "defu": "^6.1.7",
     "escape-string-regexp": "^5.0.0",
     "exsolve": "^1.1.1",
-    "nuxt-site-config": "^4.2.2",
-    "nuxtseo-shared": "^5.3.12",
+    "nuxt-site-config": "^4.2.3",
+    "nuxtseo-shared": "^5.3.14",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.1",
     "scule": "^1.3.0",
@@ -77,39 +77,39 @@
     "ufo": "^1.6.4"
   },
   "optionalDependencies": {
-    "sharp": "^0.35.3"
+    "sharp": "^0.35.4"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.3.0",
     "@nuxt/devtools-kit": "4.0.0-alpha.9",
     "@nuxt/module-builder": "^1.0.3",
     "@nuxt/schema": "^4.5.2",
-    "@nuxt/test-utils": "^4.1.0",
-    "@nuxt/ui": "^4.10.0",
+    "@nuxt/test-utils": "^4.2.0",
+    "@nuxt/ui": "^4.11.0",
     "@nuxtjs/i18n": "^10.6.0",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.0",
     "@unhead/vue": "3.2.3",
-    "@vue/test-utils": "^2.4.11",
-    "bumpp": "^12.2.0",
+    "@vue/test-utils": "^2.5.0",
+    "bumpp": "^12.2.2",
     "case-police": "^2.2.1",
     "cheerio": "^1.2.0",
-    "eslint": "^10.8.1",
-    "eslint-plugin-harlanzw": "^0.19.2",
-    "happy-dom": "^20.11.2",
-    "lint-staged": "^17.3.0",
+    "eslint": "^10.9.1",
+    "eslint-plugin-harlanzw": "^0.20.0",
+    "happy-dom": "^20.12.0",
+    "lint-staged": "^17.4.1",
     "markdownlint-cli": "^0.49.1",
     "nuxt": "^4.5.2",
     "nuxt-security": "^2.6.0",
-    "nuxtseo-layer-devtools": "^5.3.12",
+    "nuxtseo-layer-devtools": "^5.3.14",
     "playwright-core": "^1.62.1",
-    "sass": "^1.102.0",
+    "sass": "^1.103.1",
     "typescript": "6.0.3",
     "ultrahtml": "^1.7.0",
     "unbuild": "^3.6.1",
     "unhead": "3.2.3",
-    "vitest": "^4.1.10",
-    "vue": "^3.5.41",
-    "vue-tsc": "^3.3.9"
+    "vitest": "^4.1.11",
+    "vue": "^3.5.42",
+    "vue-tsc": "^3.3.11"
   },
   "scripts": {
     "client:build": "node -e \"require('fs').cpSync('devtools','dist/devtools',{recursive:true})\"",