Merge branch 'main' into chore/upgrade-vitest-2

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -10,7 +10,7 @@ body:
 
         Please use a template below to create a minimal reproduction
         👉 https://stackblitz.com/github/nuxt/starter/tree/v3-stackblitz
-        👉 https://codesandbox.io/s/github/nuxt/starter/tree/v3-codesandbox
+        👉 https://codesandbox.io/p/github/nuxt/starter/v3-codesandbox
   - type: textarea
     id: bug-env
     attributes:
@@ -39,7 +39,7 @@ body:
     id: additonal
     attributes:
       label: Additional context
-      description: If applicable, add any other context about the problem here`
+      description: If applicable, add any other context about the problem here
   - type: textarea
     id: logs
     attributes:

.github/workflows/docs-e2e.yml

@@ -0,0 +1,32 @@
+name: docs-e2e
+
+on:
+  workflow_dispatch:
+    inputs:
+      url:
+        required: false
+        description: The URL to run the test suite against.
+        type: string
+  deployment_status:
+
+jobs:
+  crawl-docs:
+    environment:
+      name: ${{ github.event.deployment.environment || 'Production' }}
+      url: ${{ github.event.inputs.url || github.event.deployment.payload.web_url || github.event.deployment_status.target_url }}
+    if: github.event.deployment_status.state == 'success' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+          cache: "yarn"
+
+      - name: Install dependencies
+        run: yarn --immutable
+
+      - run: node ./scripts/crawl.mjs
+        env:
+          BASE_URL: ${{ github.event.inputs.url || github.event.deployment.payload.web_url || github.event.deployment_status.target_url }}

docs/.eslintrc

@@ -3,5 +3,8 @@
     "import/ignore": [
       "vue"
     ]
+  },
+  "rules": {
+    "vue/no-v-text-v-html-on-component": "off"
   }
 }

docs/.gitignore

@@ -1,2 +1,3 @@
 schema
 **/*.configuration/nuxt.config.md
+**/*.configuration/nuxt-config.md

docs/content/2.guide/1.concepts/1.introduction.md → docs/content/1.getting-started/1.introduction.md

@@ -42,7 +42,7 @@ Nuxt is the backbone of your Vue.js project, giving structure to build your proj
 Extendable with a strong module ecosystem and hooks engine, it makes it easy to connect your REST or GraphQL endpoints, favorite CMS, CSS frameworks and more. PWA and AMP support is only a module away from your Nuxt project.
 
 ::alert{type=info icon=👍}
-Ready to try? Head over to the [Installation section](/getting-started/quick-start).
+Ready to try? Head over to the [Installation section](/getting-started/installation).
 ::
 
 ### Are You *Courageously* Nuxt?

docs/content/1.getting-started/1.quick-start.md → docs/content/1.getting-started/2.installation.md

@@ -1,4 +1,4 @@
-# Quick Start
+# Installation
 
 Starting fresh? Getting started with Nuxt 3 is straightforward!
 
@@ -7,7 +7,7 @@ Starting fresh? Getting started with Nuxt 3 is straightforward!
 You can start playing with Nuxt 3 in your browser using our online sandboxes:
 
 :button-link[Play on StackBlitz]{href="https://stackblitz.com/github/nuxt/starter/tree/v3-stackblitz" blank}
-:button-link[Play on CodeSandbox]{href="https://codesandbox.io/s/github/nuxt/starter/tree/v3-codesandbox" blank}
+:button-link[Play on CodeSandbox]{href="https://codesandbox.io/p/github/nuxt/starter/v3-codesandbox" blank}
 
 ## Prerequisites
 
@@ -104,4 +104,3 @@ Well done! A browser window should automatically open for <http://localhost:3000
 Now that you've created your Nuxt 3 project, you are ready to start building your application.
 
 * Learn about the framework [concepts](/guide/concepts)
-* Learn more about the framework [features](/guide/features)

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/3.views.md

@@ -0,0 +1,130 @@
+# Views
+
+Nuxt provides several component layers to implement the user interface of your application.
+
+## `app.vue`
+
+![The `app.vue` file is the entry point of your application](/img/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>
+```
+
+::alert
+If you are familiar with Vue, you might wonder where `main.js` is (the file is that normally creates a Vue app). Nuxt does this behind the scene.
+::
+
+## Components
+
+![Components are reusable pieces of UI](/img/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/` 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](/img/getting-started/views/pages.svg)
+
+Pages represent views use for each specific route pattern. Every file in the `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` (or remove `app.vue` for default entry). You can now create more pages and their corresponding routes by adding new files in the `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>
+```
+
+::
+
+::alert
+You will learn more about pages in the [Routing section](/getting-started/routing)
+::
+
+## Layouts
+
+![Layouts are wrapper around pages](/img/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.
+
+::alert
+If you only have a single layout in your application, we recommend using app.vue with the [`<NuxtPage />` component](/api/components/nuxt-page) instead.
+::
+
+::code-group
+
+```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](/guide/directory-structure/layouts).

docs/content/2.guide/2.features/3.assets.md → docs/content/1.getting-started/4.assets.md

@@ -70,8 +70,6 @@ In your `nuxt.config`
 ::code-group
 
 ```ts [SCSS]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   vite: {
     css: {
@@ -86,8 +84,6 @@ export default defineNuxtConfig({
 ```
 
 ```ts [SASS]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   vite: {
     css: {