@nuxt/docs 0.0.0 → 3.17.1

package/3.api/4.commands/dev.md

@@ -0,0 +1,59 @@
+---
+title: 'nuxi dev'
+description: The dev command starts a development server with hot module replacement at http://localhost:3000
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/dev.ts
+    size: xs
+---
+
+<!--dev-cmd-->
+```bash [Terminal]
+npx nuxi dev [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv] [--envName] [--no-clear] [--no-fork] [-p, --port] [-h, --host] [--clipboard] [-o, --open] [--https] [--publicURL] [--qr] [--public] [--tunnel] [--sslCert] [--sslKey]
+```
+<!--/dev-cmd-->
+
+The `dev` command starts a development server with hot module replacement at [http://localhost:3000](https://localhost:3000)
+
+## Arguments
+
+<!--dev-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/dev-args-->
+
+## Options
+
+<!--dev-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
+`--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
+`--dotenv` |  | Path to `.env` file to load, relative to the root directory
+`--envName` |  | The environment to use when resolving configuration overrides (default is `production` when building, and `development` when running the dev server)
+`--no-clear` |  | Disable clear console on restart
+`--no-fork` |  | Disable forked mode
+`-p, --port` |  | Port to listen on (default: `NUXT_PORT \|\| NITRO_PORT \|\| PORT \|\| nuxtOptions.devServer.port`)
+`-h, --host` |  | Host to listen on (default: `NUXT_HOST \|\| NITRO_HOST \|\| HOST \|\| nuxtOptions._layers?.[0]?.devServer?.host`)
+`--clipboard` | `false` | Copy the URL to the clipboard
+`-o, --open` | `false` | Open the URL in the browser
+`--https` |  | Enable HTTPS
+`--publicURL` |  | Displayed public URL (used for QR code)
+`--qr` |  | Display The QR code of public URL when available
+`--public` |  | Listen to all network interfaces
+`--tunnel` |  | Open a tunnel using https://github.com/unjs/untun
+`--sslCert` |  | (DEPRECATED) Use `--https.cert` instead.
+`--sslKey` |  | (DEPRECATED) Use `--https.key` instead.
+<!--/dev-opts-->
+
+The port and host can also be set via NUXT_PORT, PORT, NUXT_HOST or HOST environment variables.
+
+Additionally to the above options, `nuxi` can pass options through to `listhen`, e.g. `--no-qr` to turn off the dev server QR code. You can find the list of `listhen` options in the [unjs/listhen](https://github.com/unjs/listhen) docs.
+
+This command sets `process.env.NODE_ENV` to `development`.
+
+::note
+If you are using a self-signed certificate in development, you will need to set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment.
+::

package/3.api/4.commands/devtools.md

@@ -0,0 +1,38 @@
+---
+title: "nuxi devtools"
+description: The devtools command allows you to enable or disable Nuxt DevTools on a per-project basis.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/devtools.ts
+    size: xs
+---
+
+<!--devtools-cmd-->
+```bash [Terminal]
+npx nuxi devtools <COMMAND> [ROOTDIR] [--cwd=<directory>]
+```
+<!--/devtools-cmd-->
+
+Running `nuxi devtools enable` will install the Nuxt DevTools globally, and also enable it within the particular project you are using. It is saved as a preference in your user-level `.nuxtrc`. If you want to remove devtools support for a particular project, you can run `nuxi devtools disable`.
+
+## Arguments
+
+<!--devtools-args-->
+Argument | Description
+--- | ---
+`COMMAND` | Command to run (options: <enable\|disable>)
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/devtools-args-->
+
+## Options
+
+<!--devtools-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
+<!--/devtools-opts-->
+
+::read-more{icon="i-simple-icons-nuxtdotjs" to="https://devtools.nuxt.com" target="\_blank"}
+Read more about the **Nuxt DevTools**.
+::

package/3.api/4.commands/generate.md

@@ -0,0 +1,41 @@
+---
+title: "nuxi generate"
+description: Pre-renders every route of the application and stores the result in plain HTML files.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/generate.ts
+    size: xs
+---
+
+<!--generate-cmd-->
+```bash [Terminal]
+npx nuxi generate [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--preset] [--dotenv] [--envName]
+```
+<!--/generate-cmd-->
+
+The `generate` command pre-renders every route of your application and stores the result in plain HTML files that you can deploy on any static hosting services. The command triggers the `nuxi build` command with the `prerender` argument set to `true`
+
+## Arguments
+
+<!--generate-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/generate-args-->
+
+## Options
+
+<!--generate-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
+`--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
+`--preset` |  | Nitro server preset
+`--dotenv` |  | Path to `.env` file to load, relative to the root directory
+`--envName` |  | The environment to use when resolving configuration overrides (default is `production` when building, and `development` when running the dev server)
+<!--/generate-opts-->
+
+::read-more{to="/docs/getting-started/deployment#static-hosting"}
+Read more about pre-rendering and static hosting.
+::

package/3.api/4.commands/info.md

@@ -0,0 +1,33 @@
+---
+title: "nuxi info"
+description: The info command logs information about the current or specified Nuxt project.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/info.ts
+    size: xs
+---
+
+<!--info-cmd-->
+```bash [Terminal]
+npx nuxi info [ROOTDIR] [--cwd=<directory>]
+```
+<!--/info-cmd-->
+
+The `info` command logs information about the current or specified Nuxt project.
+
+## Arguments
+
+<!--info-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/info-args-->
+
+## Options
+
+<!--info-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
+<!--/info-opts-->

package/3.api/4.commands/init.md

@@ -0,0 +1,46 @@
+---
+title: "nuxi init"
+description: The init command initializes a fresh Nuxt project.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/init.ts
+    size: xs
+---
+
+<!--init-cmd-->
+```bash [Terminal]
+npx nuxi init [DIR] [--cwd=<directory>] [-t, --template] [-f, --force] [--offline] [--preferOffline] [--no-install] [--gitInit] [--shell] [--packageManager]
+```
+<!--/init-cmd-->
+
+The `init` command initializes a fresh Nuxt project using [unjs/giget](https://github.com/unjs/giget).
+
+## Arguments
+
+<!--init-args-->
+Argument | Description
+--- | ---
+`DIR=""` | Project directory
+<!--/init-args-->
+
+## Options
+
+<!--init-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` | `.` | Specify the working directory
+`-t, --template` |  | Template name
+`-f, --force` |  | Override existing directory
+`--offline` |  | Force offline mode
+`--preferOffline` |  | Prefer offline mode
+`--no-install` |  | Skip installing dependencies
+`--gitInit` |  | Initialize git repository
+`--shell` |  | Start shell after installation in project directory
+`--packageManager` |  | Package manager choice (npm, pnpm, yarn, bun)
+<!--/init-opts-->
+
+## Environment variables
+
+- `NUXI_INIT_REGISTRY`: Set to a custom template registry. ([learn more](https://github.com/unjs/giget#custom-registry)).
+  - Default registry is loaded from [nuxt/starter/templates](https://github.com/nuxt/starter/tree/templates/templates)

package/3.api/4.commands/module.md

@@ -0,0 +1,84 @@
+---
+title: "nuxi module"
+description: "Search and add modules to your Nuxt application with the command line."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/module/
+    size: xs
+---
+
+Nuxi provides a few utilities to work with [Nuxt modules](/modules) seamlessly.
+
+## nuxi module add
+
+<!--module-add-cmd-->
+```bash [Terminal]
+npx nuxi module add <MODULENAME> [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--skipInstall] [--skipConfig] [--dev]
+```
+<!--/module-add-cmd-->
+
+<!--module-add-args-->
+Argument | Description
+--- | ---
+`MODULENAME` | Module name
+<!--/module-add-args-->
+
+<!--module-add-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` | `.` | Specify the working directory
+`--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
+`--skipInstall` |  | Skip npm install
+`--skipConfig` |  | Skip nuxt.config.ts update
+`--dev` |  | Install module as dev dependency
+<!--/module-add-opts-->
+
+The command lets you install [Nuxt modules](/modules) in your application with no manual work.
+
+When running the command, it will:
+
+- install the module as a dependency using your package manager
+- add it to your [package.json](/docs/guide/directory-structure/package) file
+- update your [`nuxt.config`](/docs/guide/directory-structure/nuxt-config) file
+
+**Example:**
+
+Installing the [`Pinia`](/modules/pinia) module
+
+```bash [Terminal]
+npx nuxi module add pinia
+```
+
+## nuxi module search
+
+<!--module-search-cmd-->
+```bash [Terminal]
+npx nuxi module search <QUERY> [--cwd=<directory>] [--nuxtVersion=<2|3>]
+```
+<!--/module-search-cmd-->
+
+### Arguments
+
+<!--module-search-args-->
+Argument | Description
+--- | ---
+`QUERY` | keywords to search for
+<!--/module-search-args-->
+
+### Options
+
+<!--module-search-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` | `.` | Specify the working directory
+`--nuxtVersion=<2\|3>` |  | Filter by Nuxt version and list compatible modules only (auto detected by default)
+<!--/module-search-opts-->
+
+The command searches for Nuxt modules matching your query that are compatible with your Nuxt version.
+
+**Example:**
+
+```bash [Terminal]
+npx nuxi module search pinia
+```

package/3.api/4.commands/prepare.md

@@ -0,0 +1,36 @@
+---
+title: 'nuxi prepare'
+description: The prepare command creates a .nuxt directory in your application and generates types.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/prepare.ts
+    size: xs
+---
+
+<!--prepare-cmd-->
+```bash [Terminal]
+npx nuxi prepare [ROOTDIR] [--dotenv] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName]
+```
+<!--/prepare-cmd-->
+
+The `prepare` command creates a [`.nuxt`](/docs/guide/directory-structure/nuxt) directory in your application and generates types. This can be useful in a CI environment or as a `postinstall` command in your [`package.json`](/docs/guide/directory-structure/package).
+
+## Arguments
+
+<!--prepare-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/prepare-args-->
+
+## Options
+
+<!--prepare-opts-->
+Option | Default | Description
+--- | --- | ---
+`--dotenv` |  | Path to `.env` file to load, relative to the root directory
+`--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
+`--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
+`--envName` |  | The environment to use when resolving configuration overrides (default is `production` when building, and `development` when running the dev server)
+<!--/prepare-opts-->

package/3.api/4.commands/preview.md

@@ -0,0 +1,43 @@
+---
+title: "nuxi preview"
+description: The preview command starts a server to preview your application after the build command.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/preview.ts
+    size: xs
+---
+
+<!--preview-cmd-->
+```bash [Terminal]
+npx nuxi preview [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName] [--dotenv] [-p, --port]
+```
+<!--/preview-cmd-->
+
+The `preview` command starts a server to preview your Nuxt application after running the `build` command. The `start` command is an alias for `preview`. When running your application in production refer to the [Deployment section](/docs/getting-started/deployment).
+
+## Arguments
+
+<!--preview-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/preview-args-->
+
+## Options
+
+<!--preview-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
+`--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
+`--envName` |  | The environment to use when resolving configuration overrides (default is `production` when building, and `development` when running the dev server)
+`--dotenv` |  | Path to `.env` file to load, relative to the root directory
+`-p, --port` |  | Port to listen on (default: `NUXT_PORT \|\| NITRO_PORT \|\| PORT`)
+<!--/preview-opts-->
+
+This command sets `process.env.NODE_ENV` to `production`. To override, define `NODE_ENV` in a `.env` file or as command-line argument.
+
+::note
+For convenience, in preview mode, your [`.env`](/docs/guide/directory-structure/env) file will be loaded into `process.env`. (However, in production you will need to ensure your environment variables are set yourself.)
+::

package/3.api/4.commands/typecheck.md

@@ -0,0 +1,42 @@
+---
+title: "nuxi typecheck"
+description: The typecheck command runs vue-tsc to check types throughout your app.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/typecheck.ts
+    size: xs
+---
+
+<!--typecheck-cmd-->
+```bash [Terminal]
+npx nuxi typecheck [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>]
+```
+<!--/typecheck-cmd-->
+
+The `typecheck` command runs [`vue-tsc`](https://github.com/vuejs/language-tools/tree/master/packages/tsc) to check types throughout your app.
+
+## Arguments
+
+<!--typecheck-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/typecheck-args-->
+
+## Options
+
+<!--typecheck-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
+`--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
+<!--/typecheck-opts-->
+
+::note
+This command sets `process.env.NODE_ENV` to `production`. To override, define `NODE_ENV` in a [`.env`](/docs/guide/directory-structure/env) file or as a command-line argument.
+::
+
+::read-more{to="/docs/guide/concepts/typescript#type-checking"}
+Read more on how to enable type-checking at build or development time.
+::

package/3.api/4.commands/upgrade.md

@@ -0,0 +1,37 @@
+---
+title: "nuxi upgrade"
+description: The upgrade command upgrades Nuxt to the latest version.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/upgrade.ts
+    size: xs
+---
+
+<!--upgrade-cmd-->
+```bash [Terminal]
+npx nuxi upgrade [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dedupe] [-f, --force] [-ch, --channel=<stable|nightly>]
+```
+<!--/upgrade-cmd-->
+
+The `upgrade` command upgrades Nuxt to the latest version.
+
+## Arguments
+
+<!--upgrade-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/upgrade-args-->
+
+## Options
+
+<!--upgrade-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
+`--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
+`--dedupe` |  | Will deduplicate dependencies but not recreate the lockfile
+`-f, --force` |  | Force upgrade to recreate lockfile and node_modules
+`-ch, --channel=<stable\|nightly>` | `stable` | Specify a channel to install from (default: stable)
+<!--/upgrade-opts-->

package/3.api/5.kit/.navigation.yml

@@ -0,0 +1,3 @@
+title: Nuxt Kit
+titleTemplate: '%s · Nuxt Kit'
+navigation.icon: i-lucide-package

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

@@ -0,0 +1,172 @@
+---
+title: "Modules"
+description: Nuxt Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/module
+    size: xs
+---
+
+Modules are the building blocks of Nuxt. Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules. For example, you can use the `defineNuxtModule` function to define a module and the `installModule` function to install a module programmatically.
+
+## `defineNuxtModule`
+
+Define a Nuxt module, automatically merging defaults with user provided options, installing any hooks that are provided, and calling an optional setup function for full control.
+
+### Type
+
+```ts
+function defineNuxtModule<OptionsT extends ModuleOptions> (definition: ModuleDefinition<OptionsT> | NuxtModule<OptionsT>): NuxtModule<OptionsT>
+
+type ModuleOptions = Record<string, any>
+
+interface ModuleDefinition<T extends ModuleOptions = ModuleOptions> {
+  meta?: ModuleMeta
+  defaults?: T | ((nuxt: Nuxt) => T)
+  schema?: T
+  hooks?: Partial<NuxtHooks>
+  setup?: (this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupReturn>
+}
+
+interface NuxtModule<T extends ModuleOptions = ModuleOptions> {
+  (this: void, inlineOptions: T, nuxt: Nuxt): Awaitable<void | false | ModuleSetupReturn>
+  getOptions?: (inlineOptions?: T, nuxt?: Nuxt) => Promise<T>
+  getMeta?: () => Promise<ModuleMeta>
+}
+
+interface ModuleSetupReturn {
+  timings?: {
+    setup?: number
+    [key: string]: number | undefined
+  }
+}
+
+interface ModuleMeta {
+  name?: string
+  version?: string
+  configKey?: string
+  compatibility?: NuxtCompatibility
+  [key: string]: unknown
+}
+```
+
+### Parameters
+
+#### `definition`
+
+**Type**: `ModuleDefinition<T> | NuxtModule<T>`
+
+**Required**: `true`
+
+A module definition object or a module function.
+
+- `meta` (optional)
+
+  **Type**: `ModuleMeta`
+
+  Metadata of the module. It defines the module name, version, config key and compatibility.
+
+- `defaults` (optional)
+
+  **Type**: `T | ((nuxt: Nuxt) => T)`
+
+  Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument.
+
+- `schema` (optional)
+
+  **Type**: `T`
+
+  Schema for the module options. If provided, options will be applied to the schema.
+
+- `hooks` (optional)
+
+  **Type**: `Partial<NuxtHooks>`
+
+  Hooks to be installed for the module. If provided, the module will install the hooks.
+
+- `setup` (optional)
+
+  **Type**: `(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupReturn>`
+
+  Setup function for the module. If provided, the module will call the setup function.
+
+### Examples
+
+```ts
+// https://github.com/nuxt/starter/tree/module
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+    configKey: 'myModule'
+  },
+  defaults: {
+    test: 123
+  },
+  setup (options, nuxt) {
+    nuxt.hook('modules:done', () => {
+      console.log('My module is ready with current test option: ', options.test)
+    })    
+  }
+})
+```
+
+## `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.
+
+### Type
+
+```ts
+async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)
+```
+
+### Parameters
+
+#### `moduleToInstall`
+
+**Type**: `string` | `NuxtModule`
+
+**Required**: `true`
+
+The module to install. Can be either a string with the module name or a module object itself.
+
+#### `inlineOptions`
+
+**Type**: `any`
+
+**Default**: `{}`
+
+An object with the module options to be passed to the module's `setup` function.
+
+#### `nuxt`
+
+**Type**: `Nuxt`
+
+**Default**: `useNuxt()`
+
+Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+
+### Examples
+
+```ts
+import { defineNuxtModule, installModule } from '@nuxt/kit'
+
+export default defineNuxtModule({  
+  async setup (options, nuxt) {
+    // will install @nuxtjs/fontaine with Roboto font and Impact fallback
+    await installModule('@nuxtjs/fontaine', {
+      // module configuration
+      fonts: [
+        {
+          family: 'Roboto',
+          fallbacks: ['Impact'],
+          fallbackName: 'fallback-a',
+        }
+      ]
+    })
+  }
+})
+```

package/3.api/5.kit/10.runtime-config.md

@@ -0,0 +1,27 @@
+---
+title: Runtime Config
+description: Nuxt Kit provides a set of utilities to help you access and modify Nuxt runtime configuration.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/runtime-config.ts
+    size: xs
+---
+
+## `useRuntimeConfig`
+
+At build-time, it is possible to access the resolved Nuxt [runtime config](/docs/guide/going-further/runtime-config).
+
+### Type
+
+```ts
+function useRuntimeConfig (): Record<string, unknown>
+```
+
+## `updateRuntimeConfig`
+
+It is also possible to update runtime configuration. This will be merged with the existing runtime configuration, and if Nitro has already been initialized it will trigger an HMR event to reload the Nitro runtime config.
+
+```ts
+function updateRuntimeConfig (config: Record<string, unknown>): void | Promise<void>
+```