@nuxt/docs 0.0.0 → 3.17.1

package/2.guide/.navigation.yml

@@ -0,0 +1,2 @@
+title: 'Guide'
+icon: i-lucide-book-open

package/2.guide/0.index.md

@@ -0,0 +1,22 @@
+---
+title: 'Nuxt Guide'
+titleTemplate: '%s'
+description: 'Learn how Nuxt works with in-depth guides.'
+navigation: false
+surround: false
+---
+
+::card-group{class="sm:grid-cols-1"}
+  ::card{icon="i-lucide-medal" title="Key Concepts" to="/docs/guide/concepts"}
+  Discover the main concepts behind Nuxt, from auto-import, hybrid rendering to its TypeScript support.
+  ::
+  ::card{icon="i-lucide-folders" title="Directory Structure" to="/docs/guide/directory-structure"}
+  Learn about Nuxt directory structure and what benefits each directory or file offers.
+  ::
+  ::card{icon="i-lucide-star" title="Going Further" to="/docs/guide/going-further"}
+  Master Nuxt with advanced concepts like experimental features, hooks, modules, and more.
+  ::
+  ::card{icon="i-lucide-book-open" title="Recipes" to="/docs/guide/recipes"}
+  Find solutions to common problems and learn how to implement them in your Nuxt project.
+  ::
+::

package/2.guide/1.concepts/.navigation.yml

@@ -0,0 +1,3 @@
+title: Key Concepts
+titleTemplate: '%s · Nuxt Concepts'
+icon: i-lucide-medal

package/2.guide/1.concepts/1.auto-imports.md

