@nuxt/docs 0.0.0 → 3.17.0

package/2.guide/3.going-further/4.kit.md

@@ -0,0 +1,51 @@
+---
+title: "Nuxt Kit"
+description: "@nuxt/kit provides features for module authors."
+---
+
+Nuxt Kit provides composable utilities to make interacting with [Nuxt Hooks](/docs/api/advanced/hooks), the [Nuxt Interface](/docs/guide/going-further/internals#the-nuxt-interface) and developing [Nuxt Modules](/docs/guide/going-further/modules) super easy.
+
+::read-more{to="/docs/api/kit"}
+Discover all Nuxt Kit utilities.
+::
+
+## Usage
+
+### Install Dependency
+
+You can install the latest Nuxt Kit by adding it to the `dependencies` section of your `package.json`. However, please consider always explicitly installing the `@nuxt/kit` package even if it is already installed by Nuxt.
+
+::note
+`@nuxt/kit` and `@nuxt/schema` are key dependencies for Nuxt. If you are installing it separately, make sure that the versions of `@nuxt/kit` and `@nuxt/schema` are equal to or greater than your `nuxt` version to avoid any unexpected behavior.
+::
+
+```json [package.json]
+{
+  "dependencies": {
+    "@nuxt/kit": "npm:@nuxt/kit-nightly@latest"
+  }
+}
+```
+
+### Import Kit Utilities
+
+```js [test.mjs]
+import { useNuxt } from '@nuxt/kit'
+```
+
+:read-more{to="/docs/api/kit"}
+
+::note
+Nuxt Kit utilities are only available for modules and not meant to be imported in runtime (components, Vue composables, pages, plugins, or server routes).
+::
+
+Nuxt Kit is an [esm-only package](/docs/guide/concepts/esm) meaning that you **cannot** `require('@nuxt/kit')`. As a workaround, use dynamic import in the CommonJS context:
+
+```js [test.cjs]
+// This does NOT work!
+// const kit = require('@nuxt/kit')
+async function main() {
+  const kit = await import('@nuxt/kit')
+}
+main()
+```

package/2.guide/3.going-further/6.nuxt-app.md

@@ -0,0 +1,64 @@
+---
+title: "NuxtApp"
+description: "In Nuxt, you can access runtime app context within composables, components and plugins."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts
+---
+
+In Nuxt, you can access runtime app context within composables, components and plugins.
+
+::read-more{to="https://v2.nuxt.com/docs/internals-glossary/context#the-context" target="_blank"}
+In Nuxt 2, this was referred to as **Nuxt context**.
+::
+
+## Nuxt App Interface
+
+::read-more{to="/docs/guide/going-further/internals#the-nuxtapp-interface"}
+Jump over the `NuxtApp` interface documentation.
+::
+
+## The Nuxt Context
+
+Many composables and utilities, both built-in and user-made, may require access to the Nuxt instance. This doesn't exist everywhere on your application, because a fresh instance is created on every request.
+
+Currently, the Nuxt context is only accessible in [plugins](/docs/guide/directory-structure/plugins), [Nuxt hooks](/docs/guide/going-further/hooks), [Nuxt middleware](/docs/guide/directory-structure/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup.html) (in pages and components).
+
+If a composable is called without access to the context, you may get an error stating that 'A composable that requires access to the Nuxt instance was called outside of a plugin, Nuxt hook, Nuxt middleware, or Vue setup function.' In that case, you can also explicitly call functions within this context by using [`nuxtApp.runWithContext`](/docs/api/composables/use-nuxt-app#runwithcontext).
+
+## Accessing NuxtApp
+
+Within composables, plugins and components you can access `nuxtApp` with [`useNuxtApp()`](/docs/api/composables/use-nuxt-app):
+
+```ts [composables/useMyComposable.ts]
+export function useMyComposable () {
+  const nuxtApp = useNuxtApp()
+  // access runtime nuxt app instance
+}
+```
+
+If your composable does not always need `nuxtApp` or you simply want to check if it is present or not, since [`useNuxtApp`](/docs/api/composables/use-nuxt-app) throws an exception, you can use [`tryUseNuxtApp`](/docs/api/composables/use-nuxt-app#tryusenuxtapp) instead.
+
+Plugins also receive `nuxtApp` as the first argument for convenience.
+
+:read-more{to="/docs/guide/directory-structure/plugins"}
+
+## Providing Helpers
+
+You can provide helpers to be usable across all composables and application. This usually happens within a Nuxt plugin.
+
+```ts
+const nuxtApp = useNuxtApp()
+nuxtApp.provide('hello', (name) => `Hello ${name}!`)
+
+console.log(nuxtApp.$hello('name')) // Prints "Hello name!"
+```
+
+::read-more{to="/docs/guide/directory-structure/plugins#providing-helpers"}
+It is possible to inject helpers by returning an object with a `provide` key in plugins.
+::
+
+::read-more{to="https://v2.nuxt.com/docs/directory-structure/plugins#inject-in-root--context" target="_blank"}
+In Nuxt 2 plugins, this was referred to as **inject function**.
+::

package/2.guide/3.going-further/7.layers.md

@@ -0,0 +1,227 @@
+---
+title: Authoring Nuxt Layers
+description: Nuxt provides a powerful system that allows you to extend the default files, configs, and much more.
+---
+
+Nuxt layers are a powerful feature that you can use to share and reuse partial Nuxt applications within a monorepo, or from a git repository or npm package. The layers structure is almost identical to a standard Nuxt application, which makes them easy to author and maintain.
+
+:read-more{to="/docs/getting-started/layers"}
+
+A minimal Nuxt layer directory should contain a [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file to indicate it is a layer.
+
+```ts [base/nuxt.config.ts]
+export default defineNuxtConfig({})
+```
+
+Additionally, certain other files in the layer directory will be auto-scanned and used by Nuxt for the project extending this layer.
+
+- [`components/*`](/docs/guide/directory-structure/components)   - Extend the default components
+- [`composables/*`](/docs/guide/directory-structure/composables)  - Extend the default composables
+- [`layouts/*`](/docs/guide/directory-structure/layouts)  - Extend the default layouts
+- [`pages/*`](/docs/guide/directory-structure/pages)        - Extend the default pages
+- [`plugins/*`](/docs/guide/directory-structure/plugins)        - Extend the default plugins
+- [`server/*`](/docs/guide/directory-structure/server)       - Extend the default server endpoints & middleware
+- [`utils/*`](/docs/guide/directory-structure/utils)   - Extend the default utils
+- [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config)- Extend the default nuxt config
+- [`app.config.ts`](/docs/guide/directory-structure/app-config)  - Extend the default app config
+
+## Basic Example
+
+::code-group
+
+  ```ts [nuxt.config.ts]
+  export default defineNuxtConfig({
+    extends: [
+      './base'
+    ]
+  })
+  ```
+
+  ```vue [app.vue]
+    <template>
+      <BaseComponent/>
+    </template>
+  ```
+
+  ```ts [base/nuxt.config.ts]
+    export default defineNuxtConfig({
+      // Extending from base nuxt.config.ts!
+      app: {
+        head: {
+          title: 'Extending Configs is Fun!',
+          meta: [
+            { name: 'description', content: 'I am using the extends feature in Nuxt!' }
+          ],
+        }
+      }
+    })
+  ```
+
+  ```vue [base/components/BaseComponent.vue]
+    <template>
+      <h1>Extending Components is Fun!</h1>
+    </template>
+  ```
+
+::
+
+## Starter Template
+
+To get started you can initialize a layer with the [nuxt/starter/layer template](https://github.com/nuxt/starter/tree/layer). This will create a basic structure you can build upon. Execute this command within the terminal to get started:
+
+```bash [Terminal]
+npm create nuxt -- --template layer nuxt-layer
+```
+
+Follow up on the README instructions for the next steps.
+
+## Publishing Layers
+
+You can publish and share layers by either using a remote source or an npm package.
+
+### Git Repository
+
+You can use a git repository to share your Nuxt layer. Some examples:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: [
+    'github:username/repoName',        // GitHub Remote Source
+    'github:username/repoName/base',   // GitHub Remote Source within /base directory
+    'github:username/repoName#dev',    // GitHub Remote Source from dev branch
+    'github:username/repoName#v1.0.0', // GitHub Remote Source from v1.0.0 tag
+    'gitlab:username/repoName',        // GitLab Remote Source example
+    'bitbucket:username/repoName',     // Bitbucket Remote Source example
+  ]
+})
+```
+
+::tip
+If you want to extend a private remote source, you need to add the environment variable `GIGET_AUTH=<token>` to provide a token.
+::
+
+::tip
+If you want to extend a remote source from a self-hosted GitHub or GitLab instance, you need to supply its URL with the `GIGET_GITHUB_URL=<url>` or `GIGET_GITLAB_URL=<url>` environment variable - or directly configure it with [the `auth` option](https://github.com/unjs/c12#extending-config-layer-from-remote-sources) in your `nuxt.config`.
+::
+
+::warning
+Bear in mind that if you are extending a remote source as a layer, you will not be able to access its dependencies outside of Nuxt. For example, if the remote layer depends on an eslint plugin, this will not be usable in your eslint config. That is because these dependencies will be located in a special location (`node_modules/.c12/layer_name/node_modules/`) that is not accessible to your package manager.
+::
+
+::note
+When using git remote sources, if a layer has npm dependencies and you wish to install them, you can do so by specifying `install: true` in your layer options.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: [
+    ['github:username/repoName', { install: true }]
+  ]
+})
+```
+::
+
+### npm Package
+
+You can publish Nuxt layers as an npm package that contains the files and dependencies you want to extend. This allows you to share your config with others, use it in multiple projects or use it privately.
+
+To extend from an npm package, you need to make sure that the module is published to npm and installed in the user's project as a devDependency. Then you can use the module name to extend the current nuxt config:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: [
+    // Node Module with scope
+    '@scope/moduleName',
+    // or just the module name
+    'moduleName'
+  ]
+})
+```
+
+To publish a layer directory as an npm package, you want to make sure that the `package.json` has the correct properties filled out. This will make sure that the files are included when the package is published.
+
+```json [package.json]
+{
+  "name": "my-theme",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "dependencies": {},
+  "devDependencies": {
+    "nuxt": "^3.0.0"
+  }
+}
+```
+
+::important
+Make sure any dependency imported in the layer is **explicitly added** to the `dependencies`. The `nuxt` dependency, and anything only used for testing the layer before publishing, should remain in the `devDependencies` field.
+::
+
+Now you can proceed to publish the module to npm, either publicly or privately.
+
+::important
+When publishing the layer as a private npm package, you need to make sure you log in, to authenticate with npm to download the node module.
+::
+
+## Tips
+
+### Named Layer Aliases
+
+Auto-scanned layers (from your `~~/layers` directory) automatically create aliases. For example, you can access your `~~/layers/test` layer via `#layers/test`.
+
+If you want to create named layer aliases for other layers, you can specify a name in the configuration of the layer.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  $meta: {
+    name: 'example',
+  },
+})
+```
+
+This will produce an alias of `#layers/example` which points to your layer.
+
+### Relative Paths and Aliases
+
+When importing using global aliases (such as `~/` and `@/`) in a layer components and composables, note that these aliases are resolved relative to the user's project paths. As a workaround, you can **use relative paths** to import them, or use named layer aliases.
+
+Also when using relative paths in `nuxt.config` file of a layer, (with exception of nested `extends`) they are resolved relative to user's project instead of the layer. As a workaround, use full resolved paths in `nuxt.config`:
+
+```js [nuxt.config.ts]
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+
+const currentDir = dirname(fileURLToPath(import.meta.url))
+
+export default defineNuxtConfig({
+  css: [
+    join(currentDir, './assets/main.css')
+  ]
+})
+```
+
+## Multi-Layer Support for Nuxt Modules
+
+You can use the internal array `nuxt.options._layers` to support custom multi-layer handling for your modules.
+
+```ts [modules/my-module.ts]
+export default defineNuxtModule({
+  setup(_options, nuxt) {
+    for (const layer of nuxt.options._layers) {
+      // You can check for a custom directory existence to extend for each layer
+      console.log('Custom extension for', layer.cwd, layer.config)
+    }
+  }
+})
+```
+
+**Notes:**
+- Earlier items in the `_layers` array have higher priority and override later ones
+- The user's project is the first item in the `_layers` array
+
+## Going Deeper
+
+Configuration loading and extends support is handled by [unjs/c12](https://github.com/unjs/c12), merged using [unjs/defu](https://github.com/unjs/defu) and remote git sources are supported using [unjs/giget](https://github.com/unjs/giget). Check the docs and source code to learn more.
+
+::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/13367" target="_blank"}
+Checkout our ongoing development to bring more improvements for layers support on GitHub.
+::

package/2.guide/3.going-further/9.debugging.md

@@ -0,0 +1,115 @@
+---
+title: "Debugging"
+description: "In Nuxt, you can get started with debugging your application directly in the browser as well as in your IDE."
+---
+
+## Sourcemaps
+
+Sourcemaps are enabled for your server build by default, and for the client build in dev mode, but you can enable them more specifically in your configuration.
+
+```ts
+export default defineNuxtConfig({
+  // or sourcemap: true
+  sourcemap: {
+    server: true,
+    client: true
+  }
+})
+```
+
+## Debugging with Node Inspector
+
+You can use [Node inspector](https://nodejs.org/en/learn/getting-started/debugging) to debug Nuxt server-side.
+
+```bash
+nuxi dev --inspect
+```
+This will start Nuxt in `dev` mode with debugger active. If everything is working correctly a Node.js icon will appear on your Chrome DevTools and you can attach to the debugger.
+
+::important
+Note that the Node.js and Chrome processes need to be run on the same platform. This doesn't work inside of Docker.
+::
+
+## Debugging in Your IDE
+
+It is possible to debug your Nuxt app in your IDE while you are developing it.
+
+### Example VS Code Debug Configuration
+
+You may need to update the config below with a path to your web browser. For more information, visit the [VS Code documentation about debug configuration](https://go.microsoft.com/fwlink/?linkid=830387).
+
+::important
+If you use `pnpm`, you will need to have `nuxi` installed as a devDependency for the configuration below to work.
+::
+
+```json5
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "chrome",
+      "request": "launch",
+      "name": "client: chrome",
+      "url": "http://localhost:3000",
+      "webRoot": "${workspaceFolder}"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "server: nuxt",
+      "outputCapture": "std",
+      "program": "${workspaceFolder}/node_modules/nuxt/bin/nuxt.mjs",
+      "args": [
+        "dev"
+      ],
+    }
+  ],
+  "compounds": [
+    {
+      "name": "fullstack: nuxt",
+      "configurations": [
+        "server: nuxt",
+        "client: chrome"
+      ]
+    }
+  ]
+}
+```
+
+If you prefer your usual browser extensions, add this to the _chrome_ configuration above:
+
+```json5
+"userDataDir": false,
+```
+
+### Example JetBrains IDEs Debug Configuration
+
+You can also debug your Nuxt app in JetBrains IDEs such as IntelliJ IDEA, WebStorm, or PhpStorm.
+
+1. Create a new file in your project root directory and name it `nuxt.run.xml`.
+
+2. Open the `nuxt.run.xml` file and paste the following debug configuration:
+
+```html
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="client: chrome" type="JavascriptDebugType" uri="http://localhost:3000" useFirstLineBreakpoints="true">
+    <method v="2" />
+  </configuration>
+
+  <configuration default="false" name="server: nuxt" type="NodeJSConfigurationType" application-parameters="dev" path-to-js-file="$PROJECT_DIR$/node_modules/nuxt/bin/nuxt.mjs" working-dir="$PROJECT_DIR$">
+    <method v="2" />
+  </configuration>
+
+  <configuration default="false" name="fullstack: nuxt" type="CompoundRunConfigurationType">
+    <toRun name="client: chrome" type="JavascriptDebugType" />
+    <toRun name="server: nuxt" type="NodeJSConfigurationType" />
+    <method v="2" />
+  </configuration>
+</component>
+```
+
+### Other IDEs
+
+If you have another IDE and would like to contribute sample configuration, feel free to [open a PR](https://github.com/nuxt/nuxt/edit/main/docs/2.guide/3.going-further/9.debugging.md)!

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

@@ -0,0 +1,4 @@
+---
+navigation: false
+redirect: /guide/going-further/tooling
+---

package/2.guide/4.recipes/.navigation.yml

@@ -0,0 +1,3 @@
+title: Recipes
+titleTemplate: '%s · Recipes'
+icon: i-lucide-cooking-pot

package/2.guide/4.recipes/1.custom-routing.md

@@ -0,0 +1,181 @@
+---
+title: "Custom Routing"
+description: "In Nuxt, your routing is defined by the structure of your files inside the pages directory. However, since it uses vue-router under the hood, Nuxt offers you several ways to add custom routes in your project."
+---
+
+## Adding custom routes
+
+In Nuxt, your routing is defined by the structure of your files inside the [pages directory](/docs/guide/directory-structure/pages). However, since it uses [vue-router](https://router.vuejs.org) under the hood, Nuxt offers you several ways to add custom routes in your project.
+
+### Router Config
+
+Using [router options](/docs/guide/recipes/custom-routing#router-options), you can optionally override or extend your routes using a function that accepts the scanned routes and returns customized routes.
+
+If it returns `null` or `undefined`, Nuxt will fall back to the default routes (useful to modify input array).
+
+```ts [app/router.options.ts]
+import type { RouterConfig } from '@nuxt/schema'
+
+export default {
+  // https://router.vuejs.org/api/interfaces/routeroptions.html#routes
+  routes: (_routes) => [
+    {
+      name: 'home',
+      path: '/',
+      component: () => import('~/pages/home.vue')
+    }
+  ],
+} satisfies RouterConfig
+```
+
+::note
+Nuxt will not augment any new routes you return from the `routes` function with metadata defined in `definePageMeta` of the component you provide. If you want that to happen, you should use the `pages:extend` hook which is [called at build-time](/docs/api/advanced/hooks#nuxt-hooks-build-time).
+::
+
+### Pages Hook
+
+You can add, change or remove pages from the scanned routes with the `pages:extend` nuxt hook.
+
+For example, to prevent creating routes for any `.ts` files:
+
+```ts [nuxt.config.ts]
+import type { NuxtPage } from '@nuxt/schema'
+
+export default defineNuxtConfig({
+  hooks: {
+    'pages:extend' (pages) {
+      // add a route
+      pages.push({
+        name: 'profile',
+        path: '/profile',
+        file: '~/extra-pages/profile.vue'
+      })
+
+      // remove routes
+      function removePagesMatching (pattern: RegExp, pages: NuxtPage[] = []) {
+        const pagesToRemove: NuxtPage[] = []
+        for (const page of pages) {
+          if (page.file && pattern.test(page.file)) {
+            pagesToRemove.push(page)
+          } else {
+            removePagesMatching(pattern, page.children)
+          }
+        }
+        for (const page of pagesToRemove) {
+          pages.splice(pages.indexOf(page), 1)
+        }
+      }
+      removePagesMatching(/\.ts$/, pages)
+    }
+  }
+})
+```
+
+### Nuxt Module
+
+If you plan to add a whole set of pages related with a specific functionality, you might want to use a [Nuxt module](/modules).
+
+The [Nuxt kit](/docs/guide/going-further/kit) provides a few ways [to add routes](/docs/api/kit/pages):
+- [`extendPages`](/docs/api/kit/pages#extendpages) (callback: pages => void)
+- [`extendRouteRules`](/docs/api/kit/pages#extendrouterules) (route: string, rule: NitroRouteConfig, options: ExtendRouteRulesOptions)
+
+## Router Options
+
+On top of customizing options for [`vue-router`](https://router.vuejs.org/api/interfaces/routeroptions.html), Nuxt offers [additional options](/docs/api/nuxt-config#router) to customize the router.
+
+### Using `app/router.options`
+
+This is the recommended way to specify [router options](/docs/api/nuxt-config#router).
+
+```ts [app/router.options.ts]
+import type { RouterConfig } from '@nuxt/schema'
+
+export default {
+} satisfies RouterConfig
+```
+
+It is possible to add more router options files by adding files within the `pages:routerOptions` hook. Later items in the array override earlier ones.
+
+::callout
+Adding a router options file in this hook will switch on page-based routing, unless `optional` is set, in which case it will only apply when page-based routing is already enabled.
+::
+
+```ts [nuxt.config.ts]
+import { createResolver } from '@nuxt/kit'
+
+export default defineNuxtConfig({
+  hooks: {
+    'pages:routerOptions' ({ files }) {
+      const resolver = createResolver(import.meta.url)
+      // add a route
+      files.push({
+        path: resolver.resolve('./runtime/app/router-options'),
+        optional: true
+      })
+    }
+  }
+})
+```
+
+### Using `nuxt.config`
+
+**Note:** Only JSON serializable [options](/docs/api/nuxt-config#router) are configurable:
+
+- `linkActiveClass`
+- `linkExactActiveClass`
+- `end`
+- `sensitive`
+- `strict`
+- `hashMode`
+- `scrollBehaviorType`
+
+```js [nuxt.config]
+export default defineNuxtConfig({
+  router: {
+    options: {}
+  }
+})
+```
+
+### Hash Mode (SPA)
+
+You can enable hash history in SPA mode using the `hashMode` [config](/docs/api/nuxt-config#router). In this mode, router uses a hash character (#) before the actual URL that is internally passed. When enabled, the **URL is never sent to the server** and **SSR is not supported**.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  ssr: false,
+  router: {
+    options: {
+      hashMode: true
+    }
+  }
+})
+```
+
+### Scroll Behavior for hash links
+
+You can optionally customize the scroll behavior for hash links. When you set the [config](/docs/api/nuxt-config#router) to be `smooth` and you load a page with a hash link (e.g. `https://example.com/blog/my-article#comments`), you will see that the browser smoothly scrolls to this anchor.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  router: {
+    options: {
+      scrollBehaviorType: 'smooth'
+    }
+  }
+})
+```
+
+#### Custom History (advanced)
+
+You can optionally override history mode using a function that accepts the base URL and returns the history mode. If it returns `null` or `undefined`, Nuxt will fallback to the default history.
+
+```ts [app/router.options.ts]
+import type { RouterConfig } from '@nuxt/schema'
+import { createMemoryHistory } from 'vue-router'
+
+export default {
+  // https://router.vuejs.org/api/interfaces/routeroptions.html
+  history: base => import.meta.client ? createMemoryHistory(base) : null /* default */
+} satisfies RouterConfig
+```