@nuxt/docs 4.0.0-alpha.2 → 4.0.0-alpha.3

package/1.getting-started/10.data-fetching.md

@@ -230,7 +230,7 @@ Read more about `useAsyncData`.
 
 - `data`: the result of the asynchronous function that is passed in.
 - `refresh`/`execute`: a function that can be used to refresh the data returned by the `handler` function.
-- `clear`: a function that can be used to set `data` to `undefined`, set `error` to `null`, set `status` to `idle`, and mark any currently pending requests as cancelled.
+- `clear`: a function that can be used to set `data` to `undefined` (or the value of `options.default()` if provided), set `error` to `undefined`, set `status` to `idle`, and mark any currently pending requests as cancelled.
 - `error`: an error object if the data fetching failed.
 - `status`: a string indicating the status of the data request (`"idle"`, `"pending"`, `"success"`, `"error"`).
 

package/1.getting-started/13.server.md

@@ -18,7 +18,7 @@ Using Nitro gives Nuxt superpowers:
 - Universal deployment on any provider (many zero-config)
 - Hybrid rendering
 
-Nitro is internally using [h3](https://github.com/unjs/h3), a minimal H(TTP) framework built for high performance and portability.
+Nitro is internally using [h3](https://github.com/h3js/h3), a minimal H(TTP) framework built for high performance and portability.
 
 :video-accordion{title="Watch a video from Alexander Lichter to understand the responsibilities of Nuxt and Nitro in your application" videoId="DkvgJa-X31k"}
 

package/1.getting-started/15.prerendering.md

@@ -135,7 +135,7 @@ export default defineNuxtConfig({
 });
 ```
 
-## Runtime prerender configuration
+## Runtime Prerender Configuration
 
 ### `prerenderRoutes`
 

package/1.getting-started/17.testing.md

@@ -444,7 +444,7 @@ If you prefer to use `@vue/test-utils` on its own for unit testing in Nuxt, and
 
 2. Create a `vitest.config.ts` with the following content:
 
-   ```ts twoslash
+   ```ts
    import { defineConfig } from 'vitest/config'
    import vue from '@vitejs/plugin-vue'
 

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

@@ -980,6 +980,93 @@ const importName = genSafeVariableName
 You can automate this step by running `npx codemod@latest nuxt/4/template-compilation-changes`
 ::
 
+### TypeScript Configuration Changes
+
+🚦 **Impact Level**: Minimal
+
+#### What Changed
+
+Nuxt now generates separate TypeScript configurations for different contexts to provide better type-checking experiences:
+
+1. **New TypeScript configuration files**: Nuxt now generates additional TypeScript configurations:
+   * `.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.json` - Legacy configuration for backward compatibility
+
+2. **Backward compatibility**: Existing projects that extend `.nuxt/tsconfig.json` will continue to work as before.
+
+3. **Opt-in project references**: New projects or those wanting better type checking can adopt TypeScript's project references feature.
+
+4. **Context-specific type checking**: Each context now has appropriate compiler options and includes/excludes for its specific environment.
+
+5. **New `typescript.nodeTsConfig` option**: You can now customize the TypeScript configuration for Node.js build-time code.
+
+#### Reasons for Change
+
+This change provides several benefits:
+
+1. **Better type safety**: Each context (app, server, build-time) gets appropriate type checking with context-specific globals and APIs.
+2. **Improved IDE experience**: Better IntelliSense and error reporting for different parts of your codebase.
+3. **Cleaner separation**: Server code won't incorrectly suggest client-side APIs and vice versa.
+4. **Performance**: TypeScript can more efficiently check code with properly scoped configurations.
+
+For example, auto-imports are not available in your `nuxt.config.ts` (but previously this was not flagged by TypeScript). And while IDEs recognized the separate context hinted by `tsconfig.json` in your `server/` directory, this was not reflected in type-checking (requiring a separate step).
+
+#### Migration Steps
+
+**No migration is required** - existing projects will continue to work as before.
+
+However, to take advantage of improved type checking, you can opt in to the new project references approach:
+
+1. **Update your root `tsconfig.json`** to use project references:
+
+   ```json
+   {
+     "files": [],
+     "references": [
+       { "path": "./.nuxt/tsconfig.app.json" },
+       { "path": "./.nuxt/tsconfig.server.json" },
+       { "path": "./.nuxt/tsconfig.node.json" }
+     ]
+   }
+   ```
+
+2. **Remove any manual server `tsconfig.json`** files (like `server/tsconfig.json`) that extended `.nuxt/tsconfig.server.json`.
+
+3. **Update your type checking scripts** to use the build flag for project references:
+
+   ```diff
+   - "typecheck": "nuxt prepare && vue-tsc --noEmit"
+   + "typecheck": "nuxt prepare && vue-tsc -b --noEmit"
+   ```
+
+4. **Configure Node.js TypeScript options** if needed:
+   <!-- @case-police-ignore tsConfig -->
+
+   ```ts
+   export default defineNuxtConfig({
+     typescript: {
+       // Customize app/server TypeScript config
+       tsConfig: {
+         compilerOptions: {
+           strict: true
+         }
+       },
+       // Customize build-time TypeScript config  
+       nodeTsConfig: {
+         compilerOptions: {
+           strict: true
+         }
+       }
+     }
+   })
+   ```
+
+5. **Update any CI/build scripts** that run TypeScript checking to ensure they use the new project references approach.
+
+The new configuration provides better type safety and IntelliSense for projects that opt in, while maintaining full backward compatibility for existing setups.
+
 ### Removal of Experimental Features
 
 🚦 **Impact Level**: Minimal

package/2.guide/1.concepts/4.server-engine.md

@@ -16,7 +16,7 @@ It is shipped with many features:
 
 ## API Layer
 
-Server [API endpoints](/docs/guide/directory-structure/server#api-routes) and [Middleware](/docs/guide/directory-structure/server#server-middleware) are added by Nitro that internally uses [h3](https://github.com/unjs/h3).
+Server [API endpoints](/docs/guide/directory-structure/server#api-routes) and [Middleware](/docs/guide/directory-structure/server#server-middleware) are added by Nitro that internally uses [h3](https://github.com/h3js/h3).
 
 Key features include:
 
@@ -24,7 +24,7 @@ Key features include:
 - Handlers can return promises, which will be awaited (`res.end()` and `next()` are also supported)
 - Helper functions for body parsing, cookie handling, redirects, headers and more
 
-Check out [the h3 docs](https://github.com/unjs/h3) for more information.
+Check out [the h3 docs](https://github.com/h3js/h3) for more information.
 
 ::read-more{to="/docs/guide/directory-structure/server#server-routes"}
 Learn more about the API layer in the `server/` directory.

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

@@ -55,7 +55,7 @@ This file contains the types of any modules you are using, as well as the key ty
 
 Some of the references in the file are to files that are only generated within your `buildDir` (`.nuxt`) and therefore for full typings, you will need to run `nuxt dev` or `nuxt build`.
 
-### `.nuxt/tsconfig.json`
+### `.nuxt/tsconfig.app.json`
 
 This file contains the recommended basic TypeScript configuration for your project, including resolved aliases injected by Nuxt or modules you are using, so you can get full type support and path auto-complete for aliases like `~/file` or `#build/file`.
 
@@ -74,10 +74,37 @@ Nitro also [auto-generates types](/docs/guide/concepts/server-engine#typed-api-r
 ::
 
 ::note
-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 `#imports` not being recognized.
-:br :br
-In case you need to extend options provided by `./.nuxt/tsconfig.json` further, you can use the [`alias` property](/docs/api/nuxt-config#alias) within your `nuxt.config`. Nuxt will pick them up and extend `./.nuxt/tsconfig.json` accordingly.
+For backward compatibility, Nuxt still generates `./.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/guide/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance.
+
+If you do extend from `./.nuxt/tsconfig.json`, keep in mind that all options will be overwritten by those 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, which can cause module resolutions such as `#imports` to not be recognized.
+
+In case you need to extend options further, you can use the [`alias` property](/docs/api/nuxt-config#alias) within your `nuxt.config`. Nuxt will pick them up and extend the generated TypeScript configurations accordingly.
+::
+
+## Project References
+
+Nuxt uses [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) to improve type-checking performance and provide better IDE support. This feature allows TypeScript to break up your codebase into smaller, more manageable pieces.
+
+### How Nuxt Uses Project References
+
+When you run `nuxt dev` or `nuxt build`, Nuxt will generate multiple `tsconfig.json` files for different parts of your application.
+
+- **`.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.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.
+
+### Benefits of Project References
+
+- **Faster builds**: TypeScript can skip rebuilding unchanged projects
+- **Better IDE performance**: Your IDE can provide faster IntelliSense and error checking
+- **Isolated compilation**: Errors in one part of your application don't prevent compilation of other parts
+- **Clearer dependency management**: Each project explicitly declares its dependencies
+
+::note
+The project reference setup is handled automatically by Nuxt. You typically don't need to modify these configurations manually, but understanding how they work can help you troubleshoot type-checking issues.
 ::
 
 ## Strict Checks

package/2.guide/2.directory-structure/1.server.md

@@ -101,7 +101,7 @@ export default defineNitroPlugin((nitroApp) => {
 
 ## Server Utilities
 
-Server routes are powered by [unjs/h3](https://github.com/unjs/h3) which comes with a handy set of helpers.
+Server routes are powered by [h3js/h3](https://github.com/h3js/h3) which comes with a handy set of helpers.
 
 :read-more{to="https://www.jsdocs.io/package/h3#package-index-functions" title="Available H3 Request Helpers" target="_blank"}
 
@@ -136,16 +136,6 @@ export const defineWrappedResponseHandler = <T extends EventHandlerRequest, D> (
 This feature is available from Nuxt >= 3.5
 ::
 
-To improve clarity within your IDE between the auto-imports from 'nitro' and 'vue', you can add a `~/server/tsconfig.json` with the following content:
-
-```json [server/tsconfig.json]
-{
-  "extends": "../.nuxt/tsconfig.server.json"
-}
-```
-
-Currently, these values won't be respected when type checking ([`nuxt typecheck`](/docs/api/commands/typecheck)), but you should get better type hints in your IDE.
-
 ## Recipes
 
 ### Route Parameters
@@ -448,7 +438,7 @@ export default fromNodeMiddleware((req, res) => {
 ```
 
 ::important
-Legacy support is possible using [unjs/h3](https://github.com/unjs/h3), but it is advised to avoid legacy handlers as much as you can.
+Legacy support is possible using [h3js/h3](https://github.com/h3js/h3), but it is advised to avoid legacy handlers as much as you can.
 ::
 
 ```ts [server/middleware/legacy.ts]

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

@@ -1,17 +1,28 @@
 ---
 title: "tsconfig.json"
-description: "Nuxt generates a .nuxt/tsconfig.json file with sensible defaults and your aliases."
+description: "Nuxt generates multiple TypeScript configuration files with sensible defaults and your aliases."
 head.title: "tsconfig.json"
 navigation.icon: i-lucide-file
 ---
 
-Nuxt [automatically generates](/docs/guide/concepts/typescript) a `.nuxt/tsconfig.json` file 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`) 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:
 
 ```json [tsconfig.json]
 {
-  "extends": "./.nuxt/tsconfig.json"
+  "files": [],
+  "references": [
+    {
+      "path": "./.nuxt/tsconfig.app.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.server.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.node.json"
+    }
+  ]
 }
 ```
 

package/2.guide/3.going-further/1.experimental-features.md

@@ -386,6 +386,7 @@ package-lock.json
 yarn.lock
 pnpm-lock.yaml
 tsconfig.json
+bun.lock
 bun.lockb
 ```
 

package/2.guide/3.going-further/11.nightly-release-channel.md

@@ -32,7 +32,7 @@ Update `nuxt` dependency inside `package.json`:
 }
 ```
 
-Remove lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb`) and reinstall dependencies.
+Remove lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock` or `bun.lockb`) and reinstall dependencies.
 
 ## Opting Out
 
@@ -47,7 +47,7 @@ Update `nuxt` dependency inside `package.json`:
 }
 ```
 
-Remove lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb`) and reinstall dependencies.
+Remove lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock` or `bun.lockb`) and reinstall dependencies.
 
 ## Using Nightly `@nuxt/cli`
 

package/2.guide/3.going-further/3.modules.md

@@ -230,8 +230,6 @@ Learn more about asset injection in [the recipes section](#recipes).
 Published modules cannot leverage auto-imports for assets within their runtime directory. Instead, they have to import them explicitly from `#imports` or alike.
 :br :br
 Indeed, auto-imports are not enabled for files within `node_modules` (the location where a published module will eventually live) for performance reasons.
-:br :br
-If you are using the module starter, auto-imports will not be enabled in your playground either.
 ::
 
 ### Tooling

package/3.api/1.components/4.nuxt-link.md

@@ -51,6 +51,10 @@ In this example, we pass the `id` param to link to the route `~/pages/posts/[id]
 Check out the Pages panel in Nuxt DevTools to see the route name and the params it might take.
 ::
 
+::tip
+When you pass an object into the `to` prop, `<NuxtLink>` will inherit Vue Router’s handling of query parameters. Keys and values will be automatically encoded, so you don’t need to call `encodeURI` or `encodeURIComponent` manually.
+::
+
 ### Handling Static File and Cross-App Links
 
 By default, `<NuxtLink>` uses Vue Router's client side navigation for relative route. When linking to static files in the `/public` directory or to another application hosted on the same domain, it might result in unexpected 404 errors because they are not part of the client routes. In such cases, you can use the `external` prop with `<NuxtLink>` to bypass Vue Router's internal routing mechanism.

package/3.api/2.composables/on-prehydrate.md

@@ -12,23 +12,33 @@ links:
 This composable is available in Nuxt v3.12+.
 ::
 
-`onPrehydrate` is a composable lifecycle hook that allows you to run a callback on the client immediately before
-Nuxt hydrates the page.
-
+`onPrehydrate` is a composable lifecycle hook that allows you to run a callback on the client immediately before Nuxt hydrates the page.
 ::note
 This is an advanced utility and should be used with care. For example, [`nuxt-time`](https://github.com/danielroe/nuxt-time/pull/251) and [`@nuxtjs/color-mode`](https://github.com/nuxt-modules/color-mode/blob/main/src/script.js) manipulate the DOM to avoid hydration mismatches.
 ::
 
 ## Usage
 
-`onPrehydrate` can be called directly in the setup function of a Vue component (for example, in `<script setup>`), or in a plugin.
-It will only have an effect when it is called on the server, and it will not be included in your client build.
+Call `onPrehydrate` in the setup function of a Vue component (e.g., in `<script setup>`) or in a plugin. It only has an effect when called on the server and will not be included in your client build.
+
+## Type
+
+```ts [Signature]
+export function onPrehydrate(callback: (el: HTMLElement) => void): void
+export function onPrehydrate(callback: string | ((el: HTMLElement) => void), key?: string): undefined | string
+```
 
 ## Parameters
 
-- `callback`: A function that will be stringified and inlined in the HTML. It should not have any external
-dependencies (such as auto-imports) or refer to variables defined outside the callback. The callback will run
-before Nuxt runtime initializes so it should not rely on the Nuxt or Vue context.
+| Parameter | Type | Required | Description |
+| ---- | --- | --- | --- |
+| `callback` | `((el: HTMLElement) => void) \| string` | Yes | A function (or stringified function) to run before Nuxt hydrates. It will be stringified and inlined in the HTML. Should not have external dependencies or reference variables outside the callback. Runs before Nuxt runtime initializes, so it should not rely on Nuxt or Vue context. |
+| `key` | `string` | No | (Advanced) A unique key to identify the prehydrate script, useful for advanced scenarios like multiple root nodes. |
+
+## Return Values
+
+- Returns `undefined` when called with only a callback function.
+- Returns a string (the prehydrate id) when called with a callback and a key, which can be used to set or access the `data-prehydrate-id` attribute for advanced use cases.
 
 ## Example
 
@@ -36,19 +46,18 @@ before Nuxt runtime initializes so it should not rely on the Nuxt or Vue context
 <script setup lang="ts">
 declare const window: Window
 // ---cut---
-// onPrehydrate is guaranteed to run before Nuxt hydrates
+// Run code before Nuxt hydrates
 onPrehydrate(() => {
   console.log(window)
 })
 
-// As long as it only has one root node, you can access the element
+// Access the root element
 onPrehydrate((el) => {
   console.log(el.outerHTML)
   // <div data-v-inspector="app.vue:15:3" data-prehydrate-id=":b3qlvSiBeH:"> Hi there </div>
 })
 
-// For _very_ advanced use cases (such as not having a single root node) you
-// can access/set `data-prehydrate-id` yourself
+// Advanced: access/set `data-prehydrate-id` yourself
 const prehydrateId = onPrehydrate((el) => {})
 </script>
 

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

@@ -154,7 +154,7 @@ const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { imm
   - `pending`: the request is in progress
   - `success`: the request has completed successfully
   - `error`: the request has failed
-- `clear`: a function which will set `data` to `undefined`, set `error` to `null`, set `status` to `'idle'`, and mark any currently pending requests as cancelled.
+- `clear`: a function that can be used to set `data` to `undefined` (or the value of `options.default()` if provided), set `error` to `undefined`, set `status` to `idle`, and mark any currently pending requests as cancelled.
 
 By default, Nuxt waits until a `refresh` is finished before it can be executed again.
 

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

@@ -8,7 +8,9 @@ links:
     size: xs
 ---
 
-Within your pages, components and plugins you can use `useCookie`, an SSR-friendly composable to read and write cookies.
+## Usage
+
+Within your pages, components, and plugins, you can use `useCookie` to read and write cookies in an SSR-friendly way.
 
 ```ts
 const cookie = useCookie(name, options)
@@ -19,144 +21,83 @@ const cookie = useCookie(name, options)
 ::
 
 ::tip
-`useCookie` ref will automatically serialize and deserialize cookie value to JSON.
+The returned ref will automatically serialize and deserialize cookie values to JSON.
 ::
 
-## Example
+## Type
 
-The example below creates a cookie called `counter`. If the cookie doesn't exist, it is initially set to a random value. Whenever we update the `counter` variable, the cookie will be updated accordingly.
+```ts [Signature]
+import type { Ref } from 'vue'
+import type { CookieParseOptions, CookieSerializeOptions } from 'cookie-es'
 
-```vue [app.vue]
-<script setup lang="ts">
-const counter = useCookie('counter')
+export interface CookieOptions<T = any> extends Omit<CookieSerializeOptions & CookieParseOptions, 'decode' | 'encode'> {
+  decode?(value: string): T
+  encode?(value: T): string
+  default?: () => T | Ref<T>
+  watch?: boolean | 'shallow'
+  readonly?: boolean
+}
 
-counter.value = counter.value || Math.round(Math.random() * 1000)
-</script>
+export interface CookieRef<T> extends Ref<T> {}
 
-<template>
-  <div>
-    <h1>Counter: {{ counter || '-' }}</h1>
-    <button @click="counter = null">reset</button>
-    <button @click="counter--">-</button>
-    <button @click="counter++">+</button>
-  </div>
-</template>
+export function useCookie<T = string | null | undefined>(
+  name: string,
+  options?: CookieOptions<T>
+): CookieRef<T>
 ```
 
-:link-example{to="/docs/examples/advanced/use-cookie"}
-
-::note
-Refresh `useCookie` values manually when a cookie has changed with [`refreshCookie`](/docs/api/utils/refresh-cookie).
-::
+## Parameters
 
-## Options
+`name`: The name of the cookie.
 
-Cookie composable accepts several options which let you modify the behavior of cookies.
+`options`: Options to control cookie behavior. The object can have the following properties:
 
 Most of the options will be directly passed to the [cookie](https://github.com/jshttp/cookie) package.
 
-### `maxAge` / `expires`
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `decode` | `(value: string) => T` | `decodeURIComponent` + [destr](https://github.com/unjs/destr). | Custom function to decode the cookie value.  Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode a previously encoded cookie value into a JavaScript string or other object. <br/> **Note:** If an error is thrown from this function, the original, non-decoded cookie value will be returned as the cookie's value. |
+| `encode` | `(value: T) => string` | `JSON.stringify` + `encodeURIComponent` | Custom function to encode the cookie value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to encode a value into a string suited for a cookie's value. |
+| `default` | `() => T \| Ref<T>` | `undefined` | Function returning the default value if the cookie does not exist.  The function can also return a `Ref`. |
+| `watch` | `boolean \| 'shallow'` | `true`  | Whether to watch for changes and update the cookie. `true` for deep watch, `'shallow'` for shallow watch, i.e. data changes for only top level properties, `false` to disable. <br/> **Note:** Refresh `useCookie` values manually when a cookie has changed with [`refreshCookie`](/docs/api/utils/refresh-cookie). |
+| `readonly` | `boolean` | `false` | If `true`, disables writing to the cookie. |
+| `maxAge` | `number` | `undefined` | Max age in seconds for the cookie, i.e. the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2). The given number will be converted to an integer by rounding down. By default, no maximum age is set. |
+| `expires` | `Date` | `undefined` | Expiration date for the cookie. By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application. <br/> **Note:** The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and `maxAge` is set, then `maxAge` takes precedence, but not all clients may obey this, so if both are set, they should point to the same date and time! <br/>If neither of `expires` and `maxAge` is set, the cookie will be session-only and removed when the user closes their browser. |
+| `httpOnly` | `boolean` | `false` | Sets the HttpOnly attribute. <br/> **Note:** Be careful when setting this to `true`, as compliant clients will not allow client-side JavaScript to see the cookie in `document.cookie`. |
+| `secure` | `boolean` | `false` | Sets the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5). <br/>**Note:** Be careful when setting this to `true`, as compliant clients will not send the cookie back to the server in the future if the browser does not have an HTTPS connection. This can lead to hydration errors. |
+| `partitioned` | `boolean` | `false` | Sets the [`Partitioned` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1). <br/>**Note:** This is an attribute that has not yet been fully standardized, and may change in the future. <br/>This also means many clients may ignore this attribute until they understand it.<br/>More information can be found in the [proposal](https://github.com/privacycg/CHIPS). |
+| `domain` | `string` | `undefined` | Sets the [`Domain` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.3). By default, no domain is set, and most clients will consider applying the cookie only to the current domain. |
+| `path` | `string` | `'/'` | Sets the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4). By default, the path is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4). |
+| `sameSite` | `boolean \| string` | `undefined` | Sets the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7). <br/>- `true` will set the `SameSite` attribute to `Strict` for strict same-site enforcement.<br/>- `false` will not set the `SameSite` attribute.<br/>- `'lax'` will set the `SameSite` attribute to `Lax` for lax same-site enforcement.<br/>- `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.<br/>- `'strict'` will set the `SameSite` attribute to `Strict` for strict same-site enforcement. |
 
-Use these options to set the expiration of the cookie.
+## Return Values
 
-`maxAge`: Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2).
-The given number will be converted to an integer by rounding down. By default, no maximum age is set.
+Returns a Vue `Ref<T>` representing the cookie value. Updating the ref will update the cookie (unless `readonly` is set). The ref is SSR-friendly and will work on both client and server.
 
-`expires`: Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.1).
-By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application.
+## Examples
 
-::note
-The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and `maxAge` is set, then `maxAge` takes precedence, but not all clients may obey this, so if both are set, they should point to the same date and time!
-::
-
-::note
-If neither of `expires` and `maxAge` is set, the cookie will be session-only and removed when the user closes their browser.
-::
-
-### `httpOnly`
-
-Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6). When truthy, the `HttpOnly` attribute is set; otherwise it is not. By default, the `HttpOnly` attribute is not set.
-
-::warning
-Be careful when setting this to `true`, as compliant clients will not allow client-side JavaScript to see the cookie in `document.cookie`.
-::
-
-### `secure`
-
-Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5). When truthy, the `Secure` attribute is set; otherwise it is not. By default, the `Secure` attribute is not set.
-
-::warning
-Be careful when setting this to `true`, as compliant clients will not send the cookie back to the server in the future if the browser does not have an HTTPS connection. This can lead to hydration errors.
-::
-
-### `partitioned`
-
-Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1) attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the `Partitioned` attribute is not set.
-
-::note
-This is an attribute that has not yet been fully standardized, and may change in the future.
-This also means many clients may ignore this attribute until they understand it.
-
-More information can be found in the [proposal](https://github.com/privacycg/CHIPS).
-::
+### Basic Usage
 
-### `domain`
-
-Specifies the value for the [`Domain` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.3). By default, no domain is set, and most clients will consider applying the cookie only to the current domain.
-
-### `path`
-
-Specifies the value for the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4). By default, the path is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4).
-
-### `sameSite`
-
-Specifies the `boolean` or `string` value for the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7).
-
-- `true` will set the `SameSite` attribute to `Strict` for strict same-site enforcement.
-- `false` will not set the `SameSite` attribute.
-- `'lax'` will set the `SameSite` attribute to `Lax` for lax same-site enforcement.
-- `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
-- `'strict'` will set the `SameSite` attribute to `Strict` for strict same-site enforcement.
-
-More information about the different enforcement levels can be found in [the specification](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7).
-
-### `encode`
-
-Specifies a function that will be used to encode a cookie's value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to encode a value into a string suited for a cookie's value.
-
-The default encoder is the `JSON.stringify` + `encodeURIComponent`.
-
-### `decode`
-
-Specifies a function that will be used to decode a cookie's value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode a previously encoded cookie value into a JavaScript string or other object.
-
-The default decoder is `decodeURIComponent` + [destr](https://github.com/unjs/destr).
-
-::note
-If an error is thrown from this function, the original, non-decoded cookie value will be returned as the cookie's value.
-::
-
-### `default`
-
-Specifies a function that returns the cookie's default value. The function can also return a `Ref`.
-
-### `readonly`
-
-Allows _accessing_ a cookie value without the ability to set it.
-
-### `watch`
+The example below creates a cookie called `counter`. If the cookie doesn't exist, it is initially set to a random value. Whenever we update the `counter` variable, the cookie will be updated accordingly.
 
-Specifies the `boolean` or `string` value for [watch](https://vuejs.org/api/reactivity-core.html#watch) cookie ref data.
+```vue [app.vue]
+<script setup lang="ts">
+const counter = useCookie('counter')
 
