Next.js Project Structure

When you create a Next.js application, it generates a specific folder and file structure. Next.js relies heavily on file-system routing and structured conventions, meaning that where you place a file dictates how it behaves in your application.

App Router vs Pages Router

Next.js currently supports two different routing paradigms. It is critical to know which one your project is using:

• App Router (app/): Introduced in Next.js 13, it uses React Server Components, nested layouts, and streaming. It is the modern standard.
• Pages Router (pages/): The legacy routing system used prior to Next.js 13. Many existing codebases still rely on it.

You can use either one, or even both simultaneously (by having both an app and a pages directory).

Top-Level Folders

The root of your project will typically contain these prominent folders:

Top-Level Configuration Files

Next.js utilizes standard configuration files at the root level:

• next.config.js: Configuration for Next.js features, environment variables, headers, and redirects.
• package.json: Lists your project dependencies and NPM scripts.
• middleware.js: Executes code before a request is completed to intercept responses.
• .env.local: Stores sensitive local environment variables.
• tsconfig.json: Typescript configuration.
• tailwind.config.js: Tailwind CSS style configuration.

App Router Conventions (`app/`)

In the App Router, folders define routes, and special file conventions define UI. A typical layout might look like:

app/
├── layout.tsx       # Root Layout (applied to all pages)
├── page.tsx         # The UI for the index route (/)
├── globals.css      # Global styles
└── dashboard/
    ├── layout.tsx   # Nested Layout for /dashboard
    ├── page.tsx     # The UI for /dashboard
    ├── loading.tsx  # Suspense fallback for /dashboard
    └── error.tsx    # Error boundary wrapper

Pages Router Conventions (`pages/`)

If using the traditional Pages router, the file itself becomes the route:

pages/
├── _app.js          # Custom App to initialize pages
├── _document.js     # Custom Document to control HTML/body
├── index.js         # Route: /
├── about.js         # Route: /about
└── api/
    └── hello.js     # API Route: /api/hello

Conclusion

Understanding Next.js folder structure is vital because the framework uses these conventions instead of standard React Router configuration files. In the next chapter, we will dive specifically into how Routing works.