docs: add and link to a section on Nuxt context (#23546)

This commit is contained in:
Michael Brevard 2024-01-31 11:46:21 +02:00 committed by GitHub
parent 8d809e6cbf
commit b485012f22
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 27 additions and 5 deletions

View File

@ -19,6 +19,14 @@ In Nuxt 2, this was referred to as **Nuxt context**.
Jump over the `NuxtApp` interface documentation. Jump over the `NuxtApp` interface documentation.
:: ::
## The Nuxt Context
Many composables and utilities, both built-in and user-made, may require access to the Nuxt instance. This doesn't exist everywhere on your application, because a fresh instance is created on every request.
Currently, the Nuxt context is only accessible in [plugins](/docs/guide/directory-structure/plugins), [Nuxt hooks](/docs/guide/going-further/hooks), [Nuxt middleware](/docs/guide/directory-structure/middleware), and [setup functions](https://vuejs.org/api/composition-api-setup.html) (in pages and components).
If a composable is called without access to the context, you may get an error stating that 'A composable that requires access to the Nuxt instance was called outside of a plugin, Nuxt hook, Nuxt middleware, or Vue setup function.' In that case, you can also explicitly call functions within this context by using [`nuxtApp.runWithContext`](/docs/api/composables/use-nuxt-app#runwithcontext).
## Accessing NuxtApp ## Accessing NuxtApp
Within composables, plugins and components you can access `nuxtApp` with [`useNuxtApp()`](/docs/api/composables/use-nuxt-app): Within composables, plugins and components you can access `nuxtApp` with [`useNuxtApp()`](/docs/api/composables/use-nuxt-app):

View File

@ -11,7 +11,7 @@ links:
Within your pages, components, and plugins you can use useAsyncData to get access to data that resolves asynchronously. Within your pages, components, and plugins you can use useAsyncData to get access to data that resolves asynchronously.
::callout ::callout
[`useAsyncData`](/docs/api/composables/use-async-data) is a composable meant to be called directly in a setup function, plugin, or route middleware. It returns reactive composables and handles adding responses to the Nuxt payload so they can be passed from server to client **without re-fetching the data on client side** when the page hydrates. [`useAsyncData`](/docs/api/composables/use-async-data) is a composable meant to be called directly in the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context). It returns reactive composables and handles adding responses to the Nuxt payload so they can be passed from server to client **without re-fetching the data on client side** when the page hydrates.
:: ::
## Usage ## Usage

View File

@ -14,6 +14,10 @@ Within your pages, components and plugins you can use `useCookie`, an SSR-friend
const cookie = useCookie(name, options) const cookie = useCookie(name, options)
``` ```
::alert{icon=👉}
`useCookie` only works in the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
::
::callout ::callout
`useCookie` ref will automatically serialize and deserialize cookie value to JSON. `useCookie` ref will automatically serialize and deserialize cookie value to JSON.
:: ::

View File

@ -8,7 +8,7 @@ links:
size: xs size: xs
--- ---
`useNuxtApp` is a built-in composable that provides a way to access shared runtime context of Nuxt, which is available on both client and server side. It helps you access the Vue app instance, runtime hooks, runtime config variables and internal states, such as `ssrContext` and `payload`. `useNuxtApp` is a built-in composable that provides a way to access shared runtime context of Nuxt, also known as the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context), which is available on both client and server side. It helps you access the Vue app instance, runtime hooks, runtime config variables and internal states, such as `ssrContext` and `payload`.
```vue [app.vue] ```vue [app.vue]
<script setup lang="ts"> <script setup lang="ts">

View File

@ -8,7 +8,7 @@ links:
size: xs size: xs
--- ---
Within your pages, components, and plugins you can use `useRequestEvent` to access the incoming request. Within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context) you can use `useRequestEvent` to access the incoming request.
```ts ```ts
// Get underlying request event // Get underlying request event

View File

@ -14,6 +14,8 @@ links:
## Usage ## Usage
`navigateTo` is available on both server side and client side. It can be used within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context), or directly, to perform page navigation.
### Within a Vue Component ### Within a Vue Component
```vue ```vue

View File

@ -10,6 +10,10 @@ links:
When prerendering, you can hint to Nitro to prerender additional paths, even if their URLs do not show up in the HTML of the generated page. When prerendering, you can hint to Nitro to prerender additional paths, even if their URLs do not show up in the HTML of the generated page.
::callout
`prerenderRoutes` can only be called within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
::
```js ```js
const route = useRoute() const route = useRoute()

View File

@ -9,7 +9,7 @@ links:
--- ---
::callout ::callout
`setPageLayout` relies on access to the Nuxt context and can only be called within components' setup functions, plugins, and route middleware. `setPageLayout` allows you to dynamically change the layout of a page. It relies on access to the Nuxt context and therefore can only be called within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
:: ::
```ts [middleware/custom-layout.ts] ```ts [middleware/custom-layout.ts]

View File

@ -12,6 +12,10 @@ Nuxt provides composables and utilities for first-class server-side-rendering su
`setResponseStatus` sets the statusCode (and optionally the statusMessage) of the response. `setResponseStatus` sets the statusCode (and optionally the statusMessage) of the response.
::callout
`setResponseStatus` can only be called in the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
::
```js ```js
const event = useRequestEvent() const event = useRequestEvent()

View File

@ -8,7 +8,7 @@ links:
size: xs size: xs
--- ---
Within your pages, components and plugins you can use `showError` to show an error. Within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context) you can use `showError` to show an error.
**Parameters:** **Parameters:**