Merge remote-tracking branch 'origin/main' into fix/ssr-false-bridge-…

…build

docs/content/1.getting-started/1.introduction.md

@@ -18,9 +18,25 @@ Before getting started, please make sure you have installed the recommended setu
 * **Node.js**<sup>*</sup> (latest LTS version) 👉 [[Download](https://nodejs.org/en/download/)]
 * **Visual Studio Code** 👉 [[Download](https://code.visualstudio.com/)]
 * **Volar Extension** 👉 [[Download](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar)]
+  * Either enable [**Take Over Mode**](https://github.com/johnsoncodehk/volar/discussions/471) (recommended)
+  * ... or add **TypeScript Vue Plugin (Volar)** 👉 [[Download](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.vscode-typescript-vue-plugin)]
 
 <sup>*</sup> If you already have Node.js installed, check with `node --version` that you are using `v14` or `v16`.
 
+::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:
+
+```js
+export default defineNuxtConfig({
+  typescript: {
+    shim: false
+  }
+})
+```
+
+::
+
 ## Nuxt 3 or Bridge?
 
 Next, decide whether to start from scratch or upgrade an existing Nuxt 2 project.
@@ -67,7 +83,7 @@ Stability                | 😊 Stable      | 😌 Semi-stable   | 😬 Unstable
 Performance              | 🏎 Fast        | ✈️ Faster        | 🚀 Fastest
 Nitro Engine             | ❌             | ✅               | ✅
 ESM support              | 🌙 Partial     | 👍 Better        | ✅
-TypeScript               | ☑️ Opt-in      | 🚧 Faster        | ✅
+TypeScript               | ☑️ Opt-in      | 🚧 Partial       | ✅
 Composition API          | ❌             | 🚧 Partial       | ✅
 Options API              | ✅             | ✅               | ✅
 Components Auto Import   | ✅             | ✅               | ✅

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

@@ -17,7 +17,7 @@ Using Nuxt Bridge, you can make sure your project is (almost) ready for Nuxt 3 a
 
 ## Upgrade Nuxt 2
 
-Remove any package lock files (`package-lock.json` and `yarn.lock`) and use the latest `nuxt-edge`:
+Make sure your dev server (`nuxt dev`) isn't running, remove any package lock files (`package-lock.json` and `yarn.lock`), and install the latest `nuxt-edge`:
 
 ```diff [package.json]
 - "nuxt": "^2.15.0"

docs/content/2.concepts/3.typescript.md

@@ -33,7 +33,7 @@ Nitro also [auto-generates types](/concepts/server-engine#typed-api-routes) for
 Keep in mind that all options extended from `./.nuxt/tsconfig.json` will be overwritten by the options defined in your `tsconfig.json`.
 Overwriting options such as `"compilerOptions.paths"` with your own configuration will lead Typescript to not factor in the module resolutions from `./.nuxt/tsconfig.json`. This can lead to module resolutions such as `#app` not being recognized.
 
-In case you need to extend options provided by `./.nuxt/tsconfig.json` further, you can use the `alias` property withing your `nuxt.config`. `nuxi` will pick them up and extend `./.nuxt/tsconfig.json` accordingly.
+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

docs/content/3.docs/1.usage/1.data-fetching.md

@@ -3,7 +3,7 @@
 Nuxt provides `useFetch`, `useLazyFetch`, `useAsyncData` and `useLazyAsyncData` to handle data fetching within your application.
 
 ::alert{icon=👉}
-**`useFetch`, `useLazyFetch`, `useAsyncData` and `useLazyAsyncData` only works during `setup` or `Lifecycle Hooks`**
+**`useFetch`, `useLazyFetch`, `useAsyncData` and `useLazyAsyncData` only work during `setup` or `Lifecycle Hooks`**
 ::
 
 ## `useAsyncData`

docs/content/3.docs/2.directory-structure/10.plugins.md

@@ -12,6 +12,23 @@ Nuxt will automatically read the files in your `plugins` directory and load them
 All plugins in your `plugins/` directory are auto-registered, so you should not add them to your `nuxt.config` separately.
 ::
 
+## Which files are registered
+
+Only files at the top level of the `plugins/` directory (or index files within any subdirectories) will be registered as plugins.
+
+For example:
+
+```bash
+plugins
+ | - myPlugin.ts
+ | - myOtherPlugin
+ | --- supportingFile.ts
+ | --- componentToRegister.vue
+ | --- index.ts
+```
+
+Only `myPlugin.ts` and `myOtherPlugin/index.ts` would be registered.
+
 ## Creating plugins
 
 The only argument passed to a plugin is [`nuxtApp`](/docs/usage/nuxt-app).

docs/content/3.docs/2.directory-structure/12.server.md

@@ -49,6 +49,22 @@ export default async (req: IncomingMessage, res: ServerResponse) => {
 }
 ```
 
+#### Accessing req data
+
+```js
+import { useBody, useCookies, useQuery } from 'h3'
+
+export default async (req, res) => {
+  const query = await useQuery(req)
+  const body = await useBody(req) // only for POST request
+  const cookies = useCookies(req)
+
+  return { query, body, cookies }
+}
+```
+
+Learn more about [h3 methods](https://www.jsdocs.io/package/h3#package-index-functions).
+
 ## Server Middleware
 
 Nuxt will automatically read in any files in the `~/server/middleware` to create server middleware for your project.

docs/content/3.docs/2.directory-structure/5.composables.md

@@ -8,7 +8,23 @@ head.title: Composables directory
 
 Nuxt 3 supports `composables/` directory to automatically import your Vue composables into your application using auto-imports!
 
-Example: (using named export)
+## How files are scanned
+
+Only files at the top level of the `composables/` directory (or index files within any subdirectories) will be scanned for composables.
+
+For example:
+
+```bash
+composables
+ | - useFoo.ts
+ | - useBar
+ | --- supportingFile.ts
+ | --- index.ts
+```
+
+Only `useFoo.ts` and `useBar/index.ts` would be searched for imports - and if the latter is a default export, it would be registered as `useBar` rather than `index`.
+
+## Example: (using named export)
 
 ```js [composables/useFoo.ts]
 import { useState } from '#app'
@@ -18,12 +34,12 @@ export const useFoo = () => {
 }
 ```
 
-Example: (using default export)
+## Example: (using default export)
 
 ```js [composables/use-foo.ts or composables/useFoo.ts]
 import { useState } from '#app'
 
-// It will be available as useFoo() (pascalCase of file name without extension)
+// It will be available as useFoo() (camelCase of file name without extension)
 export default function () {
   return useState('foo', () => 'bar')
 }

docs/content/3.docs/2.directory-structure/6.layouts.md

@@ -34,15 +34,20 @@ Given the example above, you can use a custom layout like this:
 
 ```vue
 <script>
-export default {
+// This will also work in `<script setup>`
+definePageMeta({
   layout: "custom",
-};
+});
 </script>
 ```
 
+::alert{type=info}
+Learn more about [defining page meta](/docs/directory-structure/pages#page-metadata).
+::
+
 ## Example: using with slots
 
-You can also take full control (for example, with slots) by using the `<NuxtLayout>` component (which is globally available throughout your application) and set `layout: false` in your component options.
+You can also take full control (for example, with slots) by using the `<NuxtLayout>` component (which is globally available throughout your application) by setting `layout: false`.
 
 ```vue
 <template>
@@ -53,51 +58,33 @@ You can also take full control (for example, with slots) by using the `<NuxtLayo
   </NuxtLayout>
 </template>
 
-<script>
-export default {
+<script setup>
+definePageMeta({
   layout: false,
-};
+});
 </script>
 ```
 
-## Example: using with `<script setup>`
-
-If you are utilizing Vue `<script setup>` [compile-time syntactic sugar](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup), you can use a secondary `<script>` tag to set `layout` options as needed.
-
-::alert{type=info}
-Learn more about [`<script setup>` and `<script>` tags co-existing](https://v3.vuejs.org/api/sfc-script-setup.html#usage-alongside-normal-script) in the Vue docs.
-::
-
-Assuming this directory structure:
-
-```bash
--| layouts/
----| custom.vue
--| pages/
----| my-page.vue
-```
+## Example: changing the layout
 
-And this `custom.vue` layout:
+You can also use a ref or computed property for your layout.
 
 ```vue
 <template>
   <div>
-    Some shared layout content:
-    <slot />
+    <button @click="enableCustomLayout">Update layout</button>
   </div>
 </template>
-```
-
-You can set a page layout in `my-page.vue` — alongside the `<script setup>` tag — like this:
-
-```vue
-<script>
-export default {
-  layout: "custom",
-};
-</script>
 
 <script setup>
-// your setup script
+const route = useRoute()
+function enableCustomLayout () {
+  // Note: because it's within a ref, it will persist if 
+  // you navigate away and then back to the page.
+  route.meta.layout.value = "custom"
+}
+definePageMeta({
+  layout: ref(false),
+});
 </script>
 ```

docs/content/3.docs/2.directory-structure/9.pages.md

@@ -133,3 +133,52 @@ To display the `child.vue` component, you have to insert the `<NuxtNestedPage
   </div>
 </template>
 ```
+
+## Page Metadata
+
+You might want to define metadata for each route in your app. You can do this using the `definePageMeta` macro, which will work both in `<script>` and in `<script setup>`:
+
+```vue
+<script setup>
+definePageMeta({
+  title: 'My home page'
+})
+```
+
+This data can then be accessed throughout the rest of your app from the `route.meta` object.
+
+```vue
+<script setup>
+const route = useRoute()
+console.log(route.meta.title) // My home page
+</script>
+```
+
+If you are using nested routes, the page metadata from all these routes will be merged into a single object. For more on route meta, see the [vue-router docs](https://next.router.vuejs.org/guide/advanced/meta.html#route-meta-fields).
+
+Much like `defineEmits` or `defineProps` (see [Vue docs](https://v3.vuejs.org/api/sfc-script-setup.html#defineprops-and-defineemits)), `definePageMeta` is a **compiler macro**. It will be compiled away so you cannot reference it within your component. Instead, the metadata passed to it will be hoisted out of the component. Therefore, the page meta object cannot reference the component (or values defined on the component). However, it can reference imported bindings.
+
+```vue
+<script setup>
+import { someData } from '~/utils/example'
+
+const title = ref('')
+
+definePageMeta({
+  title,
+  someData
+})
+</script>
+```
+
+### Special Metadata
+
+Of course, you are welcome to define metadata for your own use throughout your app. But some metadata defined with `definePageMeta` has a particular purpose:
+
+#### `layout`
+
+You can define the layout used to render the route. This can be either false (to disable any layout), a string or a ref/computed, if you want to make it reactive in some way. [More about layouts](/docs/directory-structure/layouts).
+
+#### `transition`
+
+You can define transition properties for the `<transition>` component that wraps your pages, or pass `false` to disable the `<transition>` wrapper for that route. [More about transitions](https://v3.vuejs.org/guide/transitions-overview.html).

docs/content/3.docs/3.deployment/99.presets/server.md

@@ -46,6 +46,14 @@ $ node .output/server/index.mjs
 Listening on http://localhost:3000
 ```
 
+## Configuring defaults at runtime
+
+This preset will respect the following runtime environment variables:
+
+- `NUXT_PORT` or `PORT` (defaults to `3000`)
+- `NUXT_HOST` or `HOST` (defaults to `'localhost'`)
+- `NITRO_SSL_CERT` and `NITRO_SSL_KEY` - if both are present, this will launch the server in HTTPS mode. In the vast majority of cases this should not be used other than for testing, and the Nitro server should be run behind a reverse proxy like nginx or Cloudflare which terminates SSL.
+
 ## Server timings
 
 You can enable the `nitro.timing` option to have the logs about the chunk loading and cold start performance.

docs/content/4.community/2.reporting-bugs.md

@@ -25,7 +25,7 @@ Start with the Nuxt 3 or Nuxt Bridge sandbox and add the **minimum** amount of c
 
 **Nuxt Bridge**:
 
-:button-link[Nuxt Bridge on CodeSandBox]{href="https://codesandbox.io/s/github/nuxt/starter/tree/bridge-codesandbox" blank}
+:button-link[Nuxt Bridge on CodeSandBox]{href="https://codesandbox.io/s/github/nuxt/starter/tree/v2-bridge-codesandbox" blank}
 
 Once you've reproduced the issue, remove as much code from your reproduction as you can (while still recreating the bug). The time spent making the reproduction as minimal as possible will make a huge difference to whoever sets out to fix the issue.
 

examples/use-async-data/app.vue

@@ -3,7 +3,7 @@ const { data, refresh, pending } = await useAsyncData('/api/hello', () => $fetch
 </script>
 
 <template>
-  <NuxtExampleLayout example="use-async-data" show-tips="true">
+  <NuxtExampleLayout example="use-async-data" show-tips>
     <div>{{ data }}</div>
     <div>
       <NButton :disabled="pending" @click="refresh">

examples/with-layouts/pages/index.vue

@@ -11,8 +11,8 @@
   </div>
 </template>
 
-<script>
-export default defineNuxtComponent({
+<script setup>
+definePageMeta({
   layout: 'custom'
 })
 </script>

examples/with-layouts/pages/manual.vue

@@ -18,8 +18,10 @@
 </template>
 
 <script>
+definePageMeta({
+  layout: false
+})
 export default {
-  layout: false,
   data: () => ({
     layout: 'custom'
   })

examples/with-layouts/pages/same.vue

@@ -8,7 +8,7 @@
 </template>
 
 <script>
-export default {
+definePageMeta({
   layout: 'custom'
-}
+})
 </script>