nuxt-seo-utils 5.0.0

package/dist/runtime/nuxt/composables/useBreadcrumbItems.d.ts

@@ -0,0 +1,95 @@
+import type { NuxtLinkProps } from 'nuxt/app';
+import type { MaybeRefOrGetter } from 'vue';
+interface NuxtUIBreadcrumbItem extends NuxtLinkProps {
+    label: string;
+    labelClass?: string;
+    icon?: string;
+    iconClass?: string;
+    as?: string;
+    type?: string;
+    disabled?: boolean;
+    active?: boolean;
+    exact?: boolean;
+    exactQuery?: boolean;
+    exactMatch?: boolean;
+    inactiveClass?: string;
+    [key: string]: any;
+}
+export interface BreadcrumbProps {
+    /**
+     * Generate the breadcrumbs based on a different path than the current route.
+     */
+    path?: MaybeRefOrGetter<string>;
+    /**
+     * The id of the breadcrumb list. It's recommended to provide a unique
+     * id when adding multiple breadcrumb lists to the same page.
+     */
+    id?: string;
+    /**
+     * Append additional breadcrumb items to the end of the list. This is applied
+     * after the `overrides` option.
+     */
+    append?: BreadcrumbItemProps[];
+    /**
+     * Prepend additional breadcrumb items to the start of the list. This is applied
+     * after the `overrides` option.
+     */
+    prepend?: BreadcrumbItemProps[];
+    /**
+     * Override any of the breadcrumb items based on the index.
+     */
+    overrides?: (BreadcrumbItemProps | false | undefined)[];
+    /**
+     * Should the schema.org breadcrumb be generated.
+     * @default true
+     */
+    schemaOrg?: boolean;
+    /**
+     * The Aria Label for the breadcrumbs.
+     * You shouldn't need to change this.
+     *
+     * @default 'Breadcrumbs'
+     */
+    ariaLabel?: string;
+    /**
+     * Should the current breadcrumb item be shown.
+     *
+     * @default false
+     */
+    hideCurrent?: MaybeRefOrGetter<boolean>;
+    /**
+     * Should the root breadcrumb be shown.
+     */
+    hideRoot?: MaybeRefOrGetter<boolean>;
+}
+export interface BreadcrumbItemProps extends NuxtUIBreadcrumbItem {
+    /** Whether the breadcrumb item represents the aria-current. */
+    current?: boolean;
+    /**
+     * The type of current location the breadcrumb item represents, if `isCurrent` is true.
+     * @default 'page'
+     */
+    ariaCurrent?: 'page' | 'step' | 'location' | 'date' | 'time' | boolean | 'true' | 'false';
+    to?: string;
+    ariaLabel?: string;
+    separator?: boolean | string;
+    class?: (string | string[] | undefined)[] | string;
+    /**
+     * @internal
+     */
+    _props?: {
+        first: boolean;
+        last: boolean;
+    };
+}
+/**
+ * Generate an automatic breadcrumb list that helps users to navigate between pages.
+ *
+ * - Integrates with [Nuxt Schema.org](/schema-org/getting-started/installation) to generate [BreadcrumbList](https://schema.org/BreadcrumbList) structured data.
+ * - Integrates with [Nuxt I18n](https://i18n.nuxtjs.org/) to generate localized breadcrumbs.
+ *
+ * @see https://github.com/harlan-zw/nuxt-seo/blob/main/src/runtime/nuxt/composables/useBreadcrumbItems.ts
+ * @docs https://nuxtseo.com/nuxt-seo/api/breadcrumbs
+ */
+export declare function useBreadcrumbItems(options?: BreadcrumbProps): import("vue").ComputedRef<BreadcrumbItemProps[]>;
+export {};

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

