Explaining Nested Routes

Nesting child routes within other routes can get very complicated very quickly. Here’s another approach that might make it click for you.

Michael Thiessen
Nuxt 3

Mastering Nuxt 3 course is here!

Get notified when we release new tutorials, lessons, and other expert Nuxt content.

Click here to view the Nuxt 3 course

Here’s a different way to think about nested routes in Nuxt.

Nesting child routes within other routes can get very complicated very quickly.

It’s hard to wrap your head around, and sometimes reading through the docs isn’t enough.

Here’s another approach that might make it click for you.

Thinking with Folders

You can think of routes like a folder hierarchy. For example, the route /one/two/three is equivalent to this folder structure:

one/
- two/
- - three/

When we combine multiple components together we get a different kind of hierarchy, this time made with components:

// ComponentA
<template>
  <ComponentB />
</template>
// ComponentB
<template>
  <ComponentC />
</template>

This component hierarchy ends up looking like this:

ComponentA
- ComponentB
- - ComponentC

Now that we have two sets of hierarchies, we can start to see how they map together.

Here’s how this works.

Nuxt is trying to map the route to the components as best as it can. It uses the NuxtPage component to render a page from your app’s pages/ directory. Adding more NuxtPage components lets it match to multiple pages in your folder hierarchy.

Let’s take our route /one/two/three. If we only have a single NuxtPage in our application, we have to match exactly:

// App.vue
<template>
  <div>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
  </div>
</template>

This will match the route /one/two/three against the component pages/one/two/three.vue. If we’re using a catchall route, we can match against pages/one/[...slug].vue or pages/one/two/[...slug].vue as well.

However, if that page also has a NuxtPage within it, we can match our route /one/two/three in more complex ways. This is how we nest child routes — by nesting child components:

// pages/one/two/three.vue
<template>
  <!-- The nested NuxtPage allows for child routes -->
  <NuxtPage />
</template>

Nesting Components like Folders

You can follow along with this live demo here. You’ll need to click “Open in New Tab” at the top in order to navigate to different routes on the demo app.

If we add in a second NuxtPage component we now have two chances to match against the filesystem.

To illustrate this, I’ll create this hierarchy in the filesystem:

pages/
- one.vue
- one/
  - two/
    - three.vue

Our one.vue component looks like this, with a nested NuxtPage so we can match a second time:

// pages/one.vue
<template>
  One
  <NuxtPage />
</template>

And three.vue looks like this, a regular component with no NuxtPage:

// pages/one/two/three.vue
<template>
  Two / Three
</template>

If we go to the route /one we match on one.vue.

Nuxt is able to match the entire route, so it stops. Only one.vue is rendered, and nothing is rendered from the second, nested, NuxtPage component.

However, if we go to /one/two, we will get a 404. Although we’re able to match the first part of the route /one against the one.vue component, we run into some issues.

Nuxt sees that there is another NuxtPage and continues trying to match. But there is nothing to match the /one/two portion, so we’re out of luck, and we get a 404.

But if we go to the route /one/two/three, we get the page one.vue rendered, with the page /one/two/three.vue rendered as a child of it!

Nuxt is able to match the entire route to two components now.

Wrapping Up

Whenever we nest things recursively, whether it’s functions, slots, or routes, it can be very difficult to understand.

This isn’t the only way of understanding nested routes, but hopefully it’s helpful to you!

If you are interested in the opportunity to learn all about Nuxt 3, make sure you register on the Mastering Nuxt website.

Michael Thiessen
Michael is a passionate full time Vue.js and Nuxt.js educator. His weekly newsletter is sent to over 11,000 Vue developers, and he has written over a hundred articles for his blog and VueSchool.

Follow MasteringNuxt on