From 58a46f22706937902cbef8a80262ce730ef219c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Tue, 15 Mar 2022 10:59:27 +0100 Subject: [PATCH] docs(routing): improvements (#3664) --- .../1.usage/{9.routing.md => 9.nuxt-link.md} | 6 +- .../3.docs/2.directory-structure/10.pages.md | 109 +++++++++++++----- docs/yarn.lock | 8 +- 3 files changed, 84 insertions(+), 39 deletions(-) rename docs/content/3.docs/1.usage/{9.routing.md => 9.nuxt-link.md} (93%) diff --git a/docs/content/3.docs/1.usage/9.routing.md b/docs/content/3.docs/1.usage/9.nuxt-link.md similarity index 93% rename from docs/content/3.docs/1.usage/9.routing.md rename to docs/content/3.docs/1.usage/9.nuxt-link.md index c13d2c96f8..8d502e73dc 100644 --- a/docs/content/3.docs/1.usage/9.routing.md +++ b/docs/content/3.docs/1.usage/9.nuxt-link.md @@ -1,10 +1,8 @@ -# Routing - -## `` +# NuxtLink Nuxt provides `` component to handle any kind of links within your application. -`` component is a drop-in replacement for both Vue Router's `` component and HTML's `` tag. It intelligently determines whether the link is _internal_ or _external_ and renders it accordingly with available optimizations (prefetching, default attributes, etc.) +`` is a drop-in replacement for both Vue Router's `` component and HTML's `` tag. It intelligently determines whether the link is _internal_ or _external_ and renders it accordingly with available optimizations (prefetching, default attributes, etc.) ## Examples diff --git a/docs/content/3.docs/2.directory-structure/10.pages.md b/docs/content/3.docs/2.directory-structure/10.pages.md index 574578dfe7..920424dfd5 100644 --- a/docs/content/3.docs/2.directory-structure/10.pages.md +++ b/docs/content/3.docs/2.directory-structure/10.pages.md @@ -6,22 +6,65 @@ head.title: Pages directory # Pages directory +Nuxt provides a file-based routing to create routes within your web application using [Vue Router](https://router.vuejs.org) under the hood. + ::alert{type="info"} -The `pages/` directory is optional, meaning that if you only use [app.vue](/docs/directory-structure/app), `vue-router` won't be included, reducing 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/directory-structure/app), reducing your application's bundle size. :: -Nuxt will automatically integrate [Vue Router](https://router.vuejs.org/) and map `pages/` directory into the routes of your application. +## Usage + +Pages are Vue components and can have the `.vue`, `.js`, `.jsx`, `.ts` or `.tsx` extension. + +::code-group + +```vue [pages/index.vue] + +``` + +```ts [pages/index.ts] +// https://vuejs.org/guide/extras/render-function.html +export default defineComponent({ + render () { + return h('h1', 'Index page') + } +}) +``` + +```ts [pages/index.tsx] +// https://vuejs.org/guide/extras/render-function.html#jsx-tsx +export default defineComponent({ + render () { + return

Index page

+ } +}) +``` + +:: + +The `pages/index.vue` file will be mapped to the `/` route of your application. + +If you are using [app.vue](/docs/directory-structure/app), make sure to use the `` component to display the current page: + +```vue [app.vue] + +``` ::alert{type=warning} -Unlike components, your pages must have a single root element to allow Nuxt to apply route transitions between pages. +Note that pages **must have a single root element** to allow route transitions between pages. :: ## Dynamic Routes If you place anything within square brackets, it will be turned into a [dynamic route](https://router.vuejs.org/guide/essentials/dynamic-matching.html) parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory. -If you need a catch-all route, you create it by using a file named like `[...slug].vue`. This will match _all_ routes under that path, and thus it doesn't support any non-dynamic text. - ### Example ```bash @@ -33,17 +76,16 @@ If you need a catch-all route, you create it by using a file named like `[...slu Given the example above, you can access group/id within your component via the `$route` object: -```vue +```vue [pages/users-[group]/[id].vue] ``` Navigating to `/users-admins/123` would render: -```text -admins 123 +```html +

