Build Optimization Plugins

Introduction

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.

Key Optimizations

The build plugins perform several important optimizations:

• Remove server-only composables from client builds (useServerHead, useServerSeoMeta)
• Transform useSeoMeta calls into raw useHead() calls (~3kb savings)
• Apply tree-shaking optimizations specific to Unhead

Installation

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

Configuration

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(),
  ],
}

Plugin Options

The build plugins accept configuration options to customize their behavior:

UnheadVite({
  // Options here
})

Available Options

Verifying Optimizations

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

Common Use Cases

Framework Integration

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(),
  ],
}

Custom Transformations

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

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

Best Practices

Troubleshooting