Frontend - Bố cục dự án Next.js

Bài viết trước giới thiệu kiến trúc tổng thể gồm 2 tầng: Frontend (Next.js) và Backend (Firebase). Bài này đi sâu vào tầng Frontend — giải thích cách bố cục và tổ chức một dự án Next.js theo 3 nhóm chính: Pages, Components và Services.

Dành cho ai? Bạn không cần biết code. Bài viết giải thích bằng ngôn ngữ đời thường, dùng ví dụ thực tế từ ứng dụng quản lý công việc (task management). Mục tiêu: giúp bạn hiểu cấu trúc dự án để mô tả yêu cầu cho Claude Code chính xác hơn.

Tổng quan: 3 nhóm chính trong dự án Next.js

Mọi dự án Next.js đều được tổ chức thành 3 nhóm rõ ràng, mỗi nhóm có vai trò riêng:

Pages

Các trang giao diệnMỗi trang = một URL. Người dùng truy cập trực tiếp.

Components

Khối xây dựng giao diệnMảnh ghép tái sử dụng: nút bấm, form, card, bảng dữ liệu.

Services

Kết nối dữ liệuCode giao tiếp với Firebase: đọc/ghi database, đăng nhập, upload file.

Phép so sánh — Xây nhà:

Pages = Các phòng trong nhà (phòng khách, phòng ngủ, nhà bếp)
Components = Nội thất (bàn, ghế, tủ — có thể dùng ở nhiều phòng)
Services = Hệ thống kỹ thuật (điện, nước, internet — chạy ngầm phục vụ cả nhà)

Cấu trúc thư mục tổng thể

├── 📁 app/
│   ├── 📁 api/
│   │   └── 📄 notifications/
│   │       └── 📄 route.ts
│   ├── 📁 crm/
│   │   └── 📄 page.tsx
│   ├── 📁 login/
│   │   └── 📄 page.tsx
│   ├── 📁 tasks/
│   │   └── 📄 page.tsx
│   ├── 📄 favicon.ico
│   ├── 🎨 globals.css
│   ├── 📄 layout.tsx
│   └── 📄 page.tsx
├── 📁 components/
│   ├── 📁 ui/
│   │   ├── 📄 alert-dialog.tsx
│   │   ├── 📄 badge.tsx
│   │   ├── 📄 button.tsx
│   │   ├── 📄 card.tsx
│   │   ├── 📄 dialog.tsx
│   │   ├── 📄 input.tsx
│   │   ├── 📄 label.tsx
│   │   ├── 📄 select.tsx
│   │   └── 📄 table.tsx
│   └── 📄 theme-provider.tsx
├── 📁 features/
│   ├── 📁 crm/
│   ├── 📁 documents/
│   ├── 📁 hrm/
│   └── 📁 tasks/
│       ├── 📁 components/
│       │   ├── 📄 delete-task-dialog.tsx
│       │   ├── 📄 task-form-dialog.tsx
│       │   ├── 📄 tasks-table.tsx
│       │   └── 📄 tasks-toolbar.tsx
│       ├── 📁 hooks/
│       │   └── 📄 use-tasks.ts
│       └── 📁 services/
│           ├── 📄 charts.ts
│           ├── 📄 create-task.ts
│           ├── 📄 delete-task.ts
│           ├── 📄 edit-task.ts
│           └── 📄 get-tasks.ts
├── 📁 lib/
│   ├── 📄 firebase.ts
│   └── 📄 utils.ts
├── ⚙️ .gitignore
├── ⚙️ components.json
├── 📄 next.config.ts
├── ⚙️ package.json
├── 📄 postcss.config.mjs
└── ⚙️ tsconfig.json

Mỗi nhóm thư mục giải quyết một bài toán khác nhau. Khi cần thay đổi giao diện nút bấm → vào components/ui/. Khi cần thêm trang mới → vào app/. Khi cần sửa cách đọc dữ liệu → vào features/tasks/services/.

1. Pages — Các trang giao diện

Pages là gì?

Pages là các trang mà người dùng truy cập qua URL. Trong Next.js, mỗi file page.tsx trong thư mục app/ tạo ra một URL tương ứng.

Phép so sánh: Pages giống các phòng trong nhà. Phòng khách (trang chủ), phòng làm việc (dashboard), phòng hồ sơ (danh sách tasks). Mỗi phòng có địa chỉ riêng (URL) và mục đích riêng.

