Bundle Optimizations

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'

// 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'

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'

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'

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

What Are the Caveats?

Ensure dependent tags are included in both environments when needed.

See Also

• Tag Positions - Control tag placement
• Vite Plugin - Build-time optimizations
• useHead() API - Full API reference