@@ -0,0 +1,98 @@
+import {
+  computed,
+  createSitePathResolver,
+  defineBreadcrumb,
+  toValue,
+  useI18n,
+  useRouter,
+  useSchemaOrg,
+  useSiteConfig
+} from "#imports";
+import { defu } from "defu";
+import { fixSlashes } from "site-config-stack/urls";
+import { withoutTrailingSlash } from "ufo";
+import { pathBreadcrumbSegments } from "../../pure/breadcrumbs.js";
+function withoutQuery(path) {
+  return path.split("?")[0];
+}
+function titleCase(s) {
+  return s.replaceAll("-", " ").replace(/\w\S*/g, (w) => w.charAt(0).toUpperCase() + w.substr(1).toLowerCase());
+}
+export function useBreadcrumbItems(options = {}) {
+  const router = useRouter();
+  const i18n = useI18n();
+  const siteResolver = createSitePathResolver({
+    canonical: true,
+    absolute: true
+  });
+  const siteConfig = useSiteConfig();
+  const items = computed(() => {
+    let rootNode = "/";
+    if (i18n) {
+      if (i18n.strategy === "prefix" || i18n.strategy !== "no_prefix" && toValue(i18n.defaultLocale) !== toValue(i18n.locale))
+        rootNode = `/${toValue(i18n.locale)}`;
+    }
+    const current = withoutQuery(withoutTrailingSlash(toValue(options.path || router.currentRoute.value?.path) || rootNode));
+    const overrides = options.overrides || [];
+    const segments = pathBreadcrumbSegments(current, rootNode).map((path, index) => {
+      let item = {
+        to: path
+      };
+      if (typeof overrides[index] !== "undefined") {
+        if (overrides[index] === false)
+          return false;
+        item = defu(overrides[index], item);
+      }
+      return item;
+    });
+    if (options.prepend)
+      segments.unshift(...options.prepend);
+    if (options.append)
+      segments.push(...options.append);
+    return segments.filter(Boolean).map((item) => {
+      const route = router.resolve(item.to)?.matched?.[0] || router.currentRoute.value;
+      const routeMeta = route?.meta || {};
+      const routeName = route ? String(route.name || route.path) : item.to === "/" ? "index" : "unknown";
+      let [name] = routeName.split("___");
+      if (name === "unknown" || name.includes("/"))
+        name = (item.to || "").split("/").pop() || "";
+      if (routeMeta.breadcrumb) {
+        item = {
+          ...item,
+          ...routeMeta.breadcrumb
+        };
+      }
+      item.label = item.label || routeMeta.breadcrumbTitle || routeMeta.title;
+      if (typeof item.label === "undefined") {
+        item.label = i18n.t(`breadcrumb.items.${name}.label`, name === "index" ? "Home" : titleCase(name), { missingWarn: false });
+      }
+      if (typeof item.ariaLabel === "undefined") {
+        item.ariaLabel = i18n.t(`breadcrumb.items.${name}.ariaLabel`, item.label, { missingWarn: false }) || item.label;
+      }
+      item.current = item.current || item.to === current;
+      if (toValue(options.hideCurrent) && item.current)
+        return false;
+      return item;
+    }).map((m) => {
+      if (m && m.to) {
+        m.to = fixSlashes(siteConfig.trailingSlash, m.to);
+        if (m.to === rootNode && toValue(options.hideRoot))
+          return false;
+      }
+      return m;
+    }).filter(Boolean);
+  });
+  const schemaOrgEnabled = typeof options.schemaOrg === "undefined" ? true : options.schemaOrg;
+  if ((import.meta.dev || import.meta.server) && schemaOrgEnabled) {
+    useSchemaOrg([
+      defineBreadcrumb({
+        id: `#${options.id || "breadcrumb"}`,
+        itemListElement: computed(() => items.value.map((item) => ({
+          name: item.label || item.ariaLabel,
+          item: item.to ? siteResolver(item.to) : void 0
+        })))
+      })
+    ]);
+  }
+  return items;
+}

package/dist/runtime/nuxt/logic/applyDefaults.d.ts

@@ -0,0 +1,4 @@
+import type { Ref } from 'vue';
+export declare function applyDefaults(i18n: {
+    locale: Ref<string>;
+}): void;

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

