Nuxt File-Based Routing: Route Design, Trust Boundaries, and Failure Modes

Problem: adding a file to pages/ instantly creates a route, but nothing prevents that file from colliding with a dynamic segment, and route parameters arrive as untrusted strings. Takeaway: treat pages/ as a routing manifest, validate every dynamic parameter at the component boundary, and inspect the generated router before deploying. This note assumes Nuxt 3; Nuxt 2 uses this.$route and this.$router where this guide uses useRoute and useRouter.

Requirements before adding a route

• Each public URL should map to exactly one page component, unless the route is intentionally abstract or shared.
• Static files take precedence over dynamic files with the same prefix; ambiguous naming creates silent collisions.
• Route parameters are strings by default. The application must coerce and validate them before use.

Smallest suitable design

Use the pages/ directory for file-based routing. Nuxt resolves components under this directory without manual configuration. A minimal layout:

pages/
  index.vue
  about.vue
  blog/
    index.vue
    [slug].vue
  [category]/
    [id].vue

This yields /, /about, /blog, /blog/:slug, and /:category/:id. Dynamic segments in brackets capture one path segment. A catch-all file such as pages/[...slug].vue captures the remainder of the path and is useful only for fallback pages, not primary navigation.

Trust and data boundaries

Route parameters and query strings are controlled by the requester. Treat them as untrusted input. Never interpolate route.params.slug directly into a database query or file-system path. Validate at the page boundary, before data fetching.

Example validation inside a Nuxt 3 page:

<script setup>
const route = useRoute()
const slug = route.params.slug

if (!/^[a-z0-9-]+$/.test(String(slug ?? ''))) {
  abortNavigation('Invalid slug')
}
</script>

useRoute returns the active route record. abortNavigation stops client-side navigation when validation fails. For server-side rendering, throw a 404 error from the page or middleware instead so the error boundary renders.

Operational checks

1. Open a terminal in the project root. No elevated permissions are required.
2. Run npx nuxi dev and visit http://localhost:3000/about. Expected: the pages/about.vue component renders without manual route registration.
3. After the dev build, inspect .nuxt/router.js. This is generated build output; do not edit it. Confirm each expected path appears as a route entry.
4. Run npx nuxi preview to validate routes in a production-like build locally.
5. Use browser devtools to check status codes: valid routes return 200; undefined paths should return 404 through Nuxt's error page.

Risk: editing .nuxt/router.js directly is lost on the next build and can cause mismatch between dev and production route resolution.

Failure modes

Failure	Cause	Check
Route collision	pages/blog.vue and pages/blog/[slug].vue share an ambiguous prefix	Inspect .nuxt/router.js; only one should match /blog
Catch-all shadowing	pages/[...slug].vue matches paths intended for static pages	Visit a static path such as /about; confirm it does not render the catch-all component
Missing 404	No pages/404.vue exists	Visit a nonexistent URL; confirm Nuxt renders its default error page or your custom one
Unvalidated parameter	Page fetches data using raw route.params.id	Pass malformed IDs; confirm the page returns 404 or a validation error, not a server exception

When the design should change

File-based routing is sufficient for content sites and standard admin panels. Move to explicit route definitions when:

• Routes need named options such as custom meta, route-level validation, or aliases that file names cannot express.
• Routes are generated from a CMS at build time and do not map to local files.
• Different routes require different middleware stacks that are awkward to express with directory layout alone.

In those cases, use defineNuxtRoute or extend the router in nuxt.config.ts rather than forcing every route into pages/.

Limitations and verification

File-based routing does not enforce parameter types. Every parameter remains a string until the application validates it. A practical check is to request a path with encoded traversal characters, such as /blog/%2F..%2Fetc, and confirm the application returns 404 instead of rendering an unintended component or leaking internal paths. Expected behavior varies by Nuxt version and server configuration, so verify against the deployed build rather than assuming protection.

Reverting a route is straightforward: delete the page file and redeploy. No database or build-state migration is required because the route exists only while the file is present.