Cấu trúc thư mục trình bày các trang (pages)

├── 📁 app/
│   ├── 📁 api/
│   │   └── 📄 notifications/
│   │       └── 📄 route.ts       ← API endpoint (chạy trên server)
│   ├── 📁 crm/
│   │   └── 📄 page.tsx           ← /crm
│   ├── 📁 login/
│   │   └── 📄 page.tsx           ← /login
│   ├── 📁 tasks/
│   │   └── 📄 page.tsx           ← /tasks
│   ├── 📄 favicon.ico
│   ├── 🎨 globals.css             ← Styles toàn cục
│   ├── 📄 layout.tsx             ← Layout gốc (áp dụng mọi trang)
│   └── 📄 page.tsx               ← / (trang chủ)

Giải thích các khái niệm trong Pages

Tên thư mục = URL

Quy tắc đơn giản: cấu trúc thư mục chính là URL.

Thư mục	URL
`app/page.tsx`	`/` (trang chủ)
`app/login/page.tsx`	`/login`
`app/tasks/page.tsx`	`/tasks`
`app/crm/page.tsx`	`/crm`

Không cần cấu hình routing — thêm thư mục mới = có URL mới.

[id] — Trang động (Dynamic Route)

Dấu ngoặc vuông [id] tạo trang dùng cho nhiều URL khác nhau. Thay vì tạo riêng 1 trang cho mỗi task, bạn tạo 1 trang duy nhất hiển thị nội dung theo ID.

app/tasks/[id]/page.tsx

→ yourapp.com/tasks/task_001    ← Hiển thị task "Làm báo cáo Q1"
→ yourapp.com/tasks/task_002    ← Hiển thị task "Review thiết kế"
→ yourapp.com/tasks/task_003    ← Hiển thị task "Họp với khách hàng"

Cùng 1 file page.tsx nhưng hiển thị nội dung khác nhau dựa trên id trong URL.

(auth) — Nhóm route (Route Group)

Dấu ngoặc tròn (auth) tạo nhóm logic nhưng không ảnh hưởng URL.

app/(auth)/login/page.tsx   → yourapp.com/login      (không có /auth/)
app/(auth)/register/page.tsx → yourapp.com/register   (không có /auth/)

Dùng để nhóm các trang liên quan (ví dụ tất cả trang xác thực) mà không thêm thư mục phụ vào URL. Giúp project gọn gàng hơn.

layout.tsx — Khung chung cho nhiều trang

Layout là phần giao diện bao bọc các trang con, giữ nguyên khi chuyển trang.

app/layout.tsx           ← Layout gốc: Header, font, theme (áp dụng tất cả trang)

Ví dụ: Khi người dùng chuyển từ /tasks sang /crm, layout gốc (header, sidebar, theme) giữ nguyên — chỉ phần nội dung chính thay đổi.

┌──────────────────────────────────────────┐
│  Header (logo, thông báo, avatar)        │ ← layout.tsx (gốc)
├──────────┬───────────────────────────────┤
│          │                               │
│ Sidebar  │   Nội dung trang              │
│          │   (thay đổi theo URL)         │
│          │                               │
│ - Tasks  │                               │
│ - CRM    │                               │
│          │                               │
└──────────┴───────────────────────────────┘

api/ — Backend nhẹ trong cùng dự án

Thư mục api/ cho phép tạo API endpoint ngay trong dự án Next.js. Code này chạy trên server (Vercel), không lộ ra trình duyệt — phù hợp cho logic cần giữ bí mật.

Khi nào dùng API Route	Khi nào dùng Firebase trực tiếp
Cần giấu API key bí mật	Đọc/ghi dữ liệu Firestore
Gọi dịch vụ thanh toán (Stripe, VNPay)	Đăng nhập/đăng ký
Gọi AI (Claude, OpenAI)	Upload file lên Storage
Gửi email (Resend, SendGrid)	Lắng nghe realtime

Mỗi Page chứa gì?

Một file page.tsx thường chứa 3 phần:

┌─────────────────────────────────┐
│  1. Lấy dữ liệu                │  ← Gọi Hook (useTasks) để đọc từ Firebase
│     (getTasks, getUsers)        │
├─────────────────────────────────┤
│  2. Ghép các Components         │  ← Lắp ráp từ feature components
│     TasksToolbar                │
│     TasksTable data={tasks}     │
│     TaskFormDialog              │
├─────────────────────────────────┤
│  3. Trả về giao diện hoàn chỉnh│  ← Next.js hiển thị trang
└─────────────────────────────────┘

