Merge branch 'main' into fix/recursive-resolve

docs/content/1.getting-started/10.upgrade.md

@@ -0,0 +1,59 @@
+# Upgrade Guide
+
+Have a Nuxt 2 project to migrate? Use these guides to upgrade your Nuxt applications to Nuxt 3 or take the first step in that direction with Nuxt Bridge.
+
+If you are already using Nuxt 3 and want to upgrade to the latest release or test new features before their release, head over to the [Upgrading Nuxt 3](#upgrading-nuxt-3) section.
+
+## Feature Comparison
+
+In the table below, there is a quick comparison between 3 versions of Nuxt:
+
+Feature / Version        | Nuxt 2          | Nuxt Bridge      | Nuxt 3
+-------------------------|-----------------|------------------|---------
+Vue                      | 2               | 2                | 3
+Stability                | 😊 Stable      | 😌 Semi-stable    | Release candidate
+Performance              | 🏎 Fast        | ✈️ Faster          | 🚀 Fastest
+Nitro Engine             | ❌             | ✅                | ✅
+ESM support              | 🌙 Partial     | 👍 Better         | ✅
+TypeScript               | ☑️ Opt-in       | 🚧 Partial        | ✅
+Composition API          | ❌             | 🚧 Partial        | ✅
+Options API              | ✅             | ✅                | ✅
+Components Auto Import   | ✅             | ✅                | ✅
+`<script setup>` syntax  | ❌             | 🚧 Partial        | ✅
+Auto Imports             | ❌             | ✅                | ✅
+Webpack                  | 4              | 4                 | 5
+Vite                     | ⚠️ Partial      | 🚧 Partial        | ✅
+Nuxi CLI                 | ❌ Old         | ✅ nuxi           | ✅ nuxi
+Static sites             | ✅             | ✅                | ✅
+
+## Nuxt 2 to Nuxt 3
+
+The migration guide provides a step-by-step comparison of Nuxt 2 features to Nuxt 3 features and guidance to adapt your current application.
+
+::alert{type=info icon=👉}
+[**Migrate from From Nuxt 2 to Nuxt 3**](/migration/overview)
+::
+
+## Nuxt 2 to Nuxt Bridge
+
+If you prefer to progressively migrate your Nuxt 2 application to Nuxt 3, you can use Nuxt Bridge. Nuxt Bridge is a compatibility layer that allows you to use Nuxt 3 features in Nuxt 2 with an opt-in mechanism.
+
+::alert{type=info icon=👉}
+[**Migrate from Nuxt 2 to Nuxt Bridge**](/bridge/overview)
+::
+
+## Upgrading Nuxt 3
+
+### Latest release
+
+To upgrade Nuxt 3 to the latest release, use the `nuxi upgrade` command.
+
+```bash
+npx nuxi upgrade
+```
+
+### Edge release channel
+
+::alert{type=info icon=👉}
+To use the latest Nuxt 3 build and test features before their release, read the [edge release channel](/guide/going-further/edge-channel) guide.
+::

docs/content/1.getting-started/3.configuration.md

@@ -0,0 +1,108 @@
+# Configuration
+
+By default, Nuxt is configured to cover most use cases. The [`nuxt.config.ts`](/guide/directory-structure/nuxt.config) file can override or extend this default configuration.
+
+## Nuxt Configuration
+
+The `nuxt.config.ts` 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 [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.
+
+::alert{type=info}
+Every configuration option is described in the [Configuration Reference](/api/configuration/nuxt.config).
+::
+
+::alert{type=info}
+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 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` are also available client-side.
+
+Those values should be defined in `nuxt.config` and can be overridden using environment variables.
+
+::code-group
+
+```ts [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'
+    }
+  }
+})
+```
+
+```text [.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`](/api/composables/use-runtime-config) composable.
+
+```vue [pages/index.vue]
+<script setup>
+const runtimeConfig = useRuntimeConfig()
+</script>
+```
+
+:ReadMore{link="/guide/going-further/runtime-config"}
+
+## App Configuration
+
+The `app.config.ts` file, also located at the root of a Nuxt project, is used to expose public variables that can be determined at build time. Contrary to the `runtimeConfig` option, these can not be overriden 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`](/api/composables/use-app-config) composable.
+
+```vue [pages/index.vue]
+<script setup>
+const appConfig = useAppConfig()
+</script>
+```
+
+:ReadMore{link="/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

docs/content/1.getting-started/8.error-handling.md

@@ -73,7 +73,7 @@ const handleError = () => clearError({ redirect: '/' })
 
 ### `useError`
 
-* `function useError (): Ref<any>`
+* `function useError (): Ref<Error | { url, statusCode, statusMessage, message, description, data }>`
 
 This function will return the global Nuxt error that is being handled.
 

docs/content/2.guide/2.directory-structure/1.server.md

@@ -66,6 +66,21 @@ export default defineEventHandler((event) => {
 })
 ```
 
+## Server Plugins
+
+Nuxt will automatically read any files in the `~/server/plugins` directory and register them as Nitro plugins. This allows extending Nitro's runtime behavior and hooking into lifecycle events.
+
+**Example:**
+
+```ts [server/plugins/nitroPlugin.ts]
+export default defineNitroPlugin((nitroApp) => {
+  console.log('Nitro plugin', nitroApp)
+})
+```
+
+::ReadMore{link="https://nitro.unjs.io/guide/advanced/plugins" title="Nitro Plugins"}
+::
+
 ## Server Utilities
 
 Server routes are powered by [unjs/h3](https://github.com/unjs/h3) which comes with a handy set of helpers.
@@ -105,7 +120,7 @@ Given the example above, fetching `/test` with:
 
 - **GET** method: Returns `Test get handler`
 - **POST** method: Returns `Test post handler`
-- Any other method: Returns 404 error
+- Any other method: Returns 405 error
 
 ### Catch-all Route
 

docs/content/2.guide/2.directory-structure/3.tsconfig.md

@@ -14,4 +14,4 @@ Nuxt [automatically generates](/guide/concepts/typescript) a `.nuxt/tsconfig.jso
 }
 ```
 
-As you need to, you can customize the contents of this file. However, note that 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` property within your `nuxt.config`, where they will get picked up and added to the autogenerated `tsconfig`.
+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`. Moreover, note that 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` property within your `nuxt.config`, where they will get picked up and added to the auto-generated `tsconfig`.

