Nested routes with folders in NextJS - Deep Dive

Overview - Nested routes with folders

What is it?

Nested routes with folders in Next.js let you organize your web pages in a folder structure that matches the URL paths users visit. Each folder inside the pages or app directory represents a part of the URL path, and files inside those folders become the pages. This helps keep your project tidy and makes it easy to build complex websites with many pages. It also allows you to create layouts and components that apply to groups of pages.

Why it matters

Without nested routes, your project would quickly become messy and hard to manage as it grows. URLs would not clearly reflect the structure of your site, confusing both developers and users. Nested routes with folders solve this by linking your file system to your website’s navigation, making development faster and your site easier to understand and maintain.

Where it fits

Before learning nested routes, you should understand basic Next.js routing and how pages work. After mastering nested routes, you can explore advanced topics like dynamic routes, layouts, and server components to build scalable and maintainable web apps.

Mental Model

Core Idea

Nested routes with folders map your website’s URL paths directly to a folder and file structure in your project.

Think of it like...

It’s like organizing your house by rooms and closets: each room (folder) holds related things (pages), so you always know where to find or add something based on its location.

root folder (app or pages)
├── about (folder)
│   └── page.js (renders /about)
├── blog (folder)
│   ├── page.js (renders /blog)
│   └── [postId] (folder)
│       └── page.js (renders /blog/:postId)
└── contact.js (renders /contact)

Build-Up - 7 Steps

1

Foundation

Basic file-based routing

Concept: Next.js uses files inside the pages or app folder to create routes automatically.

Create a file named page.js inside the app folder. This file becomes the homepage at '/'. Add another file about.js to create the '/about' page. The file name matches the URL path segment.

Result

Visiting '/' shows the homepage, and '/about' shows the about page.

Understanding that files correspond to URLs is the foundation for grasping nested routes.

2

Foundation

Folders create nested paths

Concept: Folders inside the app or pages folder represent nested parts of the URL path.

Create a folder named blog inside app. Inside blog, add page.js. This creates the '/blog' route. Add another folder inside blog named [postId] with page.js to create dynamic nested routes like '/blog/123'.

Result

The URL '/blog' shows the blog page, and '/blog/123' shows the post with id 123.

Folders let you build multi-level URLs that match your site’s structure.

3

Intermediate

Using layout.js for nested layouts

🤔Before reading on: do you think each nested folder can have its own layout that wraps its pages? Commit to yes or no.

Concept: Next.js allows you to add a layout.js file inside any folder to wrap all pages in that folder with a shared layout.

Add layout.js inside the blog folder to create a blog-specific layout. This layout wraps all pages inside blog, like /blog and /blog/[postId]. Layouts can include navigation, headers, or footers specific to that section.

Result

Pages under /blog share the same layout, separate from the rest of the site.

Layouts let you reuse UI parts for groups of pages, making your app easier to maintain and consistent.

4

Intermediate

Dynamic nested routes with parameters

🤔Before reading on: do you think dynamic route folders can be nested inside other dynamic or static folders? Commit to yes or no.

Concept: You can nest dynamic route folders inside other folders to capture multiple URL parameters.

Inside blog, create a folder [postId]. Inside that, create another folder [commentId] with page.js. This creates routes like /blog/123/456 where 123 is postId and 456 is commentId.

Result

You can access deeply nested dynamic routes with multiple parameters.

Nesting dynamic routes lets you model complex URL structures that reflect real data relationships.

5

Intermediate

Index routes with page.js files

Concept: A page.js file inside a folder acts as the index route for that folder’s path segment.

Inside a folder like blog, page.js renders the '/blog' path. If you add other files like about.js inside blog, they become '/blog/about'.

Result

You can have a default page for a folder and additional nested pages.

Index routes help you organize default content for a URL segment cleanly.

6

Advanced

Shared layouts and nested routing combined

🤔Before reading on: do you think nested layouts can be combined with nested routes to create complex UI hierarchies? Commit to yes or no.

