@nuxt/docs-nightly 4.1.0-29279382.7234ae61 → 4.1.1-29281581.418bafeb

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.1.0-29279382.7234ae61",
+  "version": "4.1.1-29281581.418bafeb",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",