@nuxt/docs-nightly 4.4.0-29533491.7793caf5 → 4.4.0-29533707.0a5a5c19

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

@@ -59,6 +59,7 @@ export default defineNuxtConfig({
 When you set your `future.compatibilityVersion` to `5`, defaults throughout your Nuxt configuration will change to opt in to Nuxt v5 behavior, including:
 
 - **Vite Environment API**: Automatically enables the new [Vite Environment API](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api) for improved build configuration
+- **`clearNuxtState` resets to defaults**: `clearNuxtState` will [reset state to its initial value](/docs/4.x/getting-started/upgrade#respect-defaults-when-clearing-usestate) instead of setting it to `undefined`
 - Other Nuxt 5 improvements and changes as they become available
 
 ::note
@@ -272,6 +273,7 @@ Nuxt now defaults to a new directory structure, with backwards compatibility (so
 - `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
 - if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
 - a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`
+- a new [`shared/`](/docs/4.x/directory-structure/shared) directory is available for code shared between the Vue app and the Nitro server, with auto-imports for `shared/utils/` and `shared/types/`
 
 <details>
 
@@ -298,6 +300,8 @@ modules/
 node_modules/
 public/
 shared/
+  types/
+  utils/
 server/
   api/
   middleware/
@@ -326,14 +330,14 @@ With this new structure, the `~` alias now points to the `app/` directory by def
 
 1. Create a new directory called `app/`.
 1. Move your `assets/`, `components/`, `composables/`, `app/layouts/`, `app/middleware/`, `app/pages/`, `app/plugins/` and `utils/` folders under it, as well as `app.vue`, `error.vue`, `app.config.ts`. If you have an `app/router-options.ts` or `app/spa-loading-template.html`, these paths remain the same.
-1. Make sure your `nuxt.config.ts`, `content/`, `layers/`, `modules/`, `public/` and `server/` folders remain outside the `app/` folder, in the root of your project.
+1. Make sure your `nuxt.config.ts`, `content/`, `layers/`, `modules/`, `public/`, `shared/` and `server/` folders remain outside the `app/` folder, in the root of your project.
 1. Remember to update any third-party configuration files to work with the new directory structure, such as your `tailwindcss` or `eslint` configuration (if required - `@nuxtjs/tailwindcss` should automatically configure `tailwindcss` correctly).
 
 ::tip
 You can automate this migration by running `npx codemod@latest nuxt/4/file-structure`
 ::
 
-However, migration is _not required_. If you wish to keep your current folder structure, Nuxt should auto-detect it. (If it does not, please raise an issue.) The one exception is that if you _already_ have a custom `srcDir`. In this case, you should be aware that your `modules/`, `public/` and `server/` folders will be resolved from your `rootDir` rather than from your custom `srcDir`. You can override this by configuring `dir.modules`, `dir.public` and `serverDir` if you need to.
+However, migration is _not required_. If you wish to keep your current folder structure, Nuxt should auto-detect it. (If it does not, please raise an issue.) The one exception is that if you _already_ have a custom `srcDir`. In this case, you should be aware that your `modules/`, `public/`, `shared/` and `server/` folders will be resolved from your `rootDir` rather than from your custom `srcDir`. You can override this by configuring `dir.modules`, `dir.public` and `serverDir` if you need to.
 
 You can also force a v3 folder structure with the following configuration:
 
@@ -846,6 +850,55 @@ If you provide a custom `default` value for `useAsyncData`, this will now be use
 
 Often users set an appropriately empty value, such as an empty array, to avoid the need to check for `null`/`undefined` when iterating over it. This should be respected when resetting/clearing the data.
 
+### Respect defaults when clearing `useState`
+
+🚦 **Impact Level**: Minimal
+
+#### What Changed
+
+With `compatibilityVersion: 5`, `clearNuxtState` will reset state to its initial value (provided by the `init` function of `useState`) instead of setting it to `undefined`. This aligns `clearNuxtState` behavior with `clearNuxtData`, which already resets to defaults.
+
+#### Reasons for Change
+
+When `clearNuxtState` sets state to `undefined`, composables that depend on that state can crash because they expect the state to always have a valid shape (e.g., accessing properties on `undefined`). Resetting to the `init` value ensures state always has a usable default.
+
+#### Migration Steps
+
+If you rely on `clearNuxtState` setting state to `undefined`, you can explicitly pass `{ reset: false }`:
+
+```diff
+- clearNuxtState('myKey')
++ clearNuxtState('myKey', { reset: false })
+```
+
+Alternatively, you can revert to the previous behavior with:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    defaults: {
+      useState: {
+        resetOnClear: false,
+      },
+    },
+  },
+})
+```
+
+You can also opt in to this behavior today without setting `compatibilityVersion: 5`:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    defaults: {
+      useState: {
+        resetOnClear: true,
+      },
+    },
+  },
+})
+```
+
 ### Alignment of `pending` value in `useAsyncData` and `useFetch`
 
 🚦 **Impact Level**: Medium

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

@@ -782,11 +782,16 @@ export default defineNuxtConfig({
       useAsyncData: {
         deep: true,
       },
+      useState: {
+        resetOnClear: true,
+      },
     },
   },
 })
 ```
 
+The `useState.resetOnClear` option controls whether [`clearNuxtState`](/docs/4.x/api/utils/clear-nuxt-state) resets state to its initial value (provided by the `init` function of [`useState`](/docs/4.x/api/composables/use-state)) instead of setting it to `undefined`. This defaults to `true` with `compatibilityVersion: 5`.
+
 ## purgeCachedData
 
 Whether to clean up Nuxt static and asyncData caches on route navigation.

package/4.api/1.components/12.nuxt-route-announcer.md

@@ -52,3 +52,7 @@ To achieve full customization, you can implement your own one based on [its sour
 ::callout
 You can hook into the underlying announcer instance using [the `useRouteAnnouncer` composable](/docs/4.x/api/composables/use-route-announcer), which allows you to set a custom announcement message.
 ::
+
+::callout
+For announcing in-page content changes (form validation, toast notifications, loading states, etc.), use the [`<NuxtAnnouncer>`](/docs/4.x/api/components/nuxt-announcer) component with the [`useAnnouncer`](/docs/4.x/api/composables/use-announcer) composable instead.
+::

package/4.api/1.components/14.nuxt-announcer.md

@@ -0,0 +1,81 @@
+---
+title: '<NuxtAnnouncer>'
+description: 'The <NuxtAnnouncer> component adds a hidden element to announce dynamic content changes to assistive technologies.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-announcer.ts
+    size: xs
+---
+
+::important
+This component is available in Nuxt v3.17+.
+::
+
+## Usage
+
+Add `<NuxtAnnouncer/>` in your [`app.vue`](/docs/4.x/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) to enable announcing dynamic content changes to screen readers. This is useful for form validation, toast notifications, loading states, and other in-page updates.
+
+```vue [app/app.vue]
+<template>
+  <NuxtAnnouncer />
+  <NuxtRouteAnnouncer />
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+Then use the [`useAnnouncer`](/docs/4.x/api/composables/use-announcer) composable anywhere in your app to announce messages:
+
+```vue [app/pages/contact.vue]
+<script setup lang="ts">
+const { polite, assertive } = useAnnouncer()
+
+async function submitForm () {
+  try {
+    await $fetch('/api/contact', { method: 'POST', body: formData })
+    polite('Message sent successfully')
+  } catch (error) {
+    assertive('Error: Failed to send message')
+  }
+}
+</script>
+```
+
+## Slots
+
+You can pass custom HTML or components through the announcer's default slot.
+
+```vue
+<template>
+  <NuxtAnnouncer>
+    <template #default="{ message }">
+      <p>{{ message }}</p>
+    </template>
+  </NuxtAnnouncer>
+</template>
+```
+
+## Props
+
+- `atomic`: Controls if screen readers announce only changes or the entire content. Set to true for full content readouts on updates, false for changes only. (default `true`)
+- `politeness`: Sets the default urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately). (default `polite`)
+
+## Differences from `<NuxtRouteAnnouncer>`
+
+| Aspect | `<NuxtRouteAnnouncer>` | `<NuxtAnnouncer>` |
+|--------|------------------------|-------------------|
+| **Purpose** | Announces route/page changes | Announces any dynamic content |
+| **Trigger** | Automatic on navigation | Manual via `polite()`/`assertive()` |
+| **Message source** | Page `<title>` | Developer-provided |
+| **atomic default** | `false` | `true` |
+
+::callout
+This component is optional. :br
+To achieve full customization, you can implement your own one based on [its source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-announcer.ts).
+::
+
+::callout
+You can hook into the underlying announcer instance using [the `useAnnouncer` composable](/docs/4.x/api/composables/use-announcer), which allows you to set custom announcement messages.
+::

