@nuxt/docs 4.0.0-alpha.3 → 4.0.0-rc.0

package/1.getting-started/18.upgrade.md

@@ -992,6 +992,7 @@ Nuxt now generates separate TypeScript configurations for different contexts to
    * `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
    * `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)  
    * `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
+   * `.nuxt/tsconfig.shared.json` - For code shared between app and server contexts (like types and non-environment specific utilities)
    * `.nuxt/tsconfig.json` - Legacy configuration for backward compatibility
 
 2. **Backward compatibility**: Existing projects that extend `.nuxt/tsconfig.json` will continue to work as before.
@@ -1027,6 +1028,7 @@ However, to take advantage of improved type checking, you can opt in to the new
      "references": [
        { "path": "./.nuxt/tsconfig.app.json" },
        { "path": "./.nuxt/tsconfig.server.json" },
+       { "path": "./.nuxt/tsconfig.shared.json" },
        { "path": "./.nuxt/tsconfig.node.json" }
      ]
    }

package/2.guide/1.concepts/10.nuxt-lifecycle.md

@@ -76,17 +76,27 @@ Any redirection on the server will result in a `Location:` header being sent to
 
 :read-more{to="/docs/guide/directory-structure/middleware"}
 
-### Step 6: Setup Page and Components
+### Step 6: Render Page and Components
 
-Nuxt initializes the page and its components during this step and fetches any required data with `useFetch` and `useAsyncData`. Since there are no dynamic updates and no DOM operations occur on the server, Vue lifecycle hooks such as `onBeforeMount`, `onMounted`, and subsequent hooks are **NOT** executed during SSR.
+Nuxt renders the page and its components and fetches any required data with `useFetch` and `useAsyncData` during this step. Since there are no dynamic updates and no DOM operations occur on the server, Vue lifecycle hooks such as `onBeforeMount`, `onMounted`, and subsequent hooks are **NOT** executed during SSR.
+
+By default, Vue pauses dependency tracking during SSR for better performance.
+
+::callout{icon="i-lucide-lightbulb"}
+There is no reactivity on the server side because Vue SSR renders the app top-down as static HTML, making it impossible to go back and modify content that has already been rendered.
+::
 
 ::important
 You should avoid code that produces side effects that need cleanup in root scope of `<script setup>`. An example of such side effects is setting up timers with `setInterval`. In client-side only code we may setup a timer and then tear it down in `onBeforeUnmount` or `onUnmounted`. However, because the unmount hooks will never be called during SSR, the timers will stay around forever. To avoid this, move your side-effect code into `onMounted` instead.
 ::
 
-### Step 7: Render and Generate HTML Output
+::tip{icon="i-lucide-video" to="https://youtu.be/dZSNW07sO-A" target="_blank"}
+Watch a video from Daniel Roe explaining Server Rendering and Global State.
+::
+
+### Step 7: Generate HTML Output
 
-After all components are initialized and data is fetched, Nuxt combines the components with settings from `unhead` to generate a complete HTML document. This HTML, along with the associated data, is sent back to the client to complete the SSR process.
+After all required data is fetched and the components are rendered, Nuxt combines the rendered components with settings from `unhead` to generate a complete HTML document. This HTML, along with the associated data, is then sent back to the client to complete the SSR process.
 
 ::callout{icon="i-lucide-lightbulb"}
 After rendering the Vue application to HTML, Nuxt calls the [`app:rendered`](/docs/api/advanced/hooks#app-hooks-runtime) hook.

package/2.guide/1.concepts/8.typescript.md

@@ -92,6 +92,7 @@ When you run `nuxt dev` or `nuxt build`, Nuxt will generate multiple `tsconfig.j
 - **`.nuxt/tsconfig.app.json`** - Configuration for your application code
 - **`.nuxt/tsconfig.node.json`** - Configuration for your `nuxt.config` and modules
 - **`.nuxt/tsconfig.server.json`** - Configuration for server-side code (when applicable)
+- **`.nuxt/tsconfig.shared.json`** - For code shared between app and server contexts (like types and non-environment specific utilities)
 - **`.nuxt/tsconfig.json`** - Legacy configuration for backward compatibility
 
 Each of these files is configured to reference the appropriate dependencies and provide optimal type-checking for their specific context.

package/2.guide/2.directory-structure/1.app/1.components.md

