@nuxt/docs-nightly 4.0.0-29181071.c858a078 → 4.0.0-29181314.14f0a876

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

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

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

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-nightly",
-  "version": "4.0.0-29181071.c858a078",
+  "version": "4.0.0-29181314.14f0a876",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",