@nuxt/docs 4.0.0-alpha.4 → 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/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/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/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.4",
+  "version": "4.0.0-rc.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",