Page không tự vẽ giao diện chi tiết. Nó dùng Hook để lấy dữ liệu, rồi ghép các Components lại thành trang hoàn chỉnh — giống người quản lý sắp xếp nội thất vào phòng.

2. Components — Khối xây dựng giao diện

Components là gì?

Components là mảnh ghép giao diện có thể tái sử dụng. Tạo một lần, ghép vào nhiều trang khác nhau, và khi sửa thì chỉ cần sửa ở một chỗ.

Phép so sánh: Components giống nội thất trong nhà. Một chiếc bàn (component Table) có thể đặt ở phòng khách, phòng ăn, hoặc phòng làm việc. Nếu muốn đổi kiểu bàn, bạn thay 1 lần — các phòng tự cập nhật.

Cấu trúc thư mục Components

Dự án chia components thành 2 nơi với vai trò khác nhau:

components/                          ← 🎨 Components cơ bản (dùng chung toàn app)
├── ui/                              ← Từ shadcn/ui
│   ├── alert-dialog.tsx             ← Hộp thoại cảnh báo
│   ├── badge.tsx                    ← Nhãn trạng thái
│   ├── button.tsx                   ← Nút bấm
│   ├── card.tsx                     ← Thẻ chứa nội dung
│   ├── dialog.tsx                   ← Hộp thoại (modal/popup)
│   ├── input.tsx                    ← Ô nhập liệu
│   ├── label.tsx                    ← Nhãn cho input
│   ├── select.tsx                   ← Dropdown chọn
│   └── table.tsx                    ← Bảng dữ liệu
└── theme-provider.tsx               ← Quản lý dark/light theme

features/tasks/components/           ← 📋 Components riêng cho tính năng Tasks
├── delete-task-dialog.tsx           ← Hộp thoại xác nhận xóa task
├── task-form-dialog.tsx             ← Form tạo/sửa task (dạng dialog)
├── tasks-table.tsx                  ← Bảng danh sách tasks
└── tasks-toolbar.tsx                ← Thanh công cụ (tìm kiếm, lọc, nút thêm)

Phân biệt 2 nơi chứa components:

components/ui/ → Viên gạch cơ bản, không biết nghiệp vụ (Button chỉ là nút bấm)
features/tasks/components/ → Khối nghiệp vụ, hiểu dữ liệu task (TasksTable biết cách hiển thị danh sách tasks)

2 loại Components

UI Components (components/ui/) — Viên gạch cơ bản

Đây là các component nhỏ nhất, đơn giản nhất — nút bấm, ô input, badge, dropdown. Lấy từ thư viện shadcn/ui (bộ component có sẵn, được tùy biến theo dự án).

Component	File	Công dụng
AlertDialog	`alert-dialog.tsx`	Hộp thoại cảnh báo (xác nhận xóa)
Badge	`badge.tsx`	Nhãn nhỏ (In Progress, Completed)
Button	`button.tsx`	Nút bấm (Lưu, Xóa, Thêm mới)
Card	`card.tsx`	Thẻ chứa nội dung
Dialog	`dialog.tsx`	Popup/modal (form tạo task)
Input	`input.tsx`	Ô nhập liệu (tiêu đề, mô tả)
Label	`label.tsx`	Nhãn cho ô nhập liệu
Select	`select.tsx`	Dropdown (chọn trạng thái, chọn người)
Table	`table.tsx`	Bảng dữ liệu (danh sách tasks)

Đặc điểm: Không biết gì về nghiệp vụ — Button chỉ biết nó là nút bấm, không biết bấm để làm gì. Tính năng do component cha quyết định.Ngoài ra, theme-provider.tsx quản lý chuyển đổi dark/light theme cho toàn ứng dụng.

Feature Components (features/tasks/components/) — Khối nghiệp vụ

Feature components ghép nhiều UI components lại để tạo thành một khối chức năng cụ thể. Chúng hiểu nghiệp vụ, biết dữ liệu trông như thế nào.

Component	File	Công dụng
TasksTable	`tasks-table.tsx`	Bảng danh sách tasks (dùng `Table`, `Badge`, `Button`)
TasksToolbar	`tasks-toolbar.tsx`	Thanh công cụ: tìm kiếm, lọc, nút thêm task
TaskFormDialog	`task-form-dialog.tsx`	Form tạo/sửa task bên trong Dialog
DeleteTaskDialog	`delete-task-dialog.tsx`	Hộp thoại xác nhận xóa task