package/4.api/2.composables/use-announcer.md

@@ -0,0 +1,128 @@
+---
+title: 'useAnnouncer'
+description: A composable for announcing messages to screen readers.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/announcer.ts
+    size: xs
+---
+
+::important
+This composable is available in Nuxt v3.17+.
+::
+
+## Description
+
+A composable for announcing dynamic content changes to screen readers. Unlike [`useRouteAnnouncer`](/docs/api/composables/use-route-announcer) which automatically announces route changes, `useAnnouncer` gives you manual control over what and when to announce.
+
+Use this for in-page updates like form validation, async operations, toast notifications, and live content changes.
+
+## Parameters
+
+- `politeness`: Sets the default urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately). (default `polite`)
+
+## Properties
+
+### `message`
+
+- **type**: `Ref<string>`
+- **description**: The current message to announce
+
+### `politeness`
+
+- **type**: `Ref<'polite' | 'assertive' | 'off'>`
+- **description**: Screen reader announcement urgency level
+
+## Methods
+
+### `set(message, politeness = "polite")`
+
+Sets the message to announce with its urgency level.
+
+### `polite(message)`
+
+Sets the message with `politeness = "polite"`. Use for non-urgent updates that can wait for the screen reader to finish its current task.
+
+### `assertive(message)`
+
+Sets the message with `politeness = "assertive"`. Use for urgent updates that should interrupt the screen reader immediately.
+
+## Example
+
+```vue [app/pages/contact.vue]
+<script setup lang="ts">
+const { polite, assertive } = useAnnouncer()
+
+async function submitForm () {
+  try {
+    await $fetch('/api/contact', { method: 'POST', body: formData })
+    polite('Message sent successfully')
+  } catch (error) {
+    assertive('Error: Failed to send message')
+  }
+}
+</script>
+```
+
+## Use Cases
+
+### Form Validation
+
+```vue [app/components/LoginForm.vue]
+<script setup lang="ts">
+const { assertive } = useAnnouncer()
+
+function validateForm () {
+  const errors = []
+  if (!email.value) { errors.push('Email is required') }
+  if (!password.value) { errors.push('Password is required') }
+
+  if (errors.length) {
+    assertive(`Form has ${errors.length} errors: ${errors.join(', ')}`)
+    return false
+  }
+  return true
+}
+</script>
+```
+
+### Loading States
+
+```vue [app/pages/dashboard.vue]
+<script setup lang="ts">
+const { polite } = useAnnouncer()
+
+const { data, status } = await useFetch('/api/data')
+
+watch(status, (newStatus) => {
+  if (newStatus === 'pending') {
+    polite('Loading data...')
+  } else if (newStatus === 'success') {
+    polite('Data loaded successfully')
+  }
+})
+</script>
+```
+
+### Search Results
+
+```vue [app/components/Search.vue]
+<script setup lang="ts">
+const { polite } = useAnnouncer()
+
+const results = ref([])
+
+watch(results, (newResults) => {
+  polite(`Found ${newResults.length} results`)
+})
+</script>
+```
+
+::callout
+You need to add the [`<NuxtAnnouncer>`](/docs/4.x/api/components/nuxt-announcer) component to your app for the announcements to be rendered in the DOM.
+::
+
+::callout
+For automatic announcements of route/page changes, use [`useRouteAnnouncer`](/docs/4.x/api/composables/use-route-announcer) with the [`<NuxtRouteAnnouncer>`](/docs/4.x/api/components/nuxt-route-announcer) component instead.
+::

