---
title: "Tree-Shaking"
description: "Automatically remove server-only composables from client bundles at build time."
canonical_url: "https://unhead.unjs.io/docs/head/guides/build-plugins/tree-shaking"
last_updated: "2026-06-30T06:50:22.844Z"
---

**Quick Answer:** The tree-shaking transform strips deprecated server composables and `useSchemaOrg` calls from client bundles so they never ship to the browser. Enabled by default.

## What Does It Do?

This transform removes calls to composables that should only run on the server. On client builds these calls are dead code; removing them reduces bundle size.

Composables removed from client bundles:

- `useServerHead()` (deprecated, use `useHead()`)
- `useServerHeadSafe()` (deprecated, use `useHeadSafe()`)
- `useServerSeoMeta()` (deprecated, use `useSeoMeta()`)
- `useSchemaOrg()`

<code-group>

```ts [Before (source)]
useHead({ title: 'My Page' })

useSchemaOrg([
  defineWebPage({ name: 'My Page' }),
])
```

```ts [After (client build)]
useHead({ title: 'My Page' })
```

</code-group>

<callout type="info">

`useServerHead`, `useServerHeadSafe`, and `useServerSeoMeta` are deprecated aliases. They exist for backwards compatibility and are identical to their non-server counterparts. New code should use `useHead`, `useHeadSafe`, and `useSeoMeta` directly. The tree-shaking transform still removes calls to the deprecated names for codebases that haven't migrated yet.

</callout>

The transform only runs on client builds. SSR builds are left untouched.

## Setup

Tree-shaking is enabled by default when using the [unified Vite plugin](/docs/head/guides/build-plugins/overview):

```ts
import { Unhead } from '@unhead/vue/vite'

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

### Disable

```ts
Unhead({
  treeshake: false,
})
```

## Options

```ts
Unhead({
  treeshake: {
    // Override the shared file filter for this transform only
    filter: {
      include: [/my-special-file/],
      exclude: [/some-file/],
    },
  },
})
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        filter
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      inherited
    </td>
    
    <td>
      Include/exclude file patterns (overrides the shared <code>
        filter
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## How It Works

The transform parses each file with [oxc-parser](https://github.com/nicolo-ribaudo/oxc-parser/tree/nicolo/oxc-parser) and walks the AST looking for `ExpressionStatement` nodes that call one of the server composable names. Matching statements are removed from the source using [magic-string](https://github.com/Rich-Harris/magic-string), preserving sourcemaps.