Validate

The Validate plugin reports non-absolute URLs, missing Open Graph companions, likely meta-property typos, conflicting robots directives, and other head mistakes. It runs only when registered.

Runtime validation

The Validate plugin inspects the final resolved head output and warns about issues that TypeScript can't catch:

• URL problems: Relative canonical or Open Graph URLs, and canonical versus og:url mismatches
• Missing tags: No title, no description on an indexable page, or missing Open Graph companions
• Content issues: Empty meta content, HTML in a title, or unresolved template params
• Conflicts: Contradictory robots directives or accessibility-harmful viewport settings
• Typos: Unknown meta properties or names, with fuzzy-matched suggestions

Setup

Register the plugin where you want head tag validation. It is omitted from builds that do not import it:

import { ValidatePlugin } from 'unhead/plugins'

const head = createHead({
  plugins: [
    ValidatePlugin()
  ]
})

By default, warnings are logged via console.warn. You can provide a custom reporter:

ValidatePlugin({
  onReport(rules) {
    // rules: Array<{ id, message, severity, source?, tag? }>
    for (const rule of rules) {
      const loc = rule.source ? ` (${rule.source})` : ''
      console.warn(`[${rule.id}] ${rule.message}${loc}`)
    }
  }
})

Options

export interface ValidatePluginOptions {
  /**
   * Callback to handle validation results. Receives all rules found per resolve cycle.
   * Defaults to `console.warn` for each rule.
   */
  onReport?: (rules: HeadValidationRule[]) => void
  /** Configure severity and per-rule options. */
  rules?: RulesConfig
  /**
   * Project root path. When set, source locations are displayed as relative paths (e.g., ./src/components/MyPage.vue:42:5).
   */
  root?: string
}

Rules

URL Validity

Google recommends absolute canonical URLs, and the Open Graph URL type is limited to http:// and https:// resources.

Content Quality

Migration and Configuration

twitter:label1, twitter:label2, twitter:data1, and twitter:data2 remain supported for Slack link unfurls.

Input shapes are checked after framework resolvers run. Vue refs, computed values, and computed getters are validated using their resolved values.

Missing Companion Tags

The Open Graph protocol defines the basic object fields and optional structured properties for og:image. og:description and image dimensions are optional in the protocol; the plugin recommends them for more complete link previews but does not treat them as conformance errors.

Conflict Detection

Typo Detection

Typo detection only runs for recognized prefixes (og:, article:, book:, profile:, fb:, twitter:, or standard meta names without a colon). Custom prefixes like custom:foo are ignored.

Performance Hints

These rules encode conservative heuristics rather than universal browser limits. Their underlying browser behavior is documented in the primary references for script loading, preload and CORS request matching, resource hints, early charset declarations, and viewport accessibility.

Rule configuration

Rules can be disabled or have their severity overridden, similar to ESLint's flat config:

ValidatePlugin({
  rules: {
    'missing-description': 'off',
    'viewport-user-scalable': 'off',
    'missing-title': 'info', // downgrade from warn to info
  }
})

Some rules accept an options object as an ESLint-style [severity, options] tuple:

ValidatePlugin({
  rules: {
    'too-many-preloads': ['warn', { max: 10 }],
    'too-many-prefetches': ['info', { max: 100 }],
    'too-many-preconnects': ['warn', { max: 6 }],
    'too-many-fetchpriority-high': ['warn', { max: 3 }],
    'charset-not-early': ['warn', { maxPosition: 5 }],
    'inline-style-size': ['info', { maxKB: 20 }],
    'inline-script-size': ['info', { maxKB: 5 }],
    'meta-beyond-1mb': ['warn', { maxBytes: 512_000 }], // 500KB instead of default 1MB
  }
})

Only rules that support options accept the tuple form, and each rule's options are typed.

Source tracing

Rules associated with a specific tag can include a source field pointing to the head.push() call that introduced it. Cross-tag rules such as a missing title may not have a source. By default, captured sources use absolute paths. Set root to make them relative:

ValidatePlugin({
  root: process.cwd(),
})
// output: [unhead] Canonical URL should be absolute, received "/page". (./src/components/MyPage.vue:42:5)

Framework DevTools integration

The onReport callback receives structured rule objects that you can pass to a UI:

ValidatePlugin({
  onReport(rules) {
    // Example: Nuxt DevTools integration
    for (const rule of rules) {
      devtools.addWarning({
        id: rule.id,
        message: rule.message,
        severity: rule.severity,
        // rule.tag contains the full HeadTag object for inspection
      })
    }
  }
})

Related

• Canonical Plugin: Auto-resolve relative URLs to absolute
• Infer SEO Meta: Auto-generate OG and Twitter meta tags
• useSeoMeta(): Type-safe SEO meta management