@@ -0,0 +1,48 @@
+import {
+  computed,
+  createSitePathResolver,
+  useHead,
+  useRoute,
+  useRuntimeConfig,
+  useSeoMeta,
+  useSiteConfig
+} from "#imports";
+import { stringifyQuery } from "ufo";
+export function applyDefaults(i18n) {
+  const { canonicalQueryWhitelist } = useRuntimeConfig().public["nuxt-seo"];
+  const siteConfig = useSiteConfig();
+  const route = useRoute();
+  const resolveUrl = createSitePathResolver({ withBase: true, absolute: true });
+  const canonicalUrl = computed(() => {
+    const { query } = route;
+    const url = resolveUrl(route.path || "/").value || route.path;
+    const filteredQuery = Object.fromEntries(
+      Object.entries(query).filter(([key]) => canonicalQueryWhitelist.includes(key))
+    );
+    return Object.keys(filteredQuery).length ? `${url}?${stringifyQuery(filteredQuery)}` : url;
+  });
+  const minimalPriority = {
+    // give nuxt.config values higher priority
+    tagPriority: 101
+  };
+  useHead({
+    htmlAttrs: { lang: i18n.locale },
+    templateParams: { site: siteConfig, siteName: siteConfig.name || "" },
+    titleTemplate: "%s %separator %siteName",
+    link: [{ rel: "canonical", href: () => canonicalUrl.value }]
+  }, minimalPriority);
+  const seoMeta = {
+    ogType: "website",
+    ogUrl: () => canonicalUrl.value,
+    ogLocale: () => i18n.locale.value,
+    ogSiteName: siteConfig.name
+  };
+  if (siteConfig.description)
+    seoMeta.description = siteConfig.description;
+  if (siteConfig.twitter) {
+    const id = siteConfig.twitter.startsWith("@") ? siteConfig.twitter : `@${siteConfig.twitter}`;
+    seoMeta.twitterCreator = id;
+    seoMeta.twitterSite = id;
+  }
+  useSeoMeta(seoMeta, minimalPriority);
+}

package/dist/runtime/nuxt/plugins/0.routeRules.server.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/nuxt/plugins/0.routeRules.server.js

@@ -0,0 +1,21 @@
+import { useRequestEvent } from "#imports";
+import { unpackMeta } from "@unhead/shared";
+import { injectHead } from "@unhead/vue";
+import { defineNuxtPlugin } from "nuxt/app";
+export default defineNuxtPlugin({
+  enforce: "post",
+  async setup() {
+    const head = injectHead();
+    if (!head)
+      return;
+    const event = useRequestEvent();
+    if (event.context._nitro.routeRules.head)
+      head.push(event.context._nitro.routeRules.head, { mode: "server" });
+    if (event.context._nitro.routeRules.seoMeta) {
+      const meta = unpackMeta({ ...event.context._nitro.routeRules.seoMeta });
+      head.push({
+        meta
+      }, { mode: "server" });
+    }
+  }
+});

package/dist/runtime/nuxt/plugins/1.absoluteImageUrls.server.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/nuxt/plugins/1.absoluteImageUrls.server.js

@@ -0,0 +1,31 @@
+import { createSitePathResolver, unref } from "#imports";
+import { injectHead } from "@unhead/vue";
+import { defineNuxtPlugin } from "nuxt/app";
+export default defineNuxtPlugin({
+  enforce: "post",
+  setup() {
+    const head = injectHead();
+    if (!head)
+      return;
+    const resolver = createSitePathResolver({
+      withBase: true,
+      absolute: true,
+      canonical: true
+    });
+    head.use({
+      hooks: {
+        "tags:resolve": async ({ tags }) => {
+          for (const tag of tags) {
+            if (tag.tag !== "meta")
+              continue;
+            if (tag.props.property !== "og:image:url" && tag.props.property !== "og:image" && tag.props.name !== "twitter:image")
+              continue;
+            if (typeof tag.props.content !== "string" || !tag.props.content.trim() || tag.props.content.startsWith("http") || tag.props.content.startsWith("//"))
+              continue;
+            tag.props.content = unref(resolver(tag.props.content));
+          }
+        }
+      }
+    });
+  }
+});

package/dist/runtime/nuxt/plugins/defaults.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/nuxt/plugins/defaults.js