@@ -187,7 +187,7 @@ Hydrates the component after a specified interaction (e.g., click, mouseover).
 </template>
 ```
 
-If you do not pass an event or list of events, it defaults to hydrating on `pointerenter` and `focus`.
+If you do not pass an event or list of events, it defaults to hydrating on `pointerenter`, `click` and `focus`.
 
 ::note
 Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-interaction).

package/2.guide/2.directory-structure/2.env.md

@@ -55,6 +55,10 @@ Since `.env` files are not used in production, you must explicitly set environme
 
 * Many cloud service providers, such as Vercel, Netlify, and AWS, provide interfaces for setting environment variables via their dashboards, CLI tools or configuration files.
 
+::important
+`runtimeConfig` [won't pick up environment variables that don't start with `NUXT_` in production] (https://nuxt.com/docs/guide/going-further/runtime-config#environment-variables).
+::
+
 ## Production Preview
 
 For local production preview purpose, we recommend using [`nuxt preview`](/docs/api/commands/preview) since using this command, the `.env` file will be loaded into `process.env` for convenience. Note that this command requires dependencies to be installed in the package directory.

package/2.guide/2.directory-structure/2.nuxtignore.md

@@ -17,18 +17,18 @@ You can also configure [`ignoreOptions`](/docs/api/nuxt-config#ignoreoptions), [
 
 ```bash [.nuxtignore]
 # ignore layout foo.vue
-layouts/foo.vue
+app/layouts/foo.vue
 # ignore layout files whose name ends with -ignore.vue
