---
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-08-11T00:43:40.640Z"
---

The tree-shaking transform removes standalone calls to deprecated server composables and `useSchemaOrg` from client builds. It is enabled by default.

## Removed calls

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 backward 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. It removes standalone call statements; a call used as part of an assignment or larger expression is retained.

## 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 and walks the AST for standalone calls to the server composable names. It recognizes calls imported from Unhead packages and unbound auto-imported names, but leaves locally declared functions with the same names alone. Matching statements are removed while preserving sourcemaps.