Bundle Optimizations

On this page

How Do I Add Client-Only Tags?
How Do I Add Server-Only Tags?
Example Use Cases
What Are the Caveats?
See Also

Quick Answer: To reduce bundle size, use import.meta.client to conditionally add tags only on the client. For Vite, use the Unhead Vite plugin to tree-shake server-only code.

Unhead runs on both server and client. You can conditionally render tags in one environment to optimize bundle size.

How Do I Add Client-Only Tags?

Client-only tags render exclusively in the browser, reducing server-side bundle size.

When to Use Client-Only Tags

Analytics scripts (Google Analytics, Plausible, etc.)
User tracking and personalization scripts
Client-side feature detection
Progressive enhancement

Use import.meta.client to conditionally add tags:

import { useHead } from '@unhead/react'

// Using import.meta environment variables
if (import.meta.client) {
  useHead({
    script: [
      {
        src: 'https://example.com/analytics.js',
        defer: true
      }
    ]
  })
}

How Do I Add Server-Only Tags?

Server-only tags render during SSR, reducing client-side bundle size.

When to Use Server-Only Tags

SEO metadata that doesn't need client reactivity
Open Graph images and social media metadata
Static metadata that appears on every page
Schema.org structured data

Use import.meta.server to conditionally add tags:

import { useHead } from '@unhead/react'

if (import.meta.server) {
  useHead({
    meta: [
      {
        property: 'og:image',
        content: 'https://example.com/my-image.jpg'
      }
    ]
  })
}

Example Use Cases

Analytics After Hydration

Load analytics only after the application has hydrated:

import { useHead } from '@unhead/react'

if (import.meta.client) {
  useHead({
    script: [
      {
        src: 'https://example.com/analytics.js',
        defer: true,
        async: true
      }
    ]
  })
}

Static SEO Tags on Server

Add SEO metadata that doesn't need client updates:

import { useHead } from '@unhead/react'

if (import.meta.server) {
  useHead({
    meta: [
      { name: 'robots', content: 'index, follow' },
      { name: 'description', content: 'Site description' }
    ]
  })
}

What Are the Caveats?

Some tags have dependencies that span client and server rendering:

titleTemplate affects title rendering - include on both client and server to avoid title flashing
Tags with tagPosition or tagPriority may behave differently if not consistently applied
Event handlers are only triggered in their respective environments

Ensure dependent tags are included in both environments when needed.