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

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.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/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/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

@@ -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.