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

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

@@ -41,7 +41,7 @@ async function handleFormSubmit() {
 </script>
 
 <template>
-  <div v-if="data == null">
+  <div v-if="data == undefined">
     No data
   </div>
   <div v-else>

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

@@ -40,7 +40,7 @@ The nightly release channel `latest` tag is currently tracking the Nuxt v4 branc
 
 ## Testing Nuxt 4
 
-The release date of Nuxt 4 is **to be announced**. It is dependent on having enough time after Nitro's major release to be properly tested in the community. You can follow progress towards Nitro's release in [this PR](https://github.com/nitrojs/nitro/pull/2521).
+Nuxt 4 is **scheduled for release in Q2 2025**. It will include all the features currently available through `compatibilityVersion: 4`.
 
 Until the release, it is possible to test many of Nuxt 4's breaking changes from Nuxt version 3.12+.
 
@@ -188,6 +188,10 @@ server/
 nuxt.config.ts
 ```
 
+::note
+With this new structure, the `~` alias now points to the `app/` directory by default (your `srcDir`). This means `~/components` resolves to `app/components/`, `~/pages` to `app/pages/`, etc.
+::
+
 </details>
 
 👉 For more details, see the [PR implementing this change](https://github.com/nuxt/nuxt/pull/27029).
@@ -218,7 +222,7 @@ You can also force a v3 folder structure with the following configuration:
 export default defineNuxtConfig({
   // This reverts the new srcDir default from `app` back to your root directory
   srcDir: '.',
-  // This specifies the directory prefix for `app/router.options.ts` and `app/spa-loading-template.html`
+  // This specifies the directory prefix for `router.options.ts` and `spa-loading-template.html`
   dir: {
     app: 'app'
   }
@@ -430,7 +434,7 @@ export default defineNuxtConfig({
 
 #### What Changed
 
-When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `app/spa-loading-template.html`), within the Nuxt app root:
+When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `~/app/spa-loading-template.html` - note that this has also changed to `~/spa-loading-template.html` in Nuxt 4), within the Nuxt app root:
 
 ```html
 <div id="__nuxt">
@@ -1000,6 +1004,44 @@ These options have been set to their current values for some time and we do not
 
 * `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
 
+### Removal of Top-Level `generate` Configuration
+
+🚦 **Impact Level**: Minimal
+
+#### What Changed
+
+The top-level `generate` configuration option is no longer available in Nuxt 4. This includes all of its properties:
+
+* `generate.exclude` - for excluding routes from prerendering
+* `generate.routes` - for specifying routes to prerender
+
+#### Reasons for Change
+
+The top level `generate` configuration was a holdover from Nuxt 2. We've supported `nitro.prerender` for a while now, and it is the preferred way to configure prerendering in Nuxt 3+.
+
+#### Migration Steps
+
+Replace `generate` configuration with the corresponding `nitro.prerender` options:
+
+```diff
+export default defineNuxtConfig({
+- generate: {
+-   exclude: ['/admin', '/private'],
+-   routes: ['/sitemap.xml', '/robots.txt']
+- }
++ nitro: {
++   prerender: {
++     ignore: ['/admin', '/private'],
++     routes: ['/sitemap.xml', '/robots.txt']
++   }
++ }
+})
+```
+
+::read-more{to="https://nitro.build/config/#prerender"}
+Read more about Nitro's prerender configuration options.
+::
+
 ## Nuxt 2 vs. Nuxt 3+
 
 In the table below, there is a quick comparison between 3 versions of Nuxt:

package/2.guide/1.concepts/3.rendering.md

@@ -88,7 +88,7 @@ export default defineNuxtConfig({
 ```
 
 ::note
-If you do use `ssr: false`, you should also place an HTML file in `~/app/spa-loading-template.html` with some HTML you would like to use to render a loading screen that will be rendered until your app is hydrated.
+If you do use `ssr: false`, you should also place an HTML file in `~/spa-loading-template.html` with some HTML you would like to use to render a loading screen that will be rendered until your app is hydrated.
 :read-more{title="SPA Loading Template" to="/docs/api/configuration/nuxt-config#spaloadingtemplate"}
 ::
 

package/2.guide/2.directory-structure/1.app/.navigation.yml

@@ -0,0 +1,5 @@
+title: app
+titleTemplate: '%s · Nuxt Directory Structure'
+head.title: "app/"
+defaultOpen: true
+icon: i-lucide-folders

package/2.guide/2.directory-structure/{1.pages.md → 1.app/1.pages.md}

@@ -6,7 +6,7 @@ navigation.icon: i-lucide-folder
 ---
 
 ::note
-To reduce your application's bundle size, this directory is **optional**, meaning that [`vue-router`](https://router.vuejs.org) won't be included if you only use [`app.vue`](/docs/guide/directory-structure/app). To force the pages system, set `pages: true` in `nuxt.config` or have a [`app/router.options.ts`](/docs/guide/recipes/custom-routing#using-approuteroptions).
+To reduce your application's bundle size, this directory is **optional**, meaning that [`vue-router`](https://router.vuejs.org) won't be included if you only use [`app.vue`](/docs/guide/directory-structure/app). To force the pages system, set `pages: true` in `nuxt.config` or have a [`router.options.ts`](/docs/guide/recipes/custom-routing#using-approuteroptions).
 ::
 
 ## Usage

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

@@ -454,7 +454,7 @@ By setting `experimental.normalizeComponentNames`, these two values match, and V
 
 ## spaLoadingTemplateLocation
 
-When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `app/spa-loading-template.html`).
+When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `~/spa-loading-template.html`).
 
 It can be set to `within`, which will render it like this:
 

package/2.guide/4.recipes/1.custom-routing.md

@@ -13,7 +13,7 @@ Using [router options](/docs/guide/recipes/custom-routing#router-options), you c
 
 If it returns `null` or `undefined`, Nuxt will fall back to the default routes (useful to modify input array).
 
-```ts [app/router.options.ts]
+```ts [router.options.ts]
 import type { RouterConfig } from '@nuxt/schema'
 
 export default {
@@ -83,11 +83,11 @@ The [Nuxt kit](/docs/guide/going-further/kit) provides a few ways [to add routes
 
 On top of customizing options for [`vue-router`](https://router.vuejs.org/api/interfaces/routeroptions.html), Nuxt offers [additional options](/docs/api/nuxt-config#router) to customize the router.
 
-### Using `app/router.options`
+### Using `router.options`
 
 This is the recommended way to specify [router options](/docs/api/nuxt-config#router).
 
-```ts [app/router.options.ts]
+```ts [router.options.ts]
 import type { RouterConfig } from '@nuxt/schema'
 
 export default {
@@ -109,7 +109,7 @@ export default defineNuxtConfig({
       const resolver = createResolver(import.meta.url)
       // add a route
       files.push({
-        path: resolver.resolve('./runtime/app/router-options'),
+        path: resolver.resolve('./runtime/router-options'),
         optional: true
       })
     }
@@ -170,7 +170,7 @@ export default defineNuxtConfig({
 
 You can optionally override history mode using a function that accepts the base URL and returns the history mode. If it returns `null` or `undefined`, Nuxt will fallback to the default history.
 
-```ts [app/router.options.ts]
+```ts [router.options.ts]
 import type { RouterConfig } from '@nuxt/schema'
 import { createMemoryHistory } from 'vue-router'
 

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

@@ -168,8 +168,9 @@ const user = useCookie(
   }
 )
 
-if (user.value && user.value !== null) {
-  user.value.score++; // userInfo cookie not update with this change
+if (user.value) {
+  // the actual `userInfo` cookie will not be updated
+  user.value.score++
 }
 </script>
 
@@ -196,9 +197,9 @@ function add() {
 }
 
 function save() {
-  if (list.value && list.value !== null) {
+  if (list.value) {
+    // the actual `list` cookie will be updated
     list.value = [...list.value]
-    // list cookie update with this change
   }
 }
 </script>

package/3.api/3.utils/define-page-meta.md

@@ -136,7 +136,7 @@ interface PageMeta {
 
   - **Type**: `boolean | (to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean`
 
-    Tell Nuxt to scroll to the top before rendering the page or not. If you want to overwrite the default scroll behavior of Nuxt, you can do so in `~/app/router.options.ts` (see [custom routing](/docs/guide/recipes/custom-routing#using-approuteroptions)) for more info.
+    Tell Nuxt to scroll to the top before rendering the page or not. If you want to overwrite the default scroll behavior of Nuxt, you can do so in `~/router.options.ts` (see [custom routing](/docs/guide/recipes/custom-routing#using-approuteroptions)) for more info.
 
   **`[key: string]`**
 

package/3.api/5.kit/11.nitro.md

@@ -293,6 +293,53 @@ function addPrerenderRoutes (routes: string | string[]): void
 | ----------- | ------------------------------- | -------- | ---------------------------------------------- |
 | `routes`    | `string \| string[]`{lang="ts"} | `true`   | A route or an array of routes to prerender.    |
 
+## `addServerImports`
+
+Add imports to the server. It makes your imports available in Nitro without the need to import them manually.
+
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, createResolver, addServerImports } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options) {
+    const names = [
+      'useStoryblok',
+      'useStoryblokApi',
+      'useStoryblokBridge',
+      'renderRichText',
+      'RichTextSchema'
+    ]
+
+    names.forEach((name) =>
+      addServerImports({ name, as: name, from: '@storyblok/vue' })
+    )
+  }
+})
+```
+
+### Type
+
+```ts
+function addServerImports (dirs: Import | Import[]): void
+```
+
+### Parameters
+
+`imports`: An object or an array of objects with the following properties:
+
+| Property           | Type                         | Required | Description                                                                                                     |
+| ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `name`             | `string`                     | `true`   | Import name to be detected.                                                                                     |
+| `from`             | `string`                     | `true`   | Module specifier to import from.                                                                                |
+| `priority`         | `number`                     | `false`  | Priority of the import; if multiple imports have the same name, the one with the highest priority will be used. |
+| `disabled`         | `boolean`                    | `false`  | If this import is disabled.                                                                                     |
+| `meta`             | `Record<string, any>`        | `false`  | Metadata of the import.                                                                                         |
+| `type`             | `boolean`                    | `false`  | If this import is a pure type import.                                                                           |
+| `typeFrom`         | `string`                     | `false`  | Use this as the `from` value when generating type declarations.                                                 |
+| `as`               | `string`                     | `false`  | Import as this name.                                                                                            |
+
 ## `addServerImportsDir`
 
 Add a directory to be scanned for auto-imports by Nitro.

package/3.api/5.kit/4.autoimports.md

@@ -34,16 +34,16 @@ import { defineNuxtModule, addImports } from "@nuxt/kit";
 export default defineNuxtModule({
   setup(options, nuxt) {
     const names = [
-      "useStoryblok",
-      "useStoryblokApi",
-      "useStoryblokBridge",
-      "renderRichText",
-      "RichTextSchema"
-    ];
+      'useStoryblok',
+      'useStoryblokApi',
+      'useStoryblokBridge',
+      'renderRichText',
+      'RichTextSchema'
+    ]
 
     names.forEach((name) =>
-      addImports({ name, as: name, from: "@storyblok/vue" })
-    );
+      addImports({ name, as: name, from: '@storyblok/vue' })
+    )
   }
 })
 ```

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

@@ -1340,28 +1340,6 @@ You can set it to false to use the legacy 'Node' mode, which is the default for
 
 **See**: [TypeScript PR implementing `bundler` module resolution](https://github.com/microsoft/TypeScript/pull/51669)
 
-## generate
-
-### `exclude`
-
-This option is no longer used. Instead, use `nitro.prerender.ignore`.
-
-- **Type**: `array`
-
-### `routes`
-
-The routes to generate.
-
-If you are using the crawler, this will be only the starting point for route generation. This is often necessary when using dynamic routes.
-It is preferred to use `nitro.prerender.routes`.
-
-- **Type**: `array`
-
-**Example**:
-```js
-routes: ['/users/1', '/users/2', '/users/3']
-```
-
 ## hooks
 
 Hooks are listeners to Nuxt events that are typically used in modules, but are also available in `nuxt.config`.
@@ -1793,7 +1771,7 @@ Additional router options passed to `vue-router`. On top of the options for `vue
 
 ::callout
 **Note**: Only JSON serializable options should be passed by Nuxt config.
-For more control, you can use `app/router.options.ts` file.
+For more control, you can use an `router.options.ts` file.
 ::
 
 **See**: [Vue Router documentation](https://router.vuejs.org/api/interfaces/routeroptions.html).
@@ -1902,13 +1880,13 @@ Available options for both client and server: - `true`: Generates sourcemaps and
 
 Boolean or a path to an HTML file with the contents of which will be inserted into any HTML page rendered with `ssr: false`.
 
-- If it is unset, it will use `~/app/spa-loading-template.html` file in one of your layers, if it exists. - If it is false, no SPA loading indicator will be loaded. - If true, Nuxt will look for `~/app/spa-loading-template.html` file in one of your layers, or a
+- If it is unset, it will use `~/spa-loading-template.html` file in one of your layers, if it exists. - If it is false, no SPA loading indicator will be loaded. - If true, Nuxt will look for `~/spa-loading-template.html` file in one of your layers, or a
   default Nuxt image will be used.
 Some good sources for spinners are [SpinKit](https://github.com/tobiasahlin/SpinKit) or [SVG Spinners](https://icones.js.org/collection/svg-spinners).
 
 - **Default:** `null`
 
-**Example**: ~/app/spa-loading-template.html
+**Example**: ~/spa-loading-template.html
 ```html
 <!-- https://github.com/barelyhuman/snips/blob/dev/pages/css-loader.md -->
 <div class="loader"></div>
@@ -1959,33 +1937,31 @@ Define the source directory of your Nuxt application.
 If a relative path is specified, it will be relative to the `rootDir`.
 
 - **Type**: `string`
-- **Default:** `"/<srcDir>"`
+- **Default:** `"app"` (Nuxt 4), `"."` (Nuxt 3 with `compatibilityMode: 3`)
 
 **Example**:
 ```js
 export default {
-  srcDir: 'src/'
+  srcDir: 'app/'
 }
 ```
-This would work with the following folder structure:
+This expects the following folder structure:
 ```bash
 -| app/
----| node_modules/
----| nuxt.config.js
----| package.json
----| src/
-------| assets/
-------| components/
-------| layouts/
-------| middleware/
-------| pages/
-------| plugins/
-------| public/
-------| store/
-------| server/
-------| app.config.ts
-------| app.vue
-------| error.vue
+---| assets/
+---| components/
+---| layouts/
+---| middleware/
+---| pages/
+---| plugins/
+---| app.config.ts
+---| app.vue
+---| error.vue
+-| server/
+-| public/
+-| modules/
+-| nuxt.config.js
+-| package.json
 ```
 
 ## ssr

package/5.community/6.roadmap.md

@@ -30,8 +30,8 @@ Check [Discussions](https://github.com/nuxt/nuxt/discussions) and [RFCs](https:/
 
 Milestone    | Expected date | Notes                                                                  | Description
 -------------|---------------|------------------------------------------------------------------------|-----------------------
-SEO & PWA    | 2024          | [nuxt/nuxt#18395](https://github.com/nuxt/nuxt/discussions/18395)      | Migrating from [nuxt-community/pwa-module](https://github.com/nuxt-community/pwa-module) for built-in SEO utils and service worker support
-Assets       | 2024          | [nuxt/nuxt#22012](https://github.com/nuxt/nuxt/discussions/22012)      | Allow developers and modules to handle loading third-party assets.
+SEO & PWA    | 2025          | [nuxt/nuxt#18395](https://github.com/nuxt/nuxt/discussions/18395)      | Migrating from [nuxt-community/pwa-module](https://github.com/nuxt-community/pwa-module) for built-in SEO utils and service worker support
+Assets       | 2025          | [nuxt/nuxt#22012](https://github.com/nuxt/nuxt/discussions/22012)      | Allow developers and modules to handle loading third-party assets.
 Translations | -             | [nuxt/translations#4](https://github.com/nuxt/translations/discussions/4) ([request access](https://github.com/nuxt/nuxt/discussions/16054)) | A collaborative project for a stable translation process for Nuxt docs. Currently pending for ideas and documentation tooling support (content v2 with remote sources).
 
 ## Core Modules Roadmap
@@ -40,33 +40,38 @@ In addition to the Nuxt framework, there are modules that are vital for the ecos
 
 Module                              | Status              | Nuxt Support | Repository | Description
 ------------------------------------|---------------------|--------------|------------|-------------------
-[Scripts](https://scripts.nuxt.com) | Public Beta         | 3.x          | [nuxt/scripts](https://github.com/nuxt/scripts) | Easy 3rd party script management.
-Auth Utils                          | Planned             | 3.x          | `nuxt/auth-utils` to be announced | The temporary repository [atinux/nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils) is available while awaiting its official integration into Nuxt via RFC.
-A11y                                | Planned             | 3.x          | `nuxt/a11y` to be announced | Accessibility hinting and utilities [nuxt/nuxt#23255](https://github.com/nuxt/nuxt/issues/23255)
-Hints                               | Planned             | 3.x          | `nuxt/hints` to be announced | Guidance and suggestions for enhancing development practices.
+[Scripts](https://scripts.nuxt.com) | Public Beta         | 3.x, 4.x     | [nuxt/scripts](https://github.com/nuxt/scripts) | Easy 3rd party script management.
+Auth Utils                          | Planned             | 4.x, 5.x     | `nuxt/auth-utils` to be announced | The temporary repository [atinux/nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils) is available while awaiting its official integration into Nuxt via RFC.
+A11y                                | Planned             | 4.x, 5.x     | `nuxt/a11y` to be announced | Accessibility hinting and utilities [nuxt/nuxt#23255](https://github.com/nuxt/nuxt/issues/23255)
+Hints                               | Planned             | 4.x, 5.x     | `nuxt/hints` to be announced | Guidance and suggestions for enhancing development practices.
 
 ## Release Cycle
 
 Since January 2023, we've adopted a consistent release cycle for Nuxt, following [semver](https://semver.org). We aim for major framework releases every year, with an expectation of patch releases every week or so and minor releases every month or so. They should never contain breaking changes except within options clearly marked as `experimental`.
 
+We are planning a slight variation from this plan for Nuxt 4 and Nuxt 5. Nuxt 4 will be a stability-focused release containing all `compatibilityVersion: 4` features, and will be followed shortly by Nuxt 5 which will include an upgrade to Nitro v3 and additional changes.
+
+This approach separates breaking changes into manageable phases, allowing for better ecosystem testing and smoother migrations.
+
 ### Ongoing Support for Nuxt
 
-Going forward from v3, we commit to support each major version of Nuxt for a minimum of a year after the last release, and to providing an upgrade path for current users at that point.
+We commit to support each major version of Nuxt for a minimum of six months after the release of the next major version, and to providing an upgrade path for current users at that point.
 
 ### Current Packages
 
 The current active version of [Nuxt](https://nuxt.com) is **v3** which is available as `nuxt` on npm with the `latest` tag.
 
-Nuxt 2 is in maintenance mode and is available on npm with the `2x` tag. It will reach End of Life (EOL) on June 30, 2024.
+Nuxt 2 is in maintenance mode and is available on npm with the `2x` tag. It reached End of Life (EOL) on June 30, 2024.
 
 Each active version has its own nightly releases which are generated automatically. For more about enabling the Nuxt nightly release channel, see [the nightly release channel docs](/docs/guide/going-further/nightly-release-channel).
 
 Release                                 |                                                                                                  | Initial release | End Of Life  | Docs
 ----------------------------------------|---------------------------------------------------------------------------------------------------|-----------------|--------------|-------
-**4.x** (scheduled)                     |                                                                                           | approximately 1 month after release of nitro v3             |              |  
-**3.x** (stable)           | <a href="https://npmjs.com/package/nuxt"><img alt="Nuxt latest 3.x version" src="https://flat.badgen.net/npm/v/nuxt?label=" class="not-prose"></a>            | 2022-11-16      | TBA          | [nuxt.com](/docs)
-**2.x** (unsupported)      | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 2.x version" src="https://flat.badgen.net/npm/v/nuxt/2x?label=" class="not-prose"></a>         | 2018-09-21      | 2024-06-30   | [v2.nuxt.com](https://v2.nuxt.com/docs)
-**1.x** (unsupported)      | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 1.x version" src="https://flat.badgen.net/npm/v/nuxt/1x?label=" class="not-prose"></a>         | 2018-01-08      | 2019-09-21 | &nbsp;
+**5.x** (scheduled)        |                                                                                                                                                                               | Q4 2025 (estimated)   | TBA                          | &nbsp;
+**4.x** (scheduled)        |                                                                                                                                                                               | 2025-06-30 (planned)  | 6 months after 5.x release   | &nbsp;
+**3.x** (stable)           | <a href="https://npmjs.com/package/nuxt"><img alt="Nuxt latest 3.x version" src="https://flat.badgen.net/npm/v/nuxt?label=" class="not-prose"></a>                            | 2022-11-16            | 2025-12-31 (TBC)             | [nuxt.com](/docs)
+**2.x** (unsupported)      | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 2.x version" src="https://flat.badgen.net/npm/v/nuxt/2x?label=" class="not-prose"></a>         | 2018-09-21            | 2024-06-30                   | [v2.nuxt.com](https://v2.nuxt.com/docs)
+**1.x** (unsupported)      | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 1.x version" src="https://flat.badgen.net/npm/v/nuxt/1x?label=" class="not-prose"></a>         | 2018-01-08            | 2019-09-21                   | &nbsp;
 
 ### Support Status
 

package/7.migration/7.component-options.md

@@ -103,7 +103,7 @@ This feature is not yet supported in Nuxt 3.
 
 ## `scrollToTop`
 
-This feature is not yet supported in Nuxt 3. If you want to overwrite the default scroll behavior of `vue-router`, you can do so in `~/app/router.options.ts` (see [docs](/docs/guide/recipes/custom-routing#router-options)) for more info.
+This feature is not yet supported in Nuxt 3. If you want to overwrite the default scroll behavior of `vue-router`, you can do so in an `~/router.options.ts` (see [docs](/docs/guide/recipes/custom-routing#router-options)) for more info.
 Similar to `key`, specify it within the [`definePageMeta`](/docs/api/utils/define-page-meta) compiler macro.
 
 ```diff [pages/index.vue]

package/package.json

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