@unhead/bundler

Unhead addons for build tools and bundlers

Features

• 🛠️ Build-time optimizations for Unhead
• 🎯 Transpile static inline scripts to Vite's configured browser target
• 🌲 Tree-shake server composables from client bundles
• ⚡ Transform useSeoMeta calls for better performance
• 📦 Support for Vite, Webpack, and other bundlers

Installation

# npm
npm install @unhead/bundler

# yarn
yarn add @unhead/bundler

# pnpm
pnpm add @unhead/bundler

The build transforms need a parser. If Rolldown is installed, Unhead reuses rolldown/utils. Vite 8 includes Rolldown. For Vite 6 or 7 and other bundlers, install the Oxc fallback:

# npm
npm install -D oxc-parser

# yarn
yarn add -D oxc-parser

# pnpm
pnpm add -D oxc-parser

Usage

Vite Plugin

// vite.config.ts
import { defineConfig } from 'vite'
import { Unhead } from '@unhead/bundler/vite'

export default defineConfig({
  plugins: [
    Unhead({
      // Options
    })
  ]
})

To use the Unhead panel in Vite DevTools, install its optional development packages:

pnpm add -D @vitejs/devtools @vitejs/devtools-kit

Options

interface UnpluginOptions {
  // Tree-shake server-only composables from client bundles
  treeshakeServerComposables?: boolean | TreeshakeServerComposablesOptions

  // Transform useSeoMeta calls for better performance
  useSeoMetaTransform?: boolean | UseSeoMetaTransformOptions

  // Vite: transpile static inline scripts to build.target (enabled by default)
  transformInlineScripts?: false | { target?: string | string[] | false }
}

Build Optimizations

Tree-shake Server Composables

Automatically removes server-only Unhead composables from client bundles:

// Before (in client bundle):
import { useServerHead } from '@unhead/vue'

useServerHead({ /* ... */ })

// After (removed from client bundle):
// (code is completely removed)

SEO Meta Transform

Optimizes useSeoMeta calls for better performance:

// Before:
useSeoMeta({
  title: 'My Page',
  description: 'Page description'
})

// After (optimized):
useHead({
  title: 'My Page',
  meta: [{ name: 'description', content: 'Page description' }]
})

Documentation

Visit the Unhead documentation for more details.

License

MIT