Ví dụ — TaskFormDialog ghép từ nhiều UI components:

┌──────────────────────────────────────┐
│  Tạo task mới                        │  ← Dialog title
│                                      │
│  Tiêu đề:  [________________]        │  ← Input + Label
│  Mô tả:    [________________]        │  ← Input + Label
│  Phụ trách: [Chọn người ▼]           │  ← Select
│  Trạng thái: [Todo ▼]               │  ← Select
│                                      │
│            [Hủy]  [Lưu]             │  ← Buttons
└──────────────────────────────────────┘

Ví dụ — TasksToolbar ghép từ nhiều UI components:

┌──────────────────────────────────────────────────┐
│  🔍 [Tìm kiếm...] [Trạng thái ▼] [+ Thêm task] │
└──────────────────────────────────────────────────┘
│       Input            Select         Button     │

Components lồng nhau — Xây từ nhỏ đến lớn

Components được ghép lồng vào nhau từ đơn giản đến phức tạp, tạo thành giao diện hoàn chỉnh: Đọc từ trên xuống:

Page (app/tasks/page.tsx) sử dụng Layout gốc (layout.tsx)
Page ghép Feature components (TasksToolbar, TasksTable, TaskFormDialog)
Mỗi Feature component bên trong sử dụng các UI components (Button, Table, Badge, Dialog)

3. Services — Kết nối dữ liệu

Services là gì?

Services là code giao tiếp với Firebase (hoặc bất kỳ nguồn dữ liệu nào). Chúng chứa các hàm đọc/ghi dữ liệu mà Hooks và Components gọi đến khi cần.

Phép so sánh: Services giống hệ thống kỹ thuật trong nhà — đường ống nước, dây điện, đường dây internet. Bạn không nhìn thấy chúng, nhưng khi vặn vòi nước (bấm nút lấy dữ liệu) thì nước chảy (dữ liệu hiện ra). Nếu cần sửa ống nước, bạn sửa ở hệ thống kỹ thuật — không cần đập tường phòng khách.

Cấu trúc thư mục Services

Trong dự án này, services nằm bên trong thư mục feature, không phải ở cấp gốc:

features/tasks/services/             ← 🔌 Services riêng cho tính năng Tasks
├── charts.ts                        ← Dữ liệu cho biểu đồ thống kê
├── create-task.ts                   ← Tạo task mới
├── delete-task.ts                   ← Xóa task
├── edit-task.ts                     ← Cập nhật task
└── get-tasks.ts                     ← Lấy danh sách tasks

lib/                                 ← 🛠️ Thư viện dùng chung
├── firebase.ts                      ← Cấu hình kết nối Firebase (khởi tạo 1 lần)
└── utils.ts                         ← Hàm tiện ích dùng chung

Tổ chức theo feature: Thay vì gom tất cả services vào 1 thư mục services/ ở gốc, dự án này đặt services cạnh components và hooks của cùng tính năng. Cách này giúp mỗi feature (tasks, crm, hrm) hoạt động như một module độc lập.

Mỗi Service chứa gì?

Mỗi file service chứa một hàm thực hiện một thao tác cụ thể. Ví dụ cho tính năng Tasks:

File	Công dụng
`get-tasks.ts`	Lấy danh sách tasks từ Firestore
`create-task.ts`	Tạo task mới, ghi vào Firestore
`edit-task.ts`	Cập nhật 1 task (đổi trạng thái, sửa tiêu đề)
`delete-task.ts`	Xóa 1 task
`charts.ts`	Lấy dữ liệu thống kê cho biểu đồ

Chi tiết từng nhóm

lib/firebase.ts — Khởi tạo kết nối

File này chạy một lần duy nhất khi ứng dụng khởi động. Nó đọc thông tin cấu hình từ biến môi trường (.env.local) và tạo kết nối đến Firebase.

.env.local (file cấu hình):
NEXT_PUBLIC_FIREBASE_API_KEY=AIzaSy...
NEXT_PUBLIC_FIREBASE_PROJECT_ID=my-task-app
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=my-task-app.firebaseapp.com
...

      ↓ firebase.ts đọc các biến này

Tạo kết nối → Firestore (database)
Tạo kết nối → Authentication (đăng nhập)
Tạo kết nối → Storage (file)

