Merge branch 'main' into feat/objects-router-commands

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,37 @@
+name: "🚀 Feature request"
+description: Suggest a feature that will improve Nuxt
+labels: ["pending triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to fill out this feature request!
+
+        Please carefully read the contribution docs before suggesting a new feature
+        👉 https://v3.nuxtjs.org/community/contribution/#creating-an-issue
+  - type: textarea
+    id: feature-description
+    attributes:
+      label: Describe the feature
+      description: A clear and concise description of what you think would be a helpful addition to Nuxt, including the possible use cases and alternatives you have considered. If you have a working prototype or module that implements it, please include a link.
+      placeholder: Feature description
+    validations:
+      required: true
+  - type: checkboxes
+    id: additional-info
+    attributes:
+      label: Additional information
+      description: Additional information that helps us decide how to proceed.
+      options:
+        - label: Would you be willing to help implement this feature?
+        - label: Could this feature be implemented as a module?
+  - type: checkboxes
+    id: required-info
+    attributes:
+      label: Final checks
+      description: Before submitting, please make sure you do the following
+      options:
+        - label: Read the [contribution guide](https://v3.nuxtjs.org/community/contribution).
+          required: true
+        - label: Check existing [discussions](https://github.com/nuxt/framework/discussions) and [issues](https://github.com/nuxt/framework/issues).
+          required: true

.gitignore

@@ -23,7 +23,6 @@ dist
 .nuxt-*
 .output
 .gen
-nuxt.d.ts
 
 # Junit reports
 reports

.yarnrc.yml

@@ -8,4 +8,4 @@ plugins:
   - path: .yarn/plugins/@yarnpkg/plugin-interactive-tools.cjs
     spec: "@yarnpkg/plugin-interactive-tools"
 
-yarnPath: .yarn/releases/yarn-3.2.1.cjs
+yarnPath: .yarn/releases/yarn-3.2.2.cjs

docs/components/atoms/StabilityEdge.vue

@@ -1,8 +1,10 @@
 <template>
   <Alert icon="🧪">
-    {{ title }} is available on edge channel. Check out the <Link to="/guide/going-further/edge-channel">
+    {{ title }} is available on edge channel. Check out the
+    <Link to="/guide/going-further/edge-channel">
       Edge Channel Documentation
     </Link> to beta test.
+    <slot />
   </Alert>
 </template>
 

docs/content/1.getting-started/1.quick-start.md

@@ -2,7 +2,7 @@
 
 Starting fresh? Getting started with Nuxt 3 is straightforward!
 
-## Play online
+## Play Online
 
 You can start playing with Nuxt 3 in your browser using our online sandboxes:
 
@@ -23,7 +23,7 @@ Before getting started, please make sure you have installed the recommended setu
 
 ::alert{type=info}
 
-If you have enabled **Take Over Mode** or installed the **TypeScript Vue Plugin (Volar)**, you can disable generating the shim for `*.vue` files:
+If you have enabled **Take Over Mode** or installed the **TypeScript Vue Plugin (Volar)**, you can disable generating the shim for `*.vue` files in your `nuxt.config` file:
 
 ```js
 export default defineNuxtConfig({
@@ -35,7 +35,7 @@ export default defineNuxtConfig({
 
 ::
 
-## New project
+## New Project
 
 Open a terminal, or from [Visual Studio Code](https://code.visualstudio.com/), open an [integrated terminal](https://code.visualstudio.com/docs/editor/integrated-terminal) and use the following command to create a new starter project:
 
@@ -75,7 +75,7 @@ pnpm install --shamefully-hoist
 
 ::
 
-## Development server
+## Development Server
 
 Now you'll be able to start your Nuxt app in development mode:
 
@@ -99,7 +99,7 @@ pnpm run dev -o
 Well done! A browser window should automatically open for <http://localhost:3000>.
 ::
 
-## Next steps
+## Next Steps
 
 Now that you've created your Nuxt 3 project, you are ready to start building your application.
 

docs/content/2.guide/1.concepts/1.introduction.md

@@ -20,7 +20,7 @@ Nuxt takes care of this so you can focus on what matters: **creating your web ap
 
 On top of this setup, Nuxt provides a [directory structure](/guide/directory-structure) to follow, focused on specific features to keep your focus on creating, not configuring.
 
-## How does it work?
+## How Does It Work?
 
 Nuxt is composed of different [core packages](https://github.com/nuxt/framework/tree/main/packages):
 ::list{type=info}
@@ -35,7 +35,7 @@ Nuxt is composed of different [core packages](https://github.com/nuxt/framework/
 
 We recommend reading each concept to have a full vision of Nuxt capabilities and the scope of each package.
 
-## Are you Nuxt?
+## Are You Nuxt?
 
 Nuxt is the backbone of your Vue.js project, giving structure to build your project with confidence while keeping flexibility.
 
@@ -45,6 +45,6 @@ Extendable with a strong module ecosystem and hooks engine, it makes it easy to
 Ready to try? Head over to the [Installation section](/getting-started/quick-start).
 ::
 
-### Are you *courageously* Nuxt?
+### Are You *Courageously* Nuxt?
 
 Take a stab at an open [issue](https://github.com/nuxt/framework/issues). This is the best way to learn Nuxt, by actually diving into the code. You may even bring an approach or alternative solution that makes Nuxt even better! So, what are you waiting for? Let's go!

docs/content/2.guide/1.concepts/2.vuejs-development.md

@@ -15,11 +15,11 @@ Nuxt has always used Vue as a frontend framework. We chose to build Nuxt on top
 
 ## Vue with Nuxt
 
-### Single file components
+### Single File Components
 
 [Vue’s single-file components](https://v3.vuejs.org/guide/single-file-component.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://webpack.js.org/concepts/hot-module-replacement/) that offers a seamless developer experience.
 
-### Components auto-imports
+### Components Auto-imports
 
 Every Vue component created in the [`components/` directory](/guide/directory-structure/components) 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.
 
@@ -54,13 +54,13 @@ Nuxt 3 is based on Vue 3. The new major Vue version introduces several changes t
 - Composition API
 - TypeScript support
 
-### Faster rendering
+### 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
+### 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.
 
@@ -103,7 +103,7 @@ The goal of Nuxt 3 is to provide a great developer experience around the Composi
 - Use auto-imported [Reactivity functions](https://vuejs.org/api/reactivity-core.html) from Vue and Nuxt 3 [built-in composables](/api/composables/use-async-data).
 - Write your own auto-imported reusable functions in the `composables/` directory.
 
-### TypeScript support
+### 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 lang="ts">` in a component.
 

docs/content/2.guide/1.concepts/3.rendering.md

@@ -2,7 +2,7 @@
 
 Both the browser and server can interpret JavaScript code to render Vue.js components into HTML elements. This step is called **rendering**. Nuxt supports both **client-side** and **universal** rendering. The two approaches have pros and cons that we will cover in this section.
 
-## Client-side only rendering
+## Client-side Only Rendering
 
 Out of the box, a traditional Vue.js application is rendered in the browser (or **client**). Then, Vue.js generates HTML elements after the browser downloads and parses all the JavaScript code containing the instructions to create the current interface.
 
@@ -57,7 +57,7 @@ Universal rendering is very versatile and can fit almost any use case, and is es
 
 Client-side and universal rendering are different strategies to display an interface in a browser.
 
-By default, Nuxt uses **universal rendering** to provide better user experience and performance, and to optimize search engine indexing, but you can switch rendering modes in [one line of configuration](/guide/directory-structure/nuxt.config#ssr).
+By default, Nuxt uses **universal rendering** to provide better user experience and performance, and to optimize search engine indexing, but you can switch rendering modes in [one line of configuration](/api/configuration/nuxt.config#ssr).
 
 ## Coming in Nuxt 3
 
@@ -71,7 +71,7 @@ At the moment, every page (or **route**) of a Nuxt application must use the same
 
 [Read the open RFC discussing implementation and gathering community feedback.](https://github.com/nuxt/framework/discussions/560)
 
-### Rendering on CDN edge workers
+### Rendering on CDN Edge Workers
 
 Traditionally, server-side and universal rendering was only possible using Node.js. Nuxt 3 takes it to another level by directly rendering code in CDN edge workers, reducing latency and costs.
 

docs/content/2.guide/1.concepts/4.auto-imports.md

@@ -13,7 +13,7 @@ You can find a reference for auto-imported [composables](/api/composables/use-as
 Auto imports don't currently work within the [server directory](/guide/directory-structure/server).
 ::
 
-## Nuxt auto-imports
+## Nuxt Auto-imports
 
 Nuxt auto-imports functions and composables to perform [data fetching](/guide/features/data-fetching), get access to the [app context](/api/composables/use-nuxt-app) and [runtime config](/guide/features/runtime-config), manage [state](/guide/features/state-management) or define components and plugins.
 
@@ -24,7 +24,7 @@ Nuxt auto-imports functions and composables to perform [data fetching](/guide/fe
 </script>
 ```
 
-## Vue auto-imports
+## Vue Auto-imports
 
 Vue 3 exposes Reactivity APIs like `ref` or `computed`, as well as lifecycle hooks and helpers that are auto-imported by Nuxt.
 
@@ -36,14 +36,14 @@ Vue 3 exposes Reactivity APIs like `ref` or `computed`, as well as lifecycle hoo
 </script>
 ```
 
-## Directory-based auto-imports
+## Directory-based Auto-imports
 
 Nuxt directly auto-imports files created in defined directories:
 
 - `components/` for [Vue components](/guide/directory-structure/components).
 - `composables/` for [Vue composables](/guide/directory-structure/composables).
 
-## Explicit imports
+## Explicit Imports
 
 Nuxt exposes every auto-import with the `#imports` alias that can be used to make the import explicit if needed:
 

docs/content/2.guide/1.concepts/4.server-engine.md

@@ -29,7 +29,7 @@ Check out [the h3 docs](https://github.com/unjs/h3) for more information.
 Learn more about the API layer in the [`server/`](/guide/directory-structure/server) directory.
 ::
 
-## Direct API calls
+## Direct API Calls
 
 Nitro allows 'direct' calling of routes via the globally-available `$fetch` helper. This will make an API call to the server if run on the browser, but will directly call the relevant function if run on the server, **saving an additional API call**.
 
@@ -40,7 +40,7 @@ Nitro allows 'direct' calling of routes via the globally-available `$fetch` help
 
 For more information on `$fetch` features, check out [ohmyfetch](https://github.com/unjs/ohmyfetch).
 
-## Typed API routes
+## Typed API Routes
 
 When using API routes (or middleware), Nitro will generate typings for these routes as long as you are returning a value instead of using `res.end()` to send a response.
 

docs/content/2.guide/1.concepts/6.typescript.md

@@ -4,13 +4,13 @@ Nuxt 3 is fully typed and provides helpful shortcuts to ensure you have access t
 
 ## Type-checking
 
-By default, Nuxt doesn't check types when you run `nuxi dev` or `nuxi build`, for performance reasons. However, you can enable type-checking at build or development time with [the `typescript.typeCheck` option in your `nuxt.config` file](/api/configuration/nuxt.config#typescript), or [manually check your types with nuxi](/api/commands/typecheck).
+By default, Nuxt doesn't check types when you run `nuxi dev` or `nuxi build`, for performance reasons. However, you can enable type-checking at build or development time by installing `vue-tsc` and `typescript` as devDependencies and either enabling [the `typescript.typeCheck` option in your `nuxt.config` file](/api/configuration/nuxt.config#typescript) or [manually checking your types with nuxi](/api/commands/typecheck).
 
 ```bash
 yarn nuxi typecheck
 ```
 
-## Auto-generated types
+## Auto-generated Types
 
 When you run `nuxi dev` or `nuxi build`, Nuxt generates the following files for IDE type support (and type checking):
 
@@ -37,7 +37,7 @@ Overwriting options such as `"compilerOptions.paths"` with your own configuratio
 In case you need to extend options provided by `./.nuxt/tsconfig.json` further, you can use the `alias` property within your `nuxt.config`. `nuxi` will pick them up and extend `./.nuxt/tsconfig.json` accordingly.
 ::
 
-## Stricter checks
+## Stricter Checks
 
 TypeScript comes with certain checks to give you more safety and analysis of your program.
 

docs/content/2.guide/2.features/10.app-config.md

@@ -0,0 +1,55 @@
+# App Config
+
+::StabilityEdge
+::
+
+Nuxt 3 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).
+
+::alert{type=warning}
+Do not put any secret values inside `app.config` file. It is exposed to the user client bundle.
+::
+
+## Defining App Config
+
+To expose config and environment variables to the rest of your app, you will need to define configuration in `app.config` file.
+
+**Example:**
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  theme: {
+    primaryColor: '#ababab'
+  }
+})
+```
+
+When adding `theme` to the `app.config`, Nuxt uses Vite or Webpack to bundle the code. We can universally access `theme` in both server and browser using [useAppConfig](/api/composables/use-app-config) composable.
+
+```js
+const appConfig = useAppConfig()
+
+console.log(appConfig.theme)
+```
+
+<!-- TODO: Document module author for extension -->
+
+### Manually Typing App Config
+
+Nuxt tries to automatically generate a typescript interface from provided app config.
+
+It is also possible to type app config manually:
+
+```ts [index.d.ts]
+declare module '@nuxt/schema' {
+  interface AppConfig {
+    /** Theme configuration */
+    theme: {
+      /** Primary app color */
+      primaryColor: string
+    }
+  }
+}
+
+// It is always important to ensure you import/export something when augmenting a type
+export {}
+```

docs/content/2.guide/2.features/10.runtime-config.md

@@ -1,8 +1,8 @@
 # Runtime Config
 
-Nuxt provides a runtime config API to expose config within your application and server routes with the ability to update them at runtime using environment variables.
+Nuxt provides a runtime config API to expose configuration within your application and server routes, with the ability to update it at runtime by setting environment variables.
 
-## Exposing runtime config
+## Exposing Runtime Config
 
 To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your `nuxt.config` file, using the [`runtimeConfig` option](/guide/directory-structure/nuxt.config#runtimeconfig).
 
@@ -35,11 +35,15 @@ console.log(runtimeConfig.public.apiBase)
 The most common way to provide configuration is by using [Environment Variables](https://medium.com/chingu/an-introduction-to-environment-variables-and-how-to-use-them-f602f66d15fa).
 
 ::alert{type=info}
-Nuxt CLI has built-in [dotenv](https://github.com/motdotla/dotenv) support.
+Nuxt CLI has built-in [dotenv](https://github.com/motdotla/dotenv) support in development mode and when running `nuxi build` and `nuxi generate`.
 
-In addition to any process environment variables, if you have a `.env` file in your project root directory, it will be automatically loaded into `process.env` and accessible within your `nuxt.config` file and modules.
+In addition to any process environment variables, if you have a `.env` file in your project root directory, it will be automatically loaded **at build, dev, and generate time**, and any environment variables set there will be accessible within your `nuxt.config` file and modules.
 
-However, **after your project is built**, you are responsible for setting environment variables when you run the server - your `.env` file will not be read at this point. For example, you could pass the environment variables as arguments using the terminal `DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs`.
+When updating `.env` in development mode, the Nuxt instance is automatically restarted to apply new values to the `process.env`.
+
+However, **after your server is built**, you are responsible for setting environment variables when you run the server. Your `.env` file will not be read at this point. How you do this is different for every environment. On a Linux server, you could pass the environment variables as arguments using the terminal `DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs`. Or you could source your env file using `source .env && 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.
 ::
 
 Runtime config values are automatically replaced by matching environment variables at runtime. For this to work, you _must_ have a fallback value (which can just be an empty string) defined in your `nuxt.config`.
@@ -62,9 +66,9 @@ export default defineNuxtConfig({
 })
 ```
 
-## Accessing runtime config
+## Accessing Runtime Config
 
-### Vue app
+### Vue App
 
 Within the Vue part of your Nuxt app, you will need to call `useRuntimeConfig()` to access the runtime config.
 

docs/content/2.guide/2.features/11.teleports.md

@@ -4,7 +4,7 @@ Vue 3 provides the [`<Teleport>` component](https://vuejs.org/guide/built-ins/te
 
 The `to` target of `<Teleport>` expects a CSS selector string or an actual DOM node. Nuxt currently has SSR support for teleports to `body` only, with client-side support for other targets using a `<ClientOnly>` wrapper.
 
-## Example: body teleport
+## Example: `body` Teleport
 
 ```vue
 <template>
@@ -22,9 +22,10 @@ The `to` target of `<Teleport>` expects a CSS selector string or an actual DOM n
 </template>
 ```
 
-## Example: client-side teleport
+## Example: Client-side Teleport
 
 ```vue
+<template>
   <ClientOnly>
     <Teleport to="#some-selector">
       <!-- content -->