From 9ef94d19f733eca5f457eb30f29d2745152092ce Mon Sep 17 00:00:00 2001
From: pooya parsa <pyapar@gmail.com>
Date: Thu, 27 Jan 2022 18:02:42 +0100
Subject: [PATCH] docs: add advanced section for module authors (#2950)

---
 docs/content/3.docs/1.usage/4.nuxt-app.md     |  36 ---
 .../3.docs/2.directory-structure/8.modules.md |  98 --------
 docs/content/3.docs/4.advanced/1.nuxt.md      |  77 +++++++
 docs/content/3.docs/4.advanced/2.modules.md   | 214 ++++++++++++++++++
 docs/content/3.docs/4.advanced/3.kit.md       | 124 ++++++++++
 docs/content/3.docs/4.advanced/4.hooks.md     |  63 ++++++
 6 files changed, 478 insertions(+), 134 deletions(-)
 delete mode 100644 docs/content/3.docs/2.directory-structure/8.modules.md
 create mode 100644 docs/content/3.docs/4.advanced/1.nuxt.md
 create mode 100644 docs/content/3.docs/4.advanced/2.modules.md
 create mode 100644 docs/content/3.docs/4.advanced/3.kit.md
 create mode 100644 docs/content/3.docs/4.advanced/4.hooks.md

diff --git a/docs/content/3.docs/1.usage/4.nuxt-app.md b/docs/content/3.docs/1.usage/4.nuxt-app.md
index 090498cbf4..a5b9a63fa4 100644
--- a/docs/content/3.docs/1.usage/4.nuxt-app.md
+++ b/docs/content/3.docs/1.usage/4.nuxt-app.md
@@ -39,39 +39,3 @@ In Nuxt 2 plugins, this was referred to as [inject function](https://nuxtjs.org/
 ::alert{icon=👉}
 It is possible to inject helpers by returning an object with a `provide` key. See the [plugins documentation](/docs/directory-structure/plugins) for more information.
 ::
-
-## NuxtApp interface (advanced)
-
-`nuxtApp` has the following properties: (note: this is an internal interface and some properties might change until stable release)
-
-```js
-const nuxtApp = {
-  vueApp, // 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/8.modules.md b/docs/content/3.docs/2.directory-structure/8.modules.md
deleted file mode 100644
index ece052b5d5..0000000000
--- a/docs/content/3.docs/2.directory-structure/8.modules.md
+++ /dev/null
@@ -1,98 +0,0 @@
----
-icon: IconDirectory
-title: 'modules'
-navigation: false
-head.title: Local modules directory
----
-
-# Local modules directory
-
-Nuxt has a powerful modules engine.
-
-# Creating Modules
-
-Nuxt provides helper functions (accessed from `@nuxt/kit`) to assist in creating modules that can run on both Nuxt 2 and Nuxt 3.
-
-```js
-import { defineNuxtModule } from '@nuxt/kit'
-
-export default defineNuxtModule({
-  meta: {
-    // The npm package name of your module
-    name: '@nuxtjs/sample-module',
-    // The key in `nuxt.config` that holds your module options
-    configKey: 'sample',
-  },
-  // Default configuration options for your module
-  defaults: {},
-  hooks: {},
-  setup (options, nuxt) {},
-})
-```
-
-## Module options
-
-Nuxt will automatically merge the configuration provided to your module (whether passed directly inline or in a configuration section in `nuxt.config`) with the defaults you provide.
-
-```js
-export default {
-  buildModules: [
-    ['@nuxtjs/sample-module', { sampleOption: true }]
-  ],
-  sample: {
-    anotherOption: 42
-  }
-}
-```
-
-## Hooks
-
-For simple modules, you may be able to implement all you need simply with several hooks in this section.
-
-## Setup
-
-If the `hooks` configuration is not enough, you can provide a full setup function, with access to `nuxt`. You will no longer have access to `this` as in the previous Nuxt module specification, but there are dedicated helper functions from `@nuxt/kit` to replace the module container methods from previously.
-
-```js
-import { defineNuxtModule, addPlugin } from '@nuxt/kit'
-
-export default defineNuxtModule({
-  // ...
-  setup (options, nuxt) {
-    addPlugin({
-      src: path.resolve(__dirname, 'templates/foo.js')
-    })
-  },
-})
-```
-
-## Advanced usage
-
-In some cases you may need access to the Nuxt instance in order to define your module, for example, using other Nuxt options:
-
-```js
-import { defineNuxtModule } from '@nuxt/kit'
-
-export default defineNuxtModule(nuxt => ({
-  // ...
-  defaults: {
-    root: nuxt.options.rootDir
-  },
-}))
-```
-
-## Module helpers
-
-A number of helpers are also provided for use within this context (with more coming - feature requests welcome) that ensure compatible behavior across Nuxt versions.
-
-* addTemplate
-* addErrorLayout
-* addLayout
-* addPlugin
-* addServerMiddleware
-* extendBuild
-* extendRoutes
-
-Each of these functions provides documentation via IDE hover/autocomplete.
-
-## Publishing to NPM
diff --git a/docs/content/3.docs/4.advanced/1.nuxt.md b/docs/content/3.docs/4.advanced/1.nuxt.md
new file mode 100644
index 0000000000..1498fc8395
--- /dev/null
+++ b/docs/content/3.docs/4.advanced/1.nuxt.md
@@ -0,0 +1,77 @@
+# Nuxt Internals
+
+Nuxt is a minimal but highly customizable framework to build web applications. This guide helps you better understand Nuxt internals to develop new solutions and module integrations on top of Nuxt.
+
+## The Nuxt interface
+
+When you start nuxt in development mode with `nuxi dev` or building a production application with `nuxi build`,
+a common context will be created, referred to as `nuxt` internally. It holds normalized options merged with `nuxt.config` file,
+some internal state, and a powerful [hooking system](/docs/advanced/hooks) powered by [unjs/hookable](https://github.com/unjs/hookable)
+allowing different components to communicate with each other. You can think of it as **Builder Core**.
+
+This context is globally available to be used with [nuxt/kit](/docs/advanced/kit) composables.
+Therefore only one instance of Nuxt is allowed to run per process.
+
+To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt Modules](/docs/advanced/modules).
+
+For more details, check out [the source code](https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/core/nuxt.ts).
+
+## The NuxtApp interface
+
+When rendering a page in Browser or server-side, a shared context will be created, referred to as `nuxtApp`.
+This context keeps vue instance, runtime hooks, and internal states like ssrContext and payload for hydration.
+You can think of it as **Runtime Core**.
+
+This context can be accessed using `useNuxtApp()` composable within nuxt plugins and `<script setup>` and vue composables.
+Global usage is only possible for Browser but not possible on the server-side to avoid sharing context between users.
+
+To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/directory-structure/plugins).
+
+Check [Nuxt App](http://localhost:4000/docs/usage/nuxt-app) for more information about this interface.
+
+`nuxtApp` has the following properties:
+
+Note: this is an internal interface, and some properties might change until stable release.
+
+```js
+const nuxtApp = {
+  vueApp, // 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 details, check out [the source code](https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/app/nuxt.ts).
+
+## Runtime Context vs. Build Context
+
+Nuxt builds and bundles project using Node.js but also has a runtime side.
+
+While both areas can be extended, that runtime context is isolated from build-time. Therefore, they are not supposed to share state, code, or context other than runtime configuration!
+
+`nuxt.config` and [Nuxt Modules](/docs/advanced/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/directory-structure/plugins) can be used to extend runtime.
+
+When building an application for production `nuxi build`  will generate a standalone build
+ in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/advanced/modules).
diff --git a/docs/content/3.docs/4.advanced/2.modules.md b/docs/content/3.docs/4.advanced/2.modules.md
new file mode 100644
index 0000000000..4e148231ed
--- /dev/null
+++ b/docs/content/3.docs/4.advanced/2.modules.md
@@ -0,0 +1,214 @@
+# Nuxt Modules
+
+Nuxt provides a zero-config experience with a preset of integrations and best practices to develop Web applications.
+A powerful configuration and hooks system makes it possible to customize almost every aspect of Nuxt Framework and add endless possible integrations when it comes to customization. You can learn more about how nuxt works in [Nuxt internals](/docs/advanced/nuxt) section.
+
+Nuxt exposes a powerful API called **Nuxt Modules**. Nuxt modules are simple async functions that sequentially run when starting nuxt in development mode using `nuxi dev` or building a project for production with `nuxi build`.
+Using Nuxt Modules, we can encapsulate, properly test and share custom solutions as npm packages without adding unnecessary boilerplate to the Nuxt project itself.
+Nuxt Modules can hook into lifecycle events of Nuxt builder, provide runtime app templates, update the configuration or do any other custom action based on needs.
+
+## Quick Start
+
+For the impatient ones, You can quickly start with [module-builder](https://github.com/nuxt/module-builder) and [module starter template](https://github.com/nuxt/starter/tree/module):
+
+```bash
+npx nuxi init -t module my-module
+```
+
+Starter template and module starter is a standard path of creating a Nuxt module.
+
+**Next steps:**
+
+- Open `my-module` in IDE of your choice (VSCode is recommended)
+- Install dependencies using the package manager of your choice (Yarn is recommended)
+- Ensure local files are generated using `npm run prepare`
+- Start playground using `npm run dev`
+- **Follow this document to learn more about Nuxt modules**
+
+::alert{type=warning icon=🚧}
+This is an under-the-progress guide. Please regularly check for updates.
+::
+
+## Module Anatomy
+
+A Nuxt module is a simple function accepting inline user options and `nuxt` arguments.
+
+It is totally up to you, as the module author, how to handle the rest of the logic.
+
+Starting with Nuxt 3, modules can benefit all [Nuxt Kit](/docs/advanced/kit) utilities.
+
+```ts [modules/example.ts]
+// modules/module.mjs
+export default async (inlineOptions, nuxt) => {
+  // You can do whatever you like here..
+  console.log(moduleOptions.token) // `123`
+  console.log(nuxt.options.dev) // `true` or `false`
+  nuxt.hook('ready', async nuxt => {
+    console.log('Nuxt is ready')
+  })
+}
+```
+
+```ts [nuxt.config]
+export default defineNuxtConfig({
+  modules: [
+    // Using package name (recommanded usage)
+    '@nuxtjs/example',
+
+    // Load a local module
+    './modules/example',
+
+    // Add module with inline-options
+    ['./modules/example', { token: '123' }]
+
+    // Inline module definition
+    async (inlineOptions, nuxt) => { }
+  ]
+})
+```
+
+## Defining Nuxt Modules
+
+Creating Nuxt modules involves tedious and common tasks. [Nuxt Kit](/docs/advanced/kit), provides a convenient and standard API to define Nuxt modules using `defineNuxtModule`:
+
+```js
+export default defineNuxtModule({
+  meta: {
+    // Usually  npm package name of your module
+    name: '@nuxtjs/example',
+    // The key in `nuxt.config` that holds your module options
+    configKey: 'sample',
+    // Compatibility constraints
+    compatibility: {
+      // Semver version of supported nuxt versions
+      nuxt: '^3.0.0'
+    }
+  },
+  // Default configuration options for your module
+  defaults: {},
+  hooks: {},
+  async setup(moduleOptions, nuxt) {
+    // -- Add your module logic here --
+  }
+})
+```
+
+Result of `defineNuxtModule` is a wrapper function with `(inlineOptions, nuxt)` signature. It applies defaults and other necessary steps and calls the`setup` function when called.
+
+**`defineNuxtModule` features:**
+
+- Support `defaults` and `meta.configKey` for automatically merging module options
+- Type hints and automated type inference
+- Add shims for basic Nuxt 2 compatibility
+- Ensure module get's installed only once using a unique key computed from `meta.name` or `meta.configKey`
+- Automatically register Nuxt hooks
+- Automatically check for compatibility issues based on module meta
+- Expose `getOptions` and `getMeta` for internal usage of Nuxt
+- Ensuring backward and upward compatibility as long as the module is using `defineNuxtmodule` from the latest version of `@nuxt/kit`
+- Integration with module builder tooling
+
+## Best practices
+
+### Async Modules
+
+Nuxt Modules can do asynchronous operations. For example, you may want to develop a module that needs fetching some API or calling an async function.
+
+::alert{type="warning"}
+Be careful that `nuxi dev` waits for your module setup before going to the next module and starting the development server. Do time-consuming logic using deferred Nuxt hooks.
+::
+
+### Always prefix exposed interfaces
+
+Nuxt Modules should provide an explicit prefix for any exposed configuration, plugin, API, composable, or component to avoid conflict with other modules and internals.
+
+Ideally you should prefix them with your module name (If your module is called `nuxt-foo`, expose `<FooButton>` and `useFooBar()` and **not** `<Foo>` and `useBar()`)
+
+### Be Typescript Friendly
+
+Nuxt 3, has first-class typescript integration for the best developer experience.
+
+Exposing types and using typescript to develop modules can benefit users even when not using typescript directly.
+
+### Avoid CommonJS syntax
+
+Nuxt 3, relies on native ESM. Please read [/concepts/esm](/concepts/esm) for more information.
+
+## Modules Ecosystem
+
+Nuxt tends to have a healthy and rich ecosystem of Nuxt modules and integrations. Here are some best practices if you want to jump in and contribute!
+
+### Document Module Usage
+
+Consider documenting module usage in the readme file:
+
+- Why use this module
+- How to use this module
+- What this module does?
+
+Linking to the integration website and documentation is always a good idea.
+
+### Use `nuxt-` prefix for npm packages
+
+To make your modules discoverable, use `nuxt-` prefix for the npm package name. This is always the best starting point to draft and try an idea!
+
+### Listing module to modules.nuxtjs.org
+
+Do you have a working Module and want it listed in [modules.nuxtjs.org](modules.nuxtjs.org)? Open an issue in [nuxt/modules](https://github.com/nuxt/modules/issues/new) repository.
+Nuxt team can help you to apply best practices before listing.
+
+### Do not advertise with a specific Nuxt version
+
+Nuxt 3, Nuxt Kit, and other new toolings are made to have both forward and backward compatibility in mind.
+
+Please use "X for Nuxt" instead of "X for Nuxt 3" to avoid fragmentation in the ecosystem and prefer using `meta.compatibility` to set Nuxt version constraints.
+
+### Joining nuxt-community
+
+By moving your modules to [nuxt-community](https://github.com/nuxt-community), there is always someone else to help, and this way, we can join forces to make one perfect solution.
+
+If you have an already published and working module and want to transfer it to nuxt-community, open an issue in [nuxt/modules](https://github.com/nuxt/modules/issues/new).
+
+## Examples
+
+### Provide Nuxt Plugins
+
+Commonly, modules provide one or more run plugins to add runtime logic.
+
+```ts
+import { resolve } from 'path'
+import { fileURLToPath } from 'url'
+import { defineNuxtModule, addPlugin } from '@nuxt/kit'
+
+export default defineNuxtModule<ModuleOptions>({
+  setup (options, nuxt) {
+    const runtimeDir = fileURLToPath(new URL('./runtime', import.meta.url))
+    addPlugin(resolve(runtimeDir, 'plugin'))
+  }
+})
+```
+
+### Add a CSS Library
+
+If your module will provide a CSS library, make sure to check if the user already included the library to avoid duplicates and add an option to disable the CSS library in the module.
+
+```ts
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    nuxt.options.css.push('font-awesome/css/font-awesome.css')
+  }
+})
+```
+
+### Cleanup Module
+
+If your module opens handles or starts a watcher, we should close it when the nuxt lifecycle is done. For this, we can use the `close` hook:
+
+```ts
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    nuxt.hook('close', async nuxt => {
+      // Your custom code here
+    })
+  }
+})
+```
diff --git a/docs/content/3.docs/4.advanced/3.kit.md b/docs/content/3.docs/4.advanced/3.kit.md
new file mode 100644
index 0000000000..fdda9b8ef6
--- /dev/null
+++ b/docs/content/3.docs/4.advanced/3.kit.md
@@ -0,0 +1,124 @@
+# Nuxt Kit
+
+> Nuxt Kit provides composable utilities to make interacting with [/docs/advanced/hooks](Nuxt Hooks) and [Nuxt Builder Core](/docs/advanced/nuxt#the-nuxt-interface) and developing [Nuxt Modules](/docs/advanced/modules) super easy!
+
+## Usage
+
+### Install dependency
+
+You can install the latest nuxt kit by adding it to `dependencies` of `package.json`. However, please consider always explicitly installing the `@nuxt/kit` package even if it is already installed by nuxt.
+
+```json [package.json]
+{
+  "dependencies": {
+    "@nuxt/kit": "npm:@nuxt/kit-edge@latest"
+  }
+}
+```
+
+### Import kit utilities
+
+```js [test.mjs]
+import { useNuxt } from '@nuxt/kit'
+```
+
+::alert{type="warning"}
+Nuxt kit utilities are only available for modules and not meant to be imported in runtime (components, vue composables, pages, plugins, or server routes)
+::
+
+Nuxt kit, is an [esm-only package](/concepts/esm) meaning you **cannot** `require('@nuxt/kit')`. As a workaround, we can use dynamic import to use it in the CommonJS context:
+
+```js [test.cjs]
+// This does NOT work!
+// const kit = require('@nuxt/kit')
+async function main() {
+  const kit = await import('@nuxt/kit')
+}
+main()
+```
+
+### Use kit utilities
+
+Nuxt context is globally available using [unjs/unctx](https://github.com/unjs/unctx). Because of this, most kit composables do not need to have `nuxt` instances explicitly passed.
+
+```js [test.mjs]
+import { getNuxtVersion } from '@nuxt/kit'
+
+// 3.0.0
+console.log(getNuxtVersion())
+```
+
+## Utilities
+
+### Modules
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/module)
+
+- `installModule(module, inlineOptions)`
+
+### Programmatic usage
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/loader)
+
+- `loadNuxt(loadOptions)`
+- `buildNuxt(nuxt)`
+- `loadNuxtConfig(loadOptions)`
+
+### Compatibility
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/compatibility.ts)
+
+- `checkNuxtCompatibility(constraints)`
+- `assertNuxtCompatibility(constraints)`
+- `hasNuxtCompatibility(constraints)`
+- `isNuxt2()`
+- `isNuxt3()`
+- `getNuxtVersion()`
+
+### Components
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/components.ts)
+
+- `addComponentsDir(dir)`
+- `addComponent(componentObject)`
+
+### Context
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/context.ts)
+
+- `useNuxt()`
+
+### Plugins
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/plugin.ts)
+
+- `addPlugin(pluginOptions, { append? })`
+- `addPluginTemplate(pluginOptions, { append? })`
+
+### Templates
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/template.ts)
+
+- `addTemplate(templateOptions)`
+
+### Server
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/server.ts)
+
+- `addServerMiddleware(serverMiddleware)`
+
+### Resolving
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/resolve.ts)
+
+- `resolvePath (path, resolveOptions?)`
+- `tryResolvePath (path, resolveOptions?)`
+
+### Builder
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/build.ts)
+
+- `extendWebpackConfig(callback, options?)`
+- `extendViteConfig(callback, options?)`
+- `addWebpackPlugin(webpackPlugin, options?)`
+- `addVitePlugin(vitePlugin, options?)`
diff --git a/docs/content/3.docs/4.advanced/4.hooks.md b/docs/content/3.docs/4.advanced/4.hooks.md
new file mode 100644
index 0000000000..ae92149348
--- /dev/null
+++ b/docs/content/3.docs/4.advanced/4.hooks.md
@@ -0,0 +1,63 @@
+# Lifecycle Hooks
+
+Nuxt provides a powerful hooking system to expand almost every aspect using hooks powered by [unjs/hookable](https://github.com/unjs/hookable).
+
+## Nuxt Hooks
+
+This hooks are available for [Nuxt Modules](/docs/advanced/modules) and build context.
+
+### Usage with `nuxt.config`
+
+```js [nuxt.config]
+export default defineNuxtConfig({
+  hooks: {
+    'close': () => { }
+  }
+})
+```
+
+### Usage with Nuxt Modules
+
+```js
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    nuxt.hook('close', async () => { })
+  })
+})
+```
+
+### Available hooks
+
+Check the [source code](https://github.com/nuxt/framework/blob/main/packages/schema/src/types/hooks.ts#L55) for all available hooks.
+
+## Runtime Hooks
+
+App hooks can be mainly used by [Nuxt Plugins] (/docs/directory-structure/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
+
+### Usage with Modules
+
+```js [plugins/test.ts]
+export defineNuxtPlugin(nuxtApp) {
+  nuxtApp.hook('page:start', () => { })
+}
+```
+
+### Available hooks
+
+Check the [source code](https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/app/nuxt.ts#L18) for all available hooks.
+
+**Note:** Please note
+
+Hook                   | Arguments         | Description
+-----------------------|-------------------|---------------
+`app:created`          | `vueApp`          | When initial `vueApp` instance is created
+`app:beforeMount`      | `vueApp`          | Same as `app:created`
+`app:mounted`          | `vueApp`          | When Vue app is initialized and mounted in browser
+`app:rendered`         | -                 | When SSR rendering is done
+`app:suspense:resolve` | `appComponent`    | On [Suspense](https://v3.vuejs.org/guide/migration/suspense.html) resolved event
+`page:start`           | `pageComponent`   | On [Suspense](https://v3.vuejs.org/guide/migration/suspense.html) pending event
+`page:finish`          | `pageComponent`   | On [Suspense](https://v3.vuejs.org/guide/migration/suspense.html) resolved event
+`meta:register`        | `metaRenderers`   | (internal)
+`vue:setup`            | -                 | (internal)