@nuxt/docs-nightly 4.1.0-29259944.c0e5065b → 4.1.0-29262602.c2b288d6

package/1.getting-started/07.routing.md

@@ -51,7 +51,7 @@ The [`<NuxtLink>`](/docs/api/components/nuxt-link) component links pages between
 
 When a [`<NuxtLink>`](/docs/api/components/nuxt-link) enters the viewport on the client side, Nuxt will automatically prefetch components and payload (generated pages) of the linked pages ahead of time, resulting in faster navigation.
 
-```vue [pages/app.vue]
+```vue [pages/index.vue]
 <template>
   <header>
     <nav>

package/2.guide/2.directory-structure/1.app/1.middleware.md

@@ -142,6 +142,44 @@ This is true even if you throw an error in your middleware on the server, and an
 Rendering an error page is an entirely separate page load, meaning any registered middleware will run again. You can use [`useError`](/docs/getting-started/error-handling#useerror) in middleware to check if an error is being handled.
 ::
 
+## Accessing Route in Middleware
+
+Always use the `to` and `from` parameters in your middleware to access the next and previous routes. Avoid using the [`useRoute()`](/docs/api/composables/use-route) composable in this context altogether.
+There is **no concept of a "current route" in middleware**, as middleware can abort a navigation or redirect to a different route. The `useRoute()` composable will always be inaccurate in this context.  
+
+::warning
+Sometimes, you might call a composable that uses `useRoute()` internally, which can trigger this warning even if there is no direct call in your middleware.
+This leads to the **same issue as above**, so you should structure your functions to accept the route as an argument instead when they are used in middleware.
+::
+
+::code-group
+```ts twoslash [middleware/access-route.ts]
+// @errors: 2304
+export default defineNuxtRouteMiddleware(to => {
+  // passing the route to the function to avoid calling `useRoute()` in middleware
+  doSomethingWithRoute(to)
+    
+  // ❌ this will output a warning and is NOT recommended
+  callsRouteInternally()
+})
+```
+
+```ts twoslash [utils/handle-route.ts]
+// providing the route as an argument so that it can be used in middleware correctly
+export function doSomethingWithRoute(route = useRoute()) {
+  // ...
+}
+```
+```ts twoslash [utils/dont-do-this.ts]
+// ❌ this function is not suitable for use in middleware
+export function callsRouteInternally() {
+    const route = useRoute()
+  // ...
+}
+```
+
+::
+
 ## Adding Middleware Dynamically
 
 It is possible to add global or named route middleware manually using the [`addRouteMiddleware()`](/docs/api/utils/add-route-middleware) helper function, such as from within a plugin.

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

@@ -12,6 +12,12 @@ links:
 Within the template of a Vue component, you can access the route using `$route`.
 ::
 
+The `useRoute` composable is a wrapper around the identically named composable from `vue-router`, providing access to the current route in a Nuxt application.
+
+The key difference is that in Nuxt, the composable ensures that the route is updated **only after** the page content has changed after navigation.
+In contrast, the `vue-router` version updates the route **immediately**, which can lead to synchronization issues between different parts of the template
+that rely on the route metadata, for example.
+
 ## Example
 
 In the following example, we call an API via [`useFetch`](/docs/api/composables/use-fetch) using a dynamic page parameter - `slug` - as part of the URL.
@@ -45,8 +51,37 @@ Apart from dynamic parameters and query parameters, `useRoute()` also provides t
 - `path`: encoded pathname section of the URL
 - `redirectedFrom`: route location that was attempted to access before ending up on the current route location
 
-::note
-Browsers don't send [URL fragments](https://url.spec.whatwg.org/#concept-url-fragment) (for example `#foo`) when making requests. So using `route.fullPath` in your template can trigger hydration issues because this will include the fragment on client but not the server.
+## Common Pitfalls
+
+### Route Synchronization Issues
+
+It’s important to use the `useRoute()` composable from Nuxt rather than the one from `vue-router` to avoid synchronization issues during page navigation.
+Importing `useRoute` directly from `vue-router` bypasses Nuxt's implementation.
+
+```ts twoslash
+// ❌ do not use `useRoute` from `vue-router`
+// @errors: 2300
+import { useRoute } from 'vue-router'
+// ✅ use Nuxt's `useRoute` composable
+import { useRoute } from '#app'
+```
+
+### Calling `useRoute` in Middleware
+
+Using `useRoute` in middleware is not recommended because it can lead to unexpected behavior.
+There is no concept of a "current route" in middleware.
+The `useRoute()` composable should only be used in the setup function of a Vue component or in a Nuxt plugin.
+
+::warning
+This applies to any composable that uses `useRoute()` internally too.
 ::
 
+::read-more{to="/docs/4.x/guide/directory-structure/app/middleware"}
+Read more about accessing the route in the middleware section.
+::
+
+### Hydration Issues with `route.fullPath`
+
+Browsers don't send [URL fragments](https://url.spec.whatwg.org/#concept-url-fragment) (for example `#foo`) when making requests. So using `route.fullPath` to affect the template can trigger hydration issues because this will include the fragment on client but not the server.
+
 :read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/type-aliases/RouteLocationNormalizedLoaded.html"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.1.0-29259944.c0e5065b",
+  "version": "4.1.0-29262602.c2b288d6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",