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

Related Articles

Advanced Client-Side Routing and Performance Hooks in Next.js

Next.js provides a rich set of client-side hooks and caching utilities that empower developers to build dynamic, responsive, and secure applications. From reading route parameters to tracking navigation state and reporting performance metrics, this guide walks you through the most important tools available in the App Router.

Continue

Handling Authorization and Caching in Next.js: A Developer’s Guide

Next.js introduces powerful experimental features for access control and smart caching. This guide covers the unauthorized() function for custom 401 handling, unstable_cache for persistent memoization, updateTag for instant cache invalidation, and useLinkStatus for inline navigation feedback. Learn how to use these tools to build secure, performant, and responsive applications.

Continue

redirect and refresh in Next.js — Smart Redirects and Client Refreshing via Server Actions

The redirect function in Next.js allows you to navigate users to a new route, returning either a 307 or 303 HTTP response depending on context. It works in Server Components, Client Components, Route Handlers, and Server Actions. The refresh function is used exclusively within Server Actions to refresh the client router. This article explains how both functions work, with practical examples and key considerations.

Continue

NextRequest and NextResponse in Next.js — Managing Cookies, Headers, Redirects, and Rewrites

Next.js extends the native Web Request and Response APIs with NextRequest and NextResponse, offering powerful tools for managing cookies, headers, redirects, rewrites, and JSON responses. These utilities simplify server-side logic and improve control over routing, personalization, and security. This guide walks through their capabilities with practical examples and best practices.

Continue

headers, ImageResponse, notFound, and permanentRedirect in Next.js — Request Handling, Dynamic Images, Errors, and Redirects

Next.js offers powerful tools for handling HTTP requests and responses in Server Components. The headers function lets you read incoming request headers. ImageResponse allows you to generate dynamic images using JSX and CSS. The notFound function renders a custom 404 page, and permanentRedirect enables permanent redirection to another route. This article explains how to use each feature with practical examples.

Continue

A Complete Guide to Using metadata and generateMetadata in Next.js

In modern versions of Next.js, managing page metadata is more powerful and intuitive than ever. Metadata is automatically injected into the <head> of your pages and plays a vital role in SEO, social sharing, and user experience. This guide explains the two main ways to define metadata: using the static metadata object and the dynamic generateMetadata function.

Continue
Previous ArticleNext Article