---
title: Tree-Shaking
description: Automatically remove server-only composables from client bundles at build time.
navigation.title: Tree-Shaking
---

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' })
```

::

::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.
::

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

| Option   | Type     | Default   | Description                                                       |
| -------- | -------- | --------- | ----------------------------------------------------------------- |
| `filter` | `object` | inherited | Include/exclude file patterns (overrides the shared `filter`)     |

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