@@ -0,0 +1,205 @@
+---
+title: Auto-imports
+description: "Nuxt auto-imports components, composables, helper functions and Vue APIs."
+---
+
+Nuxt auto-imports components, composables and [Vue.js APIs](https://vuejs.org/api) to use across your application without explicitly importing them.
+
+```vue twoslash [app.vue]
+<script setup lang="ts">
+const count = ref(1) // ref is auto-imported
+</script>
+```
+
+Thanks to its opinionated directory structure, Nuxt can auto-import your [`components/`](/docs/guide/directory-structure/components), [`composables/`](/docs/guide/directory-structure/composables) and [`utils/`](/docs/guide/directory-structure/utils).
+
+Contrary to a classic global declaration, Nuxt preserves typings, IDEs completions and hints, and **only includes what is used in your production code**.
+
+::note
+In the docs, every function that is not explicitly imported is auto-imported by Nuxt and can be used as-is in your code. You can find a reference for auto-imported components, composables and utilities in the [API section](/docs/api).
+::
+
+::note
+In the [`server`](/docs/guide/directory-structure/server) directory, Nuxt auto-imports exported functions and variables from `server/utils/`.
+::
+
+::note
+You can also auto-import functions exported from custom folders or third-party packages by configuring the [`imports`](/docs/api/nuxt-config#imports) section of your `nuxt.config` file.
+::
+
+## Built-in Auto-imports
+
+Nuxt auto-imports functions and composables to perform [data fetching](/docs/getting-started/data-fetching), get access to the [app context](/docs/api/composables/use-nuxt-app) and [runtime config](/docs/guide/going-further/runtime-config), manage [state](/docs/getting-started/state-management) or define components and plugins.
+
+```vue twoslash
+<script setup lang="ts">
+/* useFetch() is auto-imported */
+const { data, refresh, status } = await useFetch('/api/hello')
+</script>
+```
+
+Vue exposes Reactivity APIs like `ref` or `computed`, as well as lifecycle hooks and helpers that are auto-imported by Nuxt.
+
+```vue twoslash
+<script setup lang="ts">
+/* ref() and computed() are auto-imported */
+const count = ref(1)
+const double = computed(() => count.value * 2)
+</script>
+```
+
+### Vue and Nuxt Composables
+
+<!-- TODO: move to separate page with https://github.com/nuxt/nuxt/issues/14723 and add more information -->
+
+When you are using the built-in Composition API composables provided by Vue and Nuxt, be aware that many of them rely on being called in the right _context_.
+
+During a component lifecycle, Vue tracks the temporary instance of the current component (and similarly, Nuxt tracks a temporary instance of `nuxtApp`) via a global variable, and then unsets it in same tick. This is essential when server rendering, both to avoid cross-request state pollution (leaking a shared reference between two users) and to avoid leakage between different components.
+
+That means that (with very few exceptions) you cannot use them outside a Nuxt plugin, Nuxt route middleware or Vue setup function. On top of that, you must use them synchronously - that is, you cannot use `await` before calling a composable, except within `<script setup>` blocks, within the setup function of a component declared with `defineNuxtComponent`, in `defineNuxtPlugin` or in `defineNuxtRouteMiddleware`, where we perform a transform to keep the synchronous context even after the `await`.
+
+If you get an error message like `Nuxt instance is unavailable` then it probably means you are calling a Nuxt composable in the wrong place in the Vue or Nuxt lifecycle.
+
+:video-accordion{title="Watch a video from Alexander Lichter about avoiding the 'Nuxt instance is unavailable' error" videoId="ofuKRZLtOdY"}
+
+::tip
+When using a composable that requires the Nuxt context inside a non-SFC component, you need to wrap your component with `defineNuxtComponent` instead of `defineComponent`
+::
+
+::read-more{to="/docs/guide/going-further/experimental-features#asynccontext" icon="i-lucide-star"}
+Checkout the `asyncContext` experimental feature to use Nuxt composables in async functions.
+::
+
+::read-more{to="https://github.com/nuxt/nuxt/issues/14269#issuecomment-1397352832" target="_blank"}
+See the full explanation in this GitHub comment.
+::
+
+**Example of breaking code:**
+
+```ts twoslash [composables/example.ts]
+// trying to access runtime config outside a composable
+const config = useRuntimeConfig()
+
+export const useMyComposable = () => {
+  // accessing runtime config here
+}
+```
+
+**Example of working code:**
+
+```ts twoslash [composables/example.ts]
+export const useMyComposable = () => {
+  // Because your composable is called in the right place in the lifecycle,
+  // useRuntimeConfig will work here
+  const config = useRuntimeConfig()
+
+  // ...
+}
+```
+
+## Directory-based Auto-imports
+
+Nuxt directly auto-imports files created in defined directories:
+
+- `components/` for [Vue components](/docs/guide/directory-structure/components).
+- `composables/` for [Vue composables](/docs/guide/directory-structure/composables).
+- `utils/` for helper functions and other utilities.
+
+:link-example{to="/docs/examples/features/auto-imports"}
+
+::warning
+**Auto-imported `ref` and `computed` won't be unwrapped in a component `<template>`.** :br
+This is due to how Vue works with refs that aren't top-level to the template. You can read more about it [in the Vue documentation](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#caveat-when-unwrapping-in-templates).
+::
+
+### Explicit Imports
+
+Nuxt exposes every auto-import with the `#imports` alias that can be used to make the import explicit if needed:
+
+<!-- TODO:twoslash: Twoslash does not support tsconfig paths yet -->
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from '#imports'
+
+const count = ref(1)
+const double = computed(() => count.value * 2)
+</script>
+```
+
+### Disabling Auto-imports
+
+If you want to disable auto-importing composables and utilities, you can set `imports.autoImport` to `false` in the `nuxt.config` file.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  imports: {
+    autoImport: false
+  }
+})
+```
+
+This will disable auto-imports completely but it's still possible to use [explicit imports](#explicit-imports) from `#imports`.
+
+### Partially Disabling Auto-imports
+
+If you want framework-specific functions like `ref` to remain auto-imported but wish to disable auto-imports for your own code (e.g., custom composables), you can set the `imports.scan` option to `false` in your `nuxt.config.ts` file:
+
+```ts
+export default defineNuxtConfig({
+  imports: {
+    scan: false
+  }
+})
+```
+
+With this configuration:
+- Framework functions like `ref`, `computed`, or `watch` will still work without needing manual imports.
+- Custom code, such as composables, will need to be manually imported in your files.
+
+::warning
+**Caution:** This setup has certain limitations:
+- If you structure your project with layers, you will need to explicitly import the composables from each layer, rather than relying on auto-imports.
+- This breaks the layer system’s override feature. If you use `imports.scan: false`, ensure you understand this side-effect and adjust your architecture accordingly.
+::
+
+## Auto-imported Components
+
+Nuxt also automatically imports components from your `~/components` directory, although this is configured separately from auto-importing composables and utility functions.
+
+:read-more{to="/docs/guide/directory-structure/components"}
+
+To disable auto-importing components from your own `~/components` directory, you can set `components.dirs` to an empty array (though note that this will not affect components added by modules).
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  components: {
+    dirs: []
+  }
+})
+```
+
+## Auto-import from Third-Party Packages
+
+Nuxt also allows auto-importing from third-party packages.
+
+::tip
+If you are using the Nuxt module for that package, it is likely that the module has already configured auto-imports for that package.
+::
+
+For example, you could enable the auto-import of the `useI18n` composable from the `vue-i18n` package like this:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  imports: {
+    presets: [
+      {
+        from: 'vue-i18n',
+        imports: ['useI18n']
+      }
+    ]
+  }
+})
+```
+
+:video-accordion{title="Watch a video from Alexander Lichter on how to easily set up custom auto imports" videoId="FT2LQJ2NvVI"}

