feat(kit): useNitro() utility (#7557)

docs/content/3.api/4.advanced/2.kit.md

@@ -63,13 +63,14 @@
 
 - `addTemplate(templateOptions)`
 
-### Server
+### Nitro
 
-[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/server.ts)
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/nitro.ts)
 
 - ~~`addServerMiddleware(serverMiddleware)`~~
 - `addServerHandler (handler)`
 - `addDevServerHandler (handler)`
+- `useNitro()` (only usable after `ready` hook)
 
 ### Resolving
 

packages/kit/src/index.ts

@@ -18,7 +18,7 @@ export * from './layout'
 export * from './pages'
 export * from './plugin'
 export * from './resolve'
-export * from './server'
+export * from './nitro'
 export * from './template'
 export * from './logger'
 

packages/kit/src/module/container.ts

@@ -3,7 +3,7 @@ import type { Nuxt, ModuleContainer } from '@nuxt/schema'
 import { chainFn } from '../internal/task'
 import { addTemplate } from '../template'
 import { addLayout } from '../layout'
-import { addServerMiddleware } from '../server'
+import { addServerMiddleware } from '../nitro'
 import { isNuxt2 } from '../compatibility'
 import { addPluginTemplate } from '../plugin'
 import { useNuxt } from '../context'

packages/kit/src/nitro.ts

@@ -1,5 +1,5 @@
 import type { Middleware } from 'h3'
-import type { NitroEventHandler, NitroDevEventHandler } from 'nitropack'
+import type { NitroEventHandler, NitroDevEventHandler, Nitro } from 'nitropack'
 import { useNuxt } from './context'
 
 export interface LegacyServerMiddleware {
@@ -46,3 +46,26 @@ export function addServerHandler (handler: NitroEventHandler) {
 export function addDevServerHandler (handler: NitroDevEventHandler) {
   useNuxt().options.devServerHandlers.push(handler)
 }
+
+/**
+ * Access to the Nitro instance
+ *
+ * **Note:** You can call `useNitro()` only after `ready` hook.
+ *
+ * **Note:** Changes to the Nitro instance configuration are not applied.
+ *
+ * @example
+ *
+ * ```ts
+ * nuxt.hook('ready', () => {
+ *   console.log(useNitro())
+ * })
+ * ```
+ */
+export function useNitro (): Nitro {
+  const nuxt = useNuxt()
+  if (!(nuxt as any)._nitro) {
+    throw new Error('Nitro is not initialized yet. You can call `useNitro()` only after `ready` hook.')
+  }
+  return (nuxt as any)._nitro
+}

packages/nuxt/src/core/nitro.ts

@@ -1,6 +1,6 @@
 import { existsSync, promises as fsp } from 'node:fs'
 import { resolve, join } from 'pathe'
-import { createNitro, createDevServer, build, prepare, copyPublicAssets, writeTypes, scanHandlers, prerender } from 'nitropack'
+import { createNitro, createDevServer, build, prepare, copyPublicAssets, writeTypes, scanHandlers, prerender, Nitro } from 'nitropack'
 import type { NitroEventHandler, NitroDevEventHandler, NitroConfig } from 'nitropack'
 import type { Nuxt } from '@nuxt/schema'
 import { resolvePath } from '@nuxt/kit'
@@ -10,7 +10,7 @@ import { toEventHandler, dynamicEventHandler } from 'h3'
 import { distDir } from '../dirs'
 import { ImportProtectionPlugin } from './plugins/import-protection'
 
-export async function initNitro (nuxt: Nuxt) {
+export async function initNitro (nuxt: Nuxt & { _nitro?: Nitro }) {
   // Resolve handlers
   const { handlers, devHandlers } = await resolveHandlers(nuxt)
 
@@ -134,7 +134,8 @@ export async function initNitro (nuxt: Nuxt) {
   // Init nitro
   const nitro = await createNitro(nitroConfig)
 
-  // Expose nitro to modules
+  // Expose nitro to modules and kit
+  nuxt._nitro = nitro
   await nuxt.callHook('nitro:init', nitro)
 
   // Connect vfs storages