docs: add nuxtApp and plugin docs (#1024)

Co-authored-by: Pooya Parsa <pyapar@gmail.com>

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).

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
+  }
+}
+```

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"