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

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.