feat(nuxt): auto-register modules in ~/modules

docs/2.guide/2.directory-structure/1.modules.md

@@ -0,0 +1,18 @@
+---
+navigation.icon: IconDirectory
+title: 'modules'
+head.title: 'modules/'
+description: Use the modules/ directory to automatically register local modules within your application.
+---
+
+# Modules Directory
+
+Nuxt automatically reads the top-level files in your `modules/` directory and loads them before starting. It is a good place to place any local modules you develop while building your application.
+
+These files are auto-registered, so you do not need to add them to your `nuxt.config` separately.
+
+::alert{type=warning}
+Only files at the top level of the `modules/` directory will be automatically registered.
+::
+
+:ReadMore{link="/docs/guide/going-further/modules"}

packages/nuxt/src/core/nuxt.ts

@@ -1,7 +1,7 @@
 import { join, normalize, resolve } from 'pathe'
 import { createHooks, createDebugger } from 'hookable'
 import type { LoadNuxtOptions } from '@nuxt/kit'
-import { loadNuxtConfig, nuxtCtx, installModule, addComponent, addVitePlugin, addWebpackPlugin, tryResolveModule, addPlugin } from '@nuxt/kit'
+import { resolveFiles, loadNuxtConfig, nuxtCtx, installModule, addComponent, addVitePlugin, addWebpackPlugin, tryResolveModule, addPlugin } from '@nuxt/kit'
 
 import escapeRE from 'escape-string-regexp'
 import fse from 'fs-extra'
@@ -127,6 +127,12 @@ async function initNuxt (nuxt: Nuxt) {
     ...nuxt.options._modules
   ]
 
+  // Automatically register user modules
+  for (const config of nuxt.options._layers.map(layer => layer.config)) {
+    const userModules = await resolveFiles(config.srcDir, `${config.dir?.modules || 'modules'}/*{${nuxt.options.extensions.join(',')}}`)
+    modulesToInstall.push(...userModules)
+  }
+
   // Add <NuxtWelcome>
   addComponent({
     name: 'NuxtWelcome',

packages/schema/src/config/common.ts

@@ -219,6 +219,11 @@ export default defineUntypedSchema({
      */
     middleware: 'middleware',
 
+    /**
+     * The modules directory, each file in which will be auto-registered as a Nuxt module.
+     */
+    modules: 'modules',
+
     /**
      * The directory which will be processed to auto-generate your application page routes.
      */

test/basic.test.ts

@@ -47,6 +47,13 @@ describe('route rules', () => {
   })
 })
 
+describe('modules', () => {
+  it('should auto-register modules in ~/modules', async () => {
+    const result = await $fetch('/auto-registered-module')
+    expect(result).toEqual('handler added by auto-registered module')
+  })
+})
+
 describe('pages', () => {
   it('render index', async () => {
     const html = await $fetch('/')

test/fixtures/basic/modules/auto-registered.ts

@@ -0,0 +1,17 @@
+import { createResolver, defineNuxtModule, useNuxt } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'auto-registered-module'
+  },
+  setup () {
+    const nuxt = useNuxt()
+    const resolver = createResolver(import.meta.url)
+
+    nuxt.options.nitro.handlers = nuxt.options.nitro.handlers || []
+    nuxt.options.nitro.handlers.push({
+      handler: resolver.resolve('./runtime/handler'),
+      route: '/auto-registered-module'
+    })
+  }
+})

test/fixtures/basic/modules/runtime/handler.ts

@@ -0,0 +1 @@
+export default defineEventHandler(() => 'handler added by auto-registered module')