Index of every page on this site: llms.txt
TypeScript
Build Plugins

Server-Only Crawler Tags

Enable serverOnlyCrawlerTags to remove eligible crawler tag inputs from client builds. The option is off by default. Static stripping adds no runtime code.

Setup

Use this option with server rendering or prerendering so each page supplies its crawler tags. In a client-only app, enabling the option removes the tags crawlers need.

In your Vue Vite config, enable the option in the unified Vite plugin.

vite.config.ts
import { Unhead } from '@unhead/vue/vite'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [vue(), Unhead({ serverOnlyCrawlerTags: true })],
})

Why

Some crawlers only read the HTML response. Google Search can also run JavaScript when it renders the page. How Google processes JavaScript

If your app uses these values only for crawlers, the client can omit the inputs. When the transform removes every client use of useSeoMeta(), the bundler can also drop unpackMeta.

Crawler tags

The option targets the tags below. A meta tag's name takes precedence over its property when both specify an identity.

TaguseHead()useSeoMeta() keys
Open Graphmeta with property or name starting og:ogTitle, ogImage, ogDescription, other og* keys
Twittermeta with name or property starting twitter:twitterCard, twitterTitle, other twitter* keys
Articlemeta with name or property starting article:articleAuthor, articlePublishedTime, other article* keys
Descriptionmeta with name or property set to descriptiondescription
Robotsmeta with name or property set to robotsrobots
Keywordsmeta with name or property set to keywordskeywords
Canonicallink with rel="canonical"none
Language alternateslink with rel="alternate" and hreflangnone
Structured datascript with type="application/ld+json"none

The option leaves other tags in client entries. These include the title, titleTemplate, HTML and body attributes, styles, regular scripts, stylesheets, and icons. Browser metadata such as theme-color, color-scheme, and viewport also stays.

This example shows the code after the crawler tag transform. The useSeoMeta() transform can then turn the remaining call into useHead().

useSeoMeta(unheadInstance, {
  title: 'My Page',
  description: 'My description',
  ogTitle: 'My Page',
  ogImage: () => post.value.image,
  twitterCard: 'summary_large_image',
})
useHead(unheadInstance, {
  link: [
    { rel: 'canonical', href: 'https://example.com/my-page' },
    { rel: 'stylesheet', href: '/page.css' },
  ],
})

The transform can remove a standalone call that has no input left. If other code uses the result, the call stays with an empty input. The call also stays if its options may provide an onRendered callback.

Options

Unhead({
  serverOnlyCrawlerTags: {
    // Other modules that export useHead() or useSeoMeta()
    importPaths: ['#my-head'],
    // Override the shared file filter for this transform only
    filter: { exclude: [/keep-crawler-tags/] },
  },
})
OptionTypeDefaultDescription
importPathsstring[]UnsetExtra import paths for useHead() and useSeoMeta(). Unhead packages and the Nuxt auto-imports are always read
filterobjectinheritedReplaces the shared build filter. Use include for extra file patterns and exclude to skip files.
runtimebooleanfalseAdds a client filter that keeps client entries from adding or replacing crawler tags.

What changes on the client

  • Server builds keep crawler tag inputs.
  • During hydration, server tags stay in place if client entries leave them alone.
  • A client entry can supply a fallback for a tag you stripped. Check the hydrated head if your app registers crawler tags in multiple entries.
  • After client navigation, stripped tags can keep the initial page's values. Titles, attributes, styles, and regular scripts can still update.

If client code needs fresh crawler tags after navigation, keep the inputs it uses. For example, a share button may read og:url from the DOM. Use filter.exclude to keep the relevant inputs and leave runtime off.

Streaming SSR

Enable serverOnlyCrawlerTags alongside streaming with the async, inline, or module bootstrap. The client applies crawler tags from later server chunks. With runtime: true, the filter lets those server updates through.

If a crawler needs metadata in the HTML response before JavaScript runs, include those tags in the initial HTML shell. The browser applies late head updates with JavaScript.

If you enable the runtime filter, use different keys for streamed JSON-LD and client scripts. A shared key can combine the scripts into a tag that the filter drops.

Limitations

The transform removes inputs it can analyze at build time.

  • An input object literal, or a getter that returns one: useHead(() => ({ ... })).
  • A tag with a static identity such as name: 'description'. For a meta tag, the transform checks name or property. For a link, it checks rel and uses hreflang for alternates. For a script, it checks type. Tags with a spread or a dynamic identity stay in the bundle.
  • A tag value that the client can evaluate without running your code. Literals, variables, and getters such as () => post.value.title qualify. Vue's computed(), ref(), and shallowRef() qualify with a literal or function argument. Use JSON.stringify() only with literals that JSON can represent.

A pure reactive read is safe to remove if its value only feeds a crawler tag. The transform keeps reads such as post.value.title because a getter may have side effects.

Calls such as ref(page), t(), and toValue() can run your code. A template literal with a variable can call toString(). If the client can skip evaluating a value, pass a getter such as () => post.value.title. The transform can then remove the getter without running its body.

Dynamic inputs stay in the client bundle. These include useHead(input), head.push(), and entry.patch().

If a retained input can emit the same meta tag, the transform keeps its static counterpart in the same call. This covers aliases such as ogImage and ogImageUrl.

How It Works

The transform runs on client builds only, before the useSeoMeta transform. It finds useHead(), useHeadSafe(), and useSeoMeta() calls imported from Unhead packages, or auto-imported, and removes crawler tags from their input. For a core composable imported from unhead, the input is the second argument: useHead(head, input). A useSeoMeta() call it simplifies can then become a plain useHead() call.

Webpack and Rspack support target: 'web', including a syntax target such as ['web', 'es2020']. Use a Browserslist target with the client compiler only if every target is a browser. Builds named server and builds without a recognised browser target keep the original code. This includes plain Rollup builds.

The transform scans JavaScript, TypeScript, and Vue script modules. In Svelte, put calls you want transformed in JavaScript or TypeScript modules.

Both parts skip the Vite dev server, like tree-shaking.

Runtime Filter

If dynamic client entries must leave crawler tags to the server, enable the runtime filter.

Unhead({ serverOnlyCrawlerTags: { runtime: true } })

The build registers ServerOnlyCrawlerTagsPlugin through calls to createHead() and createStreamableHead() from Unhead's client entry points. The filter starts before configured plugins can push tags during setup. It removes crawler tags from client entries before duplicate resolution. It also filters resolved client tags. Hooks that run after the filter can still add crawler tags.

The filter adds client code even if the build strips every static crawler tag input. It also applies to entries from files excluded from the build transform.

Automatic registration imports unhead/plugins. If your package manager requires direct dependencies for imports, declare unhead in the app that calls the streaming factory.

Register the plugin yourself if you call a head factory through a variable, local re-export, or dynamic import. The same applies to calls with spread arguments, such as createHead(...args) and createStreamableHead(...args).

Import ServerOnlyCrawlerTagsPlugin from unhead/plugins. If the factory accepts a plugins option, put the filter first in that array. This lets it filter tags pushed by other plugins during setup and by init entries.

If you register the plugin on an existing head with head.use(ServerOnlyCrawlerTagsPlugin), do so before it renders client tags. A bare createUnhead() needs a client adapter that provides hooks.

When the build wraps a head factory, pass document and init directly in the options object. The wrapper can drop options inherited from a prototype.

Did this page help you?