Nuxt/docs/1.getting-started/5.seo-meta.md

328 lines
8.8 KiB
Markdown
Raw Normal View History

---
navigation.icon: uil:file-search-alt
description: Improve your Nuxt app's SEO with powerful head config, composables and components.
---
# SEO and Meta
Improve your Nuxt app's SEO with powerful head config, composables and components.
2023-03-14 14:24:41 +00:00
## Defaults
Out-of-the-box, Nuxt provides sane defaults, which you can override if needed.
- `charset`: `utf-8`
- `viewport`: `width=device-width, initial-scale=1`
2023-03-14 14:24:41 +00:00
```ts [nuxt.config.ts]
export default defineNuxtConfig({
app: {
head: {
2023-03-14 14:24:41 +00:00
charset: 'utf-8',
viewport: 'width=device-width, initial-scale=1',
}
}
})
```
2023-03-14 14:24:41 +00:00
Providing an [`app.head`](/docs/api/configuration/nuxt-config#head) property in your [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt.config) allows you to customize the head for your entire app.
::alert{type=info}
This method does not allow you to provide reactive data. We recommend to use `useHead()` in `app.vue`.
::
2023-03-14 14:24:41 +00:00
Shortcuts are available to make configuration easier: `charset` and `viewport`. You can also provide any of the keys listed below in [Types](#types).
## `useHead`
The `useHead` composable function allows you to manage your head tags in a programmatic and reactive way,
powered by [Unhead](https://unhead.harlanzw.com/).
As with all composables, it can only be used with a components `setup` and lifecycle hooks.
2023-03-14 14:24:41 +00:00
```vue [app.vue]
<script setup lang="ts">
useHead({
title: 'My App',
meta: [
{ name: 'description', content: 'My amazing site.' }
],
bodyAttrs: {
class: 'test'
},
script: [ { innerHTML: 'console.log(\'Hello world\')' } ]
})
</script>
```
2023-03-14 14:24:41 +00:00
We recommend to take a look at the [`useHead`](/docs/api/composables/use-head) and [`useHeadSafe`](/docs/api/composables/use-head-safe) composables.
2023-03-14 14:24:41 +00:00
## `useSeoMeta`
The `useSeoMeta` and `useServerSeoMeta` composables let you define your site's SEO meta tags as a flat object with full TypeScript support.
This helps you avoid typos and common mistakes, such as using `name` instead of `property`.
In most instances, the meta does not need to be reactive as robots will only scan the initial load. So we recommend using `useServerSeoMeta` as a performance-focused utility that will not do anything (or return a `head` object) on the client.
2023-03-14 14:24:41 +00:00
**Simple example:**
2023-03-14 14:24:41 +00:00
```vue [app.vue]
<script setup lang="ts">
useServerSeoMeta({
title: 'My Amazing Site',
ogTitle: 'My Amazing Site',
description: 'This is my amazing site, let me tell you all about it.',
ogDescription: 'This is my amazing site, let me tell you all about it.',
ogImage: 'https://example.com/image.png',
twitterCard: 'summary_large_image',
})
</script>
```
2023-03-14 14:24:41 +00:00
**Reactive example:**
When inserting tags that are reactive, you should use the computed getter syntax (`() => value`):
2023-03-14 14:24:41 +00:00
```vue [app.vue]
<script setup lang="ts">
const title = ref('My title')
useSeoMeta({
title,
description: () => `description: ${title.value}`
})
</script>
```
2023-03-14 14:24:41 +00:00
Read more on the [`useSeoMeta`](https://unhead.harlanzw.com/guide/composables/use-seo-meta) composable.
## Components
Nuxt provides `<Title>`, `<Base>`, `<NoScript>`, `<Style>`, `<Meta>`, `<Link>`, `<Body>`, `<Html>` and `<Head>` components so that you can interact directly with your metadata within your component's template.
Because these component names match native HTML elements, it is very important that they are capitalized in the template.
`<Head>` and `<Body>` can accept nested meta tags (for aesthetic reasons) but this has no effect on _where_ the nested meta tags are rendered in the final HTML.
<!-- @case-police-ignore html -->
2023-03-14 14:24:41 +00:00
```vue [app.vue]
<script setup>
const title = ref('Hello World')
</script>
<template>
<div>
<Head>
<Title>{{ title }}</Title>
<Meta name="description" :content="title" />
<Style type="text/css" children="body { background-color: green; }" />
</Head>
<h1>{{ title }}</h1>
</div>
</template>
```
## Types
The below is the non-reactive types used for `useHead`, `app.head` and components.
```ts
interface MetaObject {
title?: string
titleTemplate?: string | ((title?: string) => string)
templateParams?: Record<string, string | Record<string, string>>
base?: Base
link?: Link[]
meta?: Meta[]
style?: Style[]
script?: Script[]
noscript?: Noscript[];
htmlAttrs?: HtmlAttributes;
bodyAttrs?: BodyAttributes;
}
```
See [@unhead/schema](https://github.com/unjs/unhead/blob/main/packages/schema/src/schema.ts) for more detailed types.
## Features
### Reactivity
Reactivity is supported on all properties, as computed, getters and reactive.
It's recommended to use getters (`() => value`) over computed (`computed(() => value)`).
::code-group
```vue [useHead]
<script setup lang="ts">
const description = ref('My amazing site.')
useHead({
meta: [
{ name: 'description', content: description }
],
})
</script>
```
```vue [useSeoMeta]
<script setup lang="ts">
2023-03-18 06:53:54 +00:00
const description = ref('My amazing site.')
useSeoMeta({
description
})
</script>
```
```vue [Components]
<script setup>
const description = ref('My amazing site.')
</script>
<template>
<div>
<Meta name="description" :content="description" />
</div>
</template>
```
::
2023-03-14 14:24:41 +00:00
### Title Template
You can use the `titleTemplate` option to provide a dynamic template for customizing the title of your site. for example, by adding the name of your site to the title of every page.
The `titleTemplate` can either be a string, where `%s` is replaced with the title, or a function.
If you want to use a function (for full control), then this cannot be set in your `nuxt.config`, and it is recommended instead to set it within your `app.vue` file, where it will apply to all pages on your site:
::code-group
```vue [useHead]
<script setup lang="ts">
useHead({
titleTemplate: (titleChunk) => {
return titleChunk ? `${titleChunk} - Site Title` : 'Site Title';
}
})
</script>
```
::
Now, if you set the title to `My Page` with `useHead` on another page of your site, the title would appear as 'My Page - Site Title' in the browser tab. You could also pass `null` to default to the site title.
### Body Tags
You can use the `tagPosition: 'bodyClose'` option on applicable tags to append them to the end of the `<body>` tag.
For example:
```vue
<script setup lang="ts">
useHead({
script: [
{
src: 'https://third-party-script.com',
2023-03-14 14:24:41 +00:00
// valid options are: 'head' | 'bodyClose' | 'bodyOpen'
tagPosition: 'bodyClose'
}
]
})
</script>
```
## Examples
2023-03-14 14:24:41 +00:00
### With `definePageMeta`
Within your `pages/` directory, you can use `definePageMeta` along with `useHead` to set metadata based on the current route.
For example, you can first set the current page title (this is extracted at build time via a macro, so it can't be set dynamically):
```vue{}[pages/some-page.vue]
<script setup>
definePageMeta({
title: 'Some Page'
})
</script>
```
And then in your layout file, you might use the route's metadata you have previously set:
```vue{}[layouts/default.vue]
<script setup>
const route = useRoute()
useHead({
meta: [{ property: 'og:title', content: `App Name - ${route.meta.title}` }]
})
</script>
```
2022-04-09 09:25:13 +00:00
:LinkExample{link="/docs/examples/composables/use-head"}
:ReadMore{link="/docs/guide/directory-structure/pages/#page-metadata"}
2023-03-14 14:24:41 +00:00
### Dynamic Title
In the example below, `titleTemplate` is set either as a string with the `%s` placeholder or as a `function`, which allows greater flexibility in setting the page title dynamically for each route of your Nuxt app:
```vue [app.vue]
<script setup>
useHead({
// as a string,
// where `%s` is replaced with the title
titleTemplate: '%s - Site Title',
// ... or as a function
titleTemplate: (productCategory) => {
return productCategory
? `${productCategory} - Site Title`
: 'Site Title'
}
})
</script>
```
`nuxt.config` is also used as an alternative way of setting the page title. However, `nuxt.config` does not allow the page title to be dynamic. Therefore, it is recommended to use `titleTemplate` in the `app.vue` file to add a dynamic title, which is then applied to all routes of your Nuxt app.
2023-03-14 14:24:41 +00:00
### External CSS
The example below shows how you might enable Google Fonts using either the `link` property of the `useHead` composable or using the `<Link>` component:
::code-group
```vue [useHead]
<script setup lang="ts">
useHead({
link: [
{
rel: 'preconnect',
href: 'https://fonts.googleapis.com'
},
{
rel: 'stylesheet',
href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap',
crossorigin: ''
}
]
})
</script>
```
```vue [Components]
<template>
<div>
<Link rel="preconnect" href="https://fonts.googleapis.com" />
<Link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" crossorigin="" />
</div>
</template>
```
::