package/2.guide/1.concepts/10.nuxt-lifecycle.md

@@ -0,0 +1,141 @@
+---
+title: 'Nuxt Lifecycle'
+description: "Understanding the lifecycle of Nuxt applications can help you gain deeper insights into how the framework operates, especially for both server-side and client-side rendering."
+---
+
+The goal of this chapter is to provide a high-level overview of the different parts of the framework, their execution order, and how they work together.
+
+## Server
+
+On the server, the following steps are executed for every initial request to your application:
+
+### Step 1: Setup Nitro Server and Nitro Plugins (Once)
+
+Nuxt is powered by [Nitro](https://nitro.build/), a modern server engine.
+
+When Nitro starts, it initializes and executes the plugins under the `/server/plugins` directory. These plugins can:
+- Capture and handle application-wide errors.
+- Register hooks that execute when Nitro shuts down.
+- Register hooks for request lifecycle events, such as modifying responses.
+
+::callout{icon="i-lucide-lightbulb"}
+Nitro plugins are executed only once when the server starts. In a serverless environment, the server boots on each incoming request, and so do the Nitro plugins. However, they are not awaited.
+::
+
+:read-more{to="/docs/guide/directory-structure/server#server-plugins"}
+
+### Step 2: Nitro Server Middleware
+
+After initializing the Nitro server, middleware under `server/middleware/` is executed for every request. Middleware can be used for tasks such as authentication, logging, or request transformation.
+
+::warning
+Returning a value from middleware will terminate the request and send the returned value as the response. This behavior should generally be avoided to ensure proper request handling!
+::
+
+:read-more{to="/docs/guide/directory-structure/server#server-middleware"}
+
+### Step 3: Initialize Nuxt and Execute Nuxt App Plugins
+
+The Vue and Nuxt instances are created first. Afterward, Nuxt executes its server plugins. This includes:
+- Built-in plugins, such as Vue Router and `unhead`.
+- Custom plugins located in the `plugins/` directory, including those without a suffix (e.g., `myPlugin.ts`) and those with the `.server` suffix (e.g., `myServerPlugin.server.ts`).
+
+Plugins execute in a specific order and may have dependencies on one another. For more details, including execution order and parallelism, refer to the [Plugins documentation](/docs/guide/directory-structure/plugins).
+
+::callout{icon="i-lucide-lightbulb"}
+After this step, Nuxt calls the [`app:created`](/docs/api/advanced/hooks#app-hooks-runtime) hook, which can be used to execute additional logic.
+::
+
+:read-more{to="/docs/guide/directory-structure/plugins"}
+
+### Step 4: Route Validation
+
+After initializing plugins and before executing middleware, Nuxt calls the `validate` method if it is defined in the `definePageMeta` function. The `validate` method, which can be synchronous or asynchronous, is often used to validate dynamic route parameters.
+
+- The `validate` function should return `true` if the parameters are valid.
+- If validation fails, it should return `false` or an object containing a `statusCode` and/or `statusMessage` to terminate the request.
+
+For more information, see the [Route Validation documentation](/docs/getting-started/routing#route-validation).
+
+:read-more{to="/docs/getting-started/routing#route-validation"}
+
+### Step 5: Execute Nuxt App Middleware
+
+Middleware allows you to run code before navigating to a particular route. It is often used for tasks such as authentication, redirection, or logging.
+
+In Nuxt, there are three types of middleware:
+- **Global route middleware**
+- **Named route middleware**
+- **Anonymous (or inline) route middleware**
+
+Nuxt automatically executes global middleware for first time enter to the application and every time before route navigation. Named and anonymous middleware are executed only on the routes specified in the middleware property of the page(route) meta defined in the corresponding page components.
+
+For details about each type and examples, see the [Middleware documentation](/docs/guide/directory-structure/middleware).
+
+Any redirection on the server will result in a `Location:` header being sent to the browser; the browser then makes a fresh request to this new location. All application state will be reset when this happens, unless persisted in a cookie.
+
+:read-more{to="/docs/guide/directory-structure/middleware"}
+
+### Step 6: Setup Page and Components
+
+Nuxt initializes the page and its components during this step and fetches any required data with `useFetch` and `useAsyncData`. Since there are no dynamic updates and no DOM operations occur on the server, Vue lifecycle hooks such as `onBeforeMount`, `onMounted`, and subsequent hooks are **NOT** executed during SSR.
+
+::important
+You should avoid code that produces side effects that need cleanup in root scope of `<script setup>`. An example of such side effects is setting up timers with `setInterval`. In client-side only code we may setup a timer and then tear it down in `onBeforeUnmount` or `onUnmounted`. However, because the unmount hooks will never be called during SSR, the timers will stay around forever. To avoid this, move your side-effect code into `onMounted` instead.
+::
+
+### Step 7: Render and Generate HTML Output
+
+After all components are initialized and data is fetched, Nuxt combines the components with settings from `unhead` to generate a complete HTML document. This HTML, along with the associated data, is sent back to the client to complete the SSR process.
+
+::callout{icon="i-lucide-lightbulb"}
+After rendering the Vue application to HTML, Nuxt calls the [`app:rendered`](/docs/api/advanced/hooks#app-hooks-runtime) hook.
+::
+
+::callout{icon="i-lucide-lightbulb"}
+Before finalizing and sending the HTML, Nitro will call the [`render:html`](/docs/api/advanced/hooks#nitro-app-hooks-runtime-server-side) hook. This hook allows you to manipulate the generated HTML, such as injecting additional scripts or modifying meta tags.
+::
+
+## Client (browser)
+
+This part of the lifecycle is fully executed in the browser, no matter which Nuxt mode you've chosen.
+
+### Step 1: Initialize Nuxt and Execute Nuxt App Plugins
+
+This step is similar to the server-side execution and includes both built-in and custom plugins.
+
+Custom plugins in the `plugins/` directory, such as those without a suffix (e.g., `myPlugin.ts`) and with the `.client` suffix (e.g., `myClientPlugin.client.ts`), are executed on the client side.
+
+::callout{icon="i-lucide-lightbulb"}
+After this step, Nuxt calls the [`app:created`](/docs/api/advanced/hooks#app-hooks-runtime) hook, which can be used to execute additional logic.
+::
+
+:read-more{to="/docs/guide/directory-structure/plugins"}
+
+### Step 2: Route Validation
+
+This step is the same as the server-side execution and includes the `validate` method if defined in the `definePageMeta` function.
+
+### Step 3: Execute Nuxt App Middleware
+
+Nuxt middleware runs on both the server and the client. If you want certain code to run in specific environments, consider splitting it by using `import.meta.client` for the client and `import.meta.server` for the server.
+
+:read-more{to="/docs/guide/directory-structure/middleware#when-middleware-runs"}
+
+### Step 4: Mount Vue Application and Hydration
+
+Calling `app.mount('#__nuxt')` mounts the Vue application to the DOM. If the application uses SSR or SSG mode, Vue performs a hydration step to make the client-side application interactive. During hydration, Vue recreates the application (excluding [Server Components](/docs/guide/directory-structure/components#server-components)), matches each component to its corresponding DOM nodes, and attaches DOM event listeners.
+
+To ensure proper hydration, it's important to maintain consistency between the data on the server and the client. For API requests, it is recommended to use `useAsyncData`, `useFetch`, or other SSR-friendly composables. These methods ensure that the data fetched on the server side is reused during hydration, avoiding repeated requests. Any new requests should only be triggered after hydration, preventing hydration errors.
+
+::callout{icon="i-lucide-lightbulb"}
+Before mounting the Vue application, Nuxt calls the [`app:beforeMount`](/docs/api/advanced/hooks#app-hooks-runtime) hook.
+::
+
+::callout{icon="i-lucide-lightbulb"}
+After mounting the Vue application, Nuxt calls the [`app:mounted`](/docs/api/advanced/hooks#app-hooks-runtime) hook.
+::
+
+### Step 5: Vue Lifecycle
+
+Unlike on the server, the browser executes the full [Vue lifecycle](https://vuejs.org/guide/essentials/lifecycle).

package/2.guide/1.concepts/2.vuejs-development.md

@@ -0,0 +1,103 @@
+---
+title: 'Vue.js Development'
+description: "Nuxt uses Vue.js and adds features such as component auto-imports, file-based routing and composables for an SSR-friendly usage."
+---
+
+Nuxt integrates Vue 3, the new major release of Vue that enables new patterns for Nuxt users.
+
+::note
+While an in-depth knowledge of Vue is not required to use Nuxt, we recommend that you read the documentation and go through some of the examples on [vuejs.org](https://vuejs.org).
+::
+
+Nuxt has always used Vue as a frontend framework.
+
+We chose to build Nuxt on top of Vue for these reasons:
+
+- The reactivity model of Vue, where a change in data automatically triggers a change in the interface.
+- The component-based templating, while keeping HTML as the common language of the web, enables intuitive patterns to keep your interface consistent, yet powerful.
+- From small projects to large web applications, Vue keeps performing well at scale to ensure that your application keeps delivering value to your users.
+
+## Vue with Nuxt
+
+### Single File Components
+
+[Vue’s single-file components](https://vuejs.org/guide/scaling-up/sfc.html) (SFC or `*.vue` files) encapsulate the markup (`<template>`), logic (`<script>`) and styling (`<style>`) of a Vue component. Nuxt provides a zero-config experience for SFCs with [Hot Module Replacement](https://vite.dev/guide/features.html#hot-module-replacement) that offers a seamless developer experience.
+
+### Auto-imports
+
+Every Vue component created in the [`components/`](/docs/guide/directory-structure/components) directory of a Nuxt project will be available in your project without having to import it. If a component is not used anywhere, your production’s code will not include it.
+
+:read-more{to="/docs/guide/concepts/auto-imports"}
+
+### Vue Router
+
+Most applications need multiple pages and a way to navigate between them. This is called **routing**. Nuxt uses a [`pages/`](/docs/guide/directory-structure/pages) directory and naming conventions to directly create routes mapped to your files using the official [Vue Router library](https://router.vuejs.org).
+
+:read-more{to="/docs/getting-started/routing"}
+
+:link-example{to="/docs/examples/features/auto-imports"}
+
+## Differences with Nuxt 2 / Vue 2
+
+Nuxt 3+ is based on Vue 3. The new major Vue version introduces several changes that Nuxt takes advantage of:
+
+- Better performance
+- Composition API
+- TypeScript support
+
+### Faster Rendering
+
+The Vue Virtual DOM (VDOM) has been rewritten from the ground up and allows for better rendering performance. On top of that, when working with compiled Single-File Components, the Vue compiler can further optimize them at build time by separating static and dynamic markup.
+
+This results in faster first rendering (component creation) and updates, and less memory usage. In Nuxt 3, it enables faster server-side rendering as well.
+
+### Smaller Bundle
+
+With Vue 3 and Nuxt 3, a focus has been put on bundle size reduction. With version 3, most of Vue’s functionality, including template directives and built-in components, is tree-shakable. Your production bundle will not include them if you don’t use them.
+
+This way, a minimal Vue 3 application can be reduced to 12 kb gzipped.
+
+### Composition API
+
+The only way to provide data and logic to components in Vue 2 was through the Options API, which allows you to return data and methods to a template with pre-defined properties like `data` and `methods`:
+
+```vue twoslash
+<script>
+export default {
+  data() {
+    return {
+      count: 0
+    }
+  },
+  methods: {
+    increment(){
+      this.count++
+    }
+  }
+}
+</script>
+```
+
+The [Composition API](https://vuejs.org/guide/extras/composition-api-faq.html) introduced in Vue 3 is not a replacement of the Options API, but it enables better logic reuse throughout an application, and is a more natural way to group code by concern in complex components.
+
+Used with the `setup` keyword in the `<script>` definition, here is the above component rewritten with Composition API and Nuxt 3’s auto-imported Reactivity APIs:
+
+```vue twoslash [components/Counter.vue]
+<script setup lang="ts">
+const count = ref(0)
+const increment = () => count.value++
+</script>
+```
+
+The goal of Nuxt is to provide a great developer experience around the Composition API.
+
+- Use auto-imported [Reactivity functions](https://vuejs.org/api/reactivity-core.html) from Vue and Nuxt [built-in composables](/docs/api/composables/use-async-data).
+- Write your own auto-imported reusable functions in the [`composables/` directory](/docs/guide/directory-structure/composables).
+
+### TypeScript Support
+
+Both Vue 3 and Nuxt 3+ are written in TypeScript. A fully typed codebase prevents mistakes and documents APIs usage. This doesn’t mean that you have to write your application in TypeScript to take advantage of it. With Nuxt 3, you can opt-in by renaming your file from `.js` to `.ts` , or add `<script setup lang="ts">` in a component.
+
+::read-more{to="/docs/guide/concepts/typescript"}
+Read the details about TypeScript in Nuxt
+::