diff --git a/docs/content/3.docs/1.usage/4.nuxt-app.md b/docs/content/3.docs/1.usage/4.nuxt-app.md new file mode 100644 index 0000000000..f825ba1499 --- /dev/null +++ b/docs/content/3.docs/1.usage/4.nuxt-app.md @@ -0,0 +1,70 @@ +# NuxtApp + +In Nuxt 3, you can access runtime app context within composables, components, and plugins. + +In Nuxt 2, this was referred to as [nuxt context](https://nuxtjs.org/docs/internals-glossary/context#the-context) + +## Accessing NuxtApp + +Within composables, plugins and components you can access `nuxtApp` with `useNuxtApp`: + +```js +import { useNuxtApp } from '#app' + +function useMyComposable () { + const nuxtApp = useNuxtApp() + // access runtime nuxt app instance +} +``` + +Plugins also receive `nuxtApp` as the first argument for convenience. [Read more about plugins.](/docs/directory-structure/plugins) + + +## Providing helpers + +You can provide helpers to be usable across all composables and application. This usually happens within a nuxt plugin. + +```js +const nuxtApp = useNuxtApp() +nuxtApp.provide('hello', (name) => `Hello ${name}!`) + +console.log(nuxtApp.$hello('name')) // Prints "Hello name!" +``` + +In Nuxt 2 plugins, this was referred to as [inject function](https://nuxtjs.org/docs/directory-structure/plugins#inject-in-root--context) + +## NuxtApp interface (advanced) + +`nuxtApp` has the following prperties: (note: this is an internal interface and some properties might change until stable release) + +```js +const nuxtApp = { + app, // the global Vue application: https://v3.vuejs.org/api/application-api.html + + // These let you call and add runtime NuxtApp hooks + // https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/app/nuxt.ts#L18 + hooks, + hook, + callHook, + + // Only accessible on server-side + ssrContext: { + url, + req, + res, + runtimeConfig, + noSSR, + }, + + // This will be stringified and passed from server to client + payload: { + serverRendered: true, + data: {}, + state: {} + } + + provide: (name: string, value: any) => void +} +``` + +For more information, check out [the source code](https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/app/nuxt.ts#L28-L53). diff --git a/docs/content/3.docs/2.directory-structure/10.plugins.md b/docs/content/3.docs/2.directory-structure/10.plugins.md index 5485afb44b..0edfca9d5a 100644 --- a/docs/content/3.docs/2.directory-structure/10.plugins.md +++ b/docs/content/3.docs/2.directory-structure/10.plugins.md @@ -4,6 +4,40 @@ title: 'plugins' head.title: Plugins directory --- -# plugins directory +# Plugins directory Nuxt will automatically read the files in your `plugins` directory and load them. You can use `.server` or `.client` in the file name to load a plugin just on server- or client-side. + +::alert{type=warning} +All plugins in your `plugins/` directory are auto-registered, so you should not add them to your `nuxt.config` separately. +:: + +## Creating plugins + +The only argument passed to a plugin is [`nuxtApp`]((/usage/nuxt-app) + +```ts +import { defineNuxtPlugin } from '#app' + +export default defineNuxtPlugin(nuxtApp => { + // Doing something with nuxtApp +}) +``` + +## Typing plugins + +If you provide a global property on the nuxt app instance, you can declare the type of this property like this: + +```ts +import { defineNuxtPlugin } from '#app' + +export default defineNuxtPlugin(nuxtApp => { + nuxtApp.provide('hello', msg => `Hello ${msg}!`); +}) + +declare module '#app' { + interface NuxtApp { + $hello (msg: string): string + } +} +``` diff --git a/docs/yarn.lock b/docs/yarn.lock index 731120126f..9c405e78fa 100644 --- a/docs/yarn.lock +++ b/docs/yarn.lock @@ -6578,7 +6578,7 @@ json5@^1.0.1: dependencies: minimist "^1.2.0" -json5@^2.1.1, json5@^2.1.2: +json5@^2.1.1, json5@^2.1.2, json5@^2.2.0: version "2.2.0" resolved "https://registry.yarnpkg.com/json5/-/json5-2.2.0.tgz#2dfefe720c6ba525d9ebd909950f0515316c89a3" integrity sha512-f+8cldu7X/y7RAJurMEJmdoKXGB/X550w2Nr3tTbezL6RwEE/iMcm+tZnXeoZtKuOq6ft8+CqzEkrIgx1fPoQA== @@ -8172,6 +8172,13 @@ pkg-dir@^3.0.0: dependencies: find-up "^3.0.0" +pkg-types@^0.1.3: + version "0.1.5" + resolved "https://registry.yarnpkg.com/pkg-types/-/pkg-types-0.1.5.tgz#8e1740454561cebcb1037b728148f6d7b9442f28" + integrity sha512-EyZ8oKXlLv6YhW/6dbU25ei2MVr8yRd6NPh5CLH+vtTHUMKsKwYfpu02BszZYXGSn+LGc9dCVYWmc37vDWuJQQ== + dependencies: + json5 "^2.2.0" + plausible-tracker@^0.3.1: version "0.3.1" resolved "https://registry.yarnpkg.com/plausible-tracker/-/plausible-tracker-0.3.1.tgz#dd4e1f59cafc7bf1b00e30890567287b3f204efd"