Concept: Nested layouts wrap nested routes, allowing you to build UI hierarchies that match URL hierarchies.

Create a root layout.js for the whole app, then nested layout.js files inside folders like blog or dashboard. Each layout wraps its nested pages and layouts, composing the UI.

Result

Your app UI matches the URL structure, with shared parts at each level.

Combining nested routes and layouts creates scalable, maintainable apps with clear structure.

7

Expert

Route groups and folder naming tricks

🤔Before reading on: do you think you can create folders that group routes without affecting the URL path? Commit to yes or no.

Concept: Next.js supports route groups using parentheses in folder names to organize files without adding to the URL path.

Create a folder named (admin) inside app. Pages inside (admin) are not part of the URL path but help organize code. For example, app/(admin)/dashboard/page.js renders '/dashboard' but is grouped in code.

Result

You can organize routes in folders without changing URLs, keeping code clean and URLs simple.

Route groups let you separate concerns in your codebase without affecting user-facing URLs.

Under the Hood

Next.js reads the folder and file structure inside the app or pages directory at build time. Each folder corresponds to a URL segment, and each page.js file corresponds to a route endpoint. Dynamic routes use folder or file names wrapped in square brackets to capture URL parameters. layout.js files wrap pages and nested layouts by exporting React components that receive children. Route groups use parentheses in folder names to exclude folders from URL paths but include them in the component tree. This file-based routing system is powered by Next.js’s compiler and server, which map URLs to components automatically.

Why designed this way?

Next.js was designed to simplify routing by using the file system as the source of truth, reducing the need for manual route configuration. This approach makes it easy for beginners to understand and speeds up development. Dynamic routes and layouts were added to handle real-world app complexity. Route groups were introduced to improve code organization without complicating URLs. Alternatives like manual route definitions were rejected because they add boilerplate and risk mismatches between code and URLs.

app folder
├── layout.js (root layout)
├── page.js (homepage)
├── about
│   └── page.js (/about)
├── blog
│   ├── layout.js (blog layout)
│   ├── page.js (/blog)
│   └── [postId]
│       └── page.js (/blog/:postId)
└── (admin)
    └── dashboard
        └── page.js (/dashboard, not /admin/dashboard)

Myth Busters - 4 Common Misconceptions

Quick: Does creating a folder inside app always add a segment to the URL path? Commit to yes or no.

Common Belief: Many think every folder inside app becomes part of the URL path.

Reality: Folders with names in parentheses, called route groups, do NOT add to the URL path but help organize code.

Why it matters: Without this knowledge, developers may create unwanted URL segments or messy URLs.

Quick: Can you use any file name for a page in Next.js? Commit to yes or no.

Common Belief: Some believe any file name inside app can be a route.

Reality: Only files named page.js (or page.tsx) define routes; other files are ignored for routing.

Why it matters: Misnaming files causes routes not to work, leading to confusion and bugs.

Quick: Do nested layouts replace parent layouts completely? Commit to yes or no.

Common Belief: People often think nested layouts override or replace parent layouts.

Reality: Nested layouts wrap inside parent layouts, composing UI layers rather than replacing.

Why it matters: Misunderstanding this leads to broken UI structure and layout bugs.

Quick: Are dynamic route parameters always strings? Commit to yes or no.

Common Belief: Some assume dynamic route parameters are automatically typed or parsed.

Reality: Parameters are always strings and need manual parsing if other types are needed.

Why it matters: Assuming automatic typing causes runtime errors or unexpected behavior.

Expert Zone

1

Route groups can be combined with layouts to create complex UI structures without affecting URLs, a subtle but powerful pattern.

2

Dynamic route segments can be optional by using double square brackets [[param]], allowing flexible URL matching.

3

Nested layouts preserve state and React context between route changes, improving performance and user experience.

When NOT to use

