Getting Started
Core Concepts
Troubleshooting
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.
Your application code can live directly in the project root or inside a designated source folder.
app directly under your project root, or inside a src directory (src/app).app directory.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).
The App Router relies on specific file names with predefined behaviors to handle UI segments, errors, loading states, and backend logic.
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.
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.