@@ -0,0 +1,20 @@
+import {
+  defineNuxtPlugin,
+  ref,
+  useSiteConfig
+} from "#imports";
+import { applyDefaults } from "../logic/applyDefaults.js";
+export default defineNuxtPlugin({
+  name: "nuxt-seo:defaults",
+  order: 999,
+  env: {
+    islands: false
+  },
+  setup() {
+    const siteConfig = useSiteConfig();
+    const locale = ref(siteConfig.currentLocale || siteConfig.defaultLocale);
+    applyDefaults({
+      locale
+    });
+  }
+});

package/dist/runtime/nuxt/plugins/defaultsWaitI18n.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/nuxt/plugins/defaultsWaitI18n.js

@@ -0,0 +1,23 @@
+import { defineNuxtPlugin, ref, useSiteConfig } from "#imports";
+import { applyDefaults } from "../logic/applyDefaults.js";
+export default defineNuxtPlugin({
+  name: "nuxt-seo:defaults",
+  env: {
+    islands: false
+  },
+  // we need to wait for the i18n plugin to run first
+  // @ts-expect-error dynamic
+  dependsOn: import.meta.server ? [
+    "nuxt-site-config:i18n"
+  ] : [
+    "i18n:plugin"
+  ],
+  setup(nuxtApp) {
+    const siteConfig = useSiteConfig();
+    const locale = ref(nuxtApp.$i18n?.locale?.value || siteConfig.currentLocale || siteConfig.defaultLocale);
+    nuxtApp.hook("i18n:localeSwitched", ({ newLocale }) => {
+      locale.value = newLocale;
+    });
+    applyDefaults({ locale });
+  }
+});

package/dist/runtime/nuxt/plugins/inferSeoMetaPlugin.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/nuxt/plugins/inferSeoMetaPlugin.js

@@ -0,0 +1,9 @@
+import { InferSeoMetaPlugin } from "@unhead/addons";
+import { injectHead } from "@unhead/vue";
+import { defineNuxtPlugin } from "nuxt/app";
+export default defineNuxtPlugin(() => {
+  const head = injectHead();
+  if (!head)
+    return;
+  head.use(InferSeoMetaPlugin());
+});

package/dist/runtime/nuxt/plugins/siteConfig.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/nuxt/plugins/siteConfig.js

@@ -0,0 +1,30 @@
+import { useSiteConfig } from "#imports";
+import { injectHead } from "@unhead/vue";
+import { defineNuxtPlugin } from "nuxt/app";
+export default defineNuxtPlugin(() => {
+  const head = injectHead();
+  if (!head)
+    return;
+  const siteConfig = useSiteConfig();
+  const input = {
+    meta: [],
+    templateParams: {
+      site: siteConfig,
+      // support legacy
+      siteUrl: siteConfig.url,
+      siteName: siteConfig.name
+    }
+  };
+  if (siteConfig.separator)
+    input.templateParams.separator = siteConfig.separator;
+  if (siteConfig.description) {
+    input.templateParams.siteDescription = siteConfig.description;
+    input.meta.push(
+      {
+        name: "description",
+        content: "%site.description"
+      }
+    );
+  }
+  head.push(input, { tagPriority: 150 });
+});

package/dist/runtime/nuxt/plugins/titles.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/nuxt/plugins/titles.js

@@ -0,0 +1,29 @@
+import {
+  computed,
+  defineNuxtPlugin,
+  useHead,
+  useRoute
+} from "#imports";
+import { titleCase } from "scule";
+import { withoutTrailingSlash } from "ufo";
+export default defineNuxtPlugin({
+  name: "nuxt-seo:fallback-titles",
+  env: {
+    islands: false
+  },
+  setup() {
+    const route = useRoute();
+    const title = computed(() => {
+      if (typeof route.meta?.title === "string")
+        return route.meta?.title;
+      const path = withoutTrailingSlash(route.path || "/");
+      const lastSegment = path.split("/").pop();
+      return lastSegment ? titleCase(lastSegment) : null;
+    });
+    const minimalPriority = {
+      // give nuxt.config values higher priority
+      tagPriority: 101
+    };
+    useHead({ title: () => title.value }, minimalPriority);
+  }
+});

package/dist/runtime/pure/breadcrumbs.d.ts

@@ -0,0 +1 @@
+export declare function pathBreadcrumbSegments(path: string, rootNode?: string): string[];