Avoid deeply nested folder structures that are more than 4-5 levels deep as they become hard to navigate and maintain. For very dynamic or API-heavy apps, consider using API routes or client-side routing with React Router instead of deeply nested file-based routes.

Production Patterns

In production, teams use nested routes with layouts to separate concerns like admin vs public areas. Route groups organize code by feature or team ownership without changing URLs. Dynamic nested routes model real-world data hierarchies like blogs with posts and comments. Layouts are used to cache UI parts and reduce re-renders for better performance.

Connections

Filesystem Hierarchy

Nested routes mirror the folder and file hierarchy of the filesystem.

Understanding how files and folders organize data on your computer helps grasp how URLs map to files in Next.js.

URL Path Structure

Nested routes directly represent the structure of URL paths users visit.

Knowing how URLs are built from segments clarifies why nested folders create nested routes.

Object-Oriented Programming (OOP) - Composition

Nested layouts compose UI components like objects composed of smaller parts.

Seeing layouts as composable parts helps understand how nested layouts build complex interfaces from simple pieces.

Common Pitfalls

#1 Creating a folder inside app with a name that includes parentheses but expecting it to add to the URL path.

Wrong approach:

app/(admin)/dashboard/page.js // expecting URL to be /admin/dashboard

Correct approach:

app/admin/dashboard/page.js // URL is /admin/dashboard

Root cause:

Misunderstanding that folders with parentheses are route groups and do not add to the URL path.

#2 Naming a route file something other than page.js inside a folder expecting it to create a route.

Wrong approach:

app/blog/post.js // expecting /blog/post route

Correct approach:

app/blog/page.js // creates /blog route
app/blog/[postId]/page.js // creates /blog/:postId route

Root cause:

Not knowing that only page.js files define routes in the app directory.

#3 Placing layout.js files incorrectly or forgetting to nest them properly, causing layouts not to apply.

Wrong approach:

app/blog/page.js
app/layout.js
app/blog/page.js without app/blog/layout.js when needed

Correct approach:

app/layout.js (root layout)
app/blog/layout.js (blog layout)
app/blog/page.js

Root cause:

Not understanding that layouts must be placed in the folder they wrap.

Key Takeaways

Next.js uses your folder and file structure to create nested routes that match URL paths automatically.

Folders represent URL segments, and page.js files inside them become the pages users visit.

Layouts in nested folders wrap pages and other layouts, letting you build reusable UI parts for sections of your site.

Route groups with parentheses let you organize code without changing URLs, keeping your project clean.

Understanding nested routes helps you build scalable, maintainable web apps that reflect real-world URL and UI structures.

Practice

1. In Next.js 14 with the App Router, what does placing a page.tsx file inside a nested folder under app/ do?

easy

A. Bundles all pages into a single route regardless of folder structure.

B. Overrides the root page.tsx and disables routing.

C. Creates a nested route matching the folder path in the URL.

D. Automatically generates API endpoints instead of pages.

Solution

1. Step 1: Understand folder structure in Next.js App Router

   Each folder inside app/ represents a route segment in the URL.

2. Step 2: Role of page.tsx in nested folders

   A page.tsx inside a nested folder creates a page for that nested route path.

3. Final Answer:

   Creates a nested route matching the folder path in the URL. -> Option C

4. Quick Check:

   Nested folder + page.tsx = nested route [OK]

Hint: Remember: folder path + page.tsx = nested URL route [OK]

Common Mistakes:

• Thinking nested folders disable routing
• Confusing API routes with page routes
• Assuming all pages merge into one route

2. Which of the following is the correct folder and file structure to create a nested route /dashboard/settings in Next.js App Router?

easy

A. app/dashboard/settings/page.tsx

B. app/dashboard-settings/page.tsx

C. app/dashboard/page.tsx/settings.tsx

D. app/page.tsx/dashboard/settings.tsx

Solution

1. Step 1: Identify folder nesting for nested routes

   Nested routes require nested folders matching the URL segments.

2. Step 2: Match file placement for the nested page

   The page.tsx file must be inside the deepest folder representing the route.

