---
title: useServerHead()
description: Learn about server-only head tags and modern alternatives
deprecated: true
---
::warning
**DEPRECATED:** All `useServer*` composables (including `useServerHead`, `useServerSeoMeta`, etc.) are deprecated.
Use `useHead()`{lang="ts"} with `import.meta.server` conditionals instead, as described in the [Bundle Optimizations](/docs/head/guides/advanced/client-only-tags) guide.
::
## Modern Alternative
Instead of using the deprecated `useServerHead`, use the `useHead()`{lang="ts"} composable with environment conditionals:
```ts
import { useHead } from '@unhead/dynamic-import'
// Only runs on the server
if (import.meta.server) {
useHead({
title: 'My Page',
meta: [
{
name: 'description',
content: 'My page description',
},
],
})
}
```
Or use the `mode` option for more declarative code:
```ts
import { useHead } from '@unhead/dynamic-import'
useHead({
title: 'My Page',
meta: [
{
name: 'description',
content: 'My page description',
},
],
}, { mode: 'server' })
```
For a complete guide on optimizing your bundle with server and client-only tags, see the [Bundle Optimizations](/docs/head/guides/advanced/client-only-tags) guide.
## Use Cases for Server-Only Tags
Server-only tags are beneficial in several scenarios:
1. **Performance optimization**: Reduces client-side JavaScript bundle size
2. **SEO focus**: Most search engines only read the initial HTML response
3. **Server-specific resources**: Enables use of tags with values only available during server rendering
## Safe Usage with Untrusted Data
When working with user-generated content, use the `safe` option to ensure proper sanitization:
```ts
import { useHead } from '@unhead/dynamic-import'
useHead({
title: userProvidedTitle,
meta: [
{
name: 'description',
content: userProvidedDescription,
},
],
}, {
mode: 'server',
// Enable sanitization for user-provided content
safe: true
})
```
## Tree Shaking
Server-only tags can be tree-shaken from your client bundle in most frameworks when using the recommended approach:
- **Import.meta conditionals**: Code inside `if (import.meta.server)` blocks is automatically tree-shaken
- **Mode option**: When using `{ mode: 'server' }`, most bundlers can optimize this
- **Additional optimization**: Use the [Unhead Vite Plugin](/docs/head/guides/advanced/vite-plugin) for enhanced tree-shaking
## Important Considerations
### No Lifecycle Events
Server-rendered tags do not have lifecycle events. If you use server-rendered tags on a specific page, they **won't be automatically removed** when navigating away from that page.
### Tag Persistence
Consider this example:
```ts
// pages/about.vue
if (import.meta.server) {
useHead({
meta: [
{
name: 'description',
content: 'About page description',
},
],
})
}
```
When this page is server-rendered, the meta tag is included in the HTML. However, when you navigate from `/about` to another page, the tag will remain in the document `<head>` because there's no client-side code to remove it.
### Solutions for Tag Management
To manage server-rendered tags effectively:
1. **Add keys to all tags**: Use the `key` property to enable replacement
2. **Use in app root only**: Place server-only tags in root components for app-wide metadata
3. **Manual cleanup**: Register empty tags with matching keys on other pages to remove them
4. **Prefer client tags**: Use regular `useHead()`{lang="ts"} without mode restrictions for page-specific tags that need to change with navigation
## Working Example: Managing Page-Specific Scripts
This pattern demonstrates how to add a page-specific script and properly remove it when navigating away:
```ts
// pages/about.vue
import { useHead } from '@unhead/dynamic-import'
if (import.meta.server) {
useHead({
script: [
{
src: await import('~/assets/js/about.js?url'),
key: 'page-script'
}
]
})
}
```
```ts
// pages/contact.vue
import { useHead } from '@unhead/dynamic-import'
useHead({
script: [
{
// This removes the script when navigating to this page
key: 'page-script'
}
]
})
```
## Best Practices
- Use server-only tags primarily for static metadata that doesn't change between pages
- Always add keys to server-rendered tags that might need to be replaced later
- Use `useHead()`{lang="ts"} with environment conditionals instead of legacy `useServer*` composables
- Test navigation flows to ensure proper tag management
For complete documentation on bundle optimization strategies, see the [Bundle Optimizations](/docs/head/guides/advanced/client-only-tags) guide.