-layouts/*-ignore.vue
+app/layouts/*-ignore.vue
 
 # ignore page bar.vue
-pages/bar.vue
+app/pages/bar.vue
 # ignore page inside ignore folder
-pages/ignore/*.vue
+app/pages/ignore/*.vue
 
 # ignore route middleware files under foo folder except foo/bar.js
-middleware/foo/*.js
-!middleware/foo/bar.js
+app/middleware/foo/*.js
+!app/middleware/foo/bar.js
 ```
 
 ::read-more{icon="i-simple-icons-git" title="the git documentation" to="https://git-scm.com/docs/gitignore" target="_blank"}

package/2.guide/2.directory-structure/3.tsconfig.md

@@ -5,7 +5,7 @@ head.title: "tsconfig.json"
 navigation.icon: i-lucide-file
 ---
 
-Nuxt [automatically generates](/docs/guide/concepts/typescript) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json`) with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults.
+Nuxt [automatically generates](/docs/guide/concepts/typescript) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json` and `.nuxt/tsconfig.shared.json`) with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults.
 
 You can benefit from this by creating a `tsconfig.json` in the root of your project with the following content:
 
@@ -19,6 +19,9 @@ You can benefit from this by creating a `tsconfig.json` in the root of your proj
     {
       "path": "./.nuxt/tsconfig.server.json"
     },
+    {
+      "path": "./.nuxt/tsconfig.shared.json"
+    },
     {
       "path": "./.nuxt/tsconfig.node.json"
     }

package/3.api/2.composables/use-async-data.md

@@ -159,7 +159,7 @@ const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { imm
 By default, Nuxt waits until a `refresh` is finished before it can be executed again.
 
 ::note
-If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await [`useAsyncData`](/docs/api/composables/use-async-data) on the client side, `data` will remain `null` within `<script setup>`.
+If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await [`useAsyncData`](/docs/api/composables/use-async-data) on the client side, `data` will remain `undefined` within `<script setup>`.
 ::
 
 ## Type
@@ -170,7 +170,7 @@ function useAsyncData<DataT, DataE>(
   options?: AsyncDataOptions<DataT>
 ): AsyncData<DataT, DataE>
 function useAsyncData<DataT, DataE>(
-  key: string | Ref<string> | ComputedRef<string>,
+  key: MaybeRefOrGetter<string>,
   handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
   options?: AsyncDataOptions<DataT>
 ): Promise<AsyncData<DataT, DataE>>
@@ -184,7 +184,7 @@ type AsyncDataOptions<DataT> = {
   default?: () => DataT | Ref<DataT> | null
   transform?: (input: DataT) => DataT | Promise<DataT>
   pick?: string[]
-  watch?: WatchSource[] | false
+  watch?: MultiWatchSources | false
   getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
 }
 
@@ -194,11 +194,11 @@ type AsyncDataRequestContext = {
 }
 
 type AsyncData<DataT, ErrorT> = {
-  data: Ref<DataT | null>
+  data: Ref<DataT | undefined>
   refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
   execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
   clear: () => void
-  error: Ref<ErrorT | null>
+  error: Ref<ErrorT | undefined>
   status: Ref<AsyncDataRequestStatus>
 };
 

package/3.api/2.composables/use-fetch.md

@@ -103,7 +103,7 @@ function useFetch<DataT, ErrorT>(
 ): Promise<AsyncData<DataT, ErrorT>>
 
 type UseFetchOptions<DataT> = {
-  key?: string
+  key?: MaybeRefOrGetter<string>
   method?: string
   query?: SearchParams
   params?: SearchParams
@@ -119,7 +119,8 @@ type UseFetchOptions<DataT> = {
   default?: () => DataT
   transform?: (input: DataT) => DataT | Promise<DataT>
   pick?: string[]
-  watch?: WatchSource[] | false
+  $fetch?: typeof globalThis.$fetch
+  watch?: MultiWatchSources | false
 }
 
 type AsyncDataRequestContext = {
@@ -128,11 +129,11 @@ type AsyncDataRequestContext = {
 }
 
 type AsyncData<DataT, ErrorT> = {
-  data: Ref<DataT | null>
+  data: Ref<DataT | undefined>
   refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
   execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
   clear: () => void
-  error: Ref<ErrorT | null>
+  error: Ref<ErrorT | undefined>
   status: Ref<AsyncDataRequestStatus>
 }
 
@@ -151,7 +152,7 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 
 | Option | Type | Default | Description |
 | ---| --- | --- | --- |
-| `key` | `string` | auto-gen | Unique key for de-duplication. If not provided, generated from URL and options. |
+| `key` | `MaybeRefOrGetter<string>` | auto-gen | Unique key for de-duplication. If not provided, generated from URL and options. |
 | `method` | `string` | `'GET'` | HTTP request method. |
 | `query` | `object` | - | Query/search params to append to the URL. Alias: `params`. Supports refs/computed. |
 | `params` | `object` | - | Alias for `query`. |
@@ -167,10 +168,10 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 | `transform` | `(input: DataT) => DataT \| Promise<DataT>` | - | Function to transform the result after resolving. |
 | `getCachedData`| `(key, nuxtApp, ctx) => DataT \| undefined` | - | Function to return cached data. See below for default. |
 | `pick` | `string[]` | - | Only pick specified keys from the result. |
-| `watch` | `WatchSource[] \| false` | - | Array of reactive sources to watch and auto-refresh. `false` disables watching. |
+| `watch` | `MultiWatchSources \| false` | - | Array of reactive sources to watch and auto-refresh. `false` disables watching. |
 | `deep` | `boolean` | `false` | Return data in a deep ref object. |
 | `dedupe` | `'cancel' \| 'defer'` | `'cancel'` | Avoid fetching same key more than once at a time. |
-| `$fetch` | `typeof $fetch` | - | Custom $fetch implementation. |
+| `$fetch` | `typeof globalThis.$fetch` | - | Custom $fetch implementation. |
 
 ::note
 All fetch options can be given a `computed` or `ref` value. These will be watched and new requests made automatically with any new values if they are updated.
@@ -189,10 +190,10 @@ This only caches data when `experimental.payloadExtraction` in `nuxt.config` is
 
 | Name | Type | Description |
 | --- | --- |--- |
-| `data` | `Ref<DataT \| null>` | The result of the asynchronous fetch. |
+| `data` | `Ref<DataT \| undefined>` | The result of the asynchronous fetch. |
 | `refresh` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Function to manually refresh the data. By default, Nuxt waits until a `refresh` is finished before it can be executed again. |
 | `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`. |
-| `error` | `Ref<ErrorT \| null>` | Error object if the data fetching failed. |
+| `error` | `Ref<ErrorT \| undefined>` | Error object if the data fetching failed. |
 | `status` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | Status of the data request. See below for possible values. |
 | `clear` | `() => void` | Resets `data` to `undefined` (or the value of `options.default()` if provided), `error` to `undefined`, set `status` to `idle`, and cancels any pending requests. |
 

package/3.api/3.utils/define-lazy-hydration-component.md

@@ -0,0 +1,261 @@
+---
+title: 'defineLazyHydrationComponent'
+description: 'Define a lazy hydration component with a specific strategy.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/components/plugins/lazy-hydration-macro-transform.ts
+    size: xs
+---
+
+`defineLazyHydrationComponent` is a compiler macro that helps you create a component with a specific lazy hydration strategy. Lazy hydration defers hydration until components become visible or until the browser has completed more critical tasks. This can significantly reduce the initial performance cost, especially for non-essential components.
+
+## Usage
+
+### Visibility Strategy
+
+Hydrates the component when it becomes visible in the viewport.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'visible',
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!-- 
+      Hydration will be triggered when
+      the element(s) is 100px away from entering the viewport.
+    -->
+    <LazyHydrationMyComponent :hydrate-on-visible="{ rootMargin: '100px' }" />
+  </div>
+</template>
+```
+
+The `hydrateOnVisible` prop is optional. You can pass an object to customize the behavior of the `IntersectionObserver` under the hood.
+
+::read-more{to="https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver" title="IntersectionObserver options"}
+Read more about the options for `hydrate-on-visible`.
+::
+
+::note
+Under the hood, this uses Vue's built-in [`hydrateOnVisible` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-visible).
+::
+
+### Idle Strategy
+
+Hydrates the component when the browser is idle. This is suitable if you need the component to load as soon as possible, but not block the critical rendering path.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'idle',
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!-- Hydration will be triggered when the browser is idle or after 2000ms. -->
+    <LazyHydrationMyComponent :hydrate-on-idle="2000" />
+  </div>
+</template>
+```
+
+The `hydrateOnIdle` prop is optional. You can pass a positive number to specify the maximum timeout.
+
+Idle strategy is for components that can be hydrated when the browser is idle.
+
+::note
+Under the hood, this uses Vue's built-in [`hydrateOnIdle` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-idle).
+::
+
+### Interaction Strategy
+
+Hydrates the component after a specified interaction (e.g., click, mouseover).
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'interaction',
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!--
+      Hydration will be triggered when
+      the element(s) is hovered over by the pointer.
+    -->
+    <LazyHydrationMyComponent hydrate-on-interaction="mouseover" />
+  </div>
+</template>
+```
+
+The `hydrateOnInteraction` prop is optional. If you do not pass an event or a list of events, it defaults to hydrating on `pointerenter`, `click`, and `focus`.
+
+::note
+Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-interaction).
+::
+
+### Media Query Strategy
+
+Hydrates the component when the window matches a media query.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'mediaQuery',
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!--
+      Hydration will be triggered when
+      the window width is greater than or equal to 768px.
+    -->
+    <LazyHydrationMyComponent hydrate-on-media-query="(min-width: 768px)" />
+  </div>
+</template>
+```
+
+::note
+Under the hood, this uses Vue's built-in [`hydrateOnMediaQuery` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-media-query).
+::
+
+### Time Strategy
+
+Hydrates the component after a specified delay (in milliseconds).
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'time', 
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!-- Hydration is triggered after 1000ms. -->
+    <LazyHydrationMyComponent :hydrate-after="1000" />
+  </div>
+</template>
+```
+
+Time strategy is for components that can wait a specific amount of time.
+
+### If Strategy
+
+Hydrates the component based on a boolean condition.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'if',
+  () => import('./components/MyComponent.vue')
+)
+
+const isReady = ref(false)
+
+function myFunction() {
+  // Trigger custom hydration strategy...
+  isReady.value = true
+}
+</script>
+
+<template>
+  <div>
+    <!-- Hydration is triggered when isReady becomes true. -->
+    <LazyHydrationMyComponent :hydrate-when="isReady" />
+  </div>
+</template>
+```
+
+If strategy is best for components that might not always need to be hydrated.
+
+### Never Hydrate
+
+Never hydrates the component.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'never',
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!-- This component will never be hydrated by Vue. -->
+    <LazyHydrationMyComponent />
+  </div>
+</template>
+```
+
+### Listening to Hydration Events
+
+All delayed hydration components emit a `@hydrated` event when they are hydrated.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'visible',
+  () => import('./components/MyComponent.vue')
+)
+
+function onHydrate() {
+  console.log("Component has been hydrated!")
+}
+</script>
+
+<template>
+  <div>
+    <LazyHydrationMyComponent
+      :hydrate-on-visible="{ rootMargin: '100px' }"
+      @hydrated="onHydrated"
+    />
+  </div>
+</template>
+```
+
+## Parameters
+
+::warning
+To ensure that the compiler correctly recognizes this macro, avoid using external variables. The following approach will prevent the macro from being properly recognized:
+
+```vue
+<script setup lang="ts">
+const strategy = 'visible'
+const source = () => import('./components/MyComponent.vue')
+const LazyHydrationMyComponent = defineLazyHydrationComponent(strategy, source)
+</script>
+```
+::
+
+### `strategy`
+
+- **Type**: `'visible' | 'idle' | 'interaction' | 'mediaQuery' | 'if' | 'time' | 'never'`
+- **Required**: `true`
+
+| Strategy      | Description                                                    |
+|---------------|----------------------------------------------------------------|
+| `visible`     | Hydrates when the component becomes visible in the viewport.   |
+| `idle`        | Hydrates when the browser is idle or after a delay.            |
+| `interaction` | Hydrates upon user interaction (e.g., click, hover).           |
+| `mediaQuery`  | Hydrates when the specified media query condition is met.      |
+| `if`          | Hydrates when a specified boolean condition is met.            |
+| `time`        | Hydrates after a specified time delay.                         |
+| `never`       | Prevents Vue from hydrating the component.                     |
+
+### `source`
+
+- **Type**: `() => Promise<Component>`
+- **Required**: `true`

package/7.migration/2.configuration.md

@@ -164,6 +164,9 @@ Nuxt can type-check your app using [`vue-tsc`](https://github.com/vuejs/language
        {
          "path": "./.nuxt/tsconfig.server.json"
        },
+       {
+         "path": "./.nuxt/tsconfig.shared.json"
+       },
        {
          "path": "./.nuxt/tsconfig.node.json"
        }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs",
-  "version": "4.0.0-alpha.3",
+  "version": "4.0.0-rc.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",