admins - 123

``` If you want to access the route using Composition API, there is a global `useRoute` function that will allow you to access the route just like `this.$route` in the Options API. @@ -58,36 +100,22 @@ if (route.params.group === 'admins' && !route.params.id) { ``` -## Navigation +## Catch all route -To navigate between pages of your app, you should use the  `` component. This component is included with Nuxt and therefore you don't have to import it as you do with other components. It is similar to the HTML `` tag except that instead of using a `href="/about"` you use `to="/about"`. If you've used `vue-router` before, you can think of `` as a replacement for ``. +If you need a catch-all route, you create it by using a file named like `[...slug].vue`. This will match _all_ routes under that path. -A simple link to the `index.vue` page in your `pages` folder: - -```html +```vue [pages/[...slug].vue] ``` -The `` component should be used for all internal links. That means for all links to the pages within your site you should use ``. The `` tag should be used for all external links. That means if you have links to other websites you should use the `` tag for those. +Navigating to `/hello/world` would render: ```html - +

["hello", "world"]

``` -::alert{type="info"} -If you want to know more about ``, read the [Vue Router documentation](https://router.vuejs.org/api/#router-link) for more information. -:: - ## Nested Routes It is possible to display [nested routes](https://next.router.vuejs.org/guide/essentials/nested-routes.html) with ``. @@ -171,6 +199,7 @@ This data can then be accessed throughout the rest of your app from the `route.m ```vue ``` @@ -186,7 +215,7 @@ import { someData } from '~/utils/example' const title = ref('') definePageMeta({ - title, + title, // This will create an error someData }) @@ -215,3 +244,21 @@ You can define middleware to apply before loading this page. It will be merged w #### `layoutTransition` and `pageTransition` You can define transition properties for the `` components that wraps your pages and layouts, or pass `false` to disable the `` wrapper for that route. [More about transitions](https://vuejs.org/guide/built-ins/transition.html#transition). + +## Navigation + +To navigate between pages of your app, you should use the [``](/docs/usage/nuxt-link) component. + +This component is included with Nuxt and therefore you don't have to import it as you do with other components. + +A simple link to the `index.vue` page in your `pages` folder: + +```html + +``` + +::alert{type="info"} +Learn more about [``](/docs/usage/nuxt-link) usage. +:: diff --git a/docs/yarn.lock b/docs/yarn.lock index 39712b9f8b..3ec505d270 100644 --- a/docs/yarn.lock +++ b/docs/yarn.lock @@ -11150,10 +11150,10 @@ untyped@^0.2.5, untyped@^0.2.8, untyped@^0.2.9: resolved "https://registry.yarnpkg.com/untyped/-/untyped-0.2.9.tgz#3e3df96a303dec3e2eda55fcbdc02e2ab468683d" integrity sha512-8d8V+q/y5CGzV+IYnoOCMjrK+NSNp1HKO8iPQ+bV4rBP8knPIme3+j/bpej8IuMnEMxOJZNptXNOXCx7w+VJxQ== -untyped@^0.3.0: - version "0.3.0" - resolved "https://registry.yarnpkg.com/untyped/-/untyped-0.3.0.tgz#854df4dec055cc6a0a2217aa2d20152277b6ada9" - integrity sha512-n4M5/T1wWlHFmohk0EhS+yM7W/h5dOtQldOV3MVEbZY1fTy5A47UL8+d8GLW1iwmaAwNrM5ERy3qe1k0T/Yc7A== +untyped@^0.4.2: + version "0.4.2" + resolved "https://registry.yarnpkg.com/untyped/-/untyped-0.4.2.tgz#302e53b1733ff383749342b06f38277af97516ad" + integrity sha512-akHdcDop+tvtwPQxrbDfGf6zfQUgMjJXA8hXYYxcnmH6NnuMQatiY9wYDZ+jkUCcWuctb70f/QBYmbMsJpl48g== upath@^1.1.1: version "1.2.0"