docs/content/2.guide/4.going-further/2.hooks.md

@@ -45,3 +45,26 @@ export default defineNuxtPlugin((nuxtApp) => {
 ::alert{icon=👉}
 Learn more about  [available lifecycle hooks](/api/advanced/hooks)
 ::
+
+## Nitro App Hooks (Runtime)
+
+These hooks are available for [Nitro plugins](https://nitro.unjs.io/guide/advanced/plugins) to hook into Nitro's runtime behavior.
+
+### Usage within a Nitro Plugin
+
+```js [~/server/plugins/test.ts]
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('render:html', (html, { event }) => {
+    console.log('render:html', html)
+    html.bodyAppend.push('<hr>Appended by custom plugin')
+  })
+
+  nitroApp.hooks.hook('render:response', (response, { event }) => {
+    console.log('render:response', response)
+  })
+})
+```
+
+::alert{icon=👉}
+Learn more about available [Nitro lifecycle hooks](/api/advanced/hooks#nitro-hooks-runtime-server-side).
+::

docs/content/3.api/3.utils/navigate-to.md

@@ -71,13 +71,13 @@ An object accepting the following properties:
 ```vue
 <script setup>
 // passing 'to' as a string
-return navigateTo('/search')
+await navigateTo('/search')
 
 // ... or as a route object
-return navigateTo({ path: '/search' })
+await navigateTo({ path: '/search' })
 
 // ... or as a route object with query parameters
-return navigateTo({
+await navigateTo({
   path: '/search',
   query: {
     page: 1,
@@ -103,13 +103,13 @@ export default defineNuxtRouteMiddleware((to, from) => {
 
 ```vue
 <script setup>
-  // will throw an error;
-  // navigating to an external URL is not allowed by default
-  await navigateTo('https://v3.nuxtjs.org')
-
-  // will redirect successfully with the 'external' parameter set to 'true'
-  await navigateTo('https://v3.nuxtjs.org', {
-    external: true
-  })
+// will throw an error;
+// navigating to an external URL is not allowed by default
+await navigateTo('https://v3.nuxtjs.org')
+
+// will redirect successfully with the 'external' parameter set to 'true'
+await navigateTo('https://v3.nuxtjs.org', {
+  external: true
+})
 </script>
 ```

docs/content/3.api/4.advanced/1.hooks.md

@@ -28,3 +28,10 @@ Hook                   | Arguments           | Environment     | Description
 Check the [schema source code](https://github.com/nuxt/framework/blob/main/packages/schema/src/types/hooks.ts#L55) for all available hooks.
 
 :NeedContribution
+
+# Nitro App Hooks (runtime, server-side)
+
+Hook                   | Arguments             | Description                          | Types
+-----------------------|-----------------------|--------------------------------------|------------------
+`render:response`      | `response, { event }` | Called before sending the response.  | [response](https://github.com/nuxt/framework/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L24), [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
+`render:html`          | `html, { event }`     | Called before constructing the HTML. | [html](https://github.com/nuxt/framework/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L15), [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)

docs/content/3.api/5.commands/build.md

@@ -1,14 +1,15 @@
 # `nuxi build`
 
 ```{bash}
-npx nuxi build [rootDir]
+npx nuxi build [rootDir] [--prerender] [--dotenv]
 ```
 
 The `build` command creates a `.output` directory with all your application, server and dependencies ready for production.
 
 Option        | Default          | Description
 -------------------------|-----------------|------------------
 `rootDir` | `.` | The root directory of the application to bundle.
-`prerender` | `false` | Pre-render every route of your application. (**note:** This is an experimental flag. The behavior might be changed.)
+`--prerender` | `false` | Pre-render every route of your application. (**note:** This is an experimental flag. The behavior might be changed.)
+`--dotenv` | `.` | Point to another `.env` file to load, **relative** to the root directory.
 
 This command sets `process.env.NODE_ENV` to `production`.

docs/content/3.api/5.commands/dev.md

@@ -1,14 +1,15 @@
 # `nuxi dev`
 
 ```{bash}
-npx nuxi dev [rootDir] [--clipboard] [--open, -o] [--no-clear] [--port, -p] [--host, -h] [--https] [--ssl-cert] [--ssl-key]
+npx nuxi dev [rootDir] [--dotenv] [--clipboard] [--open, -o] [--no-clear] [--port, -p] [--host, -h] [--https] [--ssl-cert] [--ssl-key]
 ```
 
 The `dev` command starts a development server with hot module replacement at [http://localhost:3000](https://localhost:3000)
 
 Option        | Default          | Description
 -------------------------|-----------------|------------------
 `rootDir` | `.` | The root directory of the application to serve.
+`--dotenv` | `.` | Point to another `.env` file to load, **relative** to the root directory.
 `--clipboard` | `false` | Copy URL to clipboard.
 `--open, -o` | `false` | Open URL in browser.
 `--no-clear` | `false` | Does not clear the console after startup.

docs/content/3.api/5.commands/preview.md

@@ -1,14 +1,15 @@
 # `nuxi preview`
 
 ```{bash}
-npx nuxi preview [rootDir]
+npx nuxi preview [rootDir] [--dotenv]
 ```
 
 The `preview` command starts a server to preview your Nuxt application after running the `build` command.
 
 Option        | Default          | Description
 -------------------------|-----------------|------------------
 `rootDir` | `.` | The root directory of the application to preview.
+`--dotenv` | `.` | Point to another `.env` file to load, **relative** to the root directory.
 
 This command sets `process.env.NODE_ENV` to `production`. To override, define `NODE_ENV` in a `.env` file or as command-line argument.
 

docs/content/5.community/5.roadmap.md

@@ -18,8 +18,8 @@ Nuxt is constantly evolving, with new features and modules being added all the t
 
 Release             | Expected date   | Description
 --------------------|-----------------|---------------------------------------------------
-`nuxt@2.16`         | Summer,  2022   | Nuxt v2 cumulative updates for future compatibility with Bridge
-`nuxt@3.0.0`        | Summer,  2022   | Nuxt v3 stable release
+`nuxt@2.16`         | Autumn,  2022   | Nuxt v2 cumulative updates for future compatibility with Bridge
+`nuxt@3.0.0`        | Autumn,  2022   | Nuxt v3 final release
 
 ### Current Releases
 
@@ -61,6 +61,6 @@ Module         | Status              | Nuxt Support | Repository | Description
 ---------------|---------------------|--------------|------------|-------------------
 Content 1.x    | Maintenance         | 2.x          | [nuxt/content](https://github.com/nuxt/content/tree/v1) | Maintenance only
 Content 2.x    | Active              | 3.x          | [nuxt/content](https://github.com/nuxt/content) | Released
-Auth           | WIP                 | 3.x          | [nuxt/auth](https://github.com/nuxt/auth) | Nuxt 3 support is planned after session support
+Auth           | WIP                 | 3.x          | `nuxt/auth` to be announced | Nuxt 3 support is planned after session support
 Image          | Active              | 2.x and 3.x  | [nuxt/image](https://github.com/nuxt/image) | Nuxt 3 support is in progress: [nuxt/image#548](https://github.com/nuxt/image/discussions/548)
 Telemetry      | Active              | 2.x and 3.x  | [nuxt/telemetry](https://github.com/nuxt/telemetry/) | Nuxt 3 is supported. Stats to be public soon!