From fb0ac02fe0337268b94884399b90b24d43908a62 Mon Sep 17 00:00:00 2001 From: Krutie Patel Date: Sat, 20 Aug 2022 01:22:21 +1000 Subject: [PATCH 01/24] docs(api): add useNuxtApp composable docs --- .../3.api/1.composables/use-nuxt-app.md | 220 +++++++++++++++++- 1 file changed, 218 insertions(+), 2 deletions(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index a2f157397a7..390a4ced063 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -1,4 +1,220 @@ # `useNuxtApp` +`useNuxtApp` is a built-in composable that provides a shared runtime context. This runtime context is available on both client-side and server-side and it helps you access the Vue instance, runtime hooks, runtime config variables and internal states, such as `ssrContext` and `payload`. -::NeedContribution -:: +You can use `useNuxtApp` within composable, plugins and components. + +```jsx +// app.vue + +``` + +`useNuxtApp` will expose the following properties that you can use to extend and customize your app and share state, data and variables. + +## globalName +#### `type: string` + +`globalName` allows you to customize the global ID used in the main HTML template as well as the main Vue instance name and other options. + +The default value of `globalName` is set to `nuxt`, but you can customize it using `nuxtApp.globalName`. + +### Example + +```jsx [app.vue] + +``` + +## isHydrating +#### `type: boolean` + +You can use `nuxtApp.isHydrating` to check if the Nuxt app is hydrating on the client side. + +### Example + +```tsx [components/nuxt-error-boundary.ts] + +export default defineComponent({ + setup (_props, { slots, emit }) { + // ... + const nuxtApp = useNuxtApp() + onErrorCaptured((err) => { + if (process.client && !nuxtApp.isHydrating) { + emit('error', err) + error.value = err + return false + } + }) + // ... + } +}) +``` + +## ssrContext + +`ssrContext` is generated using runtime `vue-bundle-renderer` for Vue 3 and it is only available on the server-side. Nuxt exposes the following properties through `ssrContext`. + +- **url** - `type: string` - `url` refers to the host url where the current request is being made +- **event** - `type: HTTP request` - `event` allows access to `res` and `res` object for the current request made to Nuxt page +- **runtimeConfig** - `type: runtimeConfig object` - `runtimeConfig` exposes runtime config on the client-side via payload +- **noSSR** - `type: boolean` +- **error** - `type: error object` - returns server-side error if any +- **payload** - returns NuxtApp payload object - See [payload](#payload) section below for more detail. +- **renderMeta** - `type: NuxtMeta` - returns a `Promise` of `NuxtMeta` type that includes HTML, head and body attributes as well as head tags. +- **teleports** - `type: Record object` - renders content outside of the Vue application + +> See how the [Vue-meta plugin](https://github.com/nuxt/framework/blob/main/packages/nuxt/src/head/runtime/lib/vue-meta.plugin.ts#L23) on Nuxt uses `renderMeta` in combination with `teleports`. + +## vueApp + +`vueApp` is the global Vue application instance that you can access through `nuxtApp`. + +- **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. +- **config** - exposes a `config` object that contains the configuration settings for that application. +- **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. + +> See `directive` example: [https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives) + +- **mixins** - Applies a global `mixin` (scoped to the application). However, it is not recommended to use mixins with the Vue 3. Their sole purpose is only to provide backward compatibility. +- **mount** - Mounts the application instance in a container element. +- **provide** - Provide a value that can be injected in all descendent components within the application. +- **unmount** - Unmounts a mounted application instance, triggering the unmount lifecycle hooks for all components in the application's component tree. +- **use** - Installs a **[plugin](https://vuejs.org/guide/reusability/plugins.html)**. + +> See `use` example: [https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins) + +:ReadMore{link="https://vuejs.org/api/application.html#application-api"} + +## $router +#### `type: router object` + +You can access the Vue router object using `nuxtApp.$router`. + +:ReadMore{link="/api/composables/use-router"} + +## provide - fn + +`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 composable and components. + +`provide` function accepts `name` and `value` parameters. + +### Example + +```jsx +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 at all places where `nuxtApp` is accessible. + +## State and variables + +### $config + +`nuxtApp.$config` exposes runtime-config and environment variables on the client-side to the Nuxt app context through two keys: `app` and `public`. + +Keys found under `app` and `public` are available on the client-side. + +- **app:** + - **baseURL** - `type: string` + - **buildAssetsDir** - `type: string` + - **cdnURL** - `type: string` +- **public** - `nuxtApp.$config.public` allows you to access the public runtime config that is set in the `nuxt.config` file of your Nuxt app. + +> Same `$config` object is accessible through `nuxtApp.payload.config` as well. + +### payload + +`payload` exposes data and state variables from server-side to client-side and make them available in the `window.NUXT` object that is accessible from the browser. + +`payload` exposes following keys on client-side after they are stringified and passed from the server-side: + +- **serverRendered** - `type: boolean` +- **data** - `type: record 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 twice. + +```js [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. And the value `count` is updated accordingly as 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** - `type: record 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('color', () => 'pink') + +export default defineNuxtPlugin((nuxtApp) => { + if (process.server) { + const color = useColor() + } +}) +``` +- **config** - Same as the [$config](#config) section above. + +## Runtime `nuxtApp` hooks + +Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue composable and [Nuxt Plugins](/guide/directory-structure/plugins) to hook into the rendering lifecycle. + +### hooks + +`nuxtApp` lets you call and add the following runtime hooks: + +```tsx +// App related runtime hooks +'app:created': (app: App) => HookResult +'app:beforeMount': (app: App) => HookResult +'app:mounted': (app: App) => HookResult +'app:rendered': (ctx: AppRenderedContext) => HookResult +'app:redirected': () => HookResult +'app:suspense:resolve': (Component?: VNode) => HookResult +'app:error': (err: any) => HookResult +'app:error:cleared': (options: { redirect?: string }) => HookResult +'app:data:refresh': (keys?: string[]) => HookResult + +// Nuxt page related runtime hooks +'page:start': (Component?: VNode) => HookResult +'page:finish': (Component?: VNode) => HookResult +'meta:register': (metaRenderers: Array<(nuxt: NuxtApp) => NuxtMeta | Promise>) => HookResult + +// Vue instance related runtime hooks +'vue:setup': () => void +'vue:error': (...args: Parameters[0]>) => HookResult +``` + +### hook - `type: function` + +`hook` function is useful for adding custom logic by hooking into the rendering lifecycle at a specific point. `hook` function is mostly used in creating Nuxt plugins. + +```jsx [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 - `type: function` + +`callHook` returns promise when called with any of the existing hooks. + +```jsx +await nuxtApp.callHook('app:created', vueApp) +``` \ No newline at end of file From a36996e81287c52c22ef88f522f0c65e432a274e Mon Sep 17 00:00:00 2001 From: Krutie Patel Date: Sat, 20 Aug 2022 02:01:24 +1000 Subject: [PATCH 02/24] docs(api): fix linting issues --- .../3.api/1.composables/use-nuxt-app.md | 35 +++++++++++-------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 390a4ced063..43d35c06d36 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -1,4 +1,5 @@ # `useNuxtApp` + `useNuxtApp` is a built-in composable that provides a shared runtime context. This runtime context is available on both client-side and server-side and it helps you access the Vue instance, runtime hooks, runtime config variables and internal states, such as `ssrContext` and `payload`. You can use `useNuxtApp` within composable, plugins and components. @@ -12,8 +13,9 @@ You can use `useNuxtApp` within composable, plugins and components. `useNuxtApp` will expose the following properties that you can use to extend and customize your app and share state, data and variables. -## globalName -#### `type: string` +## globalName + +**`type: string`** `globalName` allows you to customize the global ID used in the main HTML template as well as the main Vue instance name and other options. @@ -28,10 +30,11 @@ The default value of `globalName` is set to `nuxt`, but you can customize it usi ``` -## isHydrating -#### `type: boolean` +## isHydrating -You can use `nuxtApp.isHydrating` to check if the Nuxt app is hydrating on the client side. +**`type: boolean`** + +You can use `nuxtApp.isHydrating` to check if the Nuxt app is hydrating on the client side. ### Example @@ -74,7 +77,7 @@ export default defineComponent({ - **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. - **config** - exposes a `config` object that contains the configuration settings for that application. -- **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. +- **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. > See `directive` example: [https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives) @@ -82,16 +85,17 @@ export default defineComponent({ - **mount** - Mounts the application instance in a container element. - **provide** - Provide a value that can be injected in all descendent components within the application. - **unmount** - Unmounts a mounted application instance, triggering the unmount lifecycle hooks for all components in the application's component tree. -- **use** - Installs a **[plugin](https://vuejs.org/guide/reusability/plugins.html)**. +- **use** - Installs a **[plugin](https://vuejs.org/guide/reusability/plugins.html)**. > See `use` example: [https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins) :ReadMore{link="https://vuejs.org/api/application.html#application-api"} -## $router -#### `type: router object` +## $router + +**`type: router object`** -You can access the Vue router object using `nuxtApp.$router`. +You can access the Vue router object using `nuxtApp.$router`. :ReadMore{link="/api/composables/use-router"} @@ -122,9 +126,9 @@ As you can see in the example above, `$hello` has become the new and custom part Keys found under `app` and `public` are available on the client-side. - **app:** - - **baseURL** - `type: string` - - **buildAssetsDir** - `type: string` - - **cdnURL** - `type: string` + - **baseURL** - `type: string` + - **buildAssetsDir** - `type: string` + - **cdnURL** - `type: string` - **public** - `nuxtApp.$config.public` allows you to access the public runtime config that is set in the `nuxt.config` file of your Nuxt app. > Same `$config` object is accessible through `nuxtApp.payload.config` as well. @@ -145,11 +149,11 @@ export default defineComponent({ } }) ``` + After fetching the value of `count` using `useAsyncData` in the example above, if you access `payload.data`, you will see `{ count: 1 }` recorded there. And the value `count` is updated accordingly as 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** - `type: record 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] @@ -161,6 +165,7 @@ export default defineNuxtPlugin((nuxtApp) => { } }) ``` + - **config** - Same as the [$config](#config) section above. ## Runtime `nuxtApp` hooks @@ -217,4 +222,4 @@ export default defineNuxtPlugin((nuxtApp) => { ```jsx await nuxtApp.callHook('app:created', vueApp) -``` \ No newline at end of file +``` From 1474134281a4b27030de6498f91093f45f9355d3 Mon Sep 17 00:00:00 2001 From: Krutie Patel Date: Mon, 22 Aug 2022 18:12:15 +1000 Subject: [PATCH 03/24] fix(docs): codeblocks --- .../content/3.api/1.composables/use-nuxt-app.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 43d35c06d36..7702c7d5f07 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -4,8 +4,7 @@ You can use `useNuxtApp` within composable, plugins and components. -```jsx -// app.vue +```vue [app.vue] @@ -23,7 +22,7 @@ The default value of `globalName` is set to `nuxt`, but you can customize it usi ### Example -```jsx [app.vue] +```vue [app.vue] ``` From 6166eec75a03aa24753f4e68769e53f56341353b Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:46:59 +0200 Subject: [PATCH 07/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index cbf70e2744a..053d2c4e50f 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -10,7 +10,7 @@ You can use `useNuxtApp` within composables, plugins and components. ``` -`useNuxtApp` will expose the following properties that you can use to extend and customize your app and share state, data and variables. +`useNuxtApp` exposes the following properties that you can use to extend and customize your app and share state, data and variables. ## globalName From be86ba0f7fe746ec436a250574b63006d9c29bb4 Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:47:05 +0200 Subject: [PATCH 08/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 053d2c4e50f..5f4916dac47 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -16,7 +16,7 @@ You can use `useNuxtApp` within composables, plugins and components. **`type: string`** -`globalName` allows you to customize the global ID used in the main HTML template as well as the main Vue instance name and other options. +`globalName` allows you to customize the global ID used in the main HTML template, as well as the main Vue instance name and other options. The default value of `globalName` is set to `nuxt`, but you can customize it using `nuxtApp.globalName`. From bad40ac6ccd9678a067d9b8a9c6aef50cd4a0f56 Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:53:55 +0200 Subject: [PATCH 09/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 5f4916dac47..0c5580edd23 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -24,7 +24,7 @@ The default value of `globalName` is set to `nuxt`, but you can customize it usi ```vue [app.vue] ``` From 46031019b99274237d59c591eeb1b4483ba8657d Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:54:04 +0200 Subject: [PATCH 10/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 0c5580edd23..dfd8f38eafb 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -153,7 +153,7 @@ After fetching the value of `count` using `useAsyncData` in the example above, i When accessing the same `payload.data` from [ssrcontext](#ssrcontext), you can access the same value on the server-side as well. -- **state** - `type: record object` - when you use `useState` composable in Nuxt to set shared state, this state data is accessed through payload.state.[name-of-your-state] +- **state** - `type: record 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('color', () => 'pink') From 1e351409469802c8fa9ce5b5247f1309cc8f291c Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:54:19 +0200 Subject: [PATCH 11/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index dfd8f38eafb..2c9e0396fd4 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -38,7 +38,6 @@ You can use `nuxtApp.isHydrating` to check if the Nuxt app is hydrating on the c ### Example ```ts [components/nuxt-error-boundary.ts] - export default defineComponent({ setup (_props, { slots, emit }) { // ... From 7e5a3ba54c0f9aadf6b7e317729a89efe46b5626 Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:54:31 +0200 Subject: [PATCH 12/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 2c9e0396fd4..7856d42f500 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -56,7 +56,7 @@ export default defineComponent({ ## ssrContext -`ssrContext` is generated using runtime `vue-bundle-renderer` for Vue 3 and it is only available on the server-side. Nuxt exposes the following properties through `ssrContext`. +`ssrContext` is generated using runtime `vue-bundle-renderer` for Vue 3 and it is only available on the server side. Nuxt exposes the following properties through `ssrContext`: - **url** - `type: string` - `url` refers to the host url where the current request is being made - **event** - `type: HTTP request` - `event` allows access to `res` and `res` object for the current request made to Nuxt page From 82e91f8c436e8d4a9bd22070361bf6a9a5125956 Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:54:36 +0200 Subject: [PATCH 13/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 7856d42f500..6e5ccc6f989 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -168,7 +168,7 @@ export default defineNuxtPlugin((nuxtApp) => { ## Runtime `nuxtApp` hooks -Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue composable and [Nuxt Plugins](/guide/directory-structure/plugins) to hook into the rendering lifecycle. +Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue composable and [Nuxt plugins](/guide/directory-structure/plugins) to hook into the rendering lifecycle. ### hooks From 72af002a2704f5e958faf12458dc7ecf74bfe163 Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:54:42 +0200 Subject: [PATCH 14/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 6e5ccc6f989..2eda154ba1f 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -198,7 +198,7 @@ Hooks available in `nuxtApp` allows you to customize the runtime aspects of your ### hook - `type: function` -`hook` function is useful for adding custom logic by hooking into the rendering lifecycle at a specific point. `hook` function is mostly used in creating Nuxt plugins. +`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. ```js [plugins/test.ts] export default defineNuxtPlugin((nuxtApp) => { From bf2d2be716d5ec7f2f0cc76f91d35bcc05f5fd96 Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:54:47 +0200 Subject: [PATCH 15/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 2eda154ba1f..9d5e5e9a70d 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -206,7 +206,7 @@ export default defineNuxtPlugin((nuxtApp) => { /* your code goes here */ }) nuxtApp.hook('vue:error', (..._args) => { - console.log('vue:error') + console.log('vue:error') // if (process.client) { // console.log(..._args) // } From 483d7799f8f1f6a05461eeb94c4d1548c61fc8e9 Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:56:02 +0200 Subject: [PATCH 16/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 9d5e5e9a70d..7eb48c4b643 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -216,7 +216,7 @@ export default defineNuxtPlugin((nuxtApp) => { ### callhook - `type: function` -`callHook` returns promise when called with any of the existing hooks. +`callHook` returns a promise when called with any of the existing hooks. ```js await nuxtApp.callHook('app:created', vueApp) From decaa0c8f666d04ccb0d3e7cc96e252ef9272665 Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:56:15 +0200 Subject: [PATCH 17/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 7eb48c4b643..340fb22ae78 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -59,7 +59,7 @@ export default defineComponent({ `ssrContext` is generated using runtime `vue-bundle-renderer` for Vue 3 and it is only available on the server side. Nuxt exposes the following properties through `ssrContext`: - **url** - `type: string` - `url` refers to the host url where the current request is being made -- **event** - `type: HTTP request` - `event` allows access to `res` and `res` object for the current request made to Nuxt page +- **event** - `type: HTTP request` - `event` allows access to `req` and `res` objects for the current request made to the Nuxt page - **runtimeConfig** - `type: runtimeConfig object` - `runtimeConfig` exposes runtime config on the client-side via payload - **noSSR** - `type: boolean` - **error** - `type: error object` - returns server-side error if any From 4ac796eb5e1aa50e47b774f2b9e0673441071913 Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:56:34 +0200 Subject: [PATCH 18/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 340fb22ae78..09f034f26d5 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -60,7 +60,7 @@ export default defineComponent({ - **url** - `type: string` - `url` refers to the host url where the current request is being made - **event** - `type: HTTP request` - `event` allows access to `req` and `res` objects for the current request made to the Nuxt page -- **runtimeConfig** - `type: runtimeConfig object` - `runtimeConfig` exposes runtime config on the client-side via payload +- **runtimeConfig** - `type: runtimeConfig object` - `runtimeConfig` exposes runtime config on the client side via payload - **noSSR** - `type: boolean` - **error** - `type: error object` - returns server-side error if any - **payload** - returns NuxtApp payload object - See [payload](#payload) section below for more detail. From 3deed145dc80c5b27576e7e19df87f95b8d6dc29 Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 12:57:03 +0200 Subject: [PATCH 19/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 09f034f26d5..9b729874f99 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -64,7 +64,7 @@ export default defineComponent({ - **noSSR** - `type: boolean` - **error** - `type: error object` - returns server-side error if any - **payload** - returns NuxtApp payload object - See [payload](#payload) section below for more detail. -- **renderMeta** - `type: NuxtMeta` - returns a `Promise` of `NuxtMeta` type that includes HTML, head and body attributes as well as head tags. +- **renderMeta** - `type: NuxtMeta` - returns a `Promise` of `NuxtMeta` type that includes HTML, head and body attributes, as well as head tags. - **teleports** - `type: Record object` - renders content outside of the Vue application > See how the [Vue-meta plugin](https://github.com/nuxt/framework/blob/main/packages/nuxt/src/head/runtime/lib/vue-meta.plugin.ts#L23) on Nuxt uses `renderMeta` in combination with `teleports`. From 9ea602cb16d809342faebd965eaa9a83fae22efe Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 13:22:10 +0200 Subject: [PATCH 20/24] Update docs/content/3.api/1.composables/use-nuxt-app.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- docs/content/3.api/1.composables/use-nuxt-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 9b729874f99..a8e6c941c6e 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -67,7 +67,7 @@ export default defineComponent({ - **renderMeta** - `type: NuxtMeta` - returns a `Promise` of `NuxtMeta` type that includes HTML, head and body attributes, as well as head tags. - **teleports** - `type: Record object` - renders content outside of the Vue application -> See how the [Vue-meta plugin](https://github.com/nuxt/framework/blob/main/packages/nuxt/src/head/runtime/lib/vue-meta.plugin.ts#L23) on Nuxt uses `renderMeta` in combination with `teleports`. +> See how the [`vue-meta` plugin](https://github.com/nuxt/framework/blob/main/packages/nuxt/src/head/runtime/lib/vue-meta.plugin.ts#L23) in Nuxt uses `renderMeta` in combination with `teleports`. ## vueApp From 51b8e08c65e191892fc741b186a46dbc5b3fae1d Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Mon, 22 Aug 2022 13:23:59 +0200 Subject: [PATCH 21/24] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com> --- .../3.api/1.composables/use-nuxt-app.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index a8e6c941c6e..7d757ea30a1 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -74,18 +74,18 @@ export default defineComponent({ `vueApp` is the global Vue application instance that you can access through `nuxtApp`. - **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. -- **config** - exposes a `config` object that contains the configuration settings for that application. +- **config** - exposes a `config` object that contains the configuration settings for the application. - **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. -> See `directive` example: [https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives) +> See `directive` example: [https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives). -- **mixins** - Applies a global `mixin` (scoped to the application). However, it is not recommended to use mixins with the Vue 3. Their sole purpose is only to provide backward compatibility. +- **mixins** - Applies a global `mixin` (scoped to the application). However, it is not recommended to use mixins with the Vue 3. Their sole purpose is to provide backward compatibility. - **mount** - Mounts the application instance in a container element. -- **provide** - Provide a value that can be injected in all descendent components within the application. +- **provide** - Provides a value that can be injected in all descendent components within the application. - **unmount** - Unmounts a mounted application instance, triggering the unmount lifecycle hooks for all components in the application's component tree. - **use** - Installs a **[plugin](https://vuejs.org/guide/reusability/plugins.html)**. -> See `use` example: [https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins) +> See `use` example: [https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins). :ReadMore{link="https://vuejs.org/api/application.html#application-api"} @@ -99,7 +99,7 @@ You can access the Vue router object using `nuxtApp.$router`. ## provide - fn -`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 composable and components. +`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. @@ -113,15 +113,15 @@ nuxtApp.provide('hello', (name) => `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 at all places where `nuxtApp` is accessible. +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. ## State and variables ### $config -`nuxtApp.$config` exposes runtime-config and environment variables on the client-side to the Nuxt app context through two keys: `app` and `public`. +`nuxtApp.$config` exposes a runtime config and environment variables on the client side to the Nuxt app context through two keys: `app` and `public`. -Keys found under `app` and `public` are available on the client-side. +Keys found under `app` and `public` are available on the client side. - **app:** - **baseURL** - `type: string` @@ -129,16 +129,16 @@ Keys found under `app` and `public` are available on the client-side. - **cdnURL** - `type: string` - **public** - `nuxtApp.$config.public` allows you to access the public runtime config that is set in the `nuxt.config` file of your Nuxt app. -> Same `$config` object is accessible through `nuxtApp.payload.config` as well. +> The same `$config` object is also accessible through `nuxtApp.payload.config`. ### payload -`payload` exposes data and state variables from server-side to client-side and make them available in the `window.NUXT` object that is accessible from the browser. +`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 following keys on client-side after they are stringified and passed from the server-side: +`payload` exposes the following keys on the client side after they are stringified and passed from the server side: - **serverRendered** - `type: boolean` -- **data** - `type: record 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 twice. +- **data** - `type: record 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({ @@ -148,9 +148,9 @@ export default defineComponent({ }) ``` -After fetching the value of `count` using `useAsyncData` in the example above, if you access `payload.data`, you will see `{ count: 1 }` recorded there. And the value `count` is updated accordingly as the page count increases. +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. +When accessing the same `payload.data` from [ssrcontext](#ssrcontext), you can access the same value on the server side as well. - **state** - `type: record object` - When you use `useState` composable in Nuxt to set shared state, this state data is accessed through `payload.state.[name-of-your-state]`. From d17bc1dd3980542615d08efa2124f262a7456624 Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Mon, 22 Aug 2022 16:12:12 +0200 Subject: [PATCH 22/24] remove globalName from docs it is not used and modification should be build time --- .../3.api/1.composables/use-nuxt-app.md | 21 ++----------------- 1 file changed, 2 insertions(+), 19 deletions(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 7d757ea30a1..2eb9bff8ecf 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -1,6 +1,6 @@ # `useNuxtApp` -`useNuxtApp` is a built-in composable that provides a shared runtime context, which is available on both client and server side. It helps you access the Vue instance, runtime hooks, runtime config variables and internal states, such as `ssrContext` and `payload`. +`useNuxtApp` is a built-in composable that provides a shared runtime 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`. You can use `useNuxtApp` within composables, plugins and components. @@ -12,23 +12,6 @@ You can use `useNuxtApp` within composables, plugins and components. `useNuxtApp` exposes the following properties that you can use to extend and customize your app and share state, data and variables. -## globalName - -**`type: string`** - -`globalName` allows you to customize the global ID used in the main HTML template, as well as the main Vue instance name and other options. - -The default value of `globalName` is set to `nuxt`, but you can customize it using `nuxtApp.globalName`. - -### Example - -```vue [app.vue] - -``` - ## isHydrating **`type: boolean`** @@ -110,7 +93,7 @@ const nuxtApp = useNuxtApp() nuxtApp.provide('hello', (name) => `Hello ${name}!`) // Prints "Hello name!" -console.log(nuxtApp.$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. From 83b8ad34913e65457aee7104c59cfb93c4d7765e Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Mon, 22 Aug 2022 17:04:09 +0200 Subject: [PATCH 23/24] updates - try to use external docs as possible to avoid duplicate and outdated docs - avoid mentioning internals which can potentially be changed --- .../3.api/1.composables/use-nuxt-app.md | 104 ++++-------------- 1 file changed, 24 insertions(+), 80 deletions(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 2eb9bff8ecf..4786955ee87 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -1,8 +1,8 @@ # `useNuxtApp` -`useNuxtApp` is a built-in composable that provides a shared runtime 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`. +`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. +You can use `useNuxtApp()` within composables, plugins and components. ```vue [app.vue] ``` -`useNuxtApp` exposes the following properties that you can use to extend and customize your app and share state, data and variables. +`useNuxtApp()` exposes the following properties that you can use to extend and customize your app and share state, data and variables. -## isHydrating +## `isHydrating` **`type: boolean`** @@ -23,64 +23,35 @@ You can use `nuxtApp.isHydrating` to check if the Nuxt app is hydrating on the c ```ts [components/nuxt-error-boundary.ts] export default defineComponent({ setup (_props, { slots, emit }) { - // ... const nuxtApp = useNuxtApp() onErrorCaptured((err) => { if (process.client && !nuxtApp.isHydrating) { - emit('error', err) - error.value = err - return false + // ... } }) - // ... } }) ``` -## ssrContext +## `vueApp` -`ssrContext` is generated using runtime `vue-bundle-renderer` for Vue 3 and it is only available on the server side. Nuxt exposes the following properties through `ssrContext`: +`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: -- **url** - `type: string` - `url` refers to the host url where the current request is being made -- **event** - `type: HTTP request` - `event` allows access to `req` and `res` objects for the current request made to the Nuxt page -- **runtimeConfig** - `type: runtimeConfig object` - `runtimeConfig` exposes runtime config on the client side via payload -- **noSSR** - `type: boolean` -- **error** - `type: error object` - returns server-side error if any -- **payload** - returns NuxtApp payload object - See [payload](#payload) section below for more detail. -- **renderMeta** - `type: NuxtMeta` - returns a `Promise` of `NuxtMeta` type that includes HTML, head and body attributes, as well as head tags. -- **teleports** - `type: Record object` - renders content outside of the Vue application - -> See how the [`vue-meta` plugin](https://github.com/nuxt/framework/blob/main/packages/nuxt/src/head/runtime/lib/vue-meta.plugin.ts#L23) in Nuxt uses `renderMeta` in combination with `teleports`. - -## vueApp - -`vueApp` is the global Vue application instance that you can access through `nuxtApp`. - -- **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. -- **config** - exposes a `config` object that contains the configuration settings for the application. -- **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. - -> See `directive` example: [https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives). - -- **mixins** - Applies a global `mixin` (scoped to the application). However, it is not recommended to use mixins with the Vue 3. Their sole purpose is to provide backward compatibility. -- **mount** - Mounts the application instance in a container element. -- **provide** - Provides a value that can be injected in all descendent components within the application. -- **unmount** - Unmounts a mounted application instance, triggering the unmount lifecycle hooks for all components in the application's component tree. -- **use** - Installs a **[plugin](https://vuejs.org/guide/reusability/plugins.html)**. - -> See `use` example: [https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins). +- **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 ([Read More](https://vuejs.org/api/application.html#app-component)). +- **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. ([Read More](https://vuejs.org/api/application.html#app-directive), [Example](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives)). +- **use()** - Installs a **[Vue.js Plugin](https://vuejs.org/guide/reusability/plugins.html)**. ([Read More](https://vuejs.org/api/application.html#app-use), [Example](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins)) :ReadMore{link="https://vuejs.org/api/application.html#application-api"} -## $router +## `ssrContext` -**`type: router object`** +`ssrContext` is generated during server-side rendering and it is only available on the server side. Nuxt exposes the following properties through `ssrContext`: -You can access the Vue router object using `nuxtApp.$router`. +- **`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`** - NuxtApp payload object. -:ReadMore{link="/api/composables/use-router"} - -## provide - fn +## `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. @@ -100,7 +71,7 @@ As you can see in the example above, `$hello` has become the new and custom part ## State and variables -### $config +### `$config` `nuxtApp.$config` exposes a runtime config and environment variables on the client side to the Nuxt app context through two keys: `app` and `public`. @@ -112,9 +83,7 @@ Keys found under `app` and `public` are available on the client side. - **cdnURL** - `type: string` - **public** - `nuxtApp.$config.public` allows you to access the public runtime config that is set in the `nuxt.config` file of your Nuxt app. -> The same `$config` object is also accessible through `nuxtApp.payload.config`. - -### payload +### `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. @@ -149,37 +118,10 @@ export default defineNuxtPlugin((nuxtApp) => { - **config** - Same as the [$config](#config) section above. -## Runtime `nuxtApp` hooks -Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue composable and [Nuxt plugins](/guide/directory-structure/plugins) to hook into the rendering lifecycle. +### `hook(name, cb)` -### hooks - -`nuxtApp` lets you call and add the following runtime hooks: - -```ts -// App related runtime hooks -'app:created': (app: App) => HookResult -'app:beforeMount': (app: App) => HookResult -'app:mounted': (app: App) => HookResult -'app:rendered': (ctx: AppRenderedContext) => HookResult -'app:redirected': () => HookResult -'app:suspense:resolve': (Component?: VNode) => HookResult -'app:error': (err: any) => HookResult -'app:error:cleared': (options: { redirect?: string }) => HookResult -'app:data:refresh': (keys?: string[]) => HookResult - -// Nuxt page related runtime hooks -'page:start': (Component?: VNode) => HookResult -'page:finish': (Component?: VNode) => HookResult -'meta:register': (metaRenderers: Array<(nuxt: NuxtApp) => NuxtMeta | Promise>) => HookResult - -// Vue instance related runtime hooks -'vue:setup': () => void -'vue:error': (...args: Parameters[0]>) => HookResult -``` - -### hook - `type: function` +Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue composable 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. @@ -197,10 +139,12 @@ export default defineNuxtPlugin((nuxtApp) => { }) ``` -### callhook - `type: function` +See [Runtime Hooks](/api/advanced/hooks#app-hooks-runtime) for avialble runtime hooks called by Nuxt. + +### `callhook(name, ...args)` `callHook` returns a promise when called with any of the existing hooks. ```js -await nuxtApp.callHook('app:created', vueApp) +await nuxtApp.callHook('my-plugin:init') ``` From 059abaa4699a9b464779ae9f932ca05992e4eec8 Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Mon, 22 Aug 2022 17:20:57 +0200 Subject: [PATCH 24/24] refactor ordering --- .../3.api/1.composables/use-nuxt-app.md | 143 ++++++++---------- 1 file changed, 64 insertions(+), 79 deletions(-) diff --git a/docs/content/3.api/1.composables/use-nuxt-app.md b/docs/content/3.api/1.composables/use-nuxt-app.md index 4786955ee87..46bb65acce1 100644 --- a/docs/content/3.api/1.composables/use-nuxt-app.md +++ b/docs/content/3.api/1.composables/use-nuxt-app.md @@ -10,87 +10,86 @@ You can use `useNuxtApp()` within composables, plugins and components. ``` -`useNuxtApp()` exposes the following properties that you can use to extend and customize your app and share state, data and variables. +## Methods -## `isHydrating` +### `provide (name, value)` -**`type: boolean`** +`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. -You can use `nuxtApp.isHydrating` to check if the Nuxt app is hydrating on the client side. +`provide` function accepts `name` and `value` parameters. -### Example +**Example:** -```ts [components/nuxt-error-boundary.ts] -export default defineComponent({ - setup (_props, { slots, emit }) { - const nuxtApp = useNuxtApp() - onErrorCaptured((err) => { - if (process.client && !nuxtApp.isHydrating) { - // ... - } - }) - } -}) -``` +```js +const nuxtApp = useNuxtApp() +nuxtApp.provide('hello', (name) => `Hello ${name}!`) -## `vueApp` +// Prints "Hello name!" +console.log(nuxtApp.$hello('name')) +``` -`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: +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. -- **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 ([Read More](https://vuejs.org/api/application.html#app-component)). -- **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. ([Read More](https://vuejs.org/api/application.html#app-directive), [Example](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-directives)). -- **use()** - Installs a **[Vue.js Plugin](https://vuejs.org/guide/reusability/plugins.html)**. ([Read More](https://vuejs.org/api/application.html#app-use), [Example](https://v3.nuxtjs.org/guide/directory-structure/plugins#vue-plugins)) +### `hook(name, cb)` -:ReadMore{link="https://vuejs.org/api/application.html#application-api"} +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. -## `ssrContext` +`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. -`ssrContext` is generated during server-side rendering and it is only available on the server side. Nuxt exposes the following properties through `ssrContext`: +See [Runtime Hooks](/api/advanced/hooks#app-hooks-runtime) for avialble runtime hooks called by Nuxt. -- **`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`** - NuxtApp payload object. +```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) + // } + }) +}) +``` -## `provide(name, value)` +### `callhook(name, ...args)` -`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. +`callHook` returns a promise when called with any of the existing hooks. -`provide` function accepts `name` and `value` parameters. +```js +await nuxtApp.callHook('my-plugin:init') +``` -### Example +## Properties -```js -const nuxtApp = useNuxtApp() -nuxtApp.provide('hello', (name) => `Hello ${name}!`) +`useNuxtApp()` exposes the following properties that you can use to extend and customize your app and share state, data and variables. -// Prints "Hello name!" -console.log(nuxtApp.$hello('name')) -``` +### `vueApp` -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. +`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: -## State and variables +- [**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). -### `$config` +:ReadMore{link="https://vuejs.org/api/application.html#application-api"} -`nuxtApp.$config` exposes a runtime config and environment variables on the client side to the Nuxt app context through two keys: `app` and `public`. +### `ssrContext` -Keys found under `app` and `public` are available on the client side. +`ssrContext` is generated during server-side rendering and it is only available on the server side. Nuxt exposes the following properties through `ssrContext`: -- **app:** - - **baseURL** - `type: string` - - **buildAssetsDir** - `type: string` - - **cdnURL** - `type: string` -- **public** - `nuxtApp.$config.public` allows you to access the public runtime config that is set in the `nuxt.config` file of your Nuxt app. +- **`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 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** - `type: boolean` -- **data** - `type: record 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. +- **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({ @@ -104,7 +103,7 @@ After fetching the value of `count` using `useAsyncData` in the example above, i When accessing the same `payload.data` from [ssrcontext](#ssrcontext), you can access the same value on the server side as well. -- **state** - `type: record object` - When you use `useState` composable in Nuxt to set shared state, this state data is accessed through `payload.state.[name-of-your-state]`. +- **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('color', () => 'pink') @@ -116,35 +115,21 @@ export default defineNuxtPlugin((nuxtApp) => { }) ``` -- **config** - Same as the [$config](#config) section above. - - -### `hook(name, cb)` +### `isHydrating` -Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue composable and [Nuxt plugins](/guide/directory-structure/plugins) to hook into the rendering lifecycle. +You can use `nuxtApp.isHydrating` (boolean) to check if the Nuxt app is hydrating on the client side. -`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. +**Example:** -```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) - // } - }) +```ts [components/nuxt-error-boundary.ts] +export default defineComponent({ + setup (_props, { slots, emit }) { + const nuxtApp = useNuxtApp() + onErrorCaptured((err) => { + if (process.client && !nuxtApp.isHydrating) { + // ... + } + }) + } }) ``` - -See [Runtime Hooks](/api/advanced/hooks#app-hooks-runtime) for avialble runtime hooks called by Nuxt. - -### `callhook(name, ...args)` - -`callHook` returns a promise when called with any of the existing hooks. - -```js -await nuxtApp.callHook('my-plugin:init') -```