Các service files import kết nối từ lib/firebase.ts để sử dụng.

features/tasks/services/ — CRUD tasks

Mỗi file xử lý một thao tác riêng biệt:

File	Hàm chính	Ai gọi?
`get-tasks.ts`	Lấy danh sách tasks	Hook `useTasks()`
`create-task.ts`	Tạo task mới vào Firestore	`TaskFormDialog` khi bấm Lưu
`edit-task.ts`	Cập nhật task	`TaskFormDialog` khi sửa
`delete-task.ts`	Xóa task	`DeleteTaskDialog` khi xác nhận
`charts.ts`	Dữ liệu biểu đồ	Trang thống kê

app/api/notifications/route.ts — API Route

File route.ts trong thư mục api/ tạo API endpoint chạy trên server (Vercel). Code này không lộ ra trình duyệt — phù hợp cho logic cần giữ bí mật.

Khi nào dùng API Route	Khi nào gọi Firebase trực tiếp
Cần giấu API key bí mật	Đọc/ghi dữ liệu Firestore
Gửi push notification	Đăng nhập/đăng ký
Gọi dịch vụ bên ngoài (email, AI)	Upload file lên Storage

Tại sao tách riêng Services?

Không tách (code lẫn lộn)	Tách riêng Services
Code đọc Firebase nằm rải rác khắp nơi	Code Firebase tập trung trong `features/*/services/`
Đổi database → sửa hàng chục file	Đổi database → chỉ sửa file service
Khó tìm lỗi khi dữ liệu sai	Dễ debug: lỗi dữ liệu → mở service tương ứng
Claude Code viết code lặp lại	Claude Code tái sử dụng hàm có sẵn

4. Hooks — Logic tái sử dụng

Hooks là đoạn logic mà nhiều components cùng cần, được gói gọn vào hàm riêng để tái sử dụng. Trong dự án này, hooks nằm trong thư mục feature:

features/tasks/hooks/
└── use-tasks.ts      ← Quản lý dữ liệu tasks
                         (danh sách tasks, loading, lỗi, refetch)

Hook useTasks làm gì? Nó gọi service get-tasks.ts bên trong, rồi bổ sung quản lý loading state, error handling. Khi trang Tasks cần dữ liệu, chỉ cần gọi useTasks() — có ngay danh sách tasks kèm trạng thái loading.

Khi dự án lớn hơn, mỗi feature sẽ có thêm hooks riêng. Ví dụ features/crm/hooks/use-customers.ts cho tính năng CRM.

Cách các nhóm phối hợp với nhau

Đây là phần quan trọng: Pages, Components, Hooks và Services không hoạt động độc lập — chúng phối hợp theo luồng rõ ràng.

Luồng hiển thị trang danh sách tasks

Luồng tạo task mới

Quy tắc phối hợp

Quy tắc	Giải thích
Page gọi Hook	Page dùng Hook (`useTasks`) để lấy dữ liệu, truyền vào Components
Hook gọi Service	Hook gọi service (`get-tasks.ts`) và quản lý loading/error
Component gọi Service	Component tương tác (form, nút xóa) gọi Service để ghi dữ liệu
Component không gọi Firebase trực tiếp	Mọi giao tiếp với Firebase đều đi qua Service
Service không biết giao diện	Service chỉ lo dữ liệu, không biết dữ liệu hiển thị thế nào
UI Component không biết nghiệp vụ	Button không biết bấm để tạo task hay xóa project

Ví dụ thực tế: Trang danh sách tasks

Gộp tất cả lại, đây là cách trang danh sách tasks được “lắp ráp”:

