feat(core): canonical plugin (#492)

* feat(core): canonical plugin

* doc: title

* chore: broken tests

Author: harlan-zw

Diff for: docs/3.recipes/canonical.md

@@ -0,0 +1,74 @@
+---
+title: "Canonical Plugin"
+description: Fix relative URLs in your meta tags automatically
+---
+
+## Introduction
+
+[Google](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls) requires your canonical URLs to use absolute paths. [Facebook](https://developers.facebook.com/docs/sharing/webmasters/getting-started) and [Twitter](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup) will ignore images without a full URL. This plugin fixes both problems automatically
+when you provide a relative path.
+
+The plugin converts relative paths to absolute URLs in these tags:
+- `og:image` and `twitter:image` meta tags
+- `og:url` meta tag
+- `rel="canonical"` link tag
+
+For example:
+```html
+<!-- Before -->
+<meta property="og:image" content="/images/hero.jpg">
+
+<!-- After -->
+<meta property="og:image" content="https://mysite.com/images/hero.jpg">
+```
+
+## Setup
+
+You should install the plugin in both your server & client entries.
+
+```ts
+import { CanonicalPlugin } from 'unhead/plugins'
+
+const head = createHead({
+  plugins: [
+    CanonicalPlugin({
+      canonicalHost: 'https://mysite.com'
+    })
+  ]
+})
+```
+
+## Configuration
+
+```ts
+interface CanonicalPluginOptions {
+  // Your site's domain (required)
+  canonicalHost?: string
+  // Optional: Custom function to transform URLs
+  customResolver?: (path: string) => string
+}
+```
+
+### Fallback Behavior
+
+If no `canonicalHost` is provided, the plugin will fallback to the window location origin if client side.
+
+For SSR it will just leave the URLs as is.
+
+### Custom URL Resolution
+
+Use `customResolver` to handle the transformation yourself. This function should return a fully qualified URL.
+
+```ts
+CanonicalPlugin({
+  canonicalHost: 'https://mysite.com',
+  customResolver: path => new URL(`/cdn${path}`, 'https://example.com').toString()
+})
+```
+
+This would transform:
+```html
+<meta property="og:image" content="/hero.jpg">
+<!-- to -->
+<meta property="og:image" content="https://mysite.com/cdn/hero.jpg">
+```

Diff for: packages/unhead/src/plugins/canonical.ts

@@ -0,0 +1,63 @@
+import { defineHeadPlugin } from '../utils/defineHeadPlugin'
+
+/**
+ * CanonicalPlugin resolves paths in tags that require a canonical host to be set.
+ *
+ *  - Resolves paths in meta tags like `og:image` and `twitter:image`.
+ *  - Resolves paths in the `og:url` meta tag.
+ *  - Resolves paths in the `link` tag with the `rel="canonical"` attribute.
+ * @example
+ * const plugin = CanonicalPlugin({
+ *   canonicalHost: 'https://example.com',
+ *   customResolver: (path) => `/custom${path}`,
+ * });
+ *
+ * // This plugin will resolve URLs in meta tags like:
+ * // <meta property="og:image" content="/image.jpg">
+ * // to:
+ * // <meta property="og:image" content="https://example.com/image.jpg">
+ */
+export function CanonicalPlugin(options: { canonicalHost?: string, customResolver?: (url: string) => string }) {
+  return defineHeadPlugin((head) => {
+    function resolvePath(path: string) {
+      if (options?.customResolver) {
+        return options.customResolver(path)
+      }
+      let host = options.canonicalHost || (!head.ssr ? (window.location.origin) : '')
+      // handle https if not provided
+      if (!host.startsWith('http') && !host.startsWith('//')) {
+        host = `https://${host}`
+      }
+      // have error thrown if canonicalHost is not a valid URL
+      host = new URL(host).origin
+      if (path.startsWith('http') || path.startsWith('//'))
+        return path
+      try {
+        return new URL(path, host).toString()
+      }
+      catch {
+        return path
+      }
+    }
+    return {
+      key: 'canonical',
+      hooks: {
+        'tags:resolve': (ctx) => {
+          for (const tag of ctx.tags) {
+            if (tag.tag === 'meta') {
+              if (tag.props.property?.startsWith('og:image') || tag.props.name?.startsWith('twitter:image')) {
+                tag.props.content = resolvePath(tag.props.content)
+              }
+              else if (tag.props?.property === 'og:url') {
+                tag.props.content = resolvePath(tag.props.content)
+              }
+            }
+            else if (tag.tag === 'link' && tag.props.rel === 'canonical') {
+              tag.props.href = resolvePath(tag.props.href)
+            }
+          }
+        },
+      },
+    }
+  })
+}

Diff for: packages/unhead/src/plugins/index.ts

@@ -1,3 +1,4 @@
+export { CanonicalPlugin } from './canonical'
 export { DeprecationsPlugin } from './deprecations' // optional
 export { FlatMetaPlugin } from './flatMeta' // optional
 export { InferSeoMetaPlugin } from './inferSeoMetaPlugin' // optional

Diff for: packages/unhead/test/unit/plugins/canonical.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest'
+import { CanonicalPlugin } from '../../../src/plugins/canonical'
+
+describe('canonicalPlugin', () => {
+  it('should resolve og:image URLs correctly', () => {
+    const plugin = CanonicalPlugin({ canonicalHost: 'https://example.com' })({ ssr: false })
+    const ctx = {
+      tags: [
+        { tag: 'meta', props: { property: 'og:image', content: '/image.jpg' } },
+      ],
+    }
+
+    plugin.hooks['tags:resolve'](ctx)
+
+    expect(ctx.tags[0].props.content).toBe('https://example.com/image.jpg')
+  })
+
+  it('should resolve twitter:image URLs correctly', () => {
+    const plugin = CanonicalPlugin({ canonicalHost: 'https://example.com' })({ ssr: false })
+    const ctx = {
+      tags: [
+        { tag: 'meta', props: { name: 'twitter:image', content: '/image.jpg' } },
+      ],
+    }
+
+    plugin.hooks['tags:resolve'](ctx)
+
+    expect(ctx.tags[0].props.content).toBe('https://example.com/image.jpg')
+  })
+
+  it('should resolve og:url URLs correctly', () => {
+    const plugin = CanonicalPlugin({ canonicalHost: 'https://example.com' })({ ssr: false })
+    const ctx = {
+      tags: [
+        { tag: 'meta', props: { property: 'og:url', content: '/page' } },
+      ],
+    }
+
+    plugin.hooks['tags:resolve'](ctx)
+
+    expect(ctx.tags[0].props.content).toBe('https://example.com/page')
+  })
+
+  it('should resolve canonical link URLs correctly', () => {
+    const plugin = CanonicalPlugin({ canonicalHost: 'https://example.com' })({ ssr: false })
+    const ctx = {
+      tags: [
+        { tag: 'link', props: { rel: 'canonical', href: '/page' } },
+      ],
+    }
+
+    plugin.hooks['tags:resolve'](ctx)
+
+    expect(ctx.tags[0].props.href).toBe('https://example.com/page')
+  })
+
+  it('should use custom resolver if provided', () => {
+    const plugin = CanonicalPlugin({
+      canonicalHost: 'https://example.com',
+      customResolver: path => `/custom${path}`,
+    })({ ssr: false })
+    const ctx = {
+      tags: [
+        { tag: 'meta', props: { property: 'og:image', content: '/image.jpg' } },
+      ],
+    }
+
+    plugin.hooks['tags:resolve'](ctx)
+
+    expect(ctx.tags[0].props.content).toBe('/custom/image.jpg')
+  })
+
+  it('should handle already fully qualified URLs', () => {
+    const plugin = CanonicalPlugin({ canonicalHost: 'https://example.com' })({ ssr: false })
+    const ctx = {
+      tags: [
+        { tag: 'meta', props: { property: 'og:image', content: 'https://other.com/image.jpg' } },
+      ],
+    }
+
+    plugin.hooks['tags:resolve'](ctx)
+
+    expect(ctx.tags[0].props.content).toBe('https://other.com/image.jpg')
+  })
+
+  it('should handle canonicalHost without protocol', () => {
+    const plugin = CanonicalPlugin({ canonicalHost: 'example.com' })({ ssr: false })
+    const ctx = {
+      tags: [
+        { tag: 'meta', props: { property: 'og:image', content: '/image.jpg' } },
+      ],
+    }
+
+    plugin.hooks['tags:resolve'](ctx)
+
+    expect(ctx.tags[0].props.content).toBe('https://example.com/image.jpg')
+  })
+})