|
| 1 | +# NextJS |
| 2 | + |
| 3 | +## 1. Introduction |
| 4 | + |
| 5 | +## 2. Project structure (nextjs15) |
| 6 | + |
| 7 | +Source: |
| 8 | + |
| 9 | +- <https://nextjs.org/docs/app/getting-started/project-structure> |
| 10 | +- <https://www.wisp.blog/blog/the-ultimate-guide-to-organizing-your-nextjs-15-project-structure> |
| 11 | + |
| 12 | +```text |
| 13 | +├── src/ |
| 14 | +│ ├── app/ |
| 15 | +│ ├── components/ |
| 16 | +│ ├── lib/ |
| 17 | +│ ├── utils/ |
| 18 | +│ └── styles/ |
| 19 | +├── public/ |
| 20 | +├── package.json |
| 21 | +└── next.config.js |
| 22 | +``` |
| 23 | + |
| 24 | +### 2.1. Core project structure |
| 25 | + |
| 26 | +- One of the first decisions you'll face is whether to use a `src` directory. While Next.js works perfectly fine without it, using a `src` directory offers several benefits: |
| 27 | + - Clear separation between source code and configuration files |
| 28 | + - Easier to implement tooling and build processes |
| 29 | + - Cleaner root directory |
| 30 | + - More consistent with other JavaScript/TypeScript projects |
| 31 | +- With Next.js 15's App Router, the `app` directory is where your routing magic happens. Here's how to structure it effectively: |
| 32 | + - Files directly in `app` affect the root route. |
| 33 | + - Folder create a new routes. |
| 34 | + - Parentheses `()` create route groups that don't affect the URL structure |
| 35 | + - Colocate non-routable files with folders `_folder`. |
| 36 | + - Parameterize segments with square brackets. Use `[segment]` for a single param, `[...segment]` for catch‑all, and `[[...segment]]` for optional catch‑all. Access values via the params prop. |
| 37 | + - Special files like `layout.tsx` and `page.tsx` serve specific purposes in the routing system |
| 38 | + |
| 39 | +```text |
| 40 | +src/app/ |
| 41 | +├── layout.tsx |
| 42 | +├── page.tsx |
| 43 | +├── (auth)/ |
| 44 | +│ ├── login/ |
| 45 | +│ └── register/ |
| 46 | +├── dashboard/ |
| 47 | +│ ├── layout.tsx |
| 48 | +│ ├── page.tsx |
| 49 | +│ └── settings/ |
| 50 | +└── api/ |
| 51 | +``` |
| 52 | + |
| 53 | +### 2.2. Organizing components |
| 54 | + |
| 55 | +The components directory is often the heart of your Next.js application. Here's a proven structure that scales well: |
| 56 | + |
| 57 | +```text |
| 58 | +src/components/ |
| 59 | +├── ui/ |
| 60 | +│ ├── Button/ |
| 61 | +│ │ ├── Button.tsx |
| 62 | +│ │ ├── Button.test.tsx |
| 63 | +│ │ └── index.ts |
| 64 | +│ ├── Card/ |
| 65 | +│ └── Modal/ |
| 66 | +├── layout/ |
| 67 | +│ ├── Header/ |
| 68 | +│ ├── Footer/ |
| 69 | +│ └── Sidebar/ |
| 70 | +└── features/ |
| 71 | + ├── auth/ |
| 72 | + └── dashboard/ |
| 73 | +``` |
| 74 | + |
| 75 | +- The `ui` folder contains your basic building blocks - eusable components that aren't tied to specific business logic. These are your buttons, inputs, cards, and modals. |
| 76 | +- Layout components are larger pieces that form your application's structure. They're typically used across multiple pages but might have more specific functionality than UI components. |
| 77 | +- Feature components are tied to specific business features or domains. For example, a `LoginForm` component would go in `features/auth/`, while a `DashboardStats` component belongs in `features/dashboard/`. |
| 78 | + |
| 79 | +### 2.3. Managing utilities and libraries |
| 80 | + |
| 81 | +```text |
| 82 | +src/ |
| 83 | +├── utils/ |
| 84 | +│ ├── formatting.ts |
| 85 | +│ ├── validation.ts |
| 86 | +│ └── helpers.ts |
| 87 | +└── lib/ |
| 88 | + ├── auth.ts |
| 89 | + ├── api.ts |
| 90 | + └── database.ts |
| 91 | +``` |
| 92 | + |
| 93 | +- The `utils` directory should contain pure utility functions that: |
| 94 | + - Have no side effects |
| 95 | + - Don't depend on external services |
| 96 | + - Can be easily tested in isolation |
| 97 | +- Examples include: |
| 98 | + - Date formatting functions |
| 99 | + - String manipulation helpers |
| 100 | + - Calculation utilities |
| 101 | +- The `lib` directory is for more complex functionality that often: |
| 102 | + - Interfaces with external services |
| 103 | + - Contains business logic |
| 104 | + - Manages state or side effects |
| 105 | +- Common examples include: |
| 106 | + - API client configurations |
| 107 | + - Authentication helpers |
| 108 | + - Database connections |
| 109 | + |
| 110 | +### 2.4. State management and models |
| 111 | + |
| 112 | +When using state management solutions like Zustand, organize your store files logically: |
| 113 | + |
| 114 | +```text |
| 115 | +src/ |
| 116 | +├── store/ |
| 117 | +│ ├── auth.store.ts |
| 118 | +│ ├── user.store.ts |
| 119 | +│ └── theme.store.ts |
| 120 | +└── models/ |
| 121 | + ├── user.model.ts |
| 122 | + └── product.model.ts |
| 123 | +``` |
| 124 | + |
| 125 | +- Store organization: each store file should: |
| 126 | + - Focus on a specific domain |
| 127 | + - Export a single store instance |
| 128 | + - Include related actions and selectors |
| 129 | +- The `models` directory contains TypeScript interfaces and type definitions that are used across your application: |
| 130 | + |
| 131 | +```ts |
| 132 | +// user.model.ts |
| 133 | +export interface User { |
| 134 | + id: string |
| 135 | + email: string |
| 136 | + name: string |
| 137 | + role: "user" | "admin" |
| 138 | +} |
| 139 | +``` |
| 140 | + |
| 141 | +### 2.5. Styling organization |
| 142 | + |
| 143 | +```text |
| 144 | +src/ |
| 145 | +├── styles/ |
| 146 | +│ ├── global.css |
| 147 | +│ ├── variables.css |
| 148 | +│ └── themes/ |
| 149 | +│ ├── light.css |
| 150 | +│ └── dark.css |
| 151 | +└── components/ |
| 152 | + └── Button/ |
| 153 | + ├── Button.tsx |
| 154 | + └── Button.module.css |
| 155 | +``` |
| 156 | + |
| 157 | +- Keep global styles, variables, and theme definitions in the `styles` directory. |
| 158 | +- For component-specific styles: |
| 159 | + - Use CSS Modules alongside component files. |
| 160 | + - Name them matching the component (e.g., Button.module.css for Button.tsx). |
| 161 | + - Keep them in the same folder as the component. |
0 commit comments