📄 app/tasks/page.tsx
│
│  Gọi Hook: useTasks() → lấy danh sách tasks + loading + error
│
│  Truyền dữ liệu vào Feature Components:
│
├── 🧩 TasksToolbar (features/tasks/components/tasks-toolbar.tsx)
│   ├── Input: Tìm kiếm theo tiêu đề
│   ├── Select: Lọc trạng thái (Tất cả / Đang làm / Hoàn thành)
│   └── Button: "Thêm task"
│       └── onClick → Mở TaskFormDialog
│
├── 🧩 TasksTable (features/tasks/components/tasks-table.tsx)
│   ├── Dòng 1: task "Làm báo cáo Q1"
│   │   ├── Badge: "In Progress"
│   │   ├── Text: "30/04/2026"
│   │   └── Buttons: [Sửa] [Xóa]
│   ├── Dòng 2: task "Review thiết kế"
│   └── Dòng 3: ...
│
├── 🧩 TaskFormDialog (features/tasks/components/task-form-dialog.tsx)
│   │  (Dialog — ẩn, hiện khi bấm "Thêm task" hoặc "Sửa")
│   ├── Input + Label: Tiêu đề
│   ├── Input + Label: Mô tả
│   ├── Select: Người phụ trách
│   ├── Select: Trạng thái
│   └── Buttons: [Hủy] [Lưu]
│       └── onSave → Gọi Service: create-task.ts hoặc edit-task.ts
│
└── 🧩 DeleteTaskDialog (features/tasks/components/delete-task-dialog.tsx)
    │  (Dialog — hiện khi bấm "Xóa")
    └── onConfirm → Gọi Service: delete-task.ts

Mô tả cho Claude Code

Khi bạn hiểu cấu trúc Pages / Components / Services, việc mô tả yêu cầu cho Claude Code trở nên chính xác hơn: Thêm trang mới:

"Tạo trang /reports tại app/reports/page.tsx.
Trang này hiển thị thống kê: tổng số tasks, tỷ lệ hoàn thành, tasks quá hạn.
Lấy dữ liệu từ features/tasks/services/charts.ts."

Thêm feature component:

"Tạo component TaskKanban trong features/tasks/components/task-kanban.tsx.
Hiển thị tasks dạng kanban board với 3 cột: Todo, In Progress, Completed.
Cho phép kéo-thả task giữa các cột.
Khi kéo-thả → gọi edit-task.ts từ features/tasks/services/ để cập nhật status."

Thêm feature mới (CRM):

"Tạo feature CRM trong features/crm/ với cấu trúc:
- features/crm/components/ cho components
- features/crm/hooks/ cho hooks
- features/crm/services/ cho services
Tương tự cách features/tasks/ đang tổ chức."

Câu hỏi thường gặp

Khi nào thì tạo component mới, khi nào viết thẳng trong page?

Tạo component riêng khi:

Code đó sẽ dùng lại ở 2 nơi trở lên
Khối giao diện phức tạp (nhiều hơn 30-40 dòng)
Muốn tách isolate logic (form, bảng, bộ lọc)

Viết thẳng trong page khi:

Code đơn giản, chỉ dùng 1 lần
Chỉ là vài dòng ghép components có sẵn

Khi không chắc → bắt đầu viết trong page, tách ra sau khi thấy cần tái sử dụng.

Tại sao tách services ra khỏi components?

Lý do 1 — Tái sử dụng: Nhiều components cùng cần gọi getTasks(). Nếu code nằm trong component, phải copy-paste.Lý do 2 — Dễ thay đổi: Nếu sau này chuyển từ Firebase sang Supabase, bạn chỉ sửa file service — không cần sửa bất kỳ component nào.Lý do 3 — Dễ test: Service có thể được test độc lập, không cần render giao diện.

Thư mục hooks/ khác gì services/?

Tiêu chí	`features/*/services/`	`features/*/hooks/`
Loại hàm	Hàm thuần túy, gọi Firebase	Hàm React, quản lý state giao diện
Ví dụ	`get-tasks.ts` trả về data	`use-tasks.ts` trả về data + loading + error
Dùng ở đâu	Bất cứ đâu	Chỉ trong React components

Thực tế: hooks gọi services. Hook useTasks() bên trong gọi service get-tasks.ts, rồi bổ sung quản lý loading state, error handling.

Claude Code có tự tổ chức thư mục đúng không?

Claude Code biết các quy ước tổ chức thư mục Next.js tiêu chuẩn. Khi bạn mô tả rõ tính năng, Claude Code sẽ tự tạo file ở đúng vị trí.Tuy nhiên, ban đầu nên yêu cầu Claude Code thiết lập cấu trúc thư mục trước:

"Tạo cấu trúc thư mục chuẩn cho dự án:
- app/ cho pages
- components/ui/ cho shadcn components
- features/ chia theo tính năng, mỗi feature có components/, hooks/, services/
- lib/ cho cấu hình chung (firebase.ts, utils.ts)"

Sau đó, mỗi lần thêm tính năng, Claude Code sẽ đặt file vào đúng thư mục.

Tóm tắt

