@nuxt/docs 3.17.1 → 3.17.3

package/3.api/5.kit/2.programmatic.md

@@ -17,39 +17,17 @@ Load Nuxt programmatically. It will load the Nuxt configuration, instantiate and
 ### Type
 
 ```ts
-async function loadNuxt (loadOptions?: LoadNuxtOptions): Promise<Nuxt>
-
-interface LoadNuxtOptions extends LoadNuxtConfigOptions {
-  dev?: boolean
-  ready?: boolean
-}
+function loadNuxt (loadOptions?: LoadNuxtOptions): Promise<Nuxt>
 ```
 
 ### Parameters
 
-#### `loadOptions`
-
-**Type**: `LoadNuxtOptions`
-
-**Default**: `{}`
-
-Loading conditions for Nuxt. `loadNuxt` uses [`c12`](https://github.com/unjs/c12) under the hood, so it accepts the same options as `c12.loadConfig` with some additional options:
-
-- `dev` (optional)
+**`loadOptions`**: Loading conditions for Nuxt. `loadNuxt` uses [`c12`](https://github.com/unjs/c12) under the hood, so it accepts the same options as `c12.loadConfig` with some additional options:
 
-  **Type**: `boolean`
-
-  **Default**: `false`
-
-  If set to `true`, Nuxt will be loaded in development mode.
-
-- `ready` (optional)
-  
-  **Type**: `boolean`
-  
-  **Default**: `true`
-  
-  If set to `true`, Nuxt will be ready to use after the `loadNuxt` call. If set to `false`, you will need to call `nuxt.ready()` to make sure Nuxt is ready to use.
+| Property | Type      | Required | Description                                                                                                                                                       |
+| -------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dev`    | `boolean` | `false`  | If set to `true`, Nuxt will be loaded in development mode.                                                                                                        |
+| `ready`  | `boolean` | `true`   | If set to `true`, Nuxt will be ready to use after the `loadNuxt` call. If set to `false`, you will need to call `nuxt.ready()` to make sure Nuxt is ready to use. |
 
 ## `buildNuxt`
 
@@ -58,18 +36,12 @@ Build Nuxt programmatically. It will invoke the builder (currently [@nuxt/vite-b
 ### Type
 
 ```ts
-async function buildNuxt (nuxt: Nuxt): Promise<any>
+function buildNuxt (nuxt: Nuxt): Promise<any>
 ```
 
 ### Parameters
 
-#### `nuxt`
-
-**Type**: `Nuxt`
-
-**Required**: `true`
-
-Nuxt instance to build. It can be retrieved from the context via `useNuxt()` call.
+**`nuxt`**: Nuxt instance to build. It can be retrieved from the context via `useNuxt()` call.
 
 ## `loadNuxtConfig`
 
@@ -78,18 +50,12 @@ Load Nuxt configuration. It will return the promise with the configuration objec
 ### Type
 
 ```ts
-async function loadNuxtConfig (options: LoadNuxtConfigOptions): Promise<NuxtOptions>
+function loadNuxtConfig (options: LoadNuxtConfigOptions): Promise<NuxtOptions>
 ```
 
 ### Parameters
 
-#### `options`
-
-**Type**: `LoadNuxtConfigOptions`
-
-**Required**: `true`
-
-Options to pass in [`c12`](https://github.com/unjs/c12#options) `loadConfig` call.
+**`options`**: Options to pass in [`c12`](https://github.com/unjs/c12#options) `loadConfig` call.
 
 ## `writeTypes`
 
@@ -99,27 +65,8 @@ Generates `tsconfig.json` and writes it to the project buildDir.
 
 ```ts
 function writeTypes (nuxt?: Nuxt): void
-
-interface Nuxt {
-  options: NuxtOptions
-  hooks: Hookable<NuxtHooks>
-  hook: Nuxt['hooks']['hook']
-  callHook: Nuxt['hooks']['callHook']
-  addHooks: Nuxt['hooks']['addHooks']
-  ready: () => Promise<void>
-  close: () => Promise<void>
-  server?: any
-  vfs: Record<string, string>
-  apps: Record<string, NuxtApp>
-}
 ```
 
 ### Parameters
 
-#### `nuxt`
-
-**Type**: `Nuxt`
-
-**Required**: `true`
-
-Nuxt instance to build. It can be retrieved from the context via `useNuxt()` call.
+**`nuxt`**: Nuxt instance to build. It can be retrieved from the context via `useNuxt()` call.

package/3.api/5.kit/3.compatibility.md

@@ -14,64 +14,39 @@ Nuxt Kit utilities can be used in Nuxt 3, Nuxt 2 with Bridge and even Nuxt 2 wit
 
 Checks if constraints are met for the current Nuxt version. If not, returns an array of messages. Nuxt 2 version also checks for `bridge` support.
 
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, checkNuxtCompatibility } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  async setup (_options, nuxt) {
+    const issues = await checkNuxtCompatibility({ nuxt: '^2.16.0' }, nuxt)
+    if (issues.length) {
+      console.warn('Nuxt compatibility issues found:\n' + issues.toString())
+    } else {
+      // do something
+    }
+  }
+})
+```
+
 ### Type
 
 ```ts
-async function checkNuxtCompatibility(
-  constraints: NuxtCompatibility,
-  nuxt?: Nuxt
-): Promise<NuxtCompatibilityIssues>;
-
-interface NuxtCompatibility {
-  nuxt?: string;
-  bridge?: boolean;
-  builder?: {
-    // Set `false` if your module is not compatible with a builder
-    // or a semver-compatible string version constraint
-    vite?: false | string;
-    webpack?: false | string;
-  };
-}
-
-interface NuxtCompatibilityIssue {
-  name: string;
-  message: string;
-}
-
-interface NuxtCompatibilityIssues extends Array<NuxtCompatibilityIssue> {
-  toString(): string;
-}
+function checkNuxtCompatibility(constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<NuxtCompatibilityIssues>;
 ```
 
 ### Parameters
 
-#### `constraints`
-
-**Type**: `NuxtCompatibility`
-
-**Default**: `{}`
-
-Constraints to check for. It accepts the following properties:
-
-- `nuxt` (optional)
-
-  **Type**: `string`
+**`constraints`**: Version and builder constraints to check against. It accepts the following properties:
 
-  Nuxt version in semver format. Versions may be defined in Node.js way, for example: `>=2.15.0 <3.0.0`.
+| Property | Type                                          | Required  | Description                                                                                                                                      |
+| -------- | --------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `nuxt`   | `string`                                      | `false`   | Nuxt version in semver format. Versions may be defined in Node.js way, for example: `>=2.15.0 <3.0.0`.                                           |
+| `bridge` | `Record<string, string \| false>`{lang="ts"}  | `false`   | Specifies version constraints or disables compatibility for specific Nuxt builders like `vite`, `webpack`, or `rspack`. Use `false` to disable.  |
 
-- `bridge` (optional)
-
-  **Type**: `boolean`
-
-  If set to `true`, it will check if the current Nuxt version supports `bridge`.
-
-#### `nuxt`
-
-**Type**: `Nuxt`
-
-**Default**: `useNuxt()`
-
-Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+**`nuxt`**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
 
 ## `assertNuxtCompatibility`
 
@@ -79,135 +54,119 @@ Asserts that constraints are met for the current Nuxt version. If not, throws an
 
 ### Type
 
-```ts
-async function assertNuxtCompatibility(
-  constraints: NuxtCompatibility,
-  nuxt?: Nuxt
-): Promise<true>;
-
-interface NuxtCompatibility {
-  nuxt?: string;
-  bridge?: boolean;
-}
+```ts twoslash
+// @errors: 2391
+import type { Nuxt, NuxtCompatibility } from '@nuxt/schema'
+// ---cut---
+function assertNuxtCompatibility(constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<true>;
 ```
 
 ### Parameters
 
-#### `constraints`
+**`constraints`**: Version and builder constraints to check against. Refer to the [constraints table in `checkNuxtCompatibility`](#parameters) for details.
 
-**Type**: `NuxtCompatibility`
-
-**Default**: `{}`
-
-Constraints to check for. It accepts the following properties:
-
-- `nuxt` (optional)
-
-  **Type**: `string`
-
-  Nuxt version in semver format. Versions may be defined in Node.js way, for example: `>=2.15.0 <3.0.0`.
-
-- `bridge` (optional)
-
-  **Type**: `boolean`
-
-  If set to `true`, it will check if the current Nuxt version supports `bridge`.
-
-#### `nuxt`
-
-**Type**: `Nuxt`
-
-**Default**: `useNuxt()`
-
-Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+**`nuxt`**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
 
 ## `hasNuxtCompatibility`
 
 Checks if constraints are met for the current Nuxt version. Return `true` if all constraints are met, otherwise returns `false`. Nuxt 2 version also checks for `bridge` support.
 
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, hasNuxtCompatibility } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  async setup (_options, nuxt) {
+    const usingNewPostcss = await hasNuxtCompatibility({ nuxt: '^2.16.0' }, nuxt)
+    if (usingNewPostcss) {
+      // do something
+    } else {
+      // do something else
+    }
+  }
+})
+```
+
 ### Type
 
 ```ts
-async function hasNuxtCompatibility(
-  constraints: NuxtCompatibility,
-  nuxt?: Nuxt
-): Promise<boolean>;
-
-interface NuxtCompatibility {
-  nuxt?: string;
-  bridge?: boolean;
-}
+function hasNuxtCompatibility(constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<boolean>;
 ```
 
 ### Parameters
 
-#### `constraints`
-
-**Type**: `NuxtCompatibility`
+**`constraints`**: Version and builder constraints to check against. Refer to the [constraints table in `checkNuxtCompatibility`](#parameters) for details.
 
-**Default**: `{}`
+**`nuxt`**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
 
-Constraints to check for. It accepts the following properties:
+## `isNuxtMajorVersion`
 
-- `nuxt` (optional)
+Check if current Nuxt instance is of specified major version
 
-  **Type**: `string`
+### Usage
 
-  Nuxt version in semver format. Versions may be defined in Node.js way, for example: `>=2.15.0 <3.0.0`.
+```ts twoslash
+import { defineNuxtModule, isNuxtMajorVersion } from '@nuxt/kit'
 
-- `bridge` (optional)
+export default defineNuxtModule({
+  async setup () {
+    if (isNuxtMajorVersion(3)) {
+      // do something for Nuxt 3
+    } else {
+      // do something else for other versions
+    }
+  }
+})
+```
 
-  **Type**: `boolean`
+### Type
 
-  If set to `true`, it will check if the current Nuxt version supports `bridge`.
+```ts
+function isNuxtMajorVersion(major: number, nuxt?: Nuxt): boolean;
+```
 
-#### `nuxt`
+### Parameters
 
-**Type**: `Nuxt`
+**`major`**: Major version to check against.
 
-**Default**: `useNuxt()`
+**`nuxt`**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
 
-Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+## `isNuxt3`
 
-## `isNuxt2`
+Checks if the current Nuxt version is 3.x.
 
-Checks if the current Nuxt version is 2.x.
+::note
+Use `isNuxtMajorVersion(2, nuxt)` instead. This may be removed in \@nuxt/kit v5 or a future major version.
+::
 
 ### Type
 
 ```ts
-function isNuxt2(nuxt?: Nuxt): boolean;
+function isNuxt3(nuxt?: Nuxt): boolean;
 ```
 
 ### Parameters
 
-#### `nuxt`
-
-**Type**: `Nuxt`
+**`nuxt`**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
 
-**Default**: `useNuxt()`
+## `isNuxt2`
 
-Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+Checks if the current Nuxt version is 2.x.
 
-## `isNuxt3`
-
-Checks if the current Nuxt version is 3.x.
+::note
+Use `isNuxtMajorVersion(2, nuxt)` instead. This may be removed in \@nuxt/kit v5 or a future major version.
+::
 
 ### Type
 
 ```ts
-function isNuxt3(nuxt?: Nuxt): boolean;
+function isNuxt2(nuxt?: Nuxt): boolean;
 ```
 
 ### Parameters
 
-#### `nuxt`
-
-**Type**: `Nuxt`
-
-**Default**: `useNuxt()`
-
-Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+**`nuxt`**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
 
 ## `getNuxtVersion`
 
@@ -221,10 +180,4 @@ function getNuxtVersion(nuxt?: Nuxt): string;
 
 ### Parameters
 
-#### `nuxt`
-
-**Type**: `Nuxt`
-
-**Default**: `useNuxt()`
-
-Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+**`nuxt`**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.

package/3.api/5.kit/4.autoimports.md

@@ -58,7 +58,7 @@ function addImports (imports: Import | Import[]): void
 
 `imports`: An object or an array of objects with the following properties:
 
-| Prop               | Type                         | Required | Description                                                                                                     |
+| Property           | Type                         | Required | Description                                                                                                     |
 | ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
 | `name`             | `string`                     | `true`   | Import name to be detected.                                                                                     |
 | `from`             | `string`                     | `true`   | Module specifier to import from.                                                                                |
@@ -98,7 +98,7 @@ function addImportsDir (dirs: string | string[], options?: { prepend?: boolean }
 
 ### Parameters
 
-| Prop               | Type                         | Required | Description                                                                                                     |
+| Property           | Type                         | Required | Description                                                                                                     |
 | ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
 | `dirs`             | `string \| string[]`{lang="ts"}          | `true`   | A string or an array of strings with the path to the directory to import from.                                 |
 | `options`          | `{ prepend?: boolean }`{lang="ts"}      | `false`  | Options to pass to the import. If `prepend` is set to `true`, the imports will be prepended to the list of imports. |
@@ -138,7 +138,7 @@ function addImportsSources (importSources: ImportSource | ImportSource[]): void
 
 **importSources**: An object or an array of objects with the following properties:
 
-| Prop               | Type                         | Required | Description                                                                                                     |
+| Property           | Type                         | Required | Description                                                                                                     |
 | ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
 | `from`             | `string`                     | `true`   | Module specifier to import from.                                                                                |
 | `imports`          | `PresetImport \| ImportSource[]`{lang="ts"} | `true`   | An object or an array of objects, which can be import names, import objects or import sources.                  |

package/3.api/5.kit/5.components.md

@@ -46,7 +46,7 @@ function addComponentsDir (dir: ComponentsDir, opts: { prepend?: boolean } = {})
 
 `dir` An object with the following properties:
 
-| Prop               | Type                         | Required | Description                                                                                                     |
+| Property           | Type                         | Required | Description                                                                                                     |
 | ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
 | `path`             | `string`                     | `true`   | Path (absolute or relative) to the directory containing your components. You can use Nuxt aliases (~ or @) to refer to directories inside project or directly use an npm package path similar to require. |
 | `pattern`          | `string \| string[]`{lang="ts"}          | `false`  | Accept Pattern that will be run against specified path.                                                         |
@@ -66,7 +66,7 @@ function addComponentsDir (dir: ComponentsDir, opts: { prepend?: boolean } = {})
 
 `opts`
 
-| Prop               | Type                         | Required | Description                                                                                                     |
+| Property           | Type                         | Required | Description                                                                                                     |
 | ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
 | `prepend`          | `boolean`                    | `false`  | If set to `true`, the directory will be prepended to the array with `unshift()` instead of `push()`.            |
 
@@ -110,7 +110,7 @@ function addComponent (options: AddComponentOptions): void
 
 `options`: An object with the following properties:
 
-| Prop               | Type                         | Required | Description                                                                                                     |
+| Property           | Type                         | Required | Description                                                                                                     |
 | ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |  
 | `name`             | `string`                     | `true`   | Component name.                                                                                                 |
 | `filePath`         | `string`                     | `true`   | Path to the component.                                                                                          |
@@ -125,3 +125,22 @@ function addComponent (options: AddComponentOptions): void
 | `island`           | `boolean`                    | `false`  | If enabled, registers component as island. You can read more about islands in [`<NuxtIsland/>`](/docs/api/components/nuxt-island#nuxtisland) component description. |
 | `mode`             | `'client' \| 'server' \| 'all'`{lang="ts"} | `false`  | This options indicates if component should render on client, server or both. By default, it will render on both client and server. |
 | `priority`         | `number`                     | `false`  | Priority of the component, if multiple components have the same name, the one with the highest priority will be used. |
+
+### Examples
+
+If you want to auto-import a component from an npm package, and the component is a named export (rather than the default), you can use the `export` option to specify it.
+
+```ts
+import { addComponent, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    // import { MyComponent as MyAutoImportedComponent } from 'my-npm-package'
+    addComponent({
+      name: 'MyAutoImportedComponent',
+      export: 'MyComponent',
+      filePath: 'my-npm-package',
+    })
+  },
+})
+```