package/dist/runtime/pure/breadcrumbs.js

@@ -0,0 +1,18 @@
+import { hasTrailingSlash, parseURL, stringifyParsedURL, withTrailingSlash } from "ufo";
+export function pathBreadcrumbSegments(path, rootNode = "/") {
+  const startNode = parseURL(path);
+  const appendsTrailingSlash = hasTrailingSlash(startNode.pathname);
+  const stepNode = (node, nodes = []) => {
+    const fullPath = stringifyParsedURL(node);
+    const currentPathName = node.pathname || "/";
+    nodes.push(fullPath || "/");
+    if (currentPathName !== rootNode && currentPathName !== "/") {
+      node.pathname = currentPathName.substring(0, currentPathName.lastIndexOf("/"));
+      if (appendsTrailingSlash)
+        node.pathname = withTrailingSlash(node.pathname.substring(0, node.pathname.lastIndexOf("/")));
+      stepNode(node, nodes);
+    }
+    return nodes;
+  };
+  return stepNode(startNode).reverse();
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1 @@
+export type { Head, UseSeoMetaInput } from '@unhead/schema';

package/dist/types.d.mts

@@ -0,0 +1 @@
+export { type ModuleOptions, default } from './module.js'

package/dist/types.d.ts

@@ -0,0 +1 @@
+export { type ModuleOptions, default } from './module'

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "nuxt-seo-utils",
+  "type": "module",
+  "version": "5.0.0",
+  "description": "SEO utilities to improve your Nuxt sites discoverability and shareability",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/harlan-zw",
+  "homepage": "https://nuxtseo.com/docs/utils",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harlan-zw/nuxt-seo-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/harlan-zw/nuxt-seo-utils/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/module.mjs",
+      "require": "./dist/module.cjs"
+    }
+  },
+  "main": "./dist/module.cjs",
+  "types": "./dist/types.d.ts",
+  "files": [
+    "dist"
+  ],
+  "build": {
+    "externals": [
+      "@unhead/shared",
+      "unhead"
+    ]
+  },
+  "dependencies": {
+    "@nuxt/kit": "^3.13.2",
+    "@unhead/addons": "^1.11.7",
+    "defu": "^6.1.4",
+    "escape-string-regexp": "^5.0.0",
+    "fast-glob": "^3.3.2",
+    "image-size": "^1.1.1",
+    "nuxt-site-config": "^2.2.18",
+    "nuxt-site-config-kit": "^2.2.18",
+    "pathe": "^1.1.2",
+    "scule": "^1.3.0",
+    "ufo": "^1.5.4"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "3.7.3",
+    "@nuxt/module-builder": "^0.8.4",
+    "@nuxt/test-utils": "^3.14.2",
+    "@nuxt/ui": "^2.18.6",
+    "@nuxtjs/eslint-config-typescript": "^12.1.0",
+    "@nuxtjs/i18n": "^8.5.5",
+    "@unhead/shared": "^1.11.7",
+    "@vue/test-utils": "^2.4.6",
+    "bumpp": "^9.6.1",
+    "case-police": "^0.7.0",
+    "cheerio": "1.0.0",
+    "eslint": "^9.11.1",
+    "happy-dom": "^15.7.4",
+    "markdownlint-cli": "^0.42.0",
+    "nuxt": "^3.13.2",
+    "nuxt-content-twoslash": "^0.1.1",
+    "playwright-core": "^1.47.2",
+    "sass": "^1.79.4",
+    "typescript": "5.6.2",
+    "vitest": "^2.1.2"
+  },
+  "scripts": {
+    "lint": "eslint . --fix",
+    "stub": "nuxt-build-module build --stub && nuxt-module-build prepare",
+    "build": "pnpm stub && nuxt-module-build build",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "pnpm build && bumpp -x \"npx changelogen --output=CHANGELOG.log\" && pnpm publish",
+    "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",
+    "twoslash:verify": "nuxt-content-twoslash verify --content-dir docs/content",
+    "test": "pnpm dev:prepare && vitest --run --exclude **/__runtime__ && pnpm test:runtime",
+    "test:runtime": "cd test/fixtures/basic && vitest --run"
+  }
+}