┌──────────────────────────────────────────────────────┐
│              CẤU TRÚC DỰ ÁN NEXT.JS                 │
├──────────────────────────────────────────────────────┤
│                                                      │
│  📄 PAGES (app/)                                     │
│  ├── Mỗi file page.tsx = 1 trang (1 URL)            │
│  ├── /tasks, /crm, /login                           │
│  ├── Gọi Hooks để lấy dữ liệu                      │
│  └── layout.tsx = khung chung (header, theme)       │
│                                                      │
│  🧩 UI COMPONENTS (components/ui/)                   │
│  ├── Button, Input, Badge, Table (viên gạch cơ bản) │
│  └── Từ shadcn/ui — không biết nghiệp vụ            │
│                                                      │
│  📦 FEATURES (features/)                             │
│  ├── tasks/components/ → TasksTable, TaskFormDialog  │
│  ├── tasks/hooks/      → useTasks                    │
│  ├── tasks/services/   → get-tasks, create-task, ... │
│  └── crm/, hrm/, documents/ (các feature khác)      │
│                                                      │
│  🛠️ LIB (lib/)                                       │
│  ├── firebase.ts: khởi tạo kết nối                  │
│  └── utils.ts: hàm tiện ích dùng chung              │
│                                                      │
└──────────────────────────────────────────────────────┘

Điểm mấu chốt: Dự án Next.js được tổ chức theo nguyên tắc feature-based — mỗi tính năng (tasks, crm) gom components, hooks và services vào cùng một thư mục. UI components dùng chung nằm trong components/ui/, cấu hình chung nằm trong lib/. Hiểu cấu trúc này giúp bạn mô tả yêu cầu cho Claude Code chính xác hơn — biết cần thêm component ở đâu, sửa service nào, tạo page mới ra sao.

Thực hành tạo dự án

Phần này hướng dẫn bạn tạo một dự án quản lý công việc từ đầu — từ khởi tạo dự án Next.js đến kết nối Firebase. Mỗi bước kèm prompt mẫu để bạn gửi cho Claude Code.

Khởi tạo dự án

Mở Terminal (trong VS code) và chạy lệnh sau để tạo dự án Next.js với shadcn/ui:

npx shadcn@latest init --preset b0 --template next

Lệnh này tự động tạo thư mục dự án với cấu trúc Next.js + shadcn/ui đã cấu hình sẵn.

Mở dự án trong VS Code

Trong VS Code, chọn File → Open Folder và mở thư mục vừa tạo ở bước trước.

Chạy dự án

Mở Terminal trong VS Code và chạy:

npm run dev

Truy cập http://localhost:3000 để xem kết quả.

Tạo trang login

Gửi prompt sau cho Claude Code:

Tôi đang dùng Next.js và bộ thư viện component có tên là shadcn.

Hãy tạo cho tôi trang (page) login.

Claude Code sẽ tạo file app/login/page.tsx với form đăng nhập sử dụng các UI components từ shadcn/ui.

Tạo trang quản lý công việc

Gửi prompt sau cho Claude Code:

Dùng shadcn + react-table, hãy làm cho tôi 1 page quản lý công việc /tasks
Gồm:
1. Danh sách công việc
2. Có 1 nút bấm (button) để mở 1 cửa sổ (Dialog) để thêm mới công việc
3. Cuối mỗi dòng có 2 buttons:
  - Edit button
  - Delete button (Alert Dialog: Destructive) để xác nhận lại người dùng

Yêu cầu về dữ liệu:
mock data: id, title, status: To do | In progress | Done, priority: Low | Normal | High | Urgent, dueDate.

Ở bước này Claude Code sẽ tạo trang với mock data (dữ liệu mẫu giả). Bước 7 sẽ thay thế bằng dữ liệu thật từ Firebase.

Chuẩn hóa components theo feature

Sau khi trang tasks hoạt động, yêu cầu Claude Code tách code thành các feature components riêng biệt:

Tôi có các components tại features/tasks/components/ đang để trống,
bạn hãy components hóa vào từng files cho tôi.

Các component gồm:
├── delete-task-dialog.tsx
├── task-form-dialog.tsx
├── tasks-table.tsx
└── tasks-toolbar.tsx

Claude Code sẽ tách code từ page.tsx ra thành các component riêng theo cấu trúc feature-based đã giới thiệu ở phần trước.

Kết nối Firebase

Trước tiên, tạo dự án Firebase:

