🧩 Understanding Next.js Folder & File Structure — A Complete Guide for Developers

When working with Next.js, organizing your project structure effectively can greatly improve maintainability, scalability, and clarity across teams. Next.js provides a flexible yet powerful convention system for files and folders that helps you build both small and large-scale applications efficiently.

In this article, we’ll explore Next.js folder and file conventions, routing logic, and project organization strategies that make modern development seamless.

Route segments to path segments

📁 Top-Level Folders

Next.js projects are organized into several top-level folders, each with its own responsibility.

The app folder is used with the App Router and defines your application’s routes, layouts, and UI composition. The pages folder is part of the older Pages Router system.
The public folder stores static assets like images, fonts, or icons that are directly accessible from the browser.
You can also use an optional src folder to store your application code, separating it from project configuration files for cleaner organization.

⚙️ Top-Level Files

Top-level files in a Next.js project are responsible for configuration, dependency management, and environment handling.

For example, next.config.js customizes your Next.js settings, while package.json manages dependencies and scripts.
Files like instrumentation.ts are used for monitoring and OpenTelemetry integration, and middleware.ts defines request-level middleware that runs before rendering.

Environment variables are defined in .env, .env.local, .env.production, or .env.development.
Other common files include .eslintrc.json for linting rules, .gitignore for ignored Git files, and configuration files for TypeScript or JavaScript such as tsconfig.json and jsconfig.json.

🌐 Routing Conventions

Next.js has a powerful file-based routing system that automatically maps files to routes.

Within the app directory, several special files define the behavior of your routes.
A layout.js file defines shared UI elements like headers and footers.
A page.js file makes the folder publicly accessible as a route.
Files like loading.js and error.js handle loading states and error boundaries.
not-found.js is used to customize 404 pages, and route.js can define API endpoints directly within your app.
Templates or default files help with re-rendered layouts and fallback pages in parallel routes.

🧭 Nested and Dynamic Routes

Folders inside the app directory define URL segments. When you nest folders, the segments are also nested in the final URL.
A route becomes public only when a page.js or route.js file exists in the folder.

For example:

app/page.tsx becomes /
app/blog/page.tsx becomes /blog
app/blog/authors/page.tsx becomes /blog/authors

Dynamic routes use square brackets to capture parameters. For instance, [slug] is used for a single parameter like /blog/my-first-post.
A catch-all route [...slug] can match deeper paths such as /shop/clothing/shirts.
Optional catch-all routes [[...slug]] can match paths like /docs or /docs/api-reference/use-router.
You can access all these values using the params prop inside your components.

🧩 Route Groups and Private Folders

Next.js allows developers to organize code without affecting the URL path using route groups.
To create a group, wrap the folder name in parentheses. For example, app/(marketing)/page.tsx is still served at /, while app/(shop)/cart/page.tsx is served at /cart.
This technique helps organize routes by feature, section, or team while maintaining clean URLs. It also allows for separate layouts in different route groups.

Private folders are created by prefixing a folder name with an underscore, such as app/blog/_components/Post.tsx.
These folders are not routable and are useful for organizing utility components, UI logic, or helper functions that shouldn’t be part of the public route system.
They also help avoid naming conflicts with future Next.js updates.

🧠 Parallel and Intercepted Routes

Parallel and intercepted routes are advanced Next.js features for handling complex UI patterns like modal routing or slot-based layouts.

Using @folder allows you to define named slots that can be rendered by a parent layout, ideal for sidebars or multi-view dashboards.
The (.)folder pattern lets you intercept routes at the same level, commonly used to display modals without navigating away.
Similarly, ( .. )folder or ( ... )folder allow you to intercept routes from parent or root levels, showing overlays or preview pages without changing the URL.

🖼️ Metadata and SEO Files

Next.js comes with conventions for managing icons, metadata, and SEO automatically.

You can define app icons such as favicon.ico, icon.png, or apple-icon.png.
Open Graph and Twitter images can be added with files like opengraph-image.png or twitter-image.png, which are used for social sharing previews.
For SEO, Next.js recognizes files such as sitemap.xml and robots.txt, or you can dynamically generate them using .js or .ts scripts.

🧱 Project Organization Strategies

Next.js doesn’t enforce a strict structure, but following consistent patterns is key to scalability.
Here are some common strategies:

You can store all your application code outside of the app directory, keeping it dedicated to routing only.
Alternatively, you can colocate shared components, hooks, and libraries inside the app folder to make it easier to find related files.
Another common pattern is feature-based organization, where each route folder contains its own components, styles, and utilities.
You can also use route groups to organize code by section, such as (marketing) or (dashboard), without affecting URLs.

🧩 Multiple Root Layouts and Loading Skeletons

Next.js allows you to create multiple root layouts by removing the global layout.js and adding layout files inside each route group.
This approach is helpful if your application has distinct UI sections, such as a marketing site and a customer dashboard, that require separate structures.

You can also apply loading skeletons to specific routes by creating a loading.js file inside a route group.
For example, placing a loading.tsx file inside /dashboard/(overview) ensures the skeleton is only displayed for that specific route rather than all dashboard pages.

Component Hierarchy for File Conventions

Nested File Conventions Component Hierarchy

A diagram showing how a route is not publicly accessible until a page.js or route.js file is added to a route segment.

A diagram showing how page.js and route.js files make routes publicly accessible.

A diagram showing colocated project files are not routable even when a segment contains a page.js or route.js file.

An example folder structure using private folders

An example folder structure using route groups

An example folder structure with the `src` folder

An example folder structure with project files outside of app

An example folder structure with project files inside app

An example folder structure with project files split by feature or route

Organizing Routes with Route Groups

Route Groups with Multiple Layouts

Route Groups with Opt-in Layouts

Route Groups with Multiple Root Layouts

🚀 Final Thoughts

Next.js gives developers full control over how to organize and scale their projects.
By mastering these folder and file conventions — from routing rules and dynamic segments to private folders and layout groups — you can build cleaner, faster, and more maintainable applications.

Whether you’re developing a small portfolio website or a large enterprise platform, understanding the Next.js structure is a key step toward writing professional, scalable, and future-proof React code.

Article Not Found