LogoفارسیFA

Project Structure and Organization in Next.js – Routing, Layouts, and File Conventions

This article provides a comprehensive overview of how to structure and organize a Next.js project using the App Router. It covers top-level folders and files, routing conventions, dynamic and nested routes, route groups, metadata files, and best practices for colocating components and utilities. Understanding these conventions helps build scalable, maintainable applications with clear separation of concerns.

Next.js structureApp Routerdynamic routesroute groupslayout hierarchy

~3 min read • Updated Oct 25, 2025

Introduction


Next.js offers a flexible and powerful file-based routing system. While it doesn’t enforce a strict project structure, it provides conventions and features that help developers organize their applications effectively. This article explores the recommended folder and file organization in a Next.js project using the App Router.


Top-Level Folders


  • app/ – Defines routes using the App Router.
  • pages/ – Legacy routing system (Pages Router).
  • public/ – Static assets like images and fonts.
  • src/ – Optional folder to contain all source code.

Top-Level Files


  • next.config.js – Next.js configuration.
  • package.json – Project dependencies and scripts.
  • .env, .env.local, etc. – Environment variables.
  • tsconfig.json / jsconfig.json – TypeScript or JavaScript config.
  • eslint.config.mjs – ESLint configuration.
  • proxy.ts, instrumentation.ts – Optional utilities for proxying and monitoring.

Routing Files


Each route segment is defined by a folder. To make a route public, include a page.tsx or route.ts file:


  • layout.tsx – Shared UI (e.g., header, footer).
  • page.tsx – Main content for a route.
  • loading.tsx – Skeleton UI during data fetching.
  • error.tsx – Error boundary for the route.
  • not-found.tsx – 404 UI for the route.
  • route.ts – API endpoint.
  • template.tsx – Re-rendered layout for dynamic routes.

Nested Routes


Folders define URL segments. Nesting folders creates nested routes. Layouts wrap their child segments:


app/layout.tsx → wraps all routes  
app/blog/layout.tsx → wraps /blog and its children  
app/blog/page.tsx → /blog  
app/blog/authors/page.tsx → /blog/authors

Dynamic Routes


  • [slug] – Single dynamic segment (e.g., /blog/my-post).
  • [...slug] – Catch-all segments (e.g., /shop/clothing/shirts).
  • [[...slug]] – Optional catch-all (e.g., /docs or /docs/intro).

Route Groups and Private Folders


  • (group) – Logical grouping without affecting the URL (e.g., app/(marketing)/page.tsx → /).
  • _folder – Private folders for colocating non-routable files (e.g., _components, _lib).

Parallel and Intercepted Routes


Advanced routing patterns for slot-based layouts and modal overlays:


  • @folder – Named slot (e.g., sidebar + main content).
  • (.)folder – Intercept sibling route.
  • (..)folder – Intercept parent route.
  • (...) – Intercept from root.

Metadata File Conventions


  • Icons: favicon.ico, icon.png, apple-icon.png
  • Open Graph: opengraph-image.png or opengraph-image.tsx
  • Twitter: twitter-image.png or twitter-image.tsx
  • SEO: sitemap.xml, robots.txt

Component Hierarchy


Special files are rendered in a specific order:


  1. layout.tsx
  2. template.tsx
  3. error.tsx
  4. loading.tsx
  5. not-found.tsx
  6. page.tsx

These components are rendered recursively, wrapping their nested segments.


Colocation Best Practices


Files can be colocated inside route segments without becoming routable unless a page.tsx or route.ts is present. This allows you to keep components, utilities, and styles close to where they’re used without exposing them as routes.


Conclusion


Next.js provides a flexible yet powerful structure for organizing your application. By following its file and folder conventions, you can build scalable, maintainable apps with clear routing, reusable components, and optimized developer experience.


Written & researched by Dr. Shahin Siami

Next Article