@nuxt/docs-nightly 4.1.0-29279365.79d172b6 → 4.1.1-29280872.e12125a9

package/2.guide/2.directory-structure/2.nuxtrc.md

@@ -27,6 +27,10 @@ modules[]=nuxt-security
 
 If present, the properties in the `nuxt.config` file will overwrite the properties in `.nuxtrc` file.
 
+::note
+Nuxt automatically adds a `setups` section to track module installation and upgrade state. This is used internally for [module lifecycle hooks](/docs/api/kit/modules#using-lifecycle-hooks-for-module-installation-and-upgrade) and should not be modified manually.
+::
+
 ::read-more{to="/docs/api/configuration/nuxt-config"}
 Discover all the available options in the **Nuxt configuration** documentation.
 ::

package/2.guide/3.going-further/3.modules.md

@@ -780,6 +780,38 @@ Nuxt Modules should provide an explicit prefix for any exposed configuration, pl
 
 Ideally, you should prefix them with your module's name (e.g. if your module is called `nuxt-foo`, expose `<FooButton>` and `useFooBar()` and **not** `<Button>` and `useBar()`).
 
+#### Use Lifecycle Hooks for One-Time Setup
+
+When your module needs to perform one-time setup tasks (like generating configuration files, setting up databases, or installing dependencies), use lifecycle hooks instead of running the logic in your main `setup` function.
+
+```ts
+import { addServerHandler, defineNuxtModule } from 'nuxt/kit'
+import semver from 'semver'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-database-module',
+    version: '1.0.0',
+  },
+  async onInstall (nuxt) {
+    // One-time setup: create database schema, generate config files, etc.
+    await generateDatabaseConfig(nuxt.options.rootDir)
+  },
+  async onUpgrade (options, nuxt, previousVersion) {
+    // Handle version-specific migrations
+    if (semver.lt(previousVersion, '1.0.0')) {
+      await migrateLegacyData()
+    }
+  },
+  setup (options, nuxt) {
+    // Regular setup logic that runs on every build
+    addServerHandler({ /* ... */ })
+  },
+})
+```
+
+This pattern prevents unnecessary work on every build and provides a better developer experience. See the [lifecycle hooks documentation](/docs/api/kit/modules#using-lifecycle-hooks-for-module-installation-and-upgrade) for more details.
+
 #### Be TypeScript Friendly
 
 Nuxt has first-class TypeScript integration for the best developer experience.

package/3.api/5.kit/1.modules.md

@@ -62,6 +62,8 @@ export function defineNuxtModule<TOptions extends ModuleOptions> (): {
 | `defaults`         | `T \| ((nuxt: Nuxt) => T)`{lang="ts"}                                | `false`  | Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument. |
 | `schema`           | `T`                                                                  | `false`  | Schema for the module options. If provided, options will be applied to the schema.                              |
 | `hooks`            | `Partial<NuxtHooks>`{lang="ts"}                                      | `false`  | Hooks to be installed for the module. If provided, the module will install the hooks.                           |
+| `onInstall`        | `(nuxt: Nuxt) => Awaitable<void>`{lang="ts"}                        | `false`  | Lifecycle hook called when the module is first installed. Requires `meta.name` and `meta.version` to be defined. |
+| `onUpgrade`        | `(options: T, nuxt: Nuxt, previousVersion: string) => Awaitable<void>`{lang="ts"} | `false`  | Lifecycle hook called when the module is upgraded to a newer version. Requires `meta.name` and `meta.version` to be defined. |
 | `setup`            | `(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void \| false \| ModuleSetupInstallResult>`{lang="ts"} | `false`  | Setup function for the module. If provided, the module will call the setup function.    |
 
 ### Examples
@@ -171,6 +173,72 @@ export default defineNuxtModule<ModuleOptions>().with({
 
 Without using `.with()`, the `resolvedOptions` parameter would be typed as the raw `ModuleOptions` interface, where `timeout` and `retries` could be `undefined` even when defaults are provided. The `.with()` method enables TypeScript to understand that default values make those properties non-optional in the resolved options.
 
+#### Using Lifecycle Hooks for Module Installation and Upgrade
+
+You can define lifecycle hooks that run when your module is first installed or upgraded to a new version. These hooks are useful for performing one-time setup tasks, database migrations, or cleanup operations.
+
+::important
+For lifecycle hooks to work, you **must** provide both `meta.name` and `meta.version` in your module definition. The hooks use these values to track the module's installation state in the project's `.nuxtrc` file.
+::
+
+Lifecycle hooks run before the main `setup` function, and if a hook throws an error, it's logged but doesn't stop the build process.
+
+**`onInstall`** runs only once when the module is first added to a project.
+
+**`onUpgrade`** runs each time the module version increases (using semver comparison) &mdash; but only once for each version bump.
+
+##### Example
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+import semver from 'semver'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-awesome-module',
+    version: '1.2.0', // Required for lifecycle hooks
+    configKey: 'myAwesomeModule'
+  },
+  defaults: {
+    apiKey: '',
+    enabled: true
+  },
+  
+  onInstall(nuxt) {
+    // This runs only when the module is first installed
+    console.log('Setting up my-awesome-module for the first time!')
+    
+    // You might want to:
+    // - Create initial configuration files
+    // - Set up database schemas
+    // - Display welcome messages
+    // - Perform initial data migration
+  },
+  
+  onUpgrade(options, nuxt, previousVersion) {
+    // This runs when the module is upgraded to a newer version
+    console.log(`Upgrading my-awesome-module from ${previousVersion} to 1.2.0`)
+    
+    // You might want to:
+    // - Migrate configuration files
+    // - Update database schemas  
+    // - Clean up deprecated files
+    // - Display upgrade notes
+    
+    if (semver.lt(previousVersion, '1.1.0')) {
+      console.log('⚠️  Breaking changes in 1.1.0 - please check the migration guide')
+    }
+  },
+  
+  setup(options, nuxt) {
+    // Regular setup logic runs on every build
+    if (options.enabled) {
+      // Configure the module
+    }
+  }
+})
+```
+
 ## `installModule`
 
 Install specified Nuxt module programmatically. This is helpful when your module depends on other modules. You can pass the module options as an object to `inlineOptions` and they will be passed to the module's `setup` function.

package/3.api/5.kit/16.layers.md

@@ -0,0 +1,220 @@
+---
+title: "Layers"
+description: Nuxt Kit provides utilities to help you work with layers and their directory structures.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/layers.ts
+    size: xs
+---
+
+Nuxt layers provide a powerful way to share and extend functionality across projects. When working with layers in modules, you often need to access directory paths from each layer. Nuxt Kit provides the `getLayerDirectories` utility to access resolved directory paths for all layers in your Nuxt application.
+
+## `getLayerDirectories`
+
+Get the resolved directory paths for all layers in a Nuxt application. This function provides a structured way to access layer directories without directly accessing the private `nuxt.options._layers` property.
+
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const layerDirs = getLayerDirectories()
+    
+    // Access directories from all layers
+    for (const [index, layer] of layerDirs.entries()) {
+      console.log(`Layer ${index}:`)
+      console.log(`  Root: ${layer.root}`)
+      console.log(`  App: ${layer.app}`)
+      console.log(`  Server: ${layer.server}`)
+      console.log(`  Pages: ${layer.appPages}`)
+      // ... other directories
+    }
+  }
+})
+```
+
+### Type
+
+```ts twoslash
+// @errors: 2391
+import type { Nuxt } from '@nuxt/schema'
+// ---cut---
+function getLayerDirectories(nuxt?: Nuxt): LayerDirectories[]
+
+interface LayerDirectories {
+  /** Nuxt rootDir (`/` by default) */
+  readonly root: string
+  /** Nitro source directory (`/server` by default) */
+  readonly server: string
+  /** Local modules directory (`/modules` by default) */
+  readonly modules: string
+  /** Shared directory (`/shared` by default) */
+  readonly shared: string
+  /** Public directory (`/public` by default) */
+  readonly public: string
+  /** Nuxt srcDir (`/app/` by default) */
+  readonly app: string
+  /** Layouts directory (`/app/layouts` by default) */
+  readonly appLayouts: string
+  /** Middleware directory (`/app/middleware` by default) */
+  readonly appMiddleware: string
+  /** Pages directory (`/app/pages` by default) */
+  readonly appPages: string
+  /** Plugins directory (`/app/plugins` by default) */
+  readonly appPlugins: string
+}
+```
+
+### Parameters
+
+**`nuxt`** (optional): The Nuxt instance to get layers from. If not provided, the function will use the current Nuxt context.
+
+### Return Value
+
+The `getLayerDirectories` function returns an array of `LayerDirectories` objects, one for each layer in the application.
+
+**Layer Priority Ordering**: The layers are ordered by priority, where:
+- The **first layer** is the user/project layer (highest priority)
+- **Earlier layers override later layers** in the array
+- **Base layers appear last** in the array (lowest priority)
+
+This ordering matches Nuxt's layer resolution system, where user-defined configurations and files take precedence over those from base layers.
+
+**`LayerDirectories`**: An object containing the resolved directory paths for a layer.
+
+| Property        | Type     | Description                                                                    |
+| --------------- | -------- | ------------------------------------------------------------------------------ |
+| `root`          | `string` | The root directory of the layer (equivalent to `rootDir`)                     |
+| `server`        | `string` | The server directory for Nitro server-side code                               |
+| `modules`       | `string` | The local modules directory                                                    |
+| `shared`        | `string` | The shared directory for code used by both client and server                  |
+| `app`           | `string` | The source directory of the layer (equivalent to `srcDir`)                    |
+| `public`        | `string` | The public directory for static assets                                         |
+| `appLayouts`    | `string` | The layouts directory for Vue layout components                                |
+| `appMiddleware` | `string` | The middleware directory for route middleware                                  |
+| `appPages`      | `string` | The pages directory for file-based routing                                    |
+| `appPlugins`    | `string` | The plugins directory for Nuxt plugins                                        |
+
+### Examples
+
+**Processing files from all layers:**
+
+```ts twoslash
+// @errors: 2307
+// ---cut---
+import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
+import { resolve } from 'pathe'
+import { globby } from 'globby'
+
+export default defineNuxtModule({
+  async setup() {
+    const layerDirs = getLayerDirectories()
+    
+    // Find all component files across layers
+    // Note: layerDirs[0] is the user layer (highest priority)
+    // Later layers in the array have lower priority
+    const componentFiles = []
+    for (const [index, layer] of layerDirs.entries()) {
+      const files = await globby('**/*.vue', {
+        cwd: resolve(layer.app, 'components'),
+        absolute: true
+      })
+      console.log(`Layer ${index} (${index === 0 ? 'user' : 'base'}):`, files.length, 'components')
+      componentFiles.push(...files)
+    }
+  }
+})
+```
+
+**Adding templates from multiple layers:**
+
+```ts twoslash
+import { defineNuxtModule, getLayerDirectories, addTemplate } from '@nuxt/kit'
+import { resolve, basename } from 'pathe'
+import { existsSync } from 'fs'
+
+export default defineNuxtModule({
+  async setup() {
+    const layerDirs = getLayerDirectories()
+    
+    // Add a config file from each layer that has one
+    for (const dirs of layerDirs) {
+      const configPath = resolve(dirs.app, 'my-module.config.ts')
+      if (existsSync(configPath)) {
+        addTemplate({
+          filename: `my-module-${basename(dirs.root)}.config.ts`,
+          src: configPath
+        })
+      }
+    }
+  }
+})
+```
+
+**Respecting layer priority:**
+
+```ts twoslash
+import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
+import { resolve } from 'pathe'
+import { existsSync, readFileSync } from 'fs'
+
+export default defineNuxtModule({
+  setup() {
+    const layerDirs = getLayerDirectories()
+    
+    // Find the first (highest priority) layer that has a specific config file
+    // This respects the layer priority system
+    let configContent = null
+    for (const dirs of layerDirs) {
+      const configPath = resolve(dirs.app, 'my-config.json')
+      if (existsSync(configPath)) {
+        configContent = readFileSync(configPath, 'utf-8')
+        console.log(`Using config from layer: ${dirs.root}`)
+        break // Use the first (highest priority) config found
+      }
+    }
+    
+    // Alternative: Collect configs from all layers, with user layer taking precedence
+    const allConfigs = {}
+    for (const dirs of layerDirs.reverse()) { // Process from lowest to highest priority
+      const configPath = resolve(dirs.app, 'my-config.json')
+      if (existsSync(configPath)) {
+        const config = JSON.parse(readFileSync(configPath, 'utf-8'))
+        Object.assign(allConfigs, config) // Later assignments override earlier ones
+      }
+    }
+  }
+})
+```
+
+**Checking for layer-specific directories:**
+
+```ts twoslash
+import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
+import { existsSync } from 'fs'
+import { resolve } from 'pathe'
+
+export default defineNuxtModule({
+  setup() {
+    const layerDirs = getLayerDirectories()
+    
+    // Find layers that have a specific custom directory
+    const layersWithAssets = layerDirs.filter(layer => {
+      return existsSync(resolve(layer.app, 'assets'))
+    })
+    
+    console.log(`Found ${layersWithAssets.length} layers with assets directory`)
+  }
+})
+```
+
+::note
+The `getLayerDirectories` function includes caching via a WeakMap to avoid recomputing directory paths for the same layers repeatedly, improving performance when called multiple times.
+::
+
+::note
+Directory paths returned by this function always include a trailing slash for consistency.
+::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.1.0-29279365.79d172b6",
+  "version": "4.1.1-29280872.e12125a9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",