Project Structure

🔍 What Is It?

The Next.js App Router project structure is a convention-over-configuration routing system where your file system defines your application architecture:

Root-level files:

• →next.config.ts — framework configuration (redirects, rewrites, env, headers)
• →middleware.ts — runs before every request (auth checks, redirects)
• →tsconfig.json — TypeScript configuration

Special app/ files:

• →layout.tsx — persistent UI wrapper (navbar, sidebar) — survives navigation
• →page.tsx — the actual page content — makes a route publicly accessible
• →loading.tsx — automatic Suspense boundary — shown while page data loads
• →error.tsx — error boundary — shown when the route throws
• →not-found.tsx — shown when notFound() is called
• →template.tsx — like layout but re-mounts on every navigation
• →route.ts — API endpoint (GET, POST, PUT, DELETE handlers)

🎯 Why Do We Need It?

File-based routing eliminates an entire category of configuration:

• →No router configuration files to maintain
• →No manual route registration
• →Co-location of route-specific components, tests, and utilities
• →Automatic code splitting per route — users only download JS for the routes they visit
• →Nested layouts without prop drilling — layouts wrap child routes automatically

The structure also enforces a consistent architecture across teams — a new developer can understand the app's routing just by reading the folder tree.

🏗️ What Happens in Real Projects?

A real enterprise Next.js project structure:

my-app/
├── app/
│   ├── layout.tsx              # Root layout (html, body, providers)
│   ├── page.tsx                # Homepage /
│   ├── (marketing)/            # Route group — no URL segment
│   │   ├── about/page.tsx      # /about
│   │   └── pricing/page.tsx    # /pricing
│   ├── (dashboard)/
│   │   ├── layout.tsx          # Dashboard layout (sidebar, topnav)
│   │   ├── dashboard/page.tsx  # /dashboard
│   │   └── settings/page.tsx   # /settings
│   └── api/
│       └── webhooks/route.ts   # /api/webhooks
├── components/
│   ├── ui/                     # Generic (Button, Input, Modal)
│   └── features/               # Domain-specific (UserCard, OrderTable)
├── lib/
│   ├── db.ts                   # Database client
│   ├── auth.ts                 # Auth utilities
│   └── utils.ts                # Shared helpers
├── hooks/                      # Custom React hooks
├── types/                      # TypeScript interfaces
└── middleware.ts               # Auth/redirect middleware

⚙️ How It Works

How Next.js resolves a URL to a component:

1. URL /dashboard/settings arrives
2. Next.js walks app/dashboard/settings/
3. Finds page.tsx — this is the leaf component
4. Collects all layout.tsx files from root down to this route
5. Wraps: RootLayout > DashboardLayout > SettingsPage
6. Checks for loading.tsx at each level — wraps in Suspense
7. Renders the component tree, streaming HTML to the browser

Route groups (folder) let you organise routes without affecting URLs. Use them to apply different layouts to different sections of your app.

💻 Example

Nested Layouts and Special Files — How layouts, loading, and error files work together in a dashboard route.

// This layout wraps ALL routes under (dashboard)/
// It persists across navigation — does not re-mount
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="flex h-screen">
      <Sidebar />          {/* Always visible */}
      <main className="flex-1 overflow-auto">
        {children}        {/* Page content swaps here */}
      </main>
    </div>
  );
}

🤔 Common Confusions

🚨 Common Production Issues

✅ Best Practices

🏛️ Architect's Note

💬 Frequently Asked Questions

🎯 Key Takeaways

🔗 Related Topics

🎯 Practice this topic in interviews

↗ Where this topic fits