@nuxt/docs 0.0.0 → 3.17.1

package/.navigation.yml

@@ -0,0 +1,2 @@
+title: Docs
+icon: i-lucide-book-marked

package/1.getting-started/.navigation.yml

@@ -0,0 +1,3 @@
+title: Get Started
+titleTemplate: '%s · Get Started with Nuxt'
+icon: i-lucide-rocket

package/1.getting-started/01.introduction.md

@@ -0,0 +1,81 @@
+---
+title: Introduction
+description: Nuxt's goal is to make web development intuitive and performant with a great Developer Experience in mind.
+navigation:
+  icon: i-lucide-info
+---
+
+Nuxt is a free and [open-source framework](https://github.com/nuxt/nuxt) with an intuitive and extendable way to create type-safe, performant and production-grade full-stack web applications and websites with [Vue.js](https://vuejs.org).
+
+We made everything so you can start writing `.vue` files from the beginning while enjoying hot module replacement in development and a performant application in production with server-side rendering by default.
+
+Nuxt has no vendor lock-in, allowing you to deploy your application [**everywhere, even on the edge**](/blog/nuxt-on-the-edge).
+
+::tip
+If you want to play around with Nuxt in your browser, you can [try it out in one of our online sandboxes](/docs/getting-started/installation#play-online).
+::
+
+## Automation and Conventions
+
+Nuxt uses conventions and an opinionated directory structure to automate repetitive tasks and allow developers to focus on pushing features. The configuration file can still customize and override its default behaviors.
+
+- **File-based routing:** define routes based on the structure of your [`pages/` directory](/docs/guide/directory-structure/pages). This can make it easier to organize your application and avoid the need for manual route configuration.
+- **Code splitting:** Nuxt automatically splits your code into smaller chunks, which can help reduce the initial load time of your application.
+- **Server-side rendering out of the box:** Nuxt comes with built-in SSR capabilities, so you don't have to set up a separate server yourself.
+- **Auto-imports:** write Vue composables and components in their respective directories and use them without having to import them with the benefits of tree-shaking and optimized JS bundles.
+- **Data-fetching utilities:** Nuxt provides composables to handle SSR-compatible data fetching as well as different strategies.
+- **Zero-config TypeScript support:** write type-safe code without having to learn TypeScript with our auto-generated types and `tsconfig.json`
+- **Configured build tools:** we use [Vite](https://vite.dev) by default to support hot module replacement (HMR) in development and bundling your code for production with best-practices baked-in.
+
+Nuxt takes care of these and provides both frontend and backend functionality so you can focus on what matters: **creating your web application**.
+
+## Server-Side Rendering
+
+Nuxt comes with built-in server-side rendering (SSR) capabilities by default, without having to configure a server yourself, which has many benefits for web applications:
+
+- **Faster initial page load time:** Nuxt sends a fully rendered HTML page to the browser, which can be displayed immediately. This can provide a faster perceived page load time and a better user experience (UX), especially on slower networks or devices.
+- **Improved SEO:** search engines can better index SSR pages because the HTML content is available immediately, rather than requiring JavaScript to render the content on the client-side.
+- **Better performance on low-powered devices:** it reduces the amount of JavaScript that needs to be downloaded and executed on the client-side, which can be beneficial for low-powered devices that may struggle with processing heavy JavaScript applications.
+- **Better accessibility:** the content is immediately available on the initial page load, improving accessibility for users who rely on screen readers or other assistive technologies.
+- **Easier caching:** pages can be cached on the server-side, which can further improve performance by reducing the amount of time it takes to generate and send the content to the client.
+
+Overall, server-side rendering can provide a faster and more efficient user experience, as well as improve search engine optimization and accessibility.
+
+As Nuxt is a versatile framework, it gives you the possibility to statically render your whole application to a static hosting with `nuxt generate`,
+disable SSR globally with the `ssr: false` option or leverage hybrid rendering by setting up the `routeRules` option.
+
+:read-more{title="Nuxt rendering modes" to="/docs/guide/concepts/rendering"}
+
+### Server engine
+
+The Nuxt server engine [Nitro](https://nitro.unjs.io) unlocks new full-stack capabilities.
+
+In development, it uses Rollup and Node.js workers for your server code and context isolation. It also generates your server API by reading files in `server/api/` and server middleware from `server/middleware/`.
+
+In production, Nitro builds your app and server into one universal `.output` directory. This output is light: minified and removed from any Node.js modules (except polyfills). You can deploy this output on any system supporting JavaScript, from Node.js, Serverless, Workers, Edge-side rendering or purely static.
+
+:read-more{title="Nuxt server engine" to="/docs/guide/concepts/server-engine"}
+
+### Production-ready
+
+A Nuxt application can be deployed on a Node or Deno server, pre-rendered to be hosted in static environments, or deployed to serverless and edge providers.
+
+:read-more{title="Deployment section" to="/docs/getting-started/deployment"}
+
+### Modular
+
+A module system allows to extend Nuxt with custom features and integrations with third-party services.
+
+:read-more{title="Nuxt Modules Concept" to="/docs/guide/concepts/modules"}
+
+### Architecture
+
+Nuxt is composed of different [core packages](https://github.com/nuxt/nuxt/tree/main/packages):
+
+- Core Engine: [nuxt](https://github.com/nuxt/nuxt/tree/main/packages/nuxt)
+- Bundlers: [@nuxt/vite-builder](https://github.com/nuxt/nuxt/tree/main/packages/vite) and [@nuxt/webpack-builder](https://github.com/nuxt/nuxt/tree/main/packages/webpack)
+- Command line interface: [nuxi](https://github.com/nuxt/nuxt/tree/main/packages/nuxi)
+- Server engine: [nitro](https://github.com/nitrojs/nitro)
+- Development kit: [@nuxt/kit](https://github.com/nuxt/nuxt/tree/main/packages/kit)
+
+We recommend reading each concept to have a full vision of Nuxt capabilities and the scope of each package.

package/1.getting-started/02.installation.md

@@ -0,0 +1,109 @@
+---
+title: 'Installation'
+description: 'Get started with Nuxt quickly with our online starters or start locally with your terminal.'
+navigation.icon: i-lucide-play
+---
+
+## Play Online
+
+If you just want to play around with Nuxt in your browser without setting up a project, you can use one of our online sandboxes:
+
+::card-group
+  :card{title="Open on StackBlitz" icon="i-simple-icons-stackblitz" to="https://nuxt.new/s/v3" target="_blank"}
+  :card{title="Open on CodeSandbox" icon="i-simple-icons-codesandbox" to="https://nuxt.new/c/v3" target="_blank"}
+::
+
+Or follow the steps below to set up a new Nuxt project on your computer.
+
+## New Project
+
+<!-- TODO: need to fix upstream in nuxt/nuxt.com -->
+<!-- markdownlint-disable-next-line MD001 -->
+#### Prerequisites
+
+- **Node.js** - [`18.x`](https://nodejs.org/en) or newer (but we recommend the [active LTS release](https://github.com/nodejs/release#release-schedule))
+- **Text editor** - There is no IDE requirement, but we recommend [Visual Studio Code](https://code.visualstudio.com/) with the [official Vue extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (previously known as Volar) or [WebStorm](https://www.jetbrains.com/webstorm/), which, along with [other JetBrains IDEs](https://www.jetbrains.com/ides/), offers great Nuxt support right out-of-the-box.
+- **Terminal** - In order to run Nuxt commands
+
+::note
+  ::details
+  :summary[Additional notes for an optimal setup:]
+  - **Node.js**: Make sure to use an even numbered version (18, 20, etc)
+  - **Nuxtr**: Install the community-developed [Nuxtr extension](https://marketplace.visualstudio.com/items?itemName=Nuxtr.nuxtr-vscode)
+  - **WSL**: If you are using Windows and experience slow HMR, you may want to try using [WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/install) which may solve some performance issues.
+  ::
+::
+
+Open a terminal (if you're using [Visual Studio Code](https://code.visualstudio.com), you can open an [integrated terminal](https://code.visualstudio.com/docs/editor/integrated-terminal)) and use the following command to create a new starter project:
+
+::code-group{sync="pm"}
+
+```bash [npm]
+npm create nuxt <project-name>
+```
+
+```bash [yarn]
+yarn create nuxt <project-name>
+```
+
+```bash [pnpm]
+pnpm create nuxt <project-name>
+```
+
+```bash [bun]
+bun create nuxt <project-name>
+```
+
+::
+
+::tip
+Alternatively, you can find other starters or themes by opening [nuxt.new](https://nuxt.new) and following the instructions there.
+::
+
+Open your project folder in Visual Studio Code:
+
+```bash [Terminal]
+code <project-name>
+```
+
+Or change directory into your new project from your terminal:
+
+```bash
+cd <project-name>
+```
+
+## Development Server
+
+Now you'll be able to start your Nuxt app in development mode:
+
+::code-group{sync="pm"}
+
+```bash [npm]
+npm run dev -- -o
+```
+
+```bash [yarn]
+yarn dev --open
+```
+
+```bash [pnpm]
+pnpm dev -o
+```
+
+```bash [bun]
+bun run dev -o
+
+# To use the Bun runtime during development
+# bun --bun run dev -o
+```
+::
+
+::tip{icon="i-lucide-circle-check"}
+Well done! A browser window should automatically open for <http://localhost:3000>.
+::
+
+## Next Steps
+
+Now that you've created your Nuxt project, you are ready to start building your application.
+
+:read-more{title="Nuxt Concepts" to="/docs/guide/concepts"}

package/1.getting-started/03.configuration.md

@@ -0,0 +1,226 @@
+---
+title: Configuration
+description: Nuxt is configured with sensible defaults to make you productive.
+navigation.icon: i-lucide-cog
+---
+
+By default, Nuxt is configured to cover most use cases. The [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file can override or extend this default configuration.
+
+## Nuxt Configuration
+
+The [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file is located at the root of a Nuxt project and can override or extend the application's behavior.
+
+A minimal configuration file exports the `defineNuxtConfig` function containing an object with your configuration. The `defineNuxtConfig` helper is globally available without import.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  // My Nuxt config
+})
+```
+
+This file will often be mentioned in the documentation, for example to add custom scripts, register modules or change rendering modes.
+
+::read-more{to="/docs/api/configuration/nuxt-config"}
+Every option is described in the **Configuration Reference**.
+::
+
+::note
+You don't have to use TypeScript to build an application with Nuxt. However, it is strongly recommended to use the `.ts` extension for the `nuxt.config` file. This way you can benefit from hints in your IDE to avoid typos and mistakes while editing your configuration.
+::
+
+### Environment Overrides
+
+You can configure fully typed, per-environment overrides in your nuxt.config
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  $production: {
+    routeRules: {
+      '/**': { isr: true }
+    }
+  },
+  $development: {
+    //
+  },
+  $env: {
+    staging: {
+      // 
+    }
+  },
+})
+```
+
+To select an environment when running a Nuxt CLI command, simply pass the name to the `--envName` flag, like so: `nuxi build --envName staging`.
+
+To learn more about the mechanism behind these overrides, please refer to the `c12` documentation on [environment-specific configuration](https://github.com/unjs/c12?tab=readme-ov-file#environment-specific-configuration).
+
+:video-accordion{title="Watch a video from Alexander Lichter about the env-aware nuxt.config.ts" videoId="DFZI2iVCrNc"}
+
+::note
+If you're authoring layers, you can also use the `$meta` key to provide metadata that you or the consumers of your layer might use.
+::
+
+### Environment Variables and Private Tokens
+
+The `runtimeConfig` API exposes values like environment variables to the rest of your application. By default, these keys are only available server-side. The keys within `runtimeConfig.public` and `runtimeConfig.app` (which is used by Nuxt internally) are also available client-side.
+
+Those values should be defined in `nuxt.config` and can be overridden using environment variables.
+
+::code-group
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  runtimeConfig: {
+    // The private keys which are only available server-side
+    apiSecret: '123',
+    // Keys within public are also exposed client-side
+    public: {
+      apiBase: '/api'
+    }
+  }
+})
+```
+
+```ini [.env]
+# This will override the value of apiSecret
+NUXT_API_SECRET=api_secret_token
+```
+
+::
+
+These variables are exposed to the rest of your application using the [`useRuntimeConfig()`](/docs/api/composables/use-runtime-config) composable.
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+const runtimeConfig = useRuntimeConfig()
+</script>
+```
+
+:read-more{to="/docs/guide/going-further/runtime-config"}
+
+## App Configuration
+
+The `app.config.ts` file, located in the source directory (by default the root of the project), is used to expose public variables that can be determined at build time. Contrary to the `runtimeConfig` option, these can not be overridden using environment variables.
+
+A minimal configuration file exports the `defineAppConfig` function containing an object with your configuration. The `defineAppConfig` helper is globally available without import.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  title: 'Hello Nuxt',
+  theme: {
+    dark: true,
+    colors: {
+      primary: '#ff0000'
+    }
+  }
+})
+```
+
+These variables are exposed to the rest of your application using the [`useAppConfig`](/docs/api/composables/use-app-config) composable.
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+const appConfig = useAppConfig()
+</script>
+```
+
+:read-more{to="/docs/guide/directory-structure/app-config"}
+
+## `runtimeConfig` vs. `app.config`
+
+As stated above, `runtimeConfig` and `app.config` are both used to expose variables to the rest of your application. To determine whether you should use one or the other, here are some guidelines:
+
+- `runtimeConfig`: Private or public tokens that need to be specified after build using environment variables.
+- `app.config`: Public tokens that are determined at build time, website configuration such as theme variant, title and any project config that are not sensitive.
+
+Feature                        | `runtimeConfig`  | `app.config`
+-------------------------------|------------------|-------------------
+Client Side                    | Hydrated         | Bundled
+Environment Variables          | ✅ Yes           | ❌ No
+Reactive                       | ✅ Yes           | ✅ Yes
+Types support                  | ✅ Partial       | ✅ Yes
+Configuration per Request      | ❌ No            | ✅ Yes
+Hot Module Replacement         | ❌ No            | ✅ Yes
+Non primitive JS types         | ❌ No            | ✅ Yes
+
+## External Configuration Files
+
+Nuxt uses [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file as the single source of truth for configurations and skips reading external configuration files. During the course of building your project, you may have a need to configure those. The following table highlights common configurations and, where applicable, how they can be configured with Nuxt.
+
+Name                                         | Config File               |  How To Configure
+---------------------------------------------|---------------------------|-------------------------
+[Nitro](https://nitro.unjs.io)               | ~~`nitro.config.ts`~~     | Use [`nitro`](/docs/api/nuxt-config#nitro) key in `nuxt.config`
+[PostCSS](https://postcss.org)               | ~~`postcss.config.js`~~   | Use [`postcss`](/docs/api/nuxt-config#postcss) key in `nuxt.config`
+[Vite](https://vite.dev)                     | ~~`vite.config.ts`~~      | Use [`vite`](/docs/api/nuxt-config#vite) key in `nuxt.config`
+[webpack](https://webpack.js.org)            | ~~`webpack.config.ts`~~   | Use [`webpack`](/docs/api/nuxt-config#webpack-1) key in `nuxt.config`
+
+Here is a list of other common config files:
+
+Name                                         | Config File             | How To Configure
+---------------------------------------------|-------------------------|--------------------------
+[TypeScript](https://www.typescriptlang.org) | `tsconfig.json`         | [More Info](/docs/guide/concepts/typescript#nuxttsconfigjson)
+[ESLint](https://eslint.org)                 | `eslint.config.js`      | [More Info](https://eslint.org/docs/latest/use/configure/configuration-files)
+[Prettier](https://prettier.io)              | `prettier.config.js`    | [More Info](https://prettier.io/docs/en/configuration.html)
+[Stylelint](https://stylelint.io)            | `stylelint.config.js`   | [More Info](https://stylelint.io/user-guide/configure)
+[TailwindCSS](https://tailwindcss.com)       | `tailwind.config.js`    | [More Info](https://tailwindcss.nuxtjs.org/tailwindcss/configuration)
+[Vitest](https://vitest.dev)                 | `vitest.config.ts`      | [More Info](https://vitest.dev/config/)
+
+## Vue Configuration
+
+### With Vite
+
+If you need to pass options to `@vitejs/plugin-vue` or `@vitejs/plugin-vue-jsx`, you can do this in your `nuxt.config` file.
+
+- `vite.vue` for `@vitejs/plugin-vue`. Check available options [here](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue).
+- `vite.vueJsx` for `@vitejs/plugin-vue-jsx`. Check available options [here](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx).
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  vite: {
+    vue: {
+      customElement: true
+    },
+    vueJsx: {
+      mergeProps: true
+    }
+  }
+})
+```
+
+:read-more{to="/docs/api/configuration/nuxt-config#vue"}
+
+### With webpack
+
+If you use webpack and need to configure `vue-loader`, you can do this using `webpack.loaders.vue` key inside your `nuxt.config` file. The available options are [defined here](https://github.com/vuejs/vue-loader/blob/main/src/index.ts#L32-L62).
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  webpack: {
+    loaders: {
+      vue: {
+        hotReload: true,
+      }
+    }
+  }
+})
+```
+
+:read-more{to="/docs/api/configuration/nuxt-config#loaders"}
+
+### Enabling Experimental Vue Features
+
+You may need to enable experimental features in Vue, such as `propsDestructure`. Nuxt provides an easy way to do that in `nuxt.config.ts`, no matter which builder you are using:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  vue: {
+    propsDestructure: true
+  }
+})
+```
+
+#### experimental `reactivityTransform` migration from Vue 3.4 and Nuxt 3.9
+
+Since Nuxt 3.9 and Vue 3.4, `reactivityTransform` has been moved from Vue to Vue Macros which has a [Nuxt integration](https://vue-macros.dev/guide/nuxt-integration.html).
+
+:read-more{to="/docs/api/configuration/nuxt-config#vue-1"}

package/1.getting-started/04.views.md

@@ -0,0 +1,163 @@
+---
+title: 'Views'
+description: 'Nuxt provides several component layers to implement the user interface of your application.'
+navigation.icon: i-lucide-panels-top-left
+---
+
+## `app.vue`
+
+![The app.vue file is the entry point of your application](/assets/docs/getting-started/views/app.svg)
+
+By default, Nuxt will treat this file as the **entrypoint** and render its content for every route of the application.
+
+```vue [app.vue]
+<template>
+  <div>
+   <h1>Welcome to the homepage</h1>
+  </div>
+</template>
+```
+
+::tip
+If you are familiar with Vue, you might wonder where `main.js` is (the file that normally creates a Vue app). Nuxt does this behind the scene.
+::
+
+## Components
+
+![Components are reusable pieces of UI](/assets/docs/getting-started/views/components.svg)
+
+Most components are reusable pieces of the user interface, like buttons and menus. In Nuxt, you can create these components in the [`components/`](/docs/guide/directory-structure/components) directory, and they will be automatically available across your application without having to explicitly import them.
+
+::code-group
+
+```vue [app.vue]
+<template>
+  <div>
+    <h1>Welcome to the homepage</h1>
+    <AppAlert>
+      This is an auto-imported component.
+    </AppAlert>
+  </div>
+</template>
+```
+
+```vue [components/AppAlert.vue]
+<template>
+  <span>
+    <slot />
+  </span>
+</template>
+```
+
+::
+
+## Pages
+
+![Pages are views tied to a specific route](/assets/docs/getting-started/views/pages.svg)
+
+Pages represent views for each specific route pattern. Every file in the [`pages/`](/docs/guide/directory-structure/pages) directory represents a different route displaying its content.
+
+To use pages, create `pages/index.vue` file and add `<NuxtPage />` component to the [`app.vue`](/docs/guide/directory-structure/app) (or remove `app.vue` for default entry). You can now create more pages and their corresponding routes by adding new files in the [`pages/`](/docs/guide/directory-structure/pages) directory.
+
+::code-group
+
+```vue [pages/index.vue]
+<template>
+  <div>
+    <h1>Welcome to the homepage</h1>
+    <AppAlert>
+      This is an auto-imported component
+    </AppAlert>
+  </div>
+</template>
+```
+
+```vue [pages/about.vue]
+<template>
+  <section>
+    <p>This page will be displayed at the /about route.</p>
+  </section>
+</template>
+```
+
+::
+
+:read-more{title="Routing Section" to="/docs/getting-started/routing"}
+
+## Layouts
+
+![Layouts are wrapper around pages](/assets/docs/getting-started/views/layouts.svg)
+
+Layouts are wrappers around pages that contain a common User Interface for several pages, such as a header and footer display. Layouts are Vue files using `<slot />` components to display the **page** content. The `layouts/default.vue` file will be used by default. Custom layouts can be set as part of your page metadata.
+
+::note
+If you only have a single layout in your application, we recommend using [`app.vue`](/docs/guide/directory-structure/app) with [`<NuxtPage />`](/docs/api/components/nuxt-page) instead.
+::
+
+::code-group
+
+```vue [app.vue]
+<template>
+  <div>
+    <NuxtLayout>
+      <NuxtPage />
+    </NuxtLayout>
+  </div>
+</template>
+```
+
+```vue [layouts/default.vue]
+<template>
+  <div>
+    <AppHeader />
+    <slot />
+    <AppFooter />
+  </div>
+</template>
+```
+
+```vue [pages/index.vue]
+<template>
+  <div>
+    <h1>Welcome to the homepage</h1>
+    <AppAlert>
+      This is an auto-imported component
+    </AppAlert>
+  </div>
+</template>
+```
+
+```vue [pages/about.vue]
+<template>
+  <section>
+    <p>This page will be displayed at the /about route.</p>
+  </section>
+</template>
+```
+
+::
+
+If you want to create more layouts and learn how to use them in your pages, find more information in the [Layouts section](/docs/guide/directory-structure/layouts).
+
+## Advanced: Extending the HTML Template
+
+::note
+If you only need to modify the `<head>`, you can refer to the [SEO and meta section](/docs/getting-started/seo-meta).
+::
+
+You can have full control over the HTML template by adding a Nitro plugin that registers a hook.
+The callback function of the `render:html` hook allows you to mutate the HTML before it is sent to the client.
+
+```ts twoslash [server/plugins/extend-html.ts]
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('render:html', (html, { event }) => {
+    // This will be an object representation of the html template.
+    console.log(html)
+    html.head.push(`<meta name="description" content="My custom description" />`)
+  })
+  // You can also intercept the response here.
+  nitroApp.hooks.hook('render:response', (response, { event }) => { console.log(response) })
+})
+```
+
+:read-more{to="/docs/guide/going-further/hooks"}

package/1.getting-started/05.assets.md

@@ -0,0 +1,48 @@
+---
+title: 'Assets'
+description: 'Nuxt offers two options for your assets.'
+navigation.icon: i-lucide-image
+---
+
+Nuxt uses two directories to handle assets like stylesheets, fonts or images.
+
+- The [`public/`](/docs/guide/directory-structure/public) directory content is served at the server root as-is.
+- The [`assets/`](/docs/guide/directory-structure/assets) directory contains by convention every asset that you want the build tool (Vite or webpack) to process.
+
+## Public Directory
+
+The [`public/`](/docs/guide/directory-structure/public) directory is used as a public server for static assets publicly available at a defined URL of your application.
+
+You can get a file in the [`public/`](/docs/guide/directory-structure/public) directory from your application's code or from a browser by the root URL `/`.
+
+### Example
+
+For example, referencing an image file in the `public/img/` directory, available at the static URL `/img/nuxt.png`:
+
+```vue [app.vue]
+<template>
+  <img src="/img/nuxt.png" alt="Discover Nuxt" />
+</template>
+```
+
+## Assets Directory
+
+Nuxt uses [Vite](https://vite.dev/guide/assets.html) (default) or [webpack](https://webpack.js.org/guides/asset-management) to build and bundle your application. The main function of these build tools is to process JavaScript files, but they can be extended through [plugins](https://vite.dev/plugins) (for Vite) or [loaders](https://webpack.js.org/loaders) (for webpack) to process other kinds of assets, like stylesheets, fonts or SVGs. This step transforms the original file, mainly for performance or caching purposes (such as stylesheet minification or browser cache invalidation).
+
+By convention, Nuxt uses the [`assets/`](/docs/guide/directory-structure/assets) directory to store these files but there is no auto-scan functionality for this directory, and you can use any other name for it.
+
+In your application's code, you can reference a file located in the [`assets/`](/docs/guide/directory-structure/assets) directory by using the `~/assets/` path.
+
+### Example
+
+For example, referencing an image file that will be processed if a build tool is configured to handle this file extension:
+
+```vue [app.vue]
+<template>
+  <img src="~/assets/img/nuxt.png" alt="Discover Nuxt" />
+</template>
+```
+
+::note
+Nuxt won't serve files in the [`assets/`](/docs/guide/directory-structure/assets) directory at a static URL like `/assets/my-file.png`. If you need a static URL, use the [`public/`](#public-directory) directory.
+::