Build Optimization Plugins · Unhead

[Unhead Home](https://unhead.unjs.io/ "Home")

- [Docs](https://unhead.unjs.io/docs/svelte/head/guides/get-started/overview)
- [Tools](https://unhead.unjs.io/tools)
- [Learn](https://unhead.unjs.io/learn/guides/what-is-capo)

[Releases](https://unhead.unjs.io/releases)

Search…```k`` /`

[Unhead on GitHub](https://github.com/unjs/unhead)

[User Guides](https://unhead.unjs.io/docs/svelte/head/guides/get-started/overview)

[API](https://unhead.unjs.io/docs/svelte/head/api/get-started/overview)

Svelte

- [Switch to Svelte](https://unhead.unjs.io/docs/svelte/head/guides/advanced/vite-plugin)
- [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/head/guides/advanced/vite-plugin)
- [Switch to Vue](https://unhead.unjs.io/docs/vue/head/guides/advanced/vite-plugin)
- [Switch to React](https://unhead.unjs.io/docs/react/head/guides/advanced/vite-plugin)
- [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/head/guides/advanced/vite-plugin)
- [Switch to Angular](https://unhead.unjs.io/docs/angular/head/guides/advanced/vite-plugin)
- [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/head/guides/advanced/vite-plugin)

v3 (beta)

You're viewing **Unhead v3 beta** documentation.

Head

- [Discord Support](https://discord.com/invite/275MBUBvgP)
- [Svelte Playground](https://stackblitz.com/edit/github-ckbygkxk)

- Get Started
  - [Overview](https://unhead.unjs.io/docs/svelte/head/guides/get-started/overview)
  - [Introduction to Unhead](https://unhead.unjs.io/docs/svelte/head/guides/get-started/intro-to-unhead)
  - [Starter Recipes](https://unhead.unjs.io/docs/svelte/head/guides/get-started/starter-recipes)
  - [Installation](https://unhead.unjs.io/docs/svelte/head/guides/get-started/installation)
  - [Upgrade Guide](https://unhead.unjs.io/docs/svelte/head/guides/get-started/migration)
- Core Concepts
  - [Titles & Title Templates](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/titles)
  - [Tag Sorting & Placement](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/positions)
  - [Class & Style Attributes](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/class-attr)
  - [Inline Style & Scripts](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/inner-content)
  - [Tag Deduplication](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/handling-duplicates)
  - [DOM Event Handling](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/dom-event-handling)
  - [Script Loading](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/loading-scripts)
  - [Reactivity](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/reactivity)
  - [StreamingNew](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/streaming)
- Advanced
  - [Extending Unhead](https://unhead.unjs.io/docs/svelte/head/guides/advanced/extending-unhead)
  - [Bundle Optimizations](https://unhead.unjs.io/docs/svelte/head/guides/advanced/client-only-tags)
  - [Build Plugins](https://unhead.unjs.io/docs/svelte/head/guides/advanced/vite-plugin)
- Plugins
  - [Template Params](https://unhead.unjs.io/docs/svelte/head/guides/plugins/template-params)
  - [Alias Sorting](https://unhead.unjs.io/docs/svelte/head/guides/plugins/alias-sorting)
  - [Canonical Plugin](https://unhead.unjs.io/docs/svelte/head/guides/plugins/canonical)
  - [Infer SEO Meta](https://unhead.unjs.io/docs/svelte/head/guides/plugins/infer-seo-meta-tags)
  - [Validate](https://unhead.unjs.io/docs/svelte/head/guides/plugins/validate)

Advanced

# Build Optimization Plugins

[Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/1.guides/2.advanced/9.vite-plugin.md)

Last updated Apr 5, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [feat: add `MinifyPlugin` for inline script/style minification (#705)](https://github.com/unjs/unhead/pull/705).

On this page

- [What Do the Build Plugins Do?](#what-do-the-build-plugins-do)
- [How Do I Install the Build Plugins?](#how-do-i-install-the-build-plugins)
- [How Do I Configure the Plugin?](#how-do-i-configure-the-plugin)
- [What Options Are Available?](#what-options-are-available)
- [How Do I Verify the Plugin Is Working?](#how-do-i-verify-the-plugin-is-working)
- [How Do I Use With Different Frameworks?](#how-do-i-use-with-different-frameworks)
- [What Are Best Practices?](#what-are-best-practices)
- [Why Isn't It Working?](#why-isnt-it-working)
- [See Also](#see-also)

**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?](#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?](#how-do-i-install-the-build-plugins)

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

pnpm

yarn

npm

```
pnpm add -D @unhead/addons
```

```
yarn add -D @unhead/addons
```

```
npm install -D @unhead/addons
```

## [How Do I Configure the Plugin?](#how-do-i-configure-the-plugin)

### [Vite](#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](#webpack)

Add the Unhead Webpack plugin to your webpack configuration:

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

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

## [What Options Are Available?](#what-options-are-available)

The build plugins accept configuration options to customize their behavior:

```
UnheadVite({
  // Options here
})
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `transformSeoMeta` | `boolean` | `true` | Transform `useSeoMeta` calls to `useHead()` |

## [How Do I Verify the Plugin Is Working?](#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?](#how-do-i-use-with-different-frameworks)

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

Nuxt (automatic)

Vue

React

```
// 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?](#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?](#what-are-best-practices)

- Add the plugin early in your development process
- Keep the default options for most use cases
- Add the plugin fairly late in your plugin chain to ensure it can transform all Unhead code
- Verify bundle size improvements after adding the plugin

## [Why Isn't It Working?](#why-isnt-it-working)

- If optimizations aren't applied, check that the plugin is correctly configured
- If you see unexpected behavior, try disabling specific optimizations
- For framework-specific issues, check the framework documentation for Unhead integration

## [See Also](#see-also)

- [Bundle Optimizations](https://unhead.unjs.io/docs/head/guides/advanced/client-only-tags) - Client-only tags
- [Template Params](https://unhead.unjs.io/docs/head/guides/plugins/template-params) - Dynamic parameters
- [useHead() API](https://unhead.unjs.io/docs/head/api/composables/use-head) - Full API reference

[Edit this page](https://github.com/unjs/unhead/edit/main/docs/head/1.guides/2.advanced/9.vite-plugin.md)

[Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/1.guides/2.advanced/9.vite-plugin.md)

Did this page help you?

[Bundle Optimizations Reduce bundle size with client-only and server-only tags. Use mode option or import.meta guards for SSR/CSR optimization.](https://unhead.unjs.io/docs/head/guides/advanced/client-only-tags) [Template Params Dynamic placeholders like %s and %siteName in head tags. Define site name, separator, and custom variables for consistent branding.](https://unhead.unjs.io/docs/head/guides/plugins/template-params)

On this page

- [What Do the Build Plugins Do?](#what-do-the-build-plugins-do)
- [How Do I Install the Build Plugins?](#how-do-i-install-the-build-plugins)
- [How Do I Configure the Plugin?](#how-do-i-configure-the-plugin)
- [What Options Are Available?](#what-options-are-available)
- [How Do I Verify the Plugin Is Working?](#how-do-i-verify-the-plugin-is-working)
- [How Do I Use With Different Frameworks?](#how-do-i-use-with-different-frameworks)
- [What Are Best Practices?](#what-are-best-practices)
- [Why Isn't It Working?](#why-isnt-it-working)
- [See Also](#see-also)

[GitHub](https://github.com/unjs/unhead) [ Discord](https://discord.com/invite/275MBUBvgP)

[ /llms.txt](https://unhead.unjs.io/llms.txt)

[Part of the UnJS ecosystem](https://unjs.io/)

### Articles

- [Announcing Unhead v2](https://unhead.unjs.io/v2)

### Tools

- [Meta Tag Generator](https://unhead.unjs.io/tools/meta-tag-generator)
- [OG Image Generator](https://unhead.unjs.io/tools/og-image-generator)
- [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator)

### Head

- [Overview](https://unhead.unjs.io/docs/svelte/head/guides/get-started/overview)
- [Introduction to Unhead](https://unhead.unjs.io/docs/svelte/head/guides/get-started/intro-to-unhead)
- [Starter Recipes](https://unhead.unjs.io/docs/svelte/head/guides/get-started/starter-recipes)

### Schema.org

- [Introduction](https://unhead.unjs.io/docs/svelte/schema-org/guides/get-started/overview)

Copyright © 2025-2026 Harlan Wilton - [MIT License](https://github.com/unjs/unhead/blob/main/license)