Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 32 ยท Pages and routing

File-based routing

Create routes in Nuxt by adding files to pages/. Learn index files, nested folders, NuxtPage in app.vue, NuxtLink and how link prefetching works.

In a plain Vue app with Vue Router, you write a table that says "this URL shows that component". In Nuxt the table is your folder. Put a file in pages/, and its path becomes a URL. There is nothing to register, and every page is automatically its own code chunk, loaded when needed.

This lesson covers how files map to routes, the two components that make pages appear (<NuxtPage />) and link between them (<NuxtLink>), and what prefetching does for you. If you have used Vue Router, Vue Router Basics explains the engine underneath. Dynamic segments such as [id] come in Dynamic routes and params.

Files become routes

Every .vue file in pages/ is a route. The file path, without .vue, is the URL path, and a file named index.vue stands for its folder itself:

File in pages/ URL
index.vue /
about.vue /about
blog/index.vue /blog
blog/archive.vue /blog/archive
docs/getting-started/install.vue /docs/getting-started/install

A page is an ordinary component:

VUE
<!-- app/pages/about.vue (read-only) -->
<script setup lang="ts">
useHead({ title: 'About us' })
</script>

<template>
  <section>
    <h1>About us</h1>
    <p>We build tutorials.</p>
  </section>
</template>

Two details save time. First, file names are case sensitive on most servers, so keep them lowercase. Second, pages/blog.vue and pages/blog/index.vue both produce /blog, but they are not the same thing: a blog.vue next to a blog/ folder turns into a parent route with children, which Nested routes and layouts explains. For simple sites, use index.vue.

Every route also gets a name, built from the path: blog/archive.vue is named blog-archive and index.vue is named index. Names are handy for linking and redirecting without hard-coding URLs.

From file to page

Add a file pages/pricing.vue
Route appears The URL is /pricing.
Link to it Use NuxtLink with to="/pricing".
Own chunk Code loads only when visited.
1 / 2

Turning the folder into a route table

The first stand-in does what Nuxt's scanner does, in miniature, for flat and nested files. It reads a list of page files, builds the path and name, and prints a table. Nesting is included: a file whose name matches a sibling folder becomes the parent of that folder's files. This runs on the server runner as plain Node.

Node.js Build a route table from page files

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Run it and look at the parent line: /users has children /users and /users/profile, because users/index.vue is the "empty path" child of users.vue. The real router represents this as a tree, but the information is the same.

app.vue and NuxtPage

Once pages/ exists, Nuxt switches on the router, and something must show the current page. That is <NuxtPage />. In most projects it sits in app.vue:

VUE
<!-- app/app.vue (read-only) -->
<template>
  <div>
    <header>
      <NuxtLink to="/">Home</NuxtLink>
      <NuxtLink to="/about">About</NuxtLink>
    </header>
    <NuxtPage />
  </div>
</template>

Everything outside <NuxtPage /> stays on screen between navigations, which is perfect for a header. When you want a different frame per page, you use layouts, which are covered in the lesson on nested routes and layouts.

If your project has a pages/ folder but no app.vue, Nuxt uses a built-in default that renders just <NuxtPage />. If it has app.vue but no pages/, the router is skipped entirely and app.vue is the whole site, which is a nice way to build a single-screen app. The common mistake is the combination "pages exist, app.vue exists, but no <NuxtPage /> in it": the site shows your header and nothing else.

flowchart LR
  U["URL /blog/archive"] --> R["Route table from pages/"]
  R --> P["pages/blog/archive.vue"]
  P --> A["app.vue: NuxtPage shows it"]
  A --> H["HTML on the server, or DOM in the browser"]

The URL is matched against the generated route table, and app.vue places the matching page.

Use <NuxtLink> instead of a plain <a> for links inside your site:

VUE
<NuxtLink to="/pricing">Pricing</NuxtLink>
<NuxtLink :to="{ name: 'blog-archive' }">Archive</NuxtLink>
<NuxtLink to="https://example.com" external>Other site</NuxtLink>

What NuxtLink does for you:

  • Client-side navigation. After the first page load, clicking a link swaps the page without a full browser reload. The result is fast and keeps state in your layout.
  • A real <a href> is rendered, so links work with JavaScript off, can be opened in a new tab and are visible to search engines.
  • An active class. The link that matches the current route gets router-link-active (and an exact variant), which you can style or customize with activeClass.
  • Smart external links. A link to another domain becomes a normal <a> with safe rel attributes instead of a router link.
  • Prefetching, explained next.

Use a plain <a> only when you want a full page load, for example a link to a file download or a route handled by the server rather than a page.

Prefetching

By default, when a NuxtLink to another page scrolls into view, Nuxt quietly downloads that page's JavaScript chunk in the background (in production builds, and only in the browser, not on the server). When you finally click, the code is already there and the page appears at once. For pages built ahead of time, Nuxt can fetch their pre-computed data as well.

You can control it per link:

VUE
<NuxtLink to="/docs" no-prefetch>Docs</NuxtLink>
<NuxtLink to="/docs" prefetch-on="interaction">Docs</NuxtLink>

no-prefetch turns it off for that link. prefetch-on="interaction" waits until the visitor hovers or focuses the link, which is a good choice for long lists where prefetching everything would waste bandwidth. The exact options depend on your Nuxt version, so check the documentation for the version you use.

The second stand-in is a toy of the idea. A list of links is "visible"; prefetch loads their chunks in the background. Clicking a link whose chunk is already loaded costs nothing, while an unprefetched link needs a download first. All times are made up numbers for the lesson.

Node.js Why prefetching makes clicks feel instant

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first click on /docs pays the download once, and the second is instant because the chunk is now cached, which matches what a browser does with a real chunk file.

Practical habits

  • Keep route names stable. Renaming a file changes its route and its name, and breaks every link and redirect that used them.
  • Use index.vue in folders for section landing pages.
  • Link with NuxtLink everywhere inside the app so that navigation stays client-side.
  • Do not put non-page components in pages/. Every .vue file there becomes a route. Reusable pieces belong in components/.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file serves the URL /blog?

    An index.vue inside a folder represents the folder's own path. A components file never creates a route, and server/api creates an API endpoint.
  2. 2. A project has pages/ and an app.vue, but the page content never appears. What is the most likely cause?

    With pages/ enabled, <NuxtPage /> is where the matched page is rendered. Without it, only the rest of app.vue shows.
  3. 3. What is an advantage of NuxtLink over a plain <a> for internal links?

    NuxtLink renders a real anchor but handles clicks with the router, and prefetches linked pages that enter the viewport.
  4. 4. What does the name of the route for pages/blog/archive.vue look like by default?

    Route names join the path segments with hyphens. The slash version is the path, not the name.

Summary

  • Every .vue file in pages/ is a route; index.vue stands for its folder, and each route also gets a hyphenated name.
  • <NuxtPage /> in app.vue renders the matched page; without pages/, there is no router at all.
  • <NuxtLink> gives real links with client-side navigation, active classes and prefetching.
  • Prefetching downloads linked pages' code when links become visible; you can turn it off or delay it per link.
  • Put only pages in pages/; reusable components go in components/.

Next, Dynamic routes and params adds [id], optional and catch-all segments.