@nuxt/docs 0.0.0 → 3.17.0

package/2.guide/2.directory-structure/2.env.md

@@ -0,0 +1,75 @@
+---
+title: ".env"
+description: "A .env file specifies your build/dev-time environment variables."
+head.title: ".env"
+navigation.icon: i-lucide-file
+---
+
+::important
+This file should be added to your [`.gitignore`](/docs/guide/directory-structure/gitignore) file to avoid pushing secrets to your repository.
+::
+
+## Dev, Build and Generate Time
+
+Nuxt CLI has built-in [dotenv](https://github.com/motdotla/dotenv) support in development mode and when running [`nuxi build`](/docs/api/commands/build) and [`nuxi generate`](/docs/api/commands/generate).
+
+In addition to any process environment variables, if you have a `.env` file in your project root directory, it will be automatically loaded **at dev, build and generate time**. Any environment variables set there will be accessible within your `nuxt.config` file and modules.
+
+```ini [.env]
+MY_ENV_VARIABLE=hello
+```
+
+::note
+Note that removing a variable from `.env` or removing the `.env` file entirely will not unset values that have already been set.
+::
+
+## Custom File
+
+If you want to use a different file - for example, to use `.env.local` or `.env.production` - you can do so by passing the `--dotenv` flag when using `nuxi`.
+
+```bash [Terminal]
+npx nuxi dev --dotenv .env.local
+```
+
+When updating `.env` in development mode, the Nuxt instance is automatically restarted to apply new values to the `process.env`.
+
+::important
+In your application code, you should use [Runtime Config](/docs/guide/going-further/runtime-config) instead of plain env variables.
+::
+
+## Production
+
+**After your server is built**, you are responsible for setting environment variables when you run the server.
+
+Your `.env` files will not be read at this point. How you do this is different for every environment.
+
+This design decision was made to ensure compatibility across various deployment environments, some of which may not have a traditional file system available, such as serverless platforms or edge networks like Cloudflare Workers.
+
+Since `.env` files are not used in production, you must explicitly set environment variables using the tools and methods provided by your hosting environment. Here are some common approaches:
+
+* You can pass the environment variables as arguments using the terminal:
+
+   `$ DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs`
+
+* You can set environment variables in shell configuration files like `.bashrc` or `.profile`.
+
+* Many cloud service providers, such as Vercel, Netlify, and AWS, provide interfaces for setting environment variables via their dashboards, CLI tools or configuration files.
+
+## Production Preview
+
+For local production preview purpose, we recommend using [`nuxi preview`](/docs/api/commands/preview) since using this command, the `.env` file will be loaded into `process.env` for convenience. Note that this command requires dependencies to be installed in the package directory.
+
+Or you could pass the environment variables as arguments using the terminal. For example, on Linux or macOS:
+
+```bash [Terminal]
+DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs
+```
+
+Note that for a purely static site, it is not possible to set runtime configuration config after your project is prerendered.
+
+:read-more{to="/docs/guide/going-further/runtime-config"}
+
+::note
+If you want to use environment variables set at build time but do not care about updating these down the line (or only need to update them reactively _within_ your app) then `appConfig` may be a better choice. You can define `appConfig` both within your `nuxt.config` (using environment variables) and also within an `~/app.config.ts` file in your project.
+:read-more{to="/docs/guide/directory-structure/app-config"}
+::

package/2.guide/2.directory-structure/2.gitignore.md

@@ -0,0 +1,37 @@
+---
+title: ".gitignore"
+description: "A .gitignore file specifies intentionally untracked files that git should ignore."
+head.title: ".gitignore"
+navigation.icon: i-lucide-file
+---
+
+A `.gitignore` file specifies intentionally untracked files that git should ignore.
+
+:read-more{icon="i-simple-icons-git" title="the git documentation" to="https://git-scm.com/docs/gitignore" target="_blank"}
+
+We recommend having a `.gitignore` file that has **at least** the following entries present:
+
+```bash [.gitignore]
+# Nuxt dev/build outputs
+.output
+.data
+.nuxt
+.nitro
+.cache
+dist
+
+# Node dependencies
+node_modules
+
+# Logs
+logs
+*.log
+
+# Misc
+.DS_Store
+
+# Local env files
+.env
+.env.*
+!.env.example
+```

package/2.guide/2.directory-structure/2.nuxtignore.md

@@ -0,0 +1,36 @@
+---
+title: .nuxtignore
+head.title: '.nuxtignore'
+description: The .nuxtignore file lets Nuxt ignore files in your project’s root directory during the build phase.
+navigation.icon: i-lucide-file
+---
+
+The `.nuxtignore` file tells Nuxt to ignore files in your project’s root directory ([`rootDir`](/docs/api/nuxt-config#rootdir)) during the build phase.
+
+It is subject to the same specification as [`.gitignore`](/docs/guide/directory-structure/gitignore) and `.eslintignore` files, in which each line is a glob pattern indicating which files should be ignored.
+
+::tip
+You can also configure [`ignoreOptions`](/docs/api/nuxt-config#ignoreoptions), [`ignorePrefix`](/docs/api/nuxt-config#ignoreprefix) and [`ignore`](/docs/api/nuxt-config#ignore) in your `nuxt.config` file.
+::
+
+## Usage
+
+```bash [.nuxtignore]
+# ignore layout foo.vue
+layouts/foo.vue
+# ignore layout files whose name ends with -ignore.vue
+layouts/*-ignore.vue
+
+# ignore page bar.vue
+pages/bar.vue
+# ignore page inside ignore folder
+pages/ignore/*.vue
+
+# ignore route middleware files under foo folder except foo/bar.js
+middleware/foo/*.js
+!middleware/foo/bar.js
+```
+
+::read-more{icon="i-simple-icons-git" title="the git documentation" to="https://git-scm.com/docs/gitignore" target="_blank"}
+More details about the spec are in the **gitignore documentation**.
+::

package/2.guide/2.directory-structure/2.nuxtrc.md

@@ -0,0 +1,50 @@
+---
+title: ".nuxtrc"
+description: "The .nuxtrc file allows you to define nuxt configurations in a flat syntax."
+head.title: ".nuxtrc"
+navigation.icon: i-lucide-file  
+---
+
+The `.nuxtrc` file can be used to configure Nuxt with a flat syntax. It is based on [`unjs/rc9`](https://github.com/unjs/rc9).
+
+::tip
+For more advanced configurations, use [`nuxt.config`](/docs/guide/directory-structure/nuxt-config).
+::
+
+## Usage
+
+```bash [.nuxtrc]
+# Disable SSR
+ssr=false
+
+# Configuration for `@nuxt/devtools`
+devtools.enabled=true
+
+# Add Nuxt modules
+modules[]=@nuxt/image
+modules[]=nuxt-security
+```
+
+If present, the properties in the `nuxt.config` file will overwrite the properties in `.nuxtrc` file.
+
+::read-more{to="/docs/api/configuration/nuxt-config"}
+Discover all the available options in the **Nuxt configuration** documentation.
+::
+
+## Global `.nuxtrc` File
+
+You can also create a global `.nuxtrc` file in your home directory to apply configurations globally.
+
+- On macOS/Linux, this file is located at:
+
+  ```md
+  ~/.nuxtrc
+  ```
+
+- On Windows, it is located at:
+
+  ```md
+  C:\Users\{username}\.nuxtrc
+  ```
+
+This global `.nuxtrc` file allows you to define default settings that apply to all Nuxt projects on your system. However, project-level `.nuxtrc` files will override these global settings, and `nuxt.config` will take precedence over both.

package/2.guide/2.directory-structure/3.app-config.md

@@ -0,0 +1,177 @@
+---
+title: app.config.ts
+head.title: 'app.config.ts'
+description: Expose reactive configuration within your application with the App Config file.
+navigation.icon: i-lucide-file
+---
+
+Nuxt provides an `app.config` config file to expose reactive configuration within your application with the ability to update it at runtime within lifecycle or using a nuxt plugin and editing it with HMR (hot-module-replacement).
+
+You can easily provide runtime app configuration using `app.config.ts` file. It can have either of `.ts`, `.js`, or `.mjs` extensions.
+
+```ts twoslash [app.config.ts]
+export default defineAppConfig({
+  foo: 'bar'
+})
+```
+
+::caution
+Do not put any secret values inside `app.config` file. It is exposed to the user client bundle.
+::
+
+::note
+When configuring a custom [`srcDir`](/docs/api/nuxt-config#srcdir), make sure to place the `app.config` file at the root of the new `srcDir` path.
+::
+
+## Usage
+
+To expose config and environment variables to the rest of your app, you will need to define configuration in `app.config` file.
+
+```ts twoslash [app.config.ts]
+export default defineAppConfig({
+  theme: {
+    primaryColor: '#ababab'
+  }
+})
+```
+
+We can now universally access `theme` both when server-rendering the page and in the browser using [`useAppConfig`](/docs/api/composables/use-app-config) composable.
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+const appConfig = useAppConfig()
+
+console.log(appConfig.theme)
+</script>
+```
+
+The [`updateAppConfig`](/docs/api/utils/update-app-config) utility can be used to update the `app.config` at runtime.
+
+```vue [pages/index.vue]
+<script setup>
+const appConfig = useAppConfig() // { foo: 'bar' }
+
+const newAppConfig = { foo: 'baz' }
+
+updateAppConfig(newAppConfig)
+
+console.log(appConfig) // { foo: 'baz' }
+</script>
+```
+
+::read-more{to="/docs/api/utils/update-app-config"}
+Read more about the `updateAppConfig` utility.
+::
+
+## Typing App Config
+
+Nuxt tries to automatically generate a TypeScript interface from provided app config so you won't have to type it yourself.
+
+However, there are some cases where you might want to type it yourself. There are two possible things you might want to type.
+
+### App Config Input
+
+`AppConfigInput` might be used by module authors who are declaring what valid _input_ options are when setting app config. This will not affect the type of `useAppConfig()`.
+
+```ts [index.d.ts]
+declare module 'nuxt/schema' {
+  interface AppConfigInput {
+    /** Theme configuration */
+    theme?: {
+      /** Primary app color */
+      primaryColor?: string
+    }
+  }
+}
+
+// It is always important to ensure you import/export something when augmenting a type
+export {}
+```
+
+### App Config Output
+
+If you want to type the result of calling [`useAppConfig()`](/docs/api/composables/use-app-config), then you will want to extend `AppConfig`.
+
+::warning
+Be careful when typing `AppConfig` as you will overwrite the types Nuxt infers from your actually defined app config.
+::
+
+```ts [index.d.ts]
+declare module 'nuxt/schema' {
+  interface AppConfig {
+    // This will entirely replace the existing inferred `theme` property
+    theme: {
+      // You might want to type this value to add more specific types than Nuxt can infer,
+      // such as string literal types
+      primaryColor?: 'red' | 'blue'
+    }
+  }
+}
+
+// It is always important to ensure you import/export something when augmenting a type
+export {}
+```
+
+## Merging Strategy
+
+Nuxt uses a custom merging strategy for the `AppConfig` within [the layers](/docs/getting-started/layers) of your application.
+
+This strategy is implemented using a [Function Merger](https://github.com/unjs/defu#function-merger), which allows defining a custom merging strategy for every key in `app.config` that has an array as value.
+
+::note
+The function merger can only be used in the extended layers and not the main `app.config` in project.
+::
+
+Here's an example of how you can use:
+
+::code-group
+
+```ts twoslash [layer/app.config.ts]
+export default defineAppConfig({
+  // Default array value
+  array: ['hello'],
+})
+```
+
+```ts twoslash [app.config.ts]
+export default defineAppConfig({
+  // Overwrite default array value by using a merger function
+  array: () => ['bonjour'],
+})
+```
+
+::
+
+## Known Limitations
+
+As of Nuxt v3.3, the `app.config.ts` file is shared with Nitro, which results in the following limitations:
+
+1. You cannot import Vue components directly in `app.config.ts`.
+2. Some auto-imports are not available in the Nitro context.
+
+These limitations occur because Nitro processes the app config without full Vue component support.
+
+While it's possible to use Vite plugins in the Nitro config as a workaround, this approach is not recommended:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  nitro: {
+    vite: {
+      plugins: [vue()]
+    }
+  }
+})
+```
+
+::warning
+Using this workaround may lead to unexpected behavior and bugs. The Vue plugin is one of many that are not available in the Nitro context.
+::
+
+Related issues:
+- [Issue #19858](https://github.com/nuxt/nuxt/issues/19858)
+- [Issue #19854](https://github.com/nuxt/nuxt/issues/19854)
+
+::note
+Nitro v3 will resolve these limitations by removing support for the app config.
+You can track the progress in [this pull request](https://github.com/nitrojs/nitro/pull/2521).
+::

package/2.guide/2.directory-structure/3.app.md

@@ -0,0 +1,72 @@
+---
+title: "app.vue"
+description: "The app.vue file is the main component of your Nuxt application."
+head.title: "app.vue"
+navigation.icon: i-lucide-file
+---
+
+::tip
+If you have a `pages/` directory, the `app.vue` file is optional. Nuxt will automatically include a default `app.vue`, but you can still add your own to customize the structure and content as needed.
+::
+
+## Usage
+
+### Minimal Usage
+
+With Nuxt, the [`pages/`](/docs/guide/directory-structure/pages) directory is optional. If it is not present, Nuxt will not include the [vue-router](https://router.vuejs.org) dependency. This is useful when building a landing page or an application that does not require routing.
+
+```vue [app.vue]
+<template>
+  <h1>Hello World!</h1>
+</template>
+```
+
+:link-example{to="/docs/examples/hello-world"}
+
+### Usage with Pages
+
+When you have a [`pages/`](/docs/guide/directory-structure/pages) directory, you need to use the [`<NuxtPage>`](/docs/api/components/nuxt-page) component to display the current page:
+
+```vue [app.vue]
+<template>
+  <NuxtPage />
+</template>
+```
+
+You can also define the common structure of your application directly in `app.vue`. This is useful when you want to include global elements such as a header or footer:
+
+```vue [app.vue]
+<template>
+  <header>
+    Header content
+  </header>
+  <NuxtPage />
+  <footer>
+    Footer content
+  </footer>
+</template>
+```
+
+::note
+Remember that `app.vue` acts as the main component of your Nuxt application. Anything you add to it (JS and CSS) will be global and included in every page.
+::
+
+::read-more{to="/docs/guide/directory-structure/pages"}
+Learn more about how to structure your pages using the `pages/` directory.
+::
+
+### Usage with Layouts
+
+When your application requires different layouts for different pages, you can use the `layouts/` directory with the [`<NuxtLayout>`](/docs/api/components/nuxt-layout) component. This allows you to define multiple layouts and apply them per page.
+
+```vue [app.vue]
+<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+::read-more{to="/docs/guide/directory-structure/layouts"}
+Learn more about how to structure your layouts using the `layouts/` directory.
+::

package/2.guide/2.directory-structure/3.error.md

@@ -0,0 +1,55 @@
+---
+title: "error.vue"
+description: "The error.vue file is the error page in your Nuxt application."
+head.title: "error.vue"
+navigation.icon: i-lucide-file
+---
+
+During the lifespan of your application, some errors may appear unexpectedly at runtime. In such case, we can use the `error.vue` file to override the default error files and display the error nicely.
+
+```vue [error.vue]
+<script setup lang="ts">
+import type { NuxtError } from '#app'
+
+const props = defineProps({
+  error: Object as () => NuxtError
+})
+</script>
+
+<template>
+  <div>
+    <h1>{{ error.statusCode }}</h1>
+    <NuxtLink to="/">Go back home</NuxtLink>
+  </div>
+</template>
+```
+
+::note
+Although it is called an 'error page' it's not a route and shouldn't be placed in your `~/pages` directory. For the same reason, you shouldn't use `definePageMeta` within this page. That being said, you can still use layouts in the error file, by utilizing the [`NuxtLayout`](/docs/api/components/nuxt-layout) component and specifying the name of the layout.
+::
+
+The error page has a single prop - `error` which contains an error for you to handle.
+
+The `error` object provides the following fields:
+```ts
+{
+  statusCode: number
+  fatal: boolean
+  unhandled: boolean
+  statusMessage?: string
+  data?: unknown
+  cause?: unknown
+}
+```
+
+If you have an error with custom fields they will be lost; you should assign them to `data` instead:
+
+```ts
+throw createError({
+  statusCode: 404,
+  statusMessage: 'Page Not Found',
+  data: {
+    myCustomField: true
+  }
+})
+```

package/2.guide/2.directory-structure/3.nuxt-config.md

@@ -0,0 +1,34 @@
+---
+title: "nuxt.config.ts"
+description: "Nuxt can be easily configured with a single nuxt.config file."
+head.title: "nuxt.config.ts"
+navigation.icon: i-lucide-file
+---
+
+The `nuxt.config` file extension can either be `.js`, `.ts` or `.mjs`.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  // My Nuxt config
+})
+```
+
+::tip
+`defineNuxtConfig` helper is globally available without import.
+::
+
+You can explicitly import `defineNuxtConfig` from `nuxt/config` if you prefer:
+
+```ts twoslash [nuxt.config.ts]
+import { defineNuxtConfig } from 'nuxt/config'
+
+export default defineNuxtConfig({
+  // My Nuxt config
+})
+```
+
+::read-more{to="/docs/api/configuration/nuxt-config"}
+Discover all the available options in the **Nuxt configuration** documentation.
+::
+
+To ensure your configuration is up to date, Nuxt will make a full restart when detecting changes in the main configuration file, the [`.env`](/docs/guide/directory-structure/env), [`.nuxtignore`](/docs/guide/directory-structure/nuxtignore) and [`.nuxtrc`](/docs/guide/directory-structure/nuxtrc) dotfiles.

package/2.guide/2.directory-structure/3.package.md

@@ -0,0 +1,32 @@
+---
+title: package.json
+head.title: package.json
+description: The package.json file contains all the dependencies and scripts for your application.
+navigation.icon: i-lucide-file
+---
+
+The minimal `package.json` of your Nuxt application should looks like:
+
+```json [package.json]
+{
+  "name": "nuxt-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "postinstall": "nuxt prepare"
+  },
+  "dependencies": {
+    "nuxt": "latest",
+    "vue": "latest",
+    "vue-router": "latest"
+  }
+}
+```
+
+::read-more{icon="i-simple-icons-npm" to="https://docs.npmjs.com/cli/configuring-npm/package-json" target="_blank"}
+Read more about the `package.json` file.
+::

package/2.guide/2.directory-structure/3.tsconfig.md

@@ -0,0 +1,24 @@
+---
+title: "tsconfig.json"
+description: "Nuxt generates a .nuxt/tsconfig.json file with sensible defaults and your aliases."
+head.title: "tsconfig.json"
+navigation.icon: i-lucide-file
+---
+
+Nuxt [automatically generates](/docs/guide/concepts/typescript) a `.nuxt/tsconfig.json` file with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults.
+
+You can benefit from this by creating a `tsconfig.json` in the root of your project with the following content:
+
+```json [tsconfig.json]
+{
+  "extends": "./.nuxt/tsconfig.json"
+}
+```
+
+::note
+As you need to, you can customize the contents of this file. However, it is recommended that you don't overwrite `target`, `module` and `moduleResolution`.
+::
+
+::note
+If you need to customize your `paths`, this will override the auto-generated path aliases. Instead, we recommend that you add any path aliases you need to the [`alias`](/docs/api/nuxt-config#alias) property within your `nuxt.config`, where they will get picked up and added to the auto-generated `tsconfig`.
+::

package/2.guide/3.going-further/.navigation.yml

@@ -0,0 +1,3 @@
+title: Going Further
+titleTemplate: '%s · Nuxt Advanced'
+icon: i-lucide-star