package/4.api/2.composables/use-route-announcer.md

@@ -56,3 +56,7 @@ const { message, politeness, set, polite, assertive } = useRouteAnnouncer({
 })
 </script>
 ```
+
+::callout
+For announcing dynamic in-page content changes (form validation, toasts, loading states), use [`useAnnouncer`](/docs/4.x/api/composables/use-announcer) instead.
+::

package/4.api/3.utils/clear-nuxt-state.md

@@ -9,15 +9,17 @@ links:
 ---
 
 ::note
-This method is useful if you want to invalidate the state of `useState`.
+This method is useful if you want to invalidate the state of `useState`. You can also reset the state to its initial value by passing `{ reset: true }` as the second parameter.
 ::
 
 ## Type
 
 ```ts [Signature]
-export function clearNuxtState (keys?: string | string[] | ((key: string) => boolean)): void
+export function clearNuxtState (keys?: string | string[] | ((key: string) => boolean), opts?: ClearNuxtStateOptions): void
 ```
 
 ## Parameters
 
 - `keys`: One or an array of keys that are used in [`useState`](/docs/4.x/api/composables/use-state) to delete their cached state. If no keys are provided, **all state** will be invalidated.
+- `opts`: An options object to configure the clear behavior.
+  - `reset`: When set to `true`, resets the state to the initial value provided by the `init` function of [`useState`](/docs/4.x/api/composables/use-state) instead of setting it to `undefined`. When not specified, defaults to the value of `experimental.defaults.useState.resetOnClear` in your Nuxt config (which is `true` with `compatibilityVersion: 5`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.4.0-29533491.7793caf5",
+  "version": "4.4.0-29533707.0a5a5c19",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",