3. Final Answer:

   app/dashboard/settings/page.tsx -> Option A

4. Quick Check:

   Nested folders + page.tsx file = nested route [OK]

Hint: Use nested folders named after URL segments with page.tsx inside [OK]

Common Mistakes:

• Placing page.tsx outside the nested folder
• Using hyphens instead of folders for nested routes
• Misplacing files inside page.tsx instead of folders

3. Given this folder structure inside app/:

app/
  blog/
    [slug]/
      page.tsx
  page.tsx

What URL will render the page inside app/blog/[slug]/page.tsx?

medium

A. /blog/[slug]

B. /blog/*

C. /blog/{slug}

D. /blog/:slug

Solution

1. Step 1: Understand dynamic route syntax in Next.js

   Folders with square brackets like [slug] represent dynamic route segments.

2. Step 2: Translate dynamic folder to URL pattern

   The dynamic segment is represented as :slug in URL patterns, meaning any value matches.

3. Final Answer:

   /blog/:slug -> Option D

4. Quick Check:

   Dynamic folder [slug] = URL param :slug [OK]

Hint: Dynamic folders [name] map to :name in URLs [OK]

Common Mistakes:

• Using literal [slug] in URL
• Confusing dynamic segment syntax
• Assuming wildcard * matches dynamic segments

4. You have this folder structure:

app/
  products/
    page.tsx
  details/
    page.tsx

But navigating to /products/details shows a 404 error. What is the likely cause?

medium

A. The details/page.tsx file is misplaced; it should be inside products/details/page.tsx.

B. The details folder should be named [details] for dynamic routing.

C. The products folder must not have its own page.tsx when nested routes exist.

D. Missing page.tsx inside details folder.

Solution

1. Step 1: Verify folder and file placement

   The details/page.tsx must be inside products/details/ folder to match the route /products/details.

2. Step 2: Check the given structure

   The structure shows details/page.tsx inside app/ root, not nested under products/.

3. Final Answer:

   The details/page.tsx file is misplaced; it should be inside products/details/page.tsx. -> Option A

4. Quick Check:

   Nested route files must be inside matching nested folders [OK]

Hint: Check file location matches nested folder path exactly [OK]

Common Mistakes:

• Misplacing nested page.tsx outside correct folder
• Confusing dynamic and static folder names
• Removing parent page.tsx unnecessarily

5. You want to create a nested route /profile/settings/privacy in Next.js App Router. You also want to share a layout between /profile/settings and /profile/settings/privacy. How should you organize your folders and files inside app/?

hard

A. app/profile/settings/privacy/page.tsx only; layouts are not needed for nested routes

B. app/profile/settings/layout.tsx, app/profile/settings/page.tsx, app/profile/settings/privacy/page.tsx

C. app/profile/layout.tsx, app/profile/settings/page.tsx, app/profile/settings/privacy/page.tsx

D. app/profile/settings/page.tsx, app/profile/settings/privacy/layout.tsx, app/profile/settings/privacy/page.tsx

Solution

1. Step 1: Understand layout sharing in nested routes

   Layouts placed in a folder apply to all nested routes inside that folder.

2. Step 2: Organize folders for shared layout

   To share layout between /profile/settings and /profile/settings/privacy, place layout.tsx inside settings/ folder.

3. Step 3: Place page.tsx files correctly

   Put page.tsx inside settings/ and inside settings/privacy/ for those pages.

4. Final Answer:

   app/profile/settings/layout.tsx, app/profile/settings/page.tsx, app/profile/settings/privacy/page.tsx -> Option B

5. Quick Check:

   Layout in parent folder shares UI with nested pages [OK]

Hint: Put layout.tsx in parent folder to share with nested routes [OK]

Common Mistakes:

• Placing layout.tsx too deep to share with sibling routes
• Omitting layout.tsx and expecting shared UI
• Misplacing page.tsx files outside correct folders