Skip to content

Commit 662a1d7

Browse files
sanjay-kvsanjay-kv
authored
Merge pull request #919 from Adez017/my-changes
docs: ✏️ Added project structure page
2 parents 8583014 + 784beaa commit 662a1d7

File tree

5 files changed

+268
-1
lines changed

5 files changed

+268
-1
lines changed

‎docs/Nextjs/assets/project-organization-private-folders.jpg‎

127 KB
Loading

‎docs/Nextjs/assets/route-group-organisation.jpg‎

136 KB
Loading

‎docs/Nextjs/assets/top-level-folders.jpg‎

62.4 KB
Loading

‎docs/Nextjs/project-structure.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
---
2+
id: project-structure
3+
title: Project Structure of your Next.js app
4+
sidebar_label: Project Structure
5+
sidebar_position: 3
6+
tags:
7+
[
8+
nextjs,
9+
react,
10+
web-development,
11+
front-end-development,
12+
javascript,
13+
development-environment,
14+
web-framework,
15+
nodejs,
16+
npm,
17+
setup-environment,
18+
]
19+
description: This page provides an overview of all the folder and file conventions in Next.js, and recommendations for organizing your project.
20+
---
21+
22+
## Folder and File Conventions
23+
24+
### Top-level Folders
25+
26+
Top-level folders are used to organize your application's code and static assets.
27+
28+
<BrowserWindow url="https://nodejs.org/" bodyStyle={{padding: 0}}>
29+
[![Node.js](./assets/top-level-folders.jpg)](https://nextjs.org/)
30+
</BrowserWindow>
31+
32+
| Folder | Description |
33+
|--------|-------------|
34+
| `app` | App Router |
35+
| `pages` | Pages Router |
36+
| `public` | Static assets to be served |
37+
| `src` | Optional application source folder |
38+
39+
### Top-level Files
40+
41+
Top-level files are used to configure your application, manage dependencies, run middleware, integrate monitoring tools, and define environment variables.
42+
43+
| File | Description |
44+
|------|-------------|
45+
| `next.config.js` | Configuration file for Next.js |
46+
| `package.json` | Project dependencies and scripts |
47+
| `instrumentation.ts` | OpenTelemetry and Instrumentation file |
48+
| `middleware.ts` | Next.js request middleware |
49+
| `.env` | Environment variables |
50+
| `.env.local` | Local environment variables |
51+
| `.env.production` | Production environment variables |
52+
| `.env.development` | Development environment variables |
53+
| `.eslintrc.json` | Configuration file for ESLint |
54+
| `.gitignore` | Git files and folders to ignore |
55+
| `next-env.d.ts` | TypeScript declaration file for Next.js |
56+
| `tsconfig.json` | Configuration file for TypeScript |
57+
| `jsconfig.json` | Configuration file for JavaScript |
58+
59+
### App Router Files
60+
61+
| File | Extensions | Description |
62+
|------|-----------|-------------|
63+
| `layout` | `.js` `.jsx` `.tsx` | Shared UI for a segment and its children |
64+
| `page` | `.js` `.jsx` `.tsx` | Unique UI of a route and make routes publicly accessible |
65+
| `loading` | `.js` `.jsx` `.tsx` | Loading UI for a segment and its children |
66+
| `not-found` | `.js` `.jsx` `.tsx` | Not found UI for a segment and its children |
67+
| `error` | `.js` `.jsx` `.tsx` | Error UI for a segment and its children |
68+
| `global-error` | `.js` `.jsx` `.tsx` | Global error UI |
69+
| `route` | `.js` `.ts` | Server-side API endpoint |
70+
| `template` | `.js` `.jsx` `.tsx` | Specialized re-rendered Layout UI |
71+
| `default` | `.js` `.jsx` `.tsx` | Fallback UI for Parallel Routes |
72+
73+
### Routing Conventions
74+
75+
| Convention | Description |
76+
|-----------|-------------|
77+
| `folder` | Route segment |
78+
| `folder/folder` | Nested route segment |
79+
| `[folder]` | Dynamic route segment |
80+
| `[...folder]` | Catch-all route segment |
81+
| `[[...folder]]` | Optional catch-all route segment |
82+
| `(folder)` | Route group (does not affect URL) |
83+
| `_folder` | Private folder (excluded from routing) |
84+
| `@folder` | Named slot for parallel routes |
85+
| `(.)folder` | Intercept same level |
86+
| `(..)folder` | Intercept one level above |
87+
| `(..)(..)folder` | Intercept two levels above |
88+
| `(...)folder` | Intercept from root |
89+
90+
### Metadata Files
91+
92+
| File | Extensions | Description |
93+
|------|-----------|-------------|
94+
| `favicon` | `.ico` | Favicon file |
95+
| `icon` | `.ico` `.jpg` `.jpeg` `.png` `.svg` | App Icon file |
96+
| `icon` | `.js` `.ts` `.tsx` | Generated App Icon |
97+
| `apple-icon` | `.jpg` `.jpeg` `.png` | Apple App Icon file |
98+
| `apple-icon` | `.js` `.ts` `.tsx` | Generated Apple App Icon |
99+
| `opengraph-image` | `.jpg` `.jpeg` `.png` `.gif` | Open Graph image file |
100+
| `opengraph-image` | `.js` `.ts` `.tsx` | Generated Open Graph image |
101+
| `twitter-image` | `.jpg` `.jpeg` `.png` `.gif` | Twitter image file |
102+
| `twitter-image` | `.js` `.ts` `.tsx` | Generated Twitter image |
103+
| `sitemap` | `.xml` | Sitemap file |
104+
| `sitemap` | `.js` `.ts` | Generated Sitemap |
105+
| `robots` | `.txt` | Robots file |
106+
| `robots` | `.js` `.ts` | Generated Robots file |
107+
108+
## Organizing Your Project
109+
110+
### Component Rendering Hierarchy
111+
112+
Components defined in special files are rendered in a specific hierarchy:
113+
114+
```
115+
layout.js
116+
├─ template.js
117+
├─ error.js (React error boundary)
118+
├─ loading.js (React suspense boundary)
119+
├─ not-found.js (React error boundary)
120+
└─ page.js or nested layout.js
121+
```
122+
123+
### Colocation
124+
125+
In the `app` directory, folders define the route structure. A route becomes publicly accessible only when you add a `page.js` or `route.js` file to that folder.
126+
127+
This allows you to safely place your project files (components, styles, tests) inside the `app` directory without making them accessible via URL.
128+
129+
### Private Folders
130+
131+
Create private folders by prefixing with underscore: `_folderName`
132+
133+
<BrowserWindow url="https://nodejs.org/" bodyStyle={{padding: 0}}>
134+
[![Node.js](./assets/project-organization-private-folders.jpg)](https://nextjs.org/)
135+
</BrowserWindow>
136+
137+
138+
These folders are excluded from routing and useful for:
139+
140+
- Separating UI logic from routing logic
141+
- Organizing internal files consistently
142+
- Grouping files in code editors
143+
- Avoiding naming conflicts with Next.js conventions
144+
145+
You can create URL segments starting with underscore using `%5FfolderName`.
146+
147+
### Route Groups
148+
149+
Create route groups by wrapping folder names in parentheses: `(folderName)`
150+
151+
These folders are for organization only and won't appear in the URL path.
152+
153+
Use route groups to:
154+
155+
- Organize routes by section (marketing, admin, shop)
156+
- Apply different layouts to route groups
157+
- Create multiple root layouts in your application
158+
159+
### Using `src` Directory
160+
161+
You can optionally store your application code inside a `src` folder. This separates application code from configuration files in the project root.
162+
163+
```
164+
project-root/
165+
├── src/
166+
│ └── app/ # Your application code
167+
├── public/ # Static assets
168+
├── next.config.js # Configuration
169+
└── package.json # Dependencies
170+
```
171+
172+
## Project Organization Examples
173+
174+
### Option 1: Files Outside `app`
175+
176+
Keep the `app` directory for routing only, store components and utilities in the project root.
177+
178+
```
179+
project-root/
180+
├── app/ # Routes only
181+
├── components/ # Reusable components
182+
├── lib/ # Utility functions
183+
└── public/ # Static assets
184+
```
185+
186+
### Option 2: Files Inside `app`
187+
188+
Store all application code inside the `app` directory.
189+
190+
```
191+
project-root/
192+
└── app/
193+
├── components/ # Reusable components
194+
├── lib/ # Utility functions
195+
├── page.tsx
196+
└── layout.tsx
197+
```
198+
199+
### Option 3: Split by Feature
200+
201+
Store shared code globally, route-specific code within route folders.
202+
203+
```
204+
project-root/
205+
└── app/
206+
├── components/ # Global components
207+
├── lib/ # Global utilities
208+
├── dashboard/
209+
│ ├── components/ # Dashboard components
210+
│ └── page.tsx
211+
└── page.tsx
212+
```
213+
214+
## Advanced Routing Patterns
215+
216+
### Multiple Layouts with Route Groups
217+
218+
Organize routes and apply different layouts without affecting URLs:
219+
220+
```
221+
app/
222+
├── (marketing)/
223+
│ ├── layout.tsx # Marketing layout
224+
│ ├── about/page.tsx # URL: /about
225+
│ └── blog/page.tsx # URL: /blog
226+
└── (shop)/
227+
├── layout.tsx # Shop layout
228+
├── products/page.tsx # URL: /products
229+
└── cart/page.tsx # URL: /cart
230+
```
231+
232+
### Loading UI for Specific Routes
233+
234+
Apply loading states to specific routes using route groups:
235+
236+
```
237+
app/
238+
└── dashboard/
239+
├── (overview)/
240+
│ ├── loading.tsx # Loading UI for overview
241+
│ └── page.tsx # URL: /dashboard
242+
└── settings/
243+
└── page.tsx # URL: /dashboard/settings
244+
```
245+
246+
### Multiple Root Layouts
247+
248+
Create completely different experiences for different sections:
249+
250+
<BrowserWindow url="https://nodejs.org/" bodyStyle={{padding: 0}}>
251+
[![Node.js](./assets/route-group-organisation.jpg)](https://nextjs.org/)
252+
</BrowserWindow>
253+
254+
```
255+
app/
256+
├── (marketing)/
257+
│ ├── layout.tsx # Root layout with <html> and <body>
258+
│ └── page.tsx
259+
└── (app)/
260+
├── layout.tsx # Different root layout
261+
└── page.tsx
262+
```
263+
264+
Each root layout must include `<html>` and `<body>` tags.
265+
266+
## Conclusion
267+
Congratulations! You've mastered Next.js project structure. You now understand how to organize folders and files, use routing conventions like dynamic routes and route groups, and structure your application professionally. You're ready to build well-organized Next.js projects with confidence!

‎sidebars.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,7 @@ const sidebars: SidebarsConfig = {
163163
items: [
164164
"Nextjs/intro-nextjs",
165165
"Nextjs/setup-environment",
166-
// 'Nextjs/git-commands',
166+
"Nextjs/project-structure",
167167
],
168168
},
169169
{

0 commit comments

Comments
 (0)