Next.js Project Structure: Detailed Comparison of Using src/ Directory vs Root Directory

When developing projects with Next.js (especially v13 and above), you’ll often encounter two common directory structure choices: • Placing app/ or pages/ directories directly in the project root (i.e., not using src/) • Creating a src/ folder in the root directory and placing app/ or pages/ directories under src/app or src/pages (i.e., using src/)

Below, I’ll compare these two approaches in detail from three perspectives: “structural differences,” “pros and cons,” and “use cases.”

1. Differences in Directory Structure

Structure without src/

For example:

my-next‐app/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── dashboard/
│       └── page.tsx
├── public/
├── next.config.js
├── tsconfig.json
├── package.json
└── …（other configuration files）

In this structure, app/ (or pages/) is directly in the project root. Configuration files (such as next.config.js, tsconfig.json, .env.*, etc.) are also in the root directory. The official documentation states: “If app or pages exist in the root directory, then src/app or src/pages will be ignored.”

Structure with src/

For example:

my-next‐app/
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── dashboard/
│   │       └── page.tsx
│   ├── components/
│   ├── lib/
│   └── styles/
├── public/
├── next.config.js
├── tsconfig.json
├── package.json
└── …

Here, src/ becomes the entry directory for developer source code, with app/ or pages/ placed under src/. Configuration files remain in the project root. The official documentation explicitly supports this pattern:

“As an alternative to having the special Next.js app or pages directories in the root of your project, Next.js also supports the common pattern of placing application code under the src folder.”

Additional note: The /public directory should remain in the project root.

2. Using src/ vs Not Using src/ — Pros and Cons Comparison

Summary of Pros and Cons

• Advantages of using src/ mainly include: • Clean directory structure and organized root directory. • Easier organization of code for medium to large projects (layering of components, lib, hooks, styles, etc.). • Facilitates team collaboration and higher modularity. • Disadvantages of using src/: • An extra directory layer, which might slightly increase the threshold for beginners / small projects. • Some configurations may require additional attention (aliases, Tailwind, etc.). • Advantages of not using src/: • Simple and intuitive, one less directory layer, quick start. • Sufficient for small projects / prototype development. • Disadvantages of not using src/: • As the project grows, the root directory may become messy. • Modular organization might be slightly weaker (but not necessarily).

3. Use Cases & Recommendations

• If you’re developing a small, single-page / few-page project, or just making a quick prototype, the “not using src/” structure is completely fine. The directory is simple, intuitive, and lightweight. • If your project is expected to grow, involve multiple team members, and have many modules (like numerous components, utils, hooks, styles, lib, feature splits) — then the “using src/” structure is more preferable.

4. Additional Differences: app/ Directory (New App Router) vs pages/ Directory

Although your main question is about “what’s the difference between app directory structures with and without src,” let me also briefly explain the differences between app/ vs pages/ since they’re often discussed together. • The pages/ directory is the main routing method in early Next.js (v12 and earlier). Each file corresponds to a route, and each page typically uses data fetching methods like getStaticProps/getServerSideProps. • The app/ directory is the “App Router” mode introduced in Next.js 13, supporting React Server Components, layouts (layout.tsx), loading.js, error.js, nested routes, multiple root layouts, etc. • If you use the app/ directory, you can place it in src/app/ or root directory app/; for pages/, use src/pages/ or root directory pages/. • Note: Don’t mix app/ and pages/ with the same route paths simultaneously, as this may cause conflicts or priority issues.

5. Best Practice Recommendations

• At the start of a project, choose one structure (whether to use src/) and maintain consistency throughout the project; avoid messy changes midway. • If using src/, remember: keep configuration files in the root directory (next.config.js, tsconfig.json, .env.*). The official documentation emphasizes: “Configuration files such as package.json, next.config.js, and tsconfig.json should remain in the project’s root directory.” • If using Tailwind CSS, TypeScript path aliases, etc., adjust configurations accordingly (e.g., add /src/** prefix to content in tailwind.config.js). • As the project scale grows, if you start feeling “the root directory is too messy” or “components/hooks/utils are scattered everywhere,” consider migrating to src/ structure. The migration process needs attention to path aliases, middleware location (if inside src/), etc. • For team collaboration and multi-module projects, recommend using src/ + app/ approach, as it facilitates layering and modularity. Keep configurations, tools, scripts, etc., in the root directory.