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()

useHead(unheadInstance, { title: 'My Page' })

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

useHead(unheadInstance, { title: 'My Page' })

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:

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

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

Disable

Unhead({
  treeshake: false,
})

Options

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

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.