feat(nuxt, kit): add shortcuts to register custom server handlers (#4850)

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

@@ -60,7 +60,9 @@
 
 [source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/server.ts)
 
-- `addServerMiddleware(serverMiddleware)`
+- ~~`addServerMiddleware(serverMiddleware)`~~
+- `addServerHandler (handler)`
+- `addDevServerHandler (handler)`
 
 ### Resolving
 

packages/kit/build.config.ts

@@ -7,6 +7,7 @@ export default defineBuildConfig({
   ],
   externals: [
     '@nuxt/schema',
+    'nitropack',
     'webpack',
     'vite',
     'h3'

packages/kit/src/server.ts

@@ -1,12 +1,35 @@
 import type { Middleware } from 'h3'
+import type { NitroEventHandler, NitroDevEventHandler } from 'nitropack'
 import { useNuxt } from './context'
 
-export interface ServerMiddleware {
+export interface LegacyServerMiddleware {
   route?: string,
+  path?: string,
+  handle?: Middleware | string
   handler: Middleware | string
 }
 
-/** Adds a new server middleware to the end of the server middleware array. */
+/**
-export function addServerMiddleware (middleware: ServerMiddleware) {
+ * Adds a new server middleware to the end of the server middleware array.
+ *
+ * @deprecated Use addServerHandler instead
+ */
+export function addServerMiddleware (middleware: LegacyServerMiddleware) {
   useNuxt().options.serverMiddleware.push(middleware)
 }
+
+/**
+ * Adds a nitro server handler
+ *
+ */
+export function addServerHandler (handler: NitroEventHandler) {
+  useNuxt().options.serverHandlers.push(handler)
+}
+
+/**
+ * Adds a nitro server handler for development-only
+ *
+ */
+export function addDevServerHandler (handler: NitroDevEventHandler) {
+  useNuxt().options.devServerHandlers.push(handler)
+}

packages/nuxt/src/core/nitro.ts

@@ -176,9 +176,10 @@ export async function initNitro (nuxt: Nuxt) {
 }
 
 async function resolveHandlers (nuxt: Nuxt) {
-  const handlers: NitroEventHandler[] = []
+  const handlers: NitroEventHandler[] = [...nuxt.options.serverHandlers]
-  const devHandlers: NitroDevEventHandler[] = []
+  const devHandlers: NitroDevEventHandler[] = [...nuxt.options.devServerHandlers]
 
+  // Map legacy serverMiddleware to handlers
   for (let m of nuxt.options.serverMiddleware) {
     if (typeof m === 'string' || typeof m === 'function' /* legacy middleware */) { m = { handler: m } }
     const route = m.path || m.route || '/'

packages/schema/src/config/_common.ts

@@ -393,8 +393,9 @@ export default {
    *   }
    * }
    * ```
+   *
    * @version 2
-   * @version 3
+   * @deprecated Use `serverHandlers` instead
    */
   serverMiddleware: {
     $resolve: (val: any) => {

packages/schema/src/config/nitro.ts

@@ -2,11 +2,33 @@ export default {
   /**
    * Configuration for Nitro
    *
-   * @see https://github.com/unjs/nitropack
+   * @see https://nitro.unjs.io/config/
    *
    * @type {typeof import('nitropack')['NitroConfig']}
    * @version 2
    * @version 3
   */
-  nitro: {}
+  nitro: {},
+
+  /**
+   * Nitro server handlers
+   *
+   * @see https://nitro.unjs.io/guide/routing.html
+   *
+   * **Note:** Files from `server/api`, `server/middleware` and `server/routes` will be automatically registred by Nuxt.
+   *
+   * @type {typeof import('nitropack')['NitroEventHandler'][]}
+   * @version 3
+   */
+  serverHandlers: [],
+
+  /**
+   * Nitro devevelopment-only server handlers
+   *
+   * @see https://nitro.unjs.io/guide/routing.html
+   *
+   * @type {typeof import('nitropack')['NitroDevEventHandler'][]}
+   * @version 3
+   */
+   devServerHandlers: []
 }