Build Optimization Plugins

Quick Answer: The Unhead Vite plugin enables build-time optimizations like tree-shaking server-only code and transforming useSeoMeta() for smaller bundles. Install with UnheadVite() in your Vite config.

What Do the Build Plugins Do?

Unhead provides official build plugins for Vite and Webpack that help optimize your application bundle size through automatic transformations and optimizations.

While these plugins are optional, they're highly recommended for production applications to ensure optimal performance and bundle size.

The build plugins perform several important optimizations:

• Transform useSeoMeta calls into raw useHead() calls (~3kb savings)
• Apply tree-shaking optimizations specific to Unhead

How Do I Install the Build Plugins?

First, install the addons package that contains the build plugins:

pnpm add -D @unhead/addons

yarn add -D @unhead/addons

npm install -D @unhead/addons

How Do I Configure the Plugin?

Vite

Add the Unhead Vite plugin to your vite.config.ts file:

import UnheadVite from '@unhead/addons/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnheadVite(),
  ],
})

Webpack

Add the Unhead Webpack plugin to your webpack configuration:

import { UnheadWebpack } from '@unhead/addons/webpack'

export default {
  plugins: [
    UnheadWebpack(),
  ],
}

What Options Are Available?

The build plugins accept configuration options to customize their behavior:

UnheadVite({
  // Options here
})

How Do I Verify the Plugin Is Working?

To verify that the plugin is working correctly, you can:

1. Check your production bundle size before and after adding the plugin
2. Inspect the transformed code in your build output
3. Monitor client-side performance metrics

How Do I Use With Different Frameworks?

When using Unhead with a framework, make sure to add the plugin to your build configuration:

// No configuration needed - Nuxt configures the plugin automatically

import UnheadVite from '@unhead/addons/vite'
// vite.config.ts
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [
    vue(),
    UnheadVite(),
  ],
}

import UnheadVite from '@unhead/addons/vite'
// vite.config.ts
import react from '@vitejs/plugin-react'

export default {
  plugins: [
    react(),
    UnheadVite(),
  ],
}

Can I Disable Specific Transformations?

You can customize the plugin's behavior based on your needs:

UnheadVite({
  // Disable useSeoMeta transformation if you prefer to keep it
  transformSeoMeta: false,
})

What Are Best Practices?

Why Isn't It Working?

See Also

• Bundle Optimizations - Client-only tags
• Template Params - Dynamic parameters
• useHead() API - Full API reference