Truy cập Firebase Console
Tạo project mới, đặt tên: claude-code-tasks-management
Tạo Firestore Database
Vào Project Settings → General → Your apps → Web và thêm web app
Copy các thông số config

Sau đó gửi prompt cho Claude Code:

Tôi dùng Firebase, tôi có thông tin cấu hình như sau:

const firebaseConfig = {
  apiKey: "...",
  authDomain: "...",
  projectId: "...",
  storageBucket: "...",
  messagingSenderId: "...",
  appId: "..."
};

Hãy thiết lập kết nối với Firebase.

Sau đó, hãy thiết lập services tại features/tasks/services/
Làm việc trực tiếp với Firebase Firestore (tasks collection).

Thay "..." bằng giá trị thật từ Firebase Console. Claude Code sẽ tạo lib/firebase.ts để khởi tạo kết nối và các service files trong features/tasks/services/ để thay thế mock data bằng dữ liệu thật từ Firestore.

Tổng quan

Tạo tài khoản và thiết lập

Development tools

Kiến thức nền tảng

Công nghệ

Kiến trúc phần mềm

Thực chiến

Frontend - Bố cục dự án Next.js

Tổng quan: 3 nhóm chính trong dự án Next.js

Pages

Components

Services

Cấu trúc thư mục tổng thể

1. Pages — Các trang giao diện

Pages là gì?

Cấu trúc thư mục trình bày các trang (pages)

Giải thích các khái niệm trong Pages

Mỗi Page chứa gì?

2. Components — Khối xây dựng giao diện

Components là gì?

Cấu trúc thư mục Components

2 loại Components

Components lồng nhau — Xây từ nhỏ đến lớn

3. Services — Kết nối dữ liệu

Services là gì?

Cấu trúc thư mục Services

Mỗi Service chứa gì?

Chi tiết từng nhóm

Tại sao tách riêng Services?

4. Hooks — Logic tái sử dụng

Cách các nhóm phối hợp với nhau

Luồng hiển thị trang danh sách tasks

Luồng tạo task mới

Quy tắc phối hợp

Ví dụ thực tế: Trang danh sách tasks

Mô tả cho Claude Code

Câu hỏi thường gặp

Tóm tắt

Thực hành tạo dự án

​Tổng quan: 3 nhóm chính trong dự án Next.js

Pages

Components

Services

​Cấu trúc thư mục tổng thể

​1. Pages — Các trang giao diện

​Pages là gì?

​Cấu trúc thư mục trình bày các trang (pages)

​Giải thích các khái niệm trong Pages

​Mỗi Page chứa gì?

​2. Components — Khối xây dựng giao diện

​Components là gì?

​Cấu trúc thư mục Components

​2 loại Components

​Components lồng nhau — Xây từ nhỏ đến lớn

​3. Services — Kết nối dữ liệu

​Services là gì?

​Cấu trúc thư mục Services

​Mỗi Service chứa gì?

​Chi tiết từng nhóm

​Tại sao tách riêng Services?

​4. Hooks — Logic tái sử dụng

​Cách các nhóm phối hợp với nhau

​Luồng hiển thị trang danh sách tasks

​Luồng tạo task mới

​Quy tắc phối hợp

​Ví dụ thực tế: Trang danh sách tasks

​Mô tả cho Claude Code

​Câu hỏi thường gặp

​Tóm tắt

​Thực hành tạo dự án

Tổng quan: 3 nhóm chính trong dự án Next.js

Cấu trúc thư mục tổng thể

1. Pages — Các trang giao diện

Pages là gì?

Cấu trúc thư mục trình bày các trang (pages)

Giải thích các khái niệm trong Pages

Mỗi Page chứa gì?

2. Components — Khối xây dựng giao diện

Components là gì?

Cấu trúc thư mục Components

2 loại Components

Components lồng nhau — Xây từ nhỏ đến lớn

3. Services — Kết nối dữ liệu

Services là gì?

Cấu trúc thư mục Services

Mỗi Service chứa gì?

Chi tiết từng nhóm

Tại sao tách riêng Services?

4. Hooks — Logic tái sử dụng

Cách các nhóm phối hợp với nhau

Luồng hiển thị trang danh sách tasks

Luồng tạo task mới

Quy tắc phối hợp

Ví dụ thực tế: Trang danh sách tasks

Mô tả cho Claude Code

Câu hỏi thường gặp

Tóm tắt

Thực hành tạo dự án