# @unhead/bundler

> Unhead build-time optimizations for Vite and Webpack.

Latest version **3.4.0** (published 2026-08-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install @unhead/bundler
pnpm add @unhead/bundler
yarn add @unhead/bundler
bun add @unhead/bundler
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.4.0 |
| Published | 2026-08-21 |
| First published | 2026-04-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 1.4 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1306 |
| Author | Harlan Wilton <harlan@harlanzw.com> |
| Maintainers | harlan_zw |

## Links

- npm: https://www.npmjs.com/package/@unhead/bundler
- Repository: https://github.com/unjs/unhead
- Homepage: https://unhead.unjs.io
- Issues: https://github.com/unjs/unhead/issues
- Funding: https://github.com/sponsors/harlan-zw
- npm.io page: https://npm.io/package/@unhead/bundler

## Dependencies (3)

- [unplugin](https://npm.io/package/unplugin.md) ^3.3.0
- [oxc-walker](https://npm.io/package/oxc-walker.md) ^1.1.1
- [magic-string](https://npm.io/package/magic-string.md) ^1.1.0

## Recent versions

- 3.4.0 (latest) — 2026-08-21
- 3.0.0-rc.4 (rc) — 2026-04-09
- 3.0.0-rc.1 (next) — 2026-04-09
- 3.3.2 — 2026-08-13
- 3.3.1 — 2026-08-04
- 3.3.0 — 2026-08-03
- 3.2.3 — 2026-07-22
- 3.2.2 — 2026-07-22
- 3.2.1 — 2026-07-19
- 3.2.0 — 2026-07-19
- 3.1.8 — 2026-07-12
- 3.1.7 — 2026-07-01
- 3.1.6 — 2026-06-25
- 3.1.5 — 2026-06-24
- 3.1.4 — 2026-06-12
- … 11 more at https://npm.io/package/@unhead/bundler/versions

## README

# @unhead/bundler

> Unhead addons for build tools and bundlers

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]

## 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

```bash
# 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:

```bash
# npm
npm install -D oxc-parser

# yarn
yarn add -D oxc-parser

# pnpm
pnpm add -D oxc-parser
```

## Usage

### Vite Plugin

```ts
// 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:

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

### Options

```ts
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:

```ts
// 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:

```ts
// 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](https://unhead.unjs.io/) for more details.

## License

[MIT](./LICENSE)

<!-- Badges -->
[npm-version-src]: https://img.shields.io/npm/v/@unhead/bundler/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
[npm-version-href]: https://npmjs.com/package/@unhead/bundler

[npm-downloads-src]: https://img.shields.io/npm/dm/@unhead/bundler.svg?style=flat&colorA=18181B&colorB=28CF8D
[npm-downloads-href]: https://npmjs.com/package/@unhead/bundler

[license-src]: https://img.shields.io/github/license/unjs/unhead.svg?style=flat&colorA=18181B&colorB=28CF8D
[license-href]: https://github.com/unjs/unhead/blob/main/LICENSE

---
_Source: https://npm.io/package/@unhead/bundler · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._