npm - @nuxt/docs - Versions diffs - 0.0.0 → 3.17.1 - Mend

@nuxt/docs 0.0.0 → 3.17.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (224) hide show

package/.navigation.yml +2 -0
package/1.getting-started/.navigation.yml +3 -0
package/1.getting-started/01.introduction.md +81 -0
package/1.getting-started/02.installation.md +109 -0
package/1.getting-started/03.configuration.md +226 -0
package/1.getting-started/04.views.md +163 -0
package/1.getting-started/05.assets.md +48 -0
package/1.getting-started/06.styling.md +565 -0
package/1.getting-started/07.routing.md +149 -0
package/1.getting-started/08.seo-meta.md +360 -0
package/1.getting-started/09.transitions.md +473 -0
package/1.getting-started/10.data-fetching.md +795 -0
package/1.getting-started/11.state-management.md +223 -0
package/1.getting-started/12.error-handling.md +233 -0
package/1.getting-started/13.server.md +94 -0
package/1.getting-started/14.layers.md +92 -0
package/1.getting-started/15.prerendering.md +194 -0
package/1.getting-started/16.deployment.md +130 -0
package/1.getting-started/17.testing.md +728 -0
package/1.getting-started/18.upgrade.md +997 -0
package/2.guide/.navigation.yml +2 -0
package/2.guide/0.index.md +22 -0
package/2.guide/1.concepts/.navigation.yml +3 -0
package/2.guide/1.concepts/1.auto-imports.md +205 -0
package/2.guide/1.concepts/10.nuxt-lifecycle.md +141 -0
package/2.guide/1.concepts/2.vuejs-development.md +103 -0
package/2.guide/1.concepts/3.rendering.md +255 -0
package/2.guide/1.concepts/4.server-engine.md +62 -0
package/2.guide/1.concepts/5.modules.md +48 -0
package/2.guide/1.concepts/7.esm.md +299 -0
package/2.guide/1.concepts/8.typescript.md +97 -0
package/2.guide/1.concepts/9.code-style.md +22 -0
package/2.guide/2.directory-structure/.navigation.yml +3 -0
package/2.guide/2.directory-structure/0.nuxt.md +20 -0
package/2.guide/2.directory-structure/0.output.md +18 -0
package/2.guide/2.directory-structure/1.assets.md +16 -0
package/2.guide/2.directory-structure/1.components.md +608 -0
package/2.guide/2.directory-structure/1.composables.md +121 -0
package/2.guide/2.directory-structure/1.content.md +64 -0
package/2.guide/2.directory-structure/1.layouts.md +180 -0
package/2.guide/2.directory-structure/1.middleware.md +209 -0
package/2.guide/2.directory-structure/1.modules.md +66 -0
package/2.guide/2.directory-structure/1.node_modules.md +12 -0
package/2.guide/2.directory-structure/1.pages.md +440 -0
package/2.guide/2.directory-structure/1.plugins.md +299 -0
package/2.guide/2.directory-structure/1.public.md +27 -0
package/2.guide/2.directory-structure/1.server.md +546 -0
package/2.guide/2.directory-structure/1.shared.md +104 -0
package/2.guide/2.directory-structure/1.utils.md +49 -0
package/2.guide/2.directory-structure/2.env.md +75 -0
package/2.guide/2.directory-structure/2.gitignore.md +37 -0
package/2.guide/2.directory-structure/2.nuxtignore.md +36 -0
package/2.guide/2.directory-structure/2.nuxtrc.md +50 -0
package/2.guide/2.directory-structure/3.app-config.md +177 -0
package/2.guide/2.directory-structure/3.app.md +72 -0
package/2.guide/2.directory-structure/3.error.md +55 -0
package/2.guide/2.directory-structure/3.nuxt-config.md +34 -0
package/2.guide/2.directory-structure/3.package.md +32 -0
package/2.guide/2.directory-structure/3.tsconfig.md +24 -0
package/2.guide/3.going-further/.navigation.yml +3 -0
package/2.guide/3.going-further/1.experimental-features.md +689 -0
package/2.guide/3.going-further/1.features.md +103 -0
package/2.guide/3.going-further/1.internals.md +81 -0
package/2.guide/3.going-further/10.runtime-config.md +174 -0
package/2.guide/3.going-further/11.nightly-release-channel.md +68 -0
package/2.guide/3.going-further/2.hooks.md +98 -0
package/2.guide/3.going-further/3.modules.md +811 -0
package/2.guide/3.going-further/4.kit.md +51 -0
package/2.guide/3.going-further/6.nuxt-app.md +64 -0
package/2.guide/3.going-further/7.layers.md +227 -0
package/2.guide/3.going-further/9.debugging.md +115 -0
package/2.guide/3.going-further/index.md +4 -0
package/2.guide/4.recipes/.navigation.yml +3 -0
package/2.guide/4.recipes/1.custom-routing.md +181 -0
package/2.guide/4.recipes/2.vite-plugin.md +65 -0
package/2.guide/4.recipes/3.custom-usefetch.md +125 -0
package/2.guide/4.recipes/4.sessions-and-authentication.md +203 -0
package/3.api/.navigation.yml +3 -0
package/3.api/1.components/.navigation.yml +3 -0
package/3.api/1.components/1.client-only.md +76 -0
package/3.api/1.components/1.dev-only.md +51 -0
package/3.api/1.components/1.nuxt-client-fallback.md +80 -0
package/3.api/1.components/10.nuxt-picture.md +27 -0
package/3.api/1.components/11.teleports.md +40 -0
package/3.api/1.components/12.nuxt-route-announcer.md +56 -0
package/3.api/1.components/13.nuxt-time.md +173 -0
package/3.api/1.components/2.nuxt-page.md +154 -0
package/3.api/1.components/3.nuxt-layout.md +156 -0
package/3.api/1.components/4.nuxt-link.md +322 -0
package/3.api/1.components/5.nuxt-loading-indicator.md +50 -0
package/3.api/1.components/6.nuxt-error-boundary.md +65 -0
package/3.api/1.components/7.nuxt-welcome.md +25 -0
package/3.api/1.components/8.nuxt-island.md +70 -0
package/3.api/1.components/9.nuxt-img.md +43 -0
package/3.api/2.composables/.navigation.yml +3 -0
package/3.api/2.composables/on-prehydrate.md +60 -0
package/3.api/2.composables/use-app-config.md +19 -0
package/3.api/2.composables/use-async-data.md +212 -0
package/3.api/2.composables/use-cookie.md +233 -0
package/3.api/2.composables/use-error.md +32 -0
package/3.api/2.composables/use-fetch.md +217 -0
package/3.api/2.composables/use-head-safe.md +55 -0
package/3.api/2.composables/use-head.md +69 -0
package/3.api/2.composables/use-hydration.md +68 -0
package/3.api/2.composables/use-lazy-async-data.md +47 -0
package/3.api/2.composables/use-lazy-fetch.md +55 -0
package/3.api/2.composables/use-loading-indicator.md +77 -0
package/3.api/2.composables/use-nuxt-app.md +294 -0
package/3.api/2.composables/use-nuxt-data.md +112 -0
package/3.api/2.composables/use-preview-mode.md +118 -0
package/3.api/2.composables/use-request-event.md +23 -0
package/3.api/2.composables/use-request-fetch.md +52 -0
package/3.api/2.composables/use-request-header.md +34 -0
package/3.api/2.composables/use-request-headers.md +37 -0
package/3.api/2.composables/use-request-url.md +41 -0
package/3.api/2.composables/use-response-header.md +48 -0
package/3.api/2.composables/use-route-announcer.md +60 -0
package/3.api/2.composables/use-route.md +52 -0
package/3.api/2.composables/use-router.md +92 -0
package/3.api/2.composables/use-runtime-config.md +142 -0
package/3.api/2.composables/use-runtime-hook.md +43 -0
package/3.api/2.composables/use-seo-meta.md +80 -0
package/3.api/2.composables/use-server-seo-meta.md +27 -0
package/3.api/2.composables/use-state.md +48 -0
package/3.api/3.utils/$fetch.md +98 -0
package/3.api/3.utils/.navigation.yml +3 -0
package/3.api/3.utils/abort-navigation.md +73 -0
package/3.api/3.utils/add-route-middleware.md +88 -0
package/3.api/3.utils/call-once.md +92 -0
package/3.api/3.utils/clear-error.md +29 -0
package/3.api/3.utils/clear-nuxt-data.md +23 -0
package/3.api/3.utils/clear-nuxt-state.md +23 -0
package/3.api/3.utils/create-error.md +55 -0
package/3.api/3.utils/define-nuxt-component.md +53 -0
package/3.api/3.utils/define-nuxt-route-middleware.md +67 -0
package/3.api/3.utils/define-page-meta.md +234 -0
package/3.api/3.utils/define-route-rules.md +52 -0
package/3.api/3.utils/navigate-to.md +230 -0
package/3.api/3.utils/on-before-route-leave.md +11 -0
package/3.api/3.utils/on-before-route-update.md +11 -0
package/3.api/3.utils/on-nuxt-ready.md +25 -0
package/3.api/3.utils/prefetch-components.md +28 -0
package/3.api/3.utils/preload-components.md +23 -0
package/3.api/3.utils/preload-route-components.md +41 -0
package/3.api/3.utils/prerender-routes.md +46 -0
package/3.api/3.utils/refresh-cookie.md +46 -0
package/3.api/3.utils/refresh-nuxt-data.md +91 -0
package/3.api/3.utils/reload-nuxt-app.md +74 -0
package/3.api/3.utils/set-page-layout.md +24 -0
package/3.api/3.utils/set-response-status.md +36 -0
package/3.api/3.utils/show-error.md +31 -0
package/3.api/3.utils/update-app-config.md +27 -0
package/3.api/4.commands/.navigation.yml +3 -0
package/3.api/4.commands/add.md +112 -0
package/3.api/4.commands/analyze.md +41 -0
package/3.api/4.commands/build-module.md +42 -0
package/3.api/4.commands/build.md +46 -0
package/3.api/4.commands/cleanup.md +38 -0
package/3.api/4.commands/dev.md +59 -0
package/3.api/4.commands/devtools.md +38 -0
package/3.api/4.commands/generate.md +41 -0
package/3.api/4.commands/info.md +33 -0
package/3.api/4.commands/init.md +46 -0
package/3.api/4.commands/module.md +84 -0
package/3.api/4.commands/prepare.md +36 -0
package/3.api/4.commands/preview.md +43 -0
package/3.api/4.commands/typecheck.md +42 -0
package/3.api/4.commands/upgrade.md +37 -0
package/3.api/5.kit/.navigation.yml +3 -0
package/3.api/5.kit/1.modules.md +172 -0
package/3.api/5.kit/10.runtime-config.md +27 -0
package/3.api/5.kit/10.templates.md +283 -0
package/3.api/5.kit/11.nitro.md +409 -0
package/3.api/5.kit/12.resolving.md +268 -0
package/3.api/5.kit/13.logging.md +65 -0
package/3.api/5.kit/14.builder.md +491 -0
package/3.api/5.kit/15.examples.md +41 -0
package/3.api/5.kit/2.programmatic.md +125 -0
package/3.api/5.kit/3.compatibility.md +230 -0
package/3.api/5.kit/4.autoimports.md +144 -0
package/3.api/5.kit/5.components.md +127 -0
package/3.api/5.kit/6.context.md +130 -0
package/3.api/5.kit/7.pages.md +295 -0
package/3.api/5.kit/8.layout.md +80 -0
package/3.api/5.kit/9.plugins.md +263 -0
package/3.api/6.advanced/.navigation.yml +1 -0
package/3.api/6.advanced/1.hooks.md +105 -0
package/3.api/6.advanced/2.import-meta.md +60 -0
package/3.api/6.nuxt-config.md +12 -0
package/3.api/index.md +31 -0
package/5.community/.navigation.yml +3 -0
package/5.community/2.getting-help.md +48 -0
package/5.community/3.reporting-bugs.md +50 -0
package/5.community/4.contribution.md +205 -0
package/5.community/5.framework-contribution.md +142 -0
package/5.community/6.roadmap.md +79 -0
package/5.community/7.changelog.md +92 -0
package/6.bridge/.navigation.yml +3 -0
package/6.bridge/1.overview.md +137 -0
package/6.bridge/10.configuration.md +96 -0
package/6.bridge/2.typescript.md +46 -0
package/6.bridge/3.bridge-composition-api.md +132 -0
package/6.bridge/4.plugins-and-middleware.md +65 -0
package/6.bridge/5.nuxt3-compatible-api.md +204 -0
package/6.bridge/6.meta.md +117 -0
package/6.bridge/7.runtime-config.md +38 -0
package/6.bridge/8.nitro.md +102 -0
package/6.bridge/9.vite.md +37 -0
package/7.migration/.navigation.yml +3 -0
package/7.migration/1.overview.md +24 -0
package/7.migration/10.bundling.md +28 -0
package/7.migration/11.server.md +17 -0
package/7.migration/2.configuration.md +240 -0
package/7.migration/20.module-authors.md +94 -0
package/7.migration/3.auto-imports.md +18 -0
package/7.migration/4.meta.md +127 -0
package/7.migration/5.plugins-and-middleware.md +80 -0
package/7.migration/6.pages-and-layouts.md +233 -0
package/7.migration/7.component-options.md +156 -0
package/7.migration/8.runtime-config.md +58 -0
package/LICENSE +21 -0
package/README.md +11 -0
package/package.json +16 -4
package/dist/.gitkeep +0 -0

package/1.getting-started/08.seo-meta.md ADDED Viewed

@@ -0,0 +1,360 @@
+---
+title: SEO and Meta
+description: Improve your Nuxt app's SEO with powerful head config, composables and components.
+navigation.icon: i-lucide-file-search
+---
+Nuxt head tag management is powered by [Unhead](https://unhead.unjs.io). It provides sensible defaults, several powerful composables
+and numerous configuration options to manage your app's head and SEO meta tags.
+## Nuxt Config
+Providing an [`app.head`](/docs/api/nuxt-config#head) property in your [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) allows you to statically customize the head for your entire app.
+::important
+This method does not allow you to provide reactive data. We recommend to use `useHead()` in `app.vue`.
+::
+It's good practice to set tags here that won't change such as your site title default, language and favicon.
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  app: {
+    head: {
+      title: 'Nuxt', // default fallback title
+      htmlAttrs: {
+        lang: 'en',
+      },
+      link: [
+        { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' },
+      ]
+    }
+  }
+})
+```
+You can also provide any of the keys listed below in [Types](#types).
+### Defaults Tags
+Some tags are provided by Nuxt by default to ensure your website works well out of the box.
+- `viewport`: `width=device-width, initial-scale=1`
+- `charset`: `utf-8`
+While most sites won't need to override these defaults, you can update them using the keyed shortcuts.
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  app: {
+    head: {
+      // update Nuxt defaults
+      charset: 'utf-16',
+      viewport: 'width=device-width, initial-scale=1, maximum-scale=1',
+    }
+  }
+})
+```
+## `useHead`
+The [`useHead`](/docs/api/composables/use-head) composable function supports reactive input, allowing you to manage your head tags programmatically.
+```vue twoslash [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>
+```
+We recommend to take a look at the [`useHead`](/docs/api/composables/use-head) and [`useHeadSafe`](/docs/api/composables/use-head-safe) composables.
+## `useSeoMeta`
+The [`useSeoMeta`](/docs/api/composables/use-seo-meta) composable lets you define your site's SEO meta tags as an object with full type safety.
+This helps you avoid typos and common mistakes, such as using `name` instead of `property`.
+```vue twoslash [app.vue]
+<script setup lang="ts">
+useSeoMeta({
+  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>
+```
+:read-more{to="/docs/api/composables/use-seo-meta"}
+## Components
+While using [`useHead`](/docs/api/composables/use-head) is recommended in all cases, you may have a personal preference for defining your head tags in your template using components.
+Nuxt provides the following components for this purpose: `<Title>`, `<Base>`, `<NoScript>`, `<Style>`, `<Meta>`, `<Link>`, `<Body>`, `<Html>` and `<Head>`. Note
+the capitalization of these components ensuring we don't use invalid native HTML tags.
+`<Head>` and `<Body>` can accept nested meta tags (for aesthetic reasons) but this does not affect _where_ the nested meta tags are rendered in the final HTML.
+<!-- @case-police-ignore html -->
+```vue [app.vue]
+<script setup lang="ts">
+const title = ref('Hello World')
+</script>
+<template>
+  <div>
+    <Head>
+      <Title>{{ title }}</Title>
+      <Meta name="description" :content="title" />
+      <Style>
+      body { background-color: green; }
+      </Style>
+    </Head>
+    <h1>{{ title }}</h1>
+  </div>
+</template>
+```
+It's suggested to wrap your components in either a `<Head>` or `<Html>` components as tags will be deduped more intuitively.
+## Types
+Below are the non-reactive types used for [`useHead`](/docs/api/composables/use-head), [`app.head`](/docs/api/nuxt-config#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/vue](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/schema.ts) for more detailed types.
+## Features
+### Reactivity
+Reactivity is supported on all properties, by providing a computed value, a getter, or a reactive object.
+::code-group
+  ```vue twoslash [useHead]
+  <script setup lang="ts">
+  const description = ref('My amazing site.')
+  useHead({
+    meta: [
+      { name: 'description', content: description }
+    ],
+  })
+  </script>
+  ```
+  ```vue twoslash [useSeoMeta]
+  <script setup lang="ts">
+  const description = ref('My amazing site.')
+  useSeoMeta({
+    description
+  })
+  </script>
+  ```
+  ```vue [Components]
+  <script setup lang="ts">
+  const description = ref('My amazing site.')
+  </script>
+  <template>
+    <div>
+      <Meta name="description" :content="description" />
+    </div>
+  </template>
+  ```
+::
+### Title Template
+You can use the `titleTemplate` option to provide a dynamic template for customizing the title of your site. For example, you could add 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`. 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 twoslash [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`](/docs/api/composables/use-head) 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 'Site Title'.
+### Template Params
+You can use `templateParams` to provide additional placeholders in your `titleTemplate` besides the default `%s`. This allows for more dynamic title generation.
+::code-group
+  ```vue twoslash [useHead]
+  <script setup lang="ts">
+  useHead({
+    titleTemplate: (titleChunk) => {
+      return titleChunk ? `${titleChunk} %separator %siteName` : '%siteName';
+    },
+    templateParams: {
+      siteName: 'Site Title',
+      separator: '-'
+    }
+  })
+  </script>
+  ```
+::
+### 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 twoslash
+<script setup lang="ts">
+useHead({
+  script: [
+    {
+      src: 'https://third-party-script.com',
+      // valid options are: 'head' | 'bodyClose' | 'bodyOpen'
+      tagPosition: 'bodyClose'
+    }
+  ]
+})
+</script>
+```
+## Examples
+### With `definePageMeta`
+Within your [`pages/` directory](/docs/guide/directory-structure/pages), you can use `definePageMeta` along with [`useHead`](/docs/api/composables/use-head) 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 twoslash [pages/some-page.vue]
+<script setup lang="ts">
+definePageMeta({
+  title: 'Some Page'
+})
+</script>
+```
+And then in your layout file, you might use the route's metadata you have previously set:
+```vue twoslash [layouts/default.vue]
+<script setup lang="ts">
+const route = useRoute()
+useHead({
+  meta: [{ property: 'og:title', content: `App Name - ${route.meta.title}` }]
+})
+</script>
+```
+:link-example{to="/docs/examples/features/meta-tags"}
+:read-more{to="/docs/guide/directory-structure/pages/#page-metadata"}
+### 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 twoslash [app.vue]
+<script setup lang="ts">
+useHead({
+  // as a string,
+  // where `%s` is replaced with the title
+  titleTemplate: '%s - Site Title',
+})
+</script>
+```
+```vue twoslash [app.vue]
+<script setup lang="ts">
+useHead({
+  // 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.
+### External CSS
+The example below shows how you might enable Google Fonts using either the `link` property of the [`useHead`](/docs/api/composables/use-head) composable or using the `<Link>` component:
+::code-group
+  ```vue twoslash [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>
+  ```
+::