---
title: "Project Structure Overview"
description: "The Next.js App Router uses a file-system routing mechanism where folders and special files define your application's routes, layouts, and user interface boundaries. Organizing your project structu..."
last_updated: "2026-09-23T10:57:21.297197+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/getting-started/project-structure-overview"
---

## Overview

### Overview
The Next.js App Router uses a file-system routing mechanism where folders and special files define your application's routes, layouts, and user interface boundaries. Organizing your project structure correctly ensures that pages, components, and assets are routed and rendered properly.

> [!NOTE]
> Next.js supports an optional `src` directory at the project root to keep your application code separate from configuration and build files.

---

## Organizing Your Project Folders

Your application code can live directly in the project root or inside a designated source folder. 

1. Create a root folder named either `app` directly under your project root, or inside a `src` directory (`src/app`).
2. Place all your route folders, layouts, and pages inside this `app` directory.
3. Keep shared public assets (like images and fonts) inside a separate `public` folder at the root level of your project.

> [!IMPORTANT]
> If you choose to use both an `app` directory and a legacy `pages` directory, make sure they both sit at the same level (either both in the root or both inside the `src` directory).

---

## Special File Conventions

The App Router relies on specific file names with predefined behaviors to handle UI segments, errors, loading states, and backend logic.

| File Name | Purpose |
| :--- | :--- |
| `page.tsx` (or `page.js`) | Creates a publicly accessible route for a specific URL segment. |
| `layout.tsx` (or `layout.js`) | Defines shared user interface wrapping around child pages and nested layouts. |
| `loading.tsx` (or `loading.js`) | Displays fallback loading content using suspense while a segment loads. |
| `error.tsx` (or `error.js`) | Acts as an error boundary to catch and handle runtime errors gracefully. |
| `not-found.tsx` (or `not-found.js`) | Renders custom fallback UI when a 404 not found error occurs. |
| `route.ts` (or `route.js`) | Implements backend API endpoint handlers (GET, POST, etc.) for a route. |

> [!TIP]
> You can also organize code by grouping folders using route groups (such as `(dashboard)`), which let you organize your project files without affecting the resulting URL paths.

---

## Common Pitfalls

> [!WARNING]
> Avoid creating conflicting files that map to the exact same URL path across the App Router and the legacy Pages Router. Next.js will throw an error and prevent building if a conflicting route is detected.

> [!CAUTION]
> Do not place API route handlers (`route.ts`) inside the same folder segments as standard UI pages (`page.tsx`) if they share the exact same URL path namespace, as this creates routing conflicts.

## Related

- [Installation and Setup](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/getting-started/installation-and-setup)
- [Routing and Navigation](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/core-concepts/routing-and-navigation)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.