This repository has been archived by the owner on Apr 6, 2023. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 1.1k
docs(api): add useNuxtApp
composable
#6786
Merged
Merged
Changes from all commits
Commits
Show all changes
26 commits
Select commit
Hold shift + click to select a range
fb0ac02
docs(api): add useNuxtApp composable docs
Krutie a36996e
docs(api): fix linting issues
Krutie ad78b00
Merge branch 'nuxt:main' into docs/api-composable-use-nuxt-app
Krutie 1474134
fix(docs): codeblocks
Krutie 97e2f34
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 4f67c03
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 f7189f2
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 6166eec
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 be86ba0
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 bad40ac
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 4603101
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 1e35140
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 7e5a3ba
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 82e91f8
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 72af002
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 bf2d2be
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 483d779
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 decaa0c
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 4ac796e
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 3deed14
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 9ea602c
Update docs/content/3.api/1.composables/use-nuxt-app.md
pi0 51b8e08
Apply suggestions from code review
pi0 307510d
Merge branch 'main' into docs/api-composable-use-nuxt-app
pi0 d17bc1d
remove globalName from docs
pi0 83b8ad3
updates
pi0 059abaa
refactor ordering
pi0 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,135 @@ | ||
# `useNuxtApp` | ||
|
||
::NeedContribution | ||
:: | ||
`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`. | ||
|
||
You can use `useNuxtApp()` within composables, plugins and components. | ||
|
||
```vue [app.vue] | ||
<script setup> | ||
const nuxtApp = useNuxtApp() | ||
</script> | ||
``` | ||
|
||
## Methods | ||
|
||
### `provide (name, value)` | ||
|
||
`nuxtApp` is a runtime context that you can extend usingΒ [Nuxt plugins](https://v3.nuxtjs.org/guide/directory-structure/plugins). You can use the `provide` function to create Nuxt plugins to make values and helper methods available in your Nuxt application across all composables and components. | ||
|
||
`provide` function accepts `name` and `value` parameters. | ||
|
||
**Example:** | ||
|
||
```js | ||
const nuxtApp = useNuxtApp() | ||
nuxtApp.provide('hello', (name) => `Hello ${name}!`) | ||
|
||
// Prints "Hello name!" | ||
console.log(nuxtApp.$hello('name')) | ||
``` | ||
|
||
As you can see in the example above, `$hello` has become the new and custom part of `nuxtApp` context and it is available in all places where `nuxtApp` is accessible. | ||
|
||
### `hook(name, cb)` | ||
|
||
Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue.js composables and [Nuxt plugins](/guide/directory-structure/plugins) to hook into the rendering lifecycle. | ||
|
||
`hook` function is useful for adding custom logic by hooking into the rendering lifecycle at a specific point. `hook` function is mostly used when creating Nuxt plugins. | ||
|
||
See [Runtime Hooks](/api/advanced/hooks#app-hooks-runtime) for avialble runtime hooks called by Nuxt. | ||
|
||
pi0 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
```js [plugins/test.ts] | ||
export default defineNuxtPlugin((nuxtApp) => { | ||
nuxtApp.hook('page:start', () => { | ||
/* your code goes here */ | ||
}) | ||
nuxtApp.hook('vue:error', (..._args) => { | ||
console.log('vue:error') | ||
// if (process.client) { | ||
// console.log(..._args) | ||
// } | ||
}) | ||
}) | ||
``` | ||
|
||
### `callhook(name, ...args)` | ||
|
||
`callHook` returns a promise when called with any of the existing hooks. | ||
|
||
```js | ||
await nuxtApp.callHook('my-plugin:init') | ||
``` | ||
|
||
## Properties | ||
|
||
`useNuxtApp()` exposes the following properties that you can use to extend and customize your app and share state, data and variables. | ||
|
||
### `vueApp` | ||
|
||
`vueApp` is the global Vue.js [application instance](https://vuejs.org/api/application.html#application-api) that you can access through `nuxtApp`. Some useful methods: | ||
|
||
- [**component()**](https://vuejs.org/api/application.html#app-component) - Registers a global component if passing both a name string and a component definition, or retrieves an already registered one if only the name is passed. | ||
- [**directive()**](https://vuejs.org/api/application.html#app-directive) - Registers a global custom directive if passing both a name string and a directive definition, or retrieves an already registered one if only the name is passed[(example)](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives). | ||
- [**use()**](https://vuejs.org/api/application.html#app-use) - Installs aΒ **[Vue.js Plugin](https://vuejs.org/guide/reusability/plugins.html)** [(example)](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins). | ||
|
||
:ReadMore{link="https://vuejs.org/api/application.html#application-api"} | ||
|
||
### `ssrContext` | ||
|
||
`ssrContext` is generated during server-side rendering and it is only available on the server side. Nuxt exposes the following properties through `ssrContext`: | ||
|
||
- **`url`** (string) - Current request url. | ||
- **`event`** ([unjs/h3](https://github.com/unjs/h3) request event) - Access to `req` and `res` objects for the current request. | ||
- **`payload`** (object) - NuxtApp payload object. | ||
|
||
### `payload` | ||
|
||
`payload` exposes data and state variables from server side to client side and makes them available in the `window.__NUXT__` object that is accessible from the browser. | ||
|
||
`payload` exposes the following keys on the client side after they are stringified and passed from the server side: | ||
|
||
- **serverRendered** (boolean) - Indicates if response is server-side-rendered. | ||
- **data** (object) - When you fetch the data from an API endpoint using either `useFetch` or `useAsyncData`, resulting payload can be accessed from the `payload.data`. This data is cached and helps you prevent fetching the same data in case an identical request is made more than once. | ||
|
||
```vue [app.vue] | ||
export default defineComponent({ | ||
async setup() { | ||
const { data } = await useAsyncData('count', () => $fetch('/api/count')) | ||
} | ||
}) | ||
``` | ||
|
||
After fetching the value of `count` using `useAsyncData` in the example above, if you access `payload.data`, you will see `{ count: 1 }` recorded there. The value of `count` is updated whenever the page count increases. | ||
|
||
When accessing the same `payload.data` from [ssrcontext](#ssrcontext), you can access the same value on the server side as well. | ||
|
||
- **state** (object) - When you use `useState` composable in Nuxt to set shared state, this state data is accessed through `payload.state.[name-of-your-state]`. | ||
|
||
```js [plugins/my-plugin.ts] | ||
export const useColor = () => useState<string>('color', () => 'pink') | ||
|
||
export default defineNuxtPlugin((nuxtApp) => { | ||
if (process.server) { | ||
const color = useColor() | ||
} | ||
}) | ||
``` | ||
|
||
### `isHydrating` | ||
|
||
You can use `nuxtApp.isHydrating` (boolean) to check if the Nuxt app is hydrating on the client side. | ||
|
||
**Example:** | ||
|
||
```ts [components/nuxt-error-boundary.ts] | ||
export default defineComponent({ | ||
setup (_props, { slots, emit }) { | ||
const nuxtApp = useNuxtApp() | ||
onErrorCaptured((err) => { | ||
if (process.client && !nuxtApp.isHydrating) { | ||
// ... | ||
} | ||
}) | ||
} | ||
}) | ||
``` |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@pi0 little typo: avialble
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thanks for the notice. (please check your discord when could. I've sent a message)