-- `true` - Will watch cookie ref data changes and its nested properties (default).
-- `shallow` - Will watch cookie ref data changes for only top level properties
-- `false` - Will not watch cookie ref data changes.
+counter.value = counter.value || Math.round(Math.random() * 1000)
+</script>
 
-::note
-Refresh `useCookie` values manually when a cookie has changed with [`refreshCookie`](/docs/api/utils/refresh-cookie).
-::
+<template>
+  <div>
+    <h1>Counter: {{ counter || '-' }}</h1>
+    <button @click="counter = null">reset</button>
+    <button @click="counter--">-</button>
+    <button @click="counter++">+</button>
+  </div>
+</template>
+```
 
-**Example 1:**
+### Readonly Cookies
 
 ```vue
 <script setup lang="ts">
@@ -179,7 +120,7 @@ if (user.value) {
 </template>
 ```
 
-**Example 2:**
+### Writable Cookies
 
 ```vue
 <script setup lang="ts">
@@ -193,7 +134,7 @@ const list = useCookie(
 
 function add() {
   list.value?.push(Math.round(Math.random() * 1000))
-  // list cookie not update with this change
+  // list cookie won't be updated with this change
 }
 
 function save() {
@@ -214,9 +155,9 @@ function save() {
 </template>
 ```
 
-## Cookies in API Routes
+### Cookies in API Routes
 
-You can use `getCookie` and `setCookie` from [`h3`](https://github.com/unjs/h3) package to set cookies in server API routes.
+You can use `getCookie` and `setCookie` from [`h3`](https://github.com/h3js/h3) package to set cookies in server API routes.
 
 ```ts [server/api/counter.ts]
 export default defineEventHandler(event => {

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

@@ -8,25 +8,48 @@ links:
     size: xs
 ---
 
-The composable returns the global Nuxt error that is being handled and it is available on both client and server.
+## Usage
+
+The `useError` composable returns the global Nuxt error that is being handled and is available on both client and server. It provides a reactive, SSR-friendly error state across your app.
 
 ```ts
 const error = useError()
 ```
 
-`useError` sets an error in the state and creates a reactive as well as SSR-friendly global Nuxt error across components.
+You can use this composable in your components, pages, or plugins to access or react to the current Nuxt error.
 
-Nuxt errors have the following properties:
+## Type
 
 ```ts
-interface {
-  //  HTTP response status code
+interface NuxtError<DataT = unknown> {
   statusCode: number
-  // HTTP response status message
   statusMessage: string
-  // Error message
   message: string
+  data?: DataT
+  error?: true
+}
+
+export const useError: () => Ref<NuxtError | undefined>
+```
+
+## Parameters
+
+This composable does not take any parameters.
+
+## Return Values
+
+Returns a `Ref` containing the current Nuxt error (or `undefined` if there is no error). The error object is reactive and will update automatically when the error state changes.
+
+## Example
+
+```ts
+<script setup lang="ts">
+const error = useError()
+
+if (error.value) {
+  console.error('Nuxt error:', error.value)
 }
+</script>
 ```
 
 :read-more{to="/docs/getting-started/error-handling"}

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

@@ -92,81 +92,8 @@ If you encounter the `data` variable destructured from a `useFetch` returns a st
 
 :video-accordion{title="Watch the video from Alexander Lichter to avoid using useFetch the wrong way" videoId="njsGVmcWviY"}
 
-:link-example{to="/docs/examples/advanced/use-custom-fetch-composable"}
-
 :read-more{to="/docs/getting-started/data-fetching"}
 
-:link-example{to="/docs/examples/features/data-fetching"}
-
-## Params
-
-- `URL`: The URL to fetch.
-- `Options` (extends [unjs/ofetch](https://github.com/unjs/ofetch) options & [AsyncDataOptions](/docs/api/composables/use-async-data#params)):
-  - `method`: Request method.
-  - `query`: Adds query search params to URL using [ufo](https://github.com/unjs/ufo)
-  - `params`: Alias for `query`
-  - `body`: Request body - automatically stringified (if an object is passed).
-  - `headers`: Request headers.
-  - `baseURL`: Base URL for the request.
-  - `timeout`: Milliseconds to automatically abort request
-  - `cache`: Handles cache control according to [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/fetch#cache)
-    - You can pass boolean to disable the cache or you can pass one of the following values: `default`, `no-store`, `reload`, `no-cache`, `force-cache`, and `only-if-cached`.
-
-::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.
-::
-
-- `Options` (from [`useAsyncData`](/docs/api/composables/use-async-data)):
-  - `key`: a unique key to ensure that data fetching can be properly de-duplicated across requests, if not provided, it will be automatically generated based on URL and fetch options
-  - `server`: whether to fetch the data on the server (defaults to `true`)
-  - `lazy`: whether to resolve the async function after loading the route, instead of blocking client-side navigation (defaults to `false`)
-  - `immediate`: when set to `false`, will prevent the request from firing immediately. (defaults to `true`)
-  - `default`: a factory function to set the default value of the `data`, before the async function resolves - useful with the `lazy: true` or `immediate: false` option
-  - `transform`: a function that can be used to alter `handler` function result after resolving
-  - `getCachedData`: Provide a function which returns cached data. A `null` or `undefined` return value will trigger a fetch. By default, this is:
-    ```ts
-    const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating 
-      ? nuxtApp.payload.data[key] 
-      : nuxtApp.static.data[key]
-    ```
-    Which only caches data when `experimental.payloadExtraction` of `nuxt.config` is enabled.
-  - `pick`: only pick specified keys in this array from the `handler` function result
-  - `watch`: watch an array of reactive sources and auto-refresh the fetch result when they change. Fetch options and URL are watched by default. You can completely ignore reactive sources by using `watch: false`. Together with `immediate: false`, this allows for a fully-manual `useFetch`. (You can [see an example here](/docs/getting-started/data-fetching#watch) of using `watch`.)
-  - `deep`: return data in a deep ref object. It is `false` by default to return data in a shallow ref object, which can improve performance if your data does not need to be deeply reactive.
-  - `dedupe`: avoid fetching same key more than once at a time (defaults to `cancel`). Possible options:
-    - `cancel` - cancels existing requests when a new one is made
-    - `defer` - does not make new requests at all if there is a pending request
-
-::note
-If you provide a function or ref as the `url` parameter, or if you provide functions as arguments to the `options` parameter, then the `useFetch` call will not match other `useFetch` calls elsewhere in your codebase, even if the options seem to be identical. If you wish to force a match, you may provide your own key in `options`.
-::
-
-::note
-If you use `useFetch` to call an (external) HTTPS URL with a self-signed certificate in development, you will need to set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment.
-::
-
-:video-accordion{title="Watch a video from Alexander Lichter about client-side caching with getCachedData" videoId="aQPR0xn-MMk"}
-
-## Return Values
-
-- `data`: the result of the asynchronous function that is passed in.
-- `refresh`/`execute`: a function that can be used to refresh the data returned by the `handler` function.
-- `error`: an error object if the data fetching failed.
-- `status`: a string indicating the status of the data request:
-  - `idle`: when the request has not started, such as:
-    - when `execute` has not yet been called and `{ immediate: false }` is set
-    - when rendering HTML on the server and `{ server: false }` is set
-  - `pending`: the request is in progress
-  - `success`: the request has completed successfully
-  - `error`: the request has failed
-- `clear`: a function which will set `data` to `undefined`, set `error` to `null`, set `status` to `'idle'`, and mark any currently pending requests as cancelled.
-
-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 `useFetch` on client-side, `data` will remain null within `<script setup>`.
-::
-
 ## Type
 
 ```ts [Signature]
@@ -215,3 +142,73 @@ interface AsyncDataExecuteOptions {
 
 type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 ```
+
+## Parameters
+
+- `URL` (`string | Request | Ref<string | Request> | () => string | Request`): The URL or request to fetch. Can be a string, a Request object, a Vue ref, or a function returning a string/Request. Supports reactivity for dynamic endpoints.
+
+- `options` (object): Configuration for the fetch request. Extends [unjs/ofetch](https://github.com/unjs/ofetch) options and [`AsyncDataOptions`](/docs/api/composables/use-async-data#params). All options can be a static value, a `ref`, or a computed value.
+
+| Option | Type | Default | Description |
+| ---| --- | --- | --- |
+| `key` | `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`. |
+| `body` | `RequestInit['body'] \| Record<string, any>` | - | Request body. Objects are automatically stringified. Supports refs/computed. |
+| `headers` | `Record<string, string> \| [key, value][] \| Headers` | - | Request headers. |
+| `baseURL` | `string` | - | Base URL for the request. |
+| `timeout` | `number` | - | Timeout in milliseconds to abort the request. |
+| `cache` | `boolean \| string` | - | Cache control. Boolean disables cache, or use Fetch API values: `default`, `no-store`, etc. |
+| `server` | `boolean` | `true` | Whether to fetch on the server. |
+| `lazy` | `boolean` | `false` | If true, resolves after route loads (does not block navigation). |
+| `immediate` | `boolean` | `true` | If false, prevents request from firing immediately. |
+| `default` | `() => DataT` | - | Factory for default value of `data` before async resolves. |
+| `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. |
+| `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. |
+
+::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.
+::
+
+**getCachedData default:**
+
+```ts
+const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating 
+ ? nuxtApp.payload.data[key] 
+ : nuxtApp.static.data[key]
+```
+This only caches data when `experimental.payloadExtraction` in `nuxt.config` is enabled.
+
+## Return Values
+
+| Name | Type | Description |
+| --- | --- |--- |
+| `data` | `Ref<DataT \| null>` | 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. |
+| `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. |
+
+### Status values
+
+- `idle`: Request has not started (e.g. `{ immediate: false }` or `{ server: false }` on server render)
+- `pending`: Request is in progress
+- `success`: Request completed successfully
+- `error`: Request failed
+
+::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 `useFetch` on client-side, `data` will remain null within `<script setup>`.
+::
+
+### Examples
+
+:link-example{to="/docs/examples/advanced/use-custom-fetch-composable"}
+
+:link-example{to="/docs/examples/features/data-fetching"}

package/3.api/2.composables/use-nuxt-app.md

@@ -95,7 +95,7 @@ Some useful methods:
 
 Nuxt exposes the following properties through `ssrContext`:
 - `url` (string) -  Current request url.
-- `event` ([unjs/h3](https://github.com/unjs/h3) request event) - Access the request & response of the current route.
+- `event` ([h3js/h3](https://github.com/h3js/h3) request event) - Access the request & response of the current route.
 - `payload` (object) - NuxtApp payload object.
 
 ### `payload`

package/3.api/3.utils/define-nuxt-plugin.md

@@ -0,0 +1,102 @@
+---
+title: "defineNuxtPlugin"
+description: defineNuxtPlugin() is a helper function for creating Nuxt plugins.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts
+    size: xs
+---
+
+`defineNuxtPlugin` is a helper function for creating Nuxt plugins with enhanced functionality and type safety. This utility normalizes different plugin formats into a consistent structure that works seamlessly within Nuxt's plugin system.
+
+```ts twoslash [plugins/hello.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  // Doing something with nuxtApp
+})
+```
+
+:read-more{to="/docs/guide/directory-structure/plugins#creating-plugins"}
+
+## Type
+
+```ts
+defineNuxtPlugin<T extends Record<string, unknown>>(plugin: Plugin<T> | ObjectPlugin<T>): Plugin<T> & ObjectPlugin<T>
+
+type Plugin<T> = (nuxt: [NuxtApp](/docs/guide/going-further/internals#the-nuxtapp-interface)) => Promise<void> | Promise<{ provide?: T }> | void | { provide?: T }
+
+interface ObjectPlugin<T> {
+  name?: string
+  enforce?: 'pre' | 'default' | 'post'
+  dependsOn?: string[]
+  order?: number
+  parallel?: boolean
+  setup?: Plugin<T>
+  hooks?: Partial<[RuntimeNuxtHooks](/docs/api/advanced/hooks#app-hooks-runtime)>
+  env?: {
+    islands?: boolean
+  }
+}
+```
+
+## Parameters
+
+**plugin**: A plugin can be defined in two ways:
+1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/guide/going-further/internals#the-nuxtapp-interface) instance and can return a promise with an potential object with a [`provide`](/docs/guide/directory-structure/plugins#providing-helpers) property if you want to provide a helper on [`NuxtApp`](/docs/guide/going-further/internals#the-nuxtapp-interface) instance.
+2. **Object Plugin**: An object that can include various properties to configure the plugin's behavior, such as `name`, `enforce`, `dependsOn`, `order`, `parallel`, `setup`, `hooks`, and `env`.
+
+| Property           | Type                                                                 | Required | Description                                                                                                     |
+| ------------------ | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `name` | `string` | `false` | Optional name for the plugin, useful for debugging and dependency management. |
+| `enforce` | `'pre'` \| `'default'` \| `'post'` | `false` | Controls when the plugin runs relative to other plugins. |
+| `dependsOn` | `string[]` | `false` | Array of plugin names this plugin depends on. Ensures proper execution order. |
+| `order` | `number` | `false` | This allows more granular control over plugin order and should only be used by advanced users. **It overrides the value of `enforce` and is used to sort plugins.** |
+| `parallel` | `boolean` | `false` | Whether to execute the plugin in parallel with other parallel plugins. |
+| `setup` | `Plugin<T>`{lang="ts"}  | `false` | The main plugin function, equivalent to a function plugin. |
+| `hooks` | `Partial<RuntimeNuxtHooks>`{lang="ts"}  | `false` | Nuxt app runtime hooks to register directly. |
+| `env` | `{ islands?: boolean }`{lang="ts"}  | `false` | Set this value to `false` if you don't want the plugin to run when rendering server-only or island components. |
+
+:video-accordion{title="Watch a video from Alexander Lichter about the Object Syntax for Nuxt plugins" videoId="2aXZyXB1QGQ"}
+
+## Examples
+
+### Basic Usage
+
+The example below demonstrates a simple plugin that adds global functionality:
+
+```ts twoslash [plugins/hello.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  // Add a global method
+  return {
+    provide: {
+      hello: (name: string) => `Hello ${name}!`
+    }
+  }
+})
+```
+
+### Object Syntax Plugin
+
+The example below shows the object syntax with advanced configuration:
+
+```ts twoslash [plugins/advanced.ts]
+export default defineNuxtPlugin({
+  name: 'my-plugin',
+  enforce: 'pre',
+  async setup (nuxtApp) {
+    // Plugin setup logic
+    const data = await $fetch('/api/config')
+    
+    return {
+      provide: {
+        config: data
+      }
+    }
+  },
+  hooks: {
+    'app:created'() {
+      console.log('App created!')
+    }
+  },
+})
+```

package/3.api/5.kit/13.logging.md

@@ -36,7 +36,7 @@ function useLogger (tag?: string, options?: Partial<ConsolaOptions>): ConsolaIns
 
 ### Parameters
 
-**`tag`**: A tag to suffix all log messages with.
+**`tag`**: A tag to suffix all log messages with, displayed on the right near the timestamp.
 
 **`options`**: Consola configuration options.
 

package/3.api/5.kit/6.context.md

@@ -128,7 +128,7 @@ The Nuxt instance as described in the `useNuxt` section.
 ::code-group
 
 ```ts twoslash [requireSiteConfig.ts]
-declare module '@nuxt/schema' {
+declare module 'nuxt/schema' {
   interface NuxtOptions {
     siteConfig: SiteConfig
   }

package/3.api/6.advanced/1.hooks.md

@@ -68,7 +68,7 @@ Hook                     | Arguments                  | Description
 `nitro:build:public-assets`     | `nitro`                    | Called after copying public assets. Allows modifying public assets before Nitro server is built.
 `prerender:routes`       | `ctx`                      | Allows extending the routes to be pre-rendered.
 `build:error`            | `error`                    | Called when an error occurs at build time.
-`prepare:types`          | `options`                  | Called before `@nuxt/cli` writes `.nuxt/tsconfig.json` and `.nuxt/nuxt.d.ts`, allowing addition of custom references and declarations in `nuxt.d.ts`, or directly modifying the options in `tsconfig.json`
+`prepare:types`          | `options`                  | Called before `@nuxt/cli` writes TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) and `.nuxt/nuxt.d.ts`, allowing addition of custom references and declarations in `nuxt.d.ts`, or directly modifying the options in generated configurations
 `listen`                 | `listenerServer, listener` | Called when the dev server is loading.
 `schema:extend`          | `schemas`                  | Allows extending default schemas.
 `schema:resolved`        | `schema`                   | Allows extending resolved schema.
@@ -95,11 +95,11 @@ See [Nitro](https://nitro.build/guide/plugins#available-hooks) for all available
 Hook                   | Arguments             | Description                          | Types
 -----------------------|-----------------------|--------------------------------------|------------------
 `dev:ssr-logs`         | `{ path, logs }`      | Server                               | Called at the end of a request cycle with an array of server-side logs.
-`render:response`      | `response, { event }` | Called before sending the response.  | [response](https://github.com/nuxt/nuxt/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L24), [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
-`render:html`          | `html, { event }`     | Called before constructing the HTML. | [html](https://github.com/nuxt/nuxt/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L15), [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
-`render:island`        | `islandResponse, { event, islandContext }` | Called before constructing the island HTML. | [islandResponse](https://github.com/nuxt/nuxt/blob/e50cabfed1984c341af0d0c056a325a8aec26980/packages/nuxt/src/core/runtime/nitro/renderer.ts#L28), [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), [islandContext](https://github.com/nuxt/nuxt/blob/e50cabfed1984c341af0d0c056a325a8aec26980/packages/nuxt/src/core/runtime/nitro/renderer.ts#L38)
+`render:response`      | `response, { event }` | Called before sending the response.  | [response](https://github.com/nuxt/nuxt/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L24), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
+`render:html`          | `html, { event }`     | Called before constructing the HTML. | [html](https://github.com/nuxt/nuxt/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L15), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
+`render:island`        | `islandResponse, { event, islandContext }` | Called before constructing the island HTML. | [islandResponse](https://github.com/nuxt/nuxt/blob/e50cabfed1984c341af0d0c056a325a8aec26980/packages/nuxt/src/core/runtime/nitro/renderer.ts#L28), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), [islandContext](https://github.com/nuxt/nuxt/blob/e50cabfed1984c341af0d0c056a325a8aec26980/packages/nuxt/src/core/runtime/nitro/renderer.ts#L38)
 `close`               | -                | Called when Nitro is closed. | -
-`error`               | `error, { event? }`          | Called when an error occurs. | [error](https://github.com/nitrojs/nitro/blob/d20ffcbd16fc4003b774445e1a01e698c2bb078a/src/types/runtime/nitro.ts#L48), [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
-`request`             | `event`        | Called when a request is received. | [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
-`beforeResponse`      | `event, { body }`        | Called before sending the response. | [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), unknown
-`afterResponse`       | `event, { body }`        | Called after sending the response. | [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), unknown
+`error`               | `error, { event? }`          | Called when an error occurs. | [error](https://github.com/nitrojs/nitro/blob/d20ffcbd16fc4003b774445e1a01e698c2bb078a/src/types/runtime/nitro.ts#L48), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
+`request`             | `event`        | Called when a request is received. | [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
+`beforeResponse`      | `event, { body }`        | Called before sending the response. | [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), unknown
+`afterResponse`       | `event, { body }`        | Called after sending the response. | [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), unknown

package/3.api/6.nuxt-config.md

@@ -31,9 +31,8 @@ your alias by prefixing it with `~`.
 ::
 
 ::callout
-**Note**: These aliases will be automatically added to the generated `.nuxt/tsconfig.json` so you can get full
-type support and path auto-complete. In case you need to extend options provided by `./.nuxt/tsconfig.json`
-further, make sure to add them here or within the `typescript.TSConfig` property in `nuxt.config`.
+<!-- @case-police-ignore tsConfig -->
+**Note**: These aliases will be automatically added to the generated TypeScript configurations (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) so you can get full type support and path auto-complete. In case you need to extend options provided by the generated configurations further, make sure to add them here or within the `typescript.tsConfig` property in `nuxt.config`.
 ::
 
 **Example**:
@@ -2058,9 +2057,11 @@ TypeScript comes with certain checks to give you more safety and analysis of you
 - **Type**: `boolean`
 - **Default:** `true`
 
-### `TSConfig`
+<!-- @case-police-ignore tsConfig -->
 
-You can extend generated `.nuxt/tsconfig.json` using this option.
+### `tsConfig`
+
+You can extend the generated TypeScript configurations (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) using this option.
 
 ### `typeCheck`
 

package/6.bridge/2.typescript.md

@@ -36,6 +36,8 @@ If you are using TypeScript, you can edit your `tsconfig.json` to benefit from a
 
 ::note
 As `.nuxt/tsconfig.json` is generated and not checked into version control, you'll need to generate that file before running your tests. Add `nuxi prepare` as a step before your tests, otherwise you'll see `TS5083: Cannot read file '~/.nuxt/tsconfig.json'`
+
+For modern Nuxt projects, we recommend using [TypeScript project references](/docs/guide/directory-structure/tsconfig) instead of directly extending `.nuxt/tsconfig.json`.
 ::
 
 ::note

package/7.migration/2.configuration.md

@@ -156,11 +156,22 @@ Nuxt can type-check your app using [`vue-tsc`](https://github.com/vuejs/language
 
    ```json
    {
-     "extends": "./.nuxt/tsconfig.json"
+     "files": [],
+     "references": [
+       {
+         "path": "./.nuxt/tsconfig.app.json"
+       },
+       {
+         "path": "./.nuxt/tsconfig.server.json"
+       },
+       {
+         "path": "./.nuxt/tsconfig.node.json"
+       }
+     ]
    }
    ```
 
-1. Run `npx nuxt prepare` to generate `.nuxt/tsconfig.json`.
+1. Run `npx nuxt prepare` to generate the tsconfig files.
 1. Install Volar following the instructions in the [docs](/docs/getting-started/introduction#prerequisites).
 
 ## Vue Changes

package/package.json

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