---
title: "Server-Only Crawler Tags"
description: "Remove eligible crawler tag inputs from client bundles while keeping server metadata."
canonical_url: "https://unhead.unjs.io/docs/head/guides/build-plugins/server-only-crawler-tags"
---

> Index of every page on this site: [llms.txt](https://unhead.unjs.io/llms.txt)

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](https://unhead.unjs.io/docs/head/guides/build-plugins/overview).

```ts [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](https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics#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.

<table>
<thead>
  <tr>
    <th>
      Tag
    </th>
    
    <th>
      <code>
        useHead()
      </code>
    </th>
    
    <th>
      <code>
        useSeoMeta()
      </code>
      
       keys
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Open Graph
    </td>
    
    <td>
      <code>
        meta
      </code>
      
       with <code>
        property
      </code>
      
       or <code>
        name
      </code>
      
       starting <code>
        og:
      </code>
    </td>
    
    <td>
      <code>
        ogTitle
      </code>
      
      , <code>
        ogImage
      </code>
      
      , <code>
        ogDescription
      </code>
      
      , other <code>
        og*
      </code>
      
       keys
    </td>
  </tr>
  
  <tr>
    <td>
      Twitter
    </td>
    
    <td>
      <code>
        meta
      </code>
      
       with <code>
        name
      </code>
      
       or <code>
        property
      </code>
      
       starting <code>
        twitter:
      </code>
    </td>
    
    <td>
      <code>
        twitterCard
      </code>
      
      , <code>
        twitterTitle
      </code>
      
      , other <code>
        twitter*
      </code>
      
       keys
    </td>
  </tr>
  
  <tr>
    <td>
      Article
    </td>
    
    <td>
      <code>
        meta
      </code>
      
       with <code>
        name
      </code>
      
       or <code>
        property
      </code>
      
       starting <code>
        article:
      </code>
    </td>
    
    <td>
      <code>
        articleAuthor
      </code>
      
      , <code>
        articlePublishedTime
      </code>
      
      , other <code>
        article*
      </code>
      
       keys
    </td>
  </tr>
  
  <tr>
    <td>
      Description
    </td>
    
    <td>
      <code>
        meta
      </code>
      
       with <code>
        name
      </code>
      
       or <code>
        property
      </code>
      
       set to <code>
        description
      </code>
    </td>
    
    <td>
      <code>
        description
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Robots
    </td>
    
    <td>
      <code>
        meta
      </code>
      
       with <code>
        name
      </code>
      
       or <code>
        property
      </code>
      
       set to <code>
        robots
      </code>
    </td>
    
    <td>
      <code>
        robots
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Keywords
    </td>
    
    <td>
      <code>
        meta
      </code>
      
       with <code>
        name
      </code>
      
       or <code>
        property
      </code>
      
       set to <code>
        keywords
      </code>
    </td>
    
    <td>
      <code>
        keywords
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Canonical
    </td>
    
    <td>
      <code>
        link
      </code>
      
       with <code>
        rel="canonical"
      </code>
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      Language alternates
    </td>
    
    <td>
      <code>
        link
      </code>
      
       with <code>
        rel="alternate"
      </code>
      
       and <code>
        hreflang
      </code>
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      Structured data
    </td>
    
    <td>
      <code>
        script
      </code>
      
       with <code>
        type="application/ld+json"
      </code>
    </td>
    
    <td>
      none
    </td>
  </tr>
</tbody>
</table>

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()`.

<code-group>

```ts [Before (source)]
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' },
  ],
})
```

```ts [After the crawler tag transform]
useSeoMeta(unheadInstance, {
  title: 'My Page',
})
useHead(unheadInstance, {
  link: [
    { rel: 'stylesheet', href: '/page.css' },
  ],
})
```

</code-group>

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

```ts
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/] },
  },
})
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        importPaths
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      Unset
    </td>
    
    <td>
      Extra import paths for <code>
        useHead()
      </code>
      
       and <code>
        useSeoMeta()
      </code>
      
      . Unhead packages and the Nuxt auto-imports are always read
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        filter
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      inherited
    </td>
    
    <td>
      Replaces the shared build filter. Use <code>
        include
      </code>
      
       for extra file patterns and <code>
        exclude
      </code>
      
       to skip files.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        runtime
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Adds a client filter that keeps client entries from adding or replacing crawler tags.
    </td>
  </tr>
</tbody>
</table>

## 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](https://unhead.unjs.io/docs/head/guides/build-plugins/seo-meta-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](https://unhead.unjs.io/docs/head/guides/build-plugins/tree-shaking).

## Runtime Filter

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

```ts
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.

## Sitemap

See the full [sitemap](https://unhead.unjs.io/sitemap.md) for all pages.
