Next.js File and Folder Structure Explained

When building modern web applications with Next.js, understanding the file and folder structure is essential. A well-organized project structure improves maintainability, scalability, collaboration, and development speed.

Next.js follows a convention-based routing system, meaning folders and files directly influence how your application works. Whether you're building a simple blog, an e-commerce platform, a SaaS product, or a large-scale enterprise application, understanding the Next.js folder structure is crucial.

In this guide, you'll learn:

Next.js project structure
Purpose of every important file and folder
App Router architecture
Route groups
Dynamic routes
API routes
Components organization
Best practices for large projects
Recommended production structure

Typical Next.js Project Structure

After creating a project, Your project may look like:

my-app/
│
├── app/
├── components/
├── public/
├── lib/
├── hooks/
├── services/
├── styles/
├── types/
├── utils/
│
├── next.config.js
├── package.json
├── middleware.js
├── .env.local
├── tsconfig.json
└── README.md

Each folder has a specific purpose.

Understanding the App Folder

The app folder is the heart of modern Next.js applications.

app/
│
├── page.js
├── layout.js
├── loading.js
├── error.js
├── not-found.js
└── dashboard/

The App Router was introduced in Next.js 13 and is now the recommended approach.

page.js

Every route requires a page file.

Example:

app/
└── page.js

This generates:

Example:

export default function HomePage() {
  return (
    <h1>Welcome to Codingy</h1>
  );
}

Nested Routes

Create folders for routes.

app/
├── page.js
└── about/
    └── page.js

URL:

/about

Dynamic Routes

Use square brackets.

app/
└── tutorial/
    └── [slug]/
        └── page.js

URLs:

/tutorial/javascript
/tutorial/react
/tutorial/nextjs

Example:

export default function TutorialPage({ params }) {
  return (
    <h1>{params.slug}</h1>
  );
}

Catch-All Routes

Capture multiple segments.

app/
└── docs/
    └── [...slug]/
        └── page.js

Examples:

/docs/react
/docs/react/hooks
/docs/react/hooks/useeffect

layout.js

Layouts provide reusable UI.

Example:

app/
├── layout.js
└── page.js

Layout:

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <header>Header</header>

        {children}

        <footer>Footer</footer>
      </body>
    </html>
  );
}

Every page automatically uses this layout.

Nested Layouts

Example:

app/
└── dashboard/
    ├── layout.js
    └── page.js

Only dashboard pages use the dashboard layout.

loading.js

Displays loading state.

app/
└── dashboard/
    └── loading.js

Example:

export default function Loading() {
  return <p>Loading...</p>;
}

Shown automatically during data fetching.

error.js

Handles route-specific errors.

app/
└── dashboard/
    └── error.js

Example:

'use client';

export default function Error() {
  return (
    <h2>Something went wrong</h2>
  );
}

not-found.js

Custom 404 page.

app/
└── not-found.js

Example:

export default function NotFound() {
  return (
    <h1>Page Not Found</h1>
  );
}

Route Groups

Organize routes without affecting URLs.

app/
├── (marketing)/
│   ├── about/
│   └── contact/
│
└── (dashboard)/
    ├── users/
    └── settings/

URLs remain:

/about
/contact
/users
/settings

API Routes

Create backend APIs.

app/
└── api/
    └── posts/
        └── route.js

Example:

export async function GET() {
  return Response.json({
    success: true
  });
}

URL:

/api/posts

Components Folder

Reusable UI components.

components/
│
├── Header.jsx
├── Footer.jsx
├── Button.jsx
├── Card.jsx
└── Sidebar.jsx

Example:

import Header from '@/components/Header';

Benefits:

Reusability
Cleaner code
Easy maintenance

Public Folder

Next Article ❯