From 198f9a23ec7e091fa0aea2f089c4098c5bda9073 Mon Sep 17 00:00:00 2001
From: Lucas <lucasdraichi@gmail.com>
Date: Sun, 5 Feb 2023 09:17:15 -0300
Subject: [PATCH] docs(schema): add NuxtHooks interface documentation (#18756)

---
 docs/3.api/4.advanced/1.hooks.md   |  46 +++++-
 packages/schema/src/types/hooks.ts | 215 +++++++++++++++++++++++++++++
 2 files changed, 260 insertions(+), 1 deletion(-)

diff --git a/docs/3.api/4.advanced/1.hooks.md b/docs/3.api/4.advanced/1.hooks.md
index b7d648ff02..02acc61d52 100644
--- a/docs/3.api/4.advanced/1.hooks.md
+++ b/docs/3.api/4.advanced/1.hooks.md
@@ -33,7 +33,51 @@ Hook                   | Arguments           | Environment     | Description
 
 Check the [schema source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/types/hooks.ts#L53) for all available hooks.
 
-:NeedContribution
+Hook                     | Arguments                  | Description
+-------------------------|----------------------------|-------------
+`kit:compatibility`      | `compatibility, issues`    | Allows extending compatibility checks.
+`ready`                  | `nuxt`                     | Called after Nuxt initialization, when the Nuxt instance is ready to work.
+`close`                  | `nuxt`                     | Called when Nuxt instance is gracefully closing.
+`modules:before`         | -                          | Called during Nuxt initialization, before installing user modules.
+`modules:done`           | -                          | Called during Nuxt initialization, after installing user modules.
+`app:resolve`            | `app`                      | Called after resolving the `app` instance.
+`app:templates`          | `app`                      | Called during `NuxtApp` generation, to allow customizing, modifying or adding new files to the build directory (either virtually or to written to `.nuxt`).
+`app:templatesGenerated` | `app`                      | Called after templates are compiled into the [virtual file system](https://nuxt.com/docs/guide/directory-structure/nuxt#virtual-file-system) (vfs).
+`build:before`           | -                          | Called before Nuxt bundle builder.
+`build:done`             | -                          | Called after Nuxt bundle builder is complete.
+`build:manifest`         | `manifest`                 | Called during the manifest build by Vite and Webpack. This allows customizing the manifest that Nitro will use to render `<script>` and `<link>` tags in the final HTML.
+`builder:generateApp`    | `options`                  | Called before generating the app.
+`builder:watch`          | `event, path`              | Called at build time in development when the watcher spots a change to a file or directory in the project.
+`pages:extend`           | `pages`                    | Called after pages routes are resolved.
+`server:devHandler`      | `handler`                  | Called when the dev middleware is being registered on the Nitro dev server.
+`imports:sources`        | `presets`                  | Called at setup allowing modules to extend sources.
+`imports:extend`         | `imports`                  | Called at setup allowing modules to extend imports.
+`imports:context`        | `context`                  | Called when the [unimport](https://github.com/unjs/unimport) context is created.
+`imports:dirs`           | `dirs`                     | Allows extending import directories.
+`components:dirs`        | `dirs`                     | Called within `app:resolve` allowing to extend the directories that are scanned for auto-importable components.
+`components:extend`      | `components`               | Allows extending new components.
+`nitro:config`           | `nitroConfig`              | Called before initializing Nitro, allowing customization of Nitro's configuration.
+`nitro:init`             | `nitro`                    | Called after Nitro is initialized, which allows registering Nitro hooks and interacting directly with Nitro.
+`nitro:build:before`     | `nitro`                    | Called before building the Nitro instance.
+`prerender:routes`       | `ctx`                      | Allows extending the routes to be pre-rendered.
+`build:error`            | `error`                    | Called when an error occurs at build time.
+`prepare:types`          | `options`                  | Called before Nuxi writes `.nuxt/tsconfig.json` and `.nuxt/nuxt.d.ts`, allowing addition of custom references and declarations in `nuxt.d.ts`, or directly modifying the options in `tsconfig.json`
+`listen`                 | `listenerServer, listener` | Called when the dev server is loading.
+`schema:extend`          | `schemas`                  | Allows extending default schemas.
+`schema:resolved`        | `schema`                   | Allows extending resolved schema.
+`schema:beforeWrite`     | `schema`                   | Called before writing the given schema.
+`schema:written`         | -                          | Called after the schema is written.
+`vite:extend`            | `viteBuildContext`         | Allows to extend Vite default context.
+`vite:extendConfig`      | `viteInlineConfig, env`    | Allows to extend Vite default config.
+`vite:serverCreated`     | `viteServer, env`          | Called when the Vite server is created.
+`vite:compiled`          | -                          | Called after Vite server is compiled.
+`webpack:config`         | `webpackConfigs`           | Called before configuring the webpack compiler.
+`webpack:compile`        | `options`                  | Called right before compilation.
+`webpack:compiled`       | `options`                  | Called after resources are loaded.
+`webpack:change`         | `shortPath`                | Called on `change` on WebpackBar.
+`webpack:error`          | -                          | Called on `done` if has errors on WebpackBar.
+`webpack:done`           | -                          | Called on `allDone` on WebpackBar.
+`webpack:progress`       | `statesArray`              | Called on `progress` on WebpackBar.
 
 # Nitro App Hooks (runtime, server-side)
 
diff --git a/packages/schema/src/types/hooks.ts b/packages/schema/src/types/hooks.ts
index f9ab2d6519..6b882387c2 100644
--- a/packages/schema/src/types/hooks.ts
+++ b/packages/schema/src/types/hooks.ts
@@ -47,72 +47,287 @@ export interface GenerateAppOptions {
   filter?: (template: ResolvedNuxtTemplate<any>) => boolean
 }
 
+/**
+ * The listeners to Nuxt build time events
+ */
 export interface NuxtHooks {
   // Kit
+  /**
+   * Allows extending compatibility checks.
+   * @param compatibility Compatibility object
+   * @param issues Issues to be mapped
+   * @returns Promise
+   */
   'kit:compatibility': (compatibility: NuxtCompatibility, issues: NuxtCompatibilityIssues) => HookResult
 
   // Nuxt
+  /** 
+   * Called after Nuxt initialization, when the Nuxt instance is ready to work.
+   * @param nuxt The configured Nuxt object
+   * @returns Promise
+   */
   'ready': (nuxt: Nuxt) => HookResult
+  /**
+   * Called when Nuxt instance is gracefully closing.
+   * @param nuxt The configured Nuxt object
+   * @returns Promise
+   */
   'close': (nuxt: Nuxt) => HookResult
 
+  /**
+   * Called during Nuxt initialization, before installing user modules.
+   * @returns Promise
+   */
   'modules:before': () => HookResult
+  /**
+   * Called during Nuxt initialization, after installing user modules.
+   * @returns Promise
+   */
   'modules:done': () => HookResult
 
+  /**
+   * Called after resolving the `app` instance.
+   * @param app The resolved `NuxtApp` object
+   * @returns Promise
+   */
   'app:resolve': (app: NuxtApp) => HookResult
+  /**
+   * Called during `NuxtApp` generation, to allow customizing, modifying or adding new files to the build directory (either virtually or to written to `.nuxt`).
+   * @param app The configured `NuxtApp` object
+   * @returns Promise
+   */
   'app:templates': (app: NuxtApp) => HookResult
+  /**
+   * Called after templates are compiled into the [virtual file system](https://nuxt.com/docs/guide/directory-structure/nuxt#virtual-file-system) (vfs).
+   * @param app The configured `NuxtApp` object
+   * @returns Promise
+   */
   'app:templatesGenerated': (app: NuxtApp) => HookResult
 
+  /**
+   * Called before Nuxt bundle builder.
+   * @returns Promise
+   */
   'build:before': () => HookResult
+  /**
+   * Called after Nuxt bundle builder is complete.
+   * @returns Promise
+   */
   'build:done': () => HookResult
+  /**
+   * Called during the manifest build by Vite and Webpack. This allows customizing the manifest that Nitro will use to render `<script>` and `<link>` tags in the final HTML.
+   * @param manifest The manifest object to build
+   * @returns Promise
+   */
   'build:manifest': (manifest: Manifest) => HookResult
 
+  /**
+   * Called before generating the app.
+   * @param options GenerateAppOptions object
+   * @returns Promise
+   */
   'builder:generateApp': (options?: GenerateAppOptions) => HookResult
+  /**
+   * Called at build time in development when the watcher spots a change to a file or directory in the project.
+   * @param event "add" | "addDir" | "change" | "unlink" | "unlinkDir"
+   * @param path the path to the watched file
+   * @returns Promise
+   */
   'builder:watch': (event: WatchEvent, path: string) => HookResult
 
+  /**
+   * Called after pages routes are resolved.
+   * @param pages Array containing resolved pages
+   * @returns Promise
+   */
   'pages:extend': (pages: NuxtPage[]) => HookResult
 
+  /**
+   * Called when the dev middleware is being registered on the Nitro dev server.
+   * @param handler the Vite or Webpack event handler
+   * @returns Promise
+   */
   'server:devHandler': (handler: EventHandler) => HookResult
 
+  /**
+   * Called at setup allowing modules to extend sources.
+   * @param presets Array containing presets objects
+   * @returns Promise
+   */
   'imports:sources': (presets: ImportPresetWithDeprecation[]) => HookResult
+  /**
+   * Called at setup allowing modules to extend imports.
+   * @param imports Array containing the imports to extend
+   * @returns Promise
+   */
   'imports:extend': (imports: Import[]) => HookResult
+  /**
+   * Called when the [unimport](https://github.com/unjs/unimport) context is created.
+   * @param context The Unimport context
+   * @returns Promise
+   */
   'imports:context': (context: Unimport) => HookResult
+  /**
+   * Allows extending import directories.
+   * @param dirs Array containing directories as string
+   * @returns Promise
+   */
   'imports:dirs': (dirs: string[]) => HookResult
 
   // Components
+  /**
+   * Called within `app:resolve` allowing to extend the directories that are scanned for auto-importable components.
+   * @param dirs The `dirs` option to push new items
+   * @returns Promise
+   */
   'components:dirs': (dirs: ComponentsOptions['dirs']) => HookResult
+  /**
+   * Allows extending new components.
+   * @param components The `components` array to push new items
+   * @returns Promise
+   */
   'components:extend': (components: Component[]) => HookResult
 
   // Nitropack
+  /**
+   * Called before initializing Nitro, allowing customization of Nitro's configuration.
+   * @param nitroConfig The nitro config to be extended
+   * @returns Promise
+   */
   'nitro:config': (nitroConfig: NitroConfig) => HookResult
+  /**
+   * Called after Nitro is initialized, which allows registering Nitro hooks and interacting directly with Nitro.
+   * @param nitro The created nitro object
+   * @returns Promise
+   */
   'nitro:init': (nitro: Nitro) => HookResult
+  /**
+   * Called before building the Nitro instance.
+   * @param nitro The created nitro object
+   * @returns Promise
+   */
   'nitro:build:before': (nitro: Nitro) => HookResult
+  /**
+   * Allows extending the routes to be pre-rendered.
+   * @param ctx Nuxt context
+   * @returns Promise
+   */
   'prerender:routes': (ctx: { routes: Set<string> }) => HookResult
 
   // Nuxi
+  /**
+   * Called when an error occurs at build time.
+   * @param error Error object
+   * @returns Promise
+   */
   'build:error': (error: Error) => HookResult
+  /**
+   * Called before Nuxi writes `.nuxt/tsconfig.json` and `.nuxt/nuxt.d.ts`, allowing addition of custom references and declarations in `nuxt.d.ts`, or directly modifying the options in `tsconfig.json`
+   * @param options Objects containing `references`, `declarations`, `tsConfig`
+   * @returns Promise
+   */
   'prepare:types': (options: { references: TSReference[], declarations: string[], tsConfig: TSConfig }) => HookResult
+  /**
+   * Called when the dev server is loading.
+   * @param listenerServer The HTTP/HTTPS server object
+   * @param listener The server's listener object
+   * @returns Promise
+   */
   'listen': (listenerServer: HttpServer | HttpsServer, listener: any) => HookResult
 
   // Schema
+  /**
+   * Allows extending default schemas.
+   * @param schemas Schemas to be extend
+   * @returns void
+   */
   'schema:extend': (schemas: SchemaDefinition[]) => void
+  /**
+   * Allows extending resolved schema.
+   * @param schema Schema object
+   * @returns void
+   */
   'schema:resolved': (schema: Schema) => void
+  /**
+   * Called before writing the given schema.
+   * @param schema Schema object
+   * @returns void
+   */
   'schema:beforeWrite': (schema: Schema) => void
+  /**
+   * Called after the schema is written.
+   * @returns void
+   */
   'schema:written': () => void
 
   // Vite
+  /**
+   * Allows to extend Vite default context.
+   * @param viteBuildContext The vite build context object
+   * @returns Promise
+   */
   'vite:extend': (viteBuildContext: { nuxt: Nuxt, config: ViteInlineConfig }) => HookResult
+  /**
+   * Allows to extend Vite default config.
+   * @param viteInlineConfig The vite inline config object
+   * @param env Server or client
+   * @returns Promise
+   */
   'vite:extendConfig': (viteInlineConfig: ViteInlineConfig, env: { isClient: boolean, isServer: boolean }) => HookResult
+  /**
+   * Called when the Vite server is created.
+   * @param viteServer Vite development server
+   * @param env Server or client
+   * @returns Promise
+   */
   'vite:serverCreated': (viteServer: ViteDevServer, env: { isClient: boolean, isServer: boolean }) => HookResult
+  /**
+   * Called after Vite server is compiled.
+   * @returns Promise
+   */
   'vite:compiled': () => HookResult
 
   // webpack
+  /**
+   * Called before configuring the webpack compiler.
+   * @param webpackConfigs Configs objects to be pushed to the compiler
+   * @returns Promise
+   */
   'webpack:config': (webpackConfigs: Configuration[]) => HookResult
+  /**
+   * Called right before compilation.
+   * @param options The options to be added
+   * @returns Promise
+   */
   'webpack:compile': (options: { name: string, compiler: Compiler }) => HookResult
+  /**
+   * Called after resources are loaded.
+   * @param options The compiler options
+   * @returns Promise
+   */
   'webpack:compiled': (options: { name: string, compiler: Compiler, stats: Stats }) => HookResult
 
+  /**
+   * Called on `change` on WebpackBar.
+   * @param shortPath the short path
+   * @returns void
+   */
   'webpack:change': (shortPath: string) => void
+  /**
+   * Called on `done` if has errors on WebpackBar.
+   * @returns void
+   */
   'webpack:error': () => void
+  /**
+   * Called on `allDone` on WebpackBar.
+   * @returns void
+   */
   'webpack:done': () => void
+  /**
+   * Called on `progress` on WebpackBar.
+   * @param statesArray The array containing the states on progress
+   * @returns void
+   */
   'webpack:progress': (statesArray: any[]) => void
 }