From 3f7cbec61c957abc9be75a9ccae7137e69a581ef Mon Sep 17 00:00:00 2001 From: Krutie Patel Date: Tue, 10 May 2022 04:40:48 +1000 Subject: [PATCH 1/6] docs: update useRouter page --- .../content/3.api/1.composables/use-router.md | 69 ++++++++++++++++++- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/docs/content/3.api/1.composables/use-router.md b/docs/content/3.api/1.composables/use-router.md index 938be24cba1..0c3511cc7dc 100644 --- a/docs/content/3.api/1.composables/use-router.md +++ b/docs/content/3.api/1.composables/use-router.md @@ -1,7 +1,72 @@ # `useRouter` -::ReadMore{link="/guide/features/routing"} +The `useRouter` composable returns the router instance and must be called in a `setup` function, plugin, or route middleware. + +Within the template of a Vue component, you can access the router using `$router`. `useRouter` provides collection of methods to help you manipulate Vue router dynamically. + +```html [~/pages/*.vue] + + + +```` + + Apart from `router.push()`, `useRouter` provides the following helper methods that we can roughly devide into four groups. + +## Basic manipulation + +- **addRoute:** Add a new route to the router instance. `parentName` can be provided to add new route as the child of an existing route. +- **removeRoute:** Remove an existing route by its name. +- **getRoutes:** Get a full list of all the route records. + +## Based on history API + +- **back:** Go back in history if possible, same as `router.go(-1)`. +- **forward:** Go forward in history if possible, same as `router.go(1)`. +- **go:** Move forward or backward through the history without the hierarchical restrictions enforced in `router.back()` and `router.forward()`. +- **push:** Programmatically navigate to a new URL by pushing an entry in the history stack. +- **replace:** Programmatically navigate to a new URL by replacing the current entry in the routes history stack. + +> TIP: `router.addRoute()` adds route details into an array of routes, while `router.push()` on the other hand, triggers a new navigation immediately. + +```js [js] + const router = useRouter(); + router.back(); + router.forward(); + router.go(); + router.push({ path: "/home" }); + router.replace({ hash: "#bio" }); +```` + +::ReadMore{link="https://developer.mozilla.org/en-US/docs/Web/API/History"} +:: + +## The ones with the guards + +- **afterEach:** Add a navigation guard that is executed after every navigation. +- **beforeEach:** Add a navigation guard that executes before any navigation. +- **beforeResolve:** Add a navigation guard that executes before navigation is about to be resolved. + +```js [js] +const router = useRouter(); +router.afterEach((to, from, failure) => { + if (isNavigationFailure(failure)) { + console.log("failed navigation", failure); + } +}); +``` + +## Checks and promise + +- **hasRoute:** Checks if a route with a given name exists +- **isReady:** Returns a Promise that resolves when the router has completed the initial navigation +- **onError:** Adds an error handler that is called every time a non caught error happens during navigation. +- **resolve:** Returns the normalized version of a route location. Also includes an href property that includes any existing base. + +::ReadMore{link="https://router.vuejs.org/api/#router-methods"} :: -::NeedContribution +::ReadMore{link="/guide/features/routing"} :: From d9f9ecfe12522fb7e31f53ae805c3eaaffbe7504 Mon Sep 17 00:00:00 2001 From: Krutie Patel Date: Tue, 10 May 2022 13:04:01 +1000 Subject: [PATCH 2/6] docs: fix typo --- docs/content/3.api/1.composables/use-router.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-router.md b/docs/content/3.api/1.composables/use-router.md index 0c3511cc7dc..54e775da07e 100644 --- a/docs/content/3.api/1.composables/use-router.md +++ b/docs/content/3.api/1.composables/use-router.md @@ -13,7 +13,7 @@ Within the template of a Vue component, you can access the router using `$router ```` - Apart from `router.push()`, `useRouter` provides the following helper methods that we can roughly devide into four groups. + Apart from `router.push()`, `useRouter` provides the following helper methods that we can roughly divide into four groups. ## Basic manipulation From 4ea67d1f8fad8c95535aa9cfb7c8e91d1bb1ba0d Mon Sep 17 00:00:00 2001 From: Krutie Patel Date: Tue, 10 May 2022 13:08:18 +1000 Subject: [PATCH 3/6] docs: update intro --- docs/content/3.api/1.composables/use-router.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/content/3.api/1.composables/use-router.md b/docs/content/3.api/1.composables/use-router.md index 54e775da07e..59d739b207d 100644 --- a/docs/content/3.api/1.composables/use-router.md +++ b/docs/content/3.api/1.composables/use-router.md @@ -2,7 +2,9 @@ The `useRouter` composable returns the router instance and must be called in a `setup` function, plugin, or route middleware. -Within the template of a Vue component, you can access the router using `$router`. `useRouter` provides collection of methods to help you manipulate Vue router dynamically. +Within the template of a Vue component, you can access the router using `$router` and you can access router in setup() function using `useRouter()` composable. + +`useRouter` provides collection of methods to help you manipulate Vue router dynamically. ```html [~/pages/*.vue] From 9bc27e977815d6f9f05d564e6a3dbebd1bdd4ee4 Mon Sep 17 00:00:00 2001 From: Krutie Patel Date: Thu, 12 May 2022 17:56:53 +1000 Subject: [PATCH 4/6] docs: add universal router section --- .../content/3.api/1.composables/use-router.md | 51 ++++++++++++------- 1 file changed, 34 insertions(+), 17 deletions(-) diff --git a/docs/content/3.api/1.composables/use-router.md b/docs/content/3.api/1.composables/use-router.md index 59d739b207d..b417fc685a8 100644 --- a/docs/content/3.api/1.composables/use-router.md +++ b/docs/content/3.api/1.composables/use-router.md @@ -9,19 +9,20 @@ Within the template of a Vue component, you can access the router using `$router ```html [~/pages/*.vue] ```` - Apart from `router.push()`, `useRouter` provides the following helper methods that we can roughly divide into four groups. + `useRouter` provides the following helper methods that we can roughly divide into four groups. ## Basic manipulation - **addRoute:** Add a new route to the router instance. `parentName` can be provided to add new route as the child of an existing route. - **removeRoute:** Remove an existing route by its name. - **getRoutes:** Get a full list of all the route records. +- **hasRoute:** Checks if a route with a given name exists ## Based on history API @@ -31,15 +32,15 @@ Within the template of a Vue component, you can access the router using `$router - **push:** Programmatically navigate to a new URL by pushing an entry in the history stack. - **replace:** Programmatically navigate to a new URL by replacing the current entry in the routes history stack. -> TIP: `router.addRoute()` adds route details into an array of routes, while `router.push()` on the other hand, triggers a new navigation immediately. +> TIP: `router.addRoute()` adds route details into an array of routes and it is useful while building Nuxt plugins while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in Nuxt Page components, Vue components and composable. ```js [js] - const router = useRouter(); - router.back(); - router.forward(); - router.go(); - router.push({ path: "/home" }); - router.replace({ hash: "#bio" }); +const router = useRouter(); +router.back(); +router.forward(); +router.go(); +router.push({ path: "/home" }); +router.replace({ hash: "#bio" }); ```` ::ReadMore{link="https://developer.mozilla.org/en-US/docs/Web/API/History"} @@ -51,24 +52,40 @@ Within the template of a Vue component, you can access the router using `$router - **beforeEach:** Add a navigation guard that executes before any navigation. - **beforeResolve:** Add a navigation guard that executes before navigation is about to be resolved. +> When we need to use navigation guards in Nuxt however, it is recommended to use Route Middleware to achieve the same results as `beforeEach` helper method. + ```js [js] const router = useRouter(); router.afterEach((to, from, failure) => { - if (isNavigationFailure(failure)) { - console.log("failed navigation", failure); - } + if (isNavigationFailure(failure)) { + console.log("failed navigation", failure); + } }); ``` -## Checks and promise +## Promise and error handling -- **hasRoute:** Checks if a route with a given name exists -- **isReady:** Returns a Promise that resolves when the router has completed the initial navigation +- **isReady:** Returns a Promise that resolves when the router has completed the initial navigation. - **onError:** Adds an error handler that is called every time a non caught error happens during navigation. -- **resolve:** Returns the normalized version of a route location. Also includes an href property that includes any existing base. +- **resolve:** Returns the normalized version of a route location. Also includes an `href` property that includes any existing base. ::ReadMore{link="https://router.vuejs.org/api/#router-methods"} :: +## Universal router instance + +Nuxt also provides a universal router instance that is different from `useRouter()`. This router instance is independent of Vue router, and provides similar helper methods as `useRouter` composable. + +You can use `useNuxtApp()` composable to access this router instance. + +```js [js] +const NuxtApp = useNuxtApp(); +const router = NuxtApp.$router; +// router.push() +// router.onError() +// router.getRoutes() +// ...and so on +``` + ::ReadMore{link="/guide/features/routing"} :: From cc8763e0a439885f59705aa28b588384a30b3d50 Mon Sep 17 00:00:00 2001 From: Krutie Patel Date: Sat, 14 May 2022 16:39:31 +1000 Subject: [PATCH 5/6] docs: add Vue router link to and update Navigation guards section as per review comment --- .../content/3.api/1.composables/use-router.md | 21 +++++++------------ 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/docs/content/3.api/1.composables/use-router.md b/docs/content/3.api/1.composables/use-router.md index b417fc685a8..66e8ebe4705 100644 --- a/docs/content/3.api/1.composables/use-router.md +++ b/docs/content/3.api/1.composables/use-router.md @@ -17,6 +17,9 @@ Within the template of a Vue component, you can access the router using `$router `useRouter` provides the following helper methods that we can roughly divide into four groups. +::ReadMore{link="https://router.vuejs.org/api/#currentroute"} +:: + ## Basic manipulation - **addRoute:** Add a new route to the router instance. `parentName` can be provided to add new route as the child of an existing route. @@ -46,22 +49,14 @@ router.replace({ hash: "#bio" }); ::ReadMore{link="https://developer.mozilla.org/en-US/docs/Web/API/History"} :: -## The ones with the guards +## Navigation guards -- **afterEach:** Add a navigation guard that is executed after every navigation. -- **beforeEach:** Add a navigation guard that executes before any navigation. -- **beforeResolve:** Add a navigation guard that executes before navigation is about to be resolved. +`useRouter` composable provides `afterEach`, `beforeEach` and `beforeResolve` helper methods that acts as nagivation guards. -> When we need to use navigation guards in Nuxt however, it is recommended to use Route Middleware to achieve the same results as `beforeEach` helper method. +However, Nuxt has a concept of **Route middleware** that simplifies the implementation of navigation guards and provides much better developer experience. -```js [js] -const router = useRouter(); -router.afterEach((to, from, failure) => { - if (isNavigationFailure(failure)) { - console.log("failed navigation", failure); - } -}); -``` +::ReadMore{link="/guide/directory-structure/middleware"} +:: ## Promise and error handling From 1b52dfc7d5e8018f618971ed7b2d070d60d53489 Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Thu, 9 Jun 2022 15:07:12 +0100 Subject: [PATCH 6/6] docs: update universal/vue-router distinction --- .../content/3.api/1.composables/use-router.md | 36 ++++--------------- 1 file changed, 6 insertions(+), 30 deletions(-) diff --git a/docs/content/3.api/1.composables/use-router.md b/docs/content/3.api/1.composables/use-router.md index 66e8ebe4705..899e6f3c3f8 100644 --- a/docs/content/3.api/1.composables/use-router.md +++ b/docs/content/3.api/1.composables/use-router.md @@ -1,21 +1,8 @@ # `useRouter` -The `useRouter` composable returns the router instance and must be called in a `setup` function, plugin, or route middleware. +The `useRouter` composable returns the router instance and must be called in a `setup` function, plugin, or route middleware. (Within the template of a Vue component, you can access the router using `$router` instead.) -Within the template of a Vue component, you can access the router using `$router` and you can access router in setup() function using `useRouter()` composable. - -`useRouter` provides collection of methods to help you manipulate Vue router dynamically. - -```html [~/pages/*.vue] - - - -```` - - `useRouter` provides the following helper methods that we can roughly divide into four groups. +If you have a `pages/` folder, `useRouter` is identical in behavior to the one provided by `vue-router`. Feel free to read the router documentation for more information on what each method does. ::ReadMore{link="https://router.vuejs.org/api/#currentroute"} :: @@ -32,8 +19,8 @@ Within the template of a Vue component, you can access the router using `$router - **back:** Go back in history if possible, same as `router.go(-1)`. - **forward:** Go forward in history if possible, same as `router.go(1)`. - **go:** Move forward or backward through the history without the hierarchical restrictions enforced in `router.back()` and `router.forward()`. -- **push:** Programmatically navigate to a new URL by pushing an entry in the history stack. -- **replace:** Programmatically navigate to a new URL by replacing the current entry in the routes history stack. +- **push:** Programmatically navigate to a new URL by pushing an entry in the history stack. **It is recommended to use [`navigateTo`](http://v3.nuxtjs.org/api/utils/navigate-to#navigateto) instead.** +- **replace:** Programmatically navigate to a new URL by replacing the current entry in the routes history stack. **It is recommended to use [`navigateTo`](http://v3.nuxtjs.org/api/utils/navigate-to#navigateto) instead.** > TIP: `router.addRoute()` adds route details into an array of routes and it is useful while building Nuxt plugins while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in Nuxt Page components, Vue components and composable. @@ -53,7 +40,7 @@ router.replace({ hash: "#bio" }); `useRouter` composable provides `afterEach`, `beforeEach` and `beforeResolve` helper methods that acts as nagivation guards. -However, Nuxt has a concept of **Route middleware** that simplifies the implementation of navigation guards and provides much better developer experience. +However, Nuxt has a concept of **route middleware** that simplifies the implementation of navigation guards and provides a better developer experience. ::ReadMore{link="/guide/directory-structure/middleware"} :: @@ -69,18 +56,7 @@ However, Nuxt has a concept of **Route middleware** that simplifies the implemen ## Universal router instance -Nuxt also provides a universal router instance that is different from `useRouter()`. This router instance is independent of Vue router, and provides similar helper methods as `useRouter` composable. - -You can use `useNuxtApp()` composable to access this router instance. - -```js [js] -const NuxtApp = useNuxtApp(); -const router = NuxtApp.$router; -// router.push() -// router.onError() -// router.getRoutes() -// ...and so on -``` +If you do not have a `pages/` folder, then `useRouter` will return a universal router instance with similar helper methods, but be aware that not all features may be supported or behave in exactly the same way as with `vue-router`. ::ReadMore{link="/guide/features/routing"} ::