Khởi tạo Next.js admin dashboard với shadcn/ui

Mục tiêu bài viết

Sau bài này, bạn sẽ tạo được một dự án Next.js admin dashboard có:

Next.js App Router, TypeScript và Tailwind CSS
shadcn/ui được cấu hình bằng preset b0
Toàn bộ UI components chính thức của shadcn/ui
Layout admin gồm sidebar, header, dashboard overview, bảng dữ liệu, form, dialog, chart và settings
Prompt rõ ràng để giao Claude Code triển khai từng phần

shadcn/ui không hoạt động như một thư viện UI đóng gói sẵn. CLI sẽ copy mã nguồn component vào dự án của bạn để bạn chỉnh sửa trực tiếp.

Phần 1: Khởi tạo dự án Next.js bằng shadcn CLI

Bạn có hai cách khởi tạo.

Dùng lệnh CLI
Dùng shadcn/create

Chạy lệnh sau trong thư mục bạn muốn tạo dự án:

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

Lệnh này dùng shadcn CLI để scaffold một dự án Next.js và áp dụng preset b0.

Truy cập trang create của shadcn:

https://ui.shadcn.com/create?template=next

Chọn cấu hình giao diện, màu sắc, font, icon và framework Next.js. Sau đó copy lệnh được tạo ra và chạy trong terminal.

Theo tài liệu shadcn/ui hiện tại, init có thể tạo project mới với --template next, còn --preset dùng để áp dụng cấu hình design system.

Phần 2: Chạy dự án

Sau khi khởi tạo xong, vào thư mục dự án và chạy development server:

Mở VS Code và mở thư mục dự án
Mở terminal trong VS Code
Chạy lệnh sau và nhấn Enter:

npm run dev

Terminal hiển thị, thường là:

http://localhost:3000

Phần 3: Thêm toàn bộ shadcn/ui components

Chạy lệnh sau trong thư mục project:

npx shadcn@latest add --all

Lệnh này thêm toàn bộ component có sẵn từ registry chính thức của shadcn/ui vào dự án.

Không nên chạy add --all cho production app nếu bạn chỉ cần vài component. Với bài thực hành dashboard, lệnh này hữu ích vì bạn muốn có đầy đủ component để Claude Code dùng khi xây giao diện.

Bạn cũng có thể thêm từng nhóm component nếu muốn kiểm soát tốt hơn:

npx shadcn@latest add sidebar breadcrumb navigation-menu menubar tabs pagination separator scroll-area resizable collapsible

Phần 4: Cấu trúc admin dashboard chuẩn

Một admin dashboard nên có các phần sau:

Khu vực	Chức năng	shadcn/ui components nên dùng
App shell	Khung tổng thể của ứng dụng	`Sidebar`, `Separator`, `Scroll Area`, `Resizable`
Sidebar	Menu điều hướng chính	`Sidebar`, `Collapsible`, `Dropdown Menu`, `Avatar`
Header	Search, notification, user menu	`Input`, `Button`, `Popover`, `Dropdown Menu`, `Avatar`
Overview	Chỉ số tổng quan	`Card`, `Badge`, `Chart`, `Progress`
Data table	Danh sách users, orders, tasks	`Table`, `Data Table`, `Checkbox`, `Pagination`, `Dropdown Menu`
Form	Tạo và sửa dữ liệu	`Field`, `Input`, `Textarea`, `Select`, `Switch`, `Calendar`
Dialog	Xác nhận, tạo nhanh, chỉnh sửa	`Dialog`, `Alert Dialog`, `Sheet`, `Drawer`
Feedback	Loading, empty, toast	`Skeleton`, `Spinner`, `Empty`, `Alert`, `Sonner`
Settings	Cấu hình tài khoản và hệ thống	`Tabs`, `Card`, `Switch`, `Button Group`

Phần 5: Giao Claude Code dựng dashboard từng bước

Thay vì yêu cầu Claude Code tạo tất cả trong một lần, hãy chia dashboard thành các bước nhỏ.

Tạo app shell

Trước tiên, thêm block sidebar chuẩn từ shadcn/ui:

npx shadcn@latest add sidebar-07

Sau đó giao Claude Code chuyển sidebar mẫu thành layout dùng chung cho nhóm route private.

Trong dự án Next.js hiện tại, dùng block sidebar-07 vừa cài để tạo admin app shell dùng chung.

Yêu cầu:    
- Đổi file app/dashboard.tsx mà sidebar-07 tạo ra thành app/(private)/layout.tsx.
- Layout này là layout dùng chung cho toàn bộ trang app/(private)/...    

Tạo trang overview

Thêm dashboard home page với chỉ số, biểu đồ và activity feed.

Tạo app/(private)/page.tsx làm dashboard mặc định cho nhóm route private.

Yêu cầu:
- 4 stats cards: Total revenue, Active users, New orders, Conversion rate.
- Mỗi card dùng Card, Badge và icon từ lucide-react.
- Thêm chart doanh thu theo tuần bằng shadcn/ui Chart.
- Thêm recent activity list bằng Card, Avatar, Badge.
- Thêm Skeleton loading component nếu cần tách thành client component.
- Dùng dữ liệu mock rõ ràng, dễ thay bằng API sau này.

Tạo trang users

Xây trang quản lý người dùng với bảng dữ liệu.

Tạo app/(private)/users/page.tsx.

Yêu cầu:
- Bảng users có columns: name, email, role, status, createdAt, actions.
- Dùng shadcn/ui Table hoặc Data Table.
- Có checkbox chọn nhiều dòng.
- Có search input theo name/email.
- Có role filter bằng Select.
- Có pagination.
- Actions menu gồm View, Edit, Disable.
- Khi danh sách trống, hiển thị Empty component.

Tạo form thêm và sửa dữ liệu

Dùng dialog hoặc sheet cho workflow tạo user.

Bổ sung chức năng Add user vào trang users.

Yêu cầu:
- Nút Add user nằm ở góc phải toolbar.
- Khi click, mở Dialog hoặc Sheet.
- Form gồm name, email, role, status, notes.
- Dùng Field, Label, Input, Textarea, Select, Switch, Button.
- Validate dữ liệu cơ bản ở client.
- Sau khi submit, hiển thị Sonner toast.
- Chưa cần kết nối backend, cập nhật mock state trước.

Tạo trang analytics

Dùng chart và filter thời gian cho báo cáo.

Tạo app/(private)/analytics/page.tsx.

Yêu cầu:
- Có Tabs cho Revenue, Users, Orders.
- Có Date Picker chọn khoảng thời gian.
- Có chart theo ngày hoặc tuần.
- Có Card hiển thị top metrics.
- Có Alert để báo dữ liệu đang là mock data.

Tạo trang settings

Dựng cấu hình tài khoản và hệ thống.

Tạo app/(private)/settings/page.tsx.

Yêu cầu:
- Dùng Tabs: Profile, Security, Notifications, Appearance.
- Profile có form cập nhật display name, email, avatar.
- Security có Input OTP demo và switch bật 2FA.
- Notifications có nhóm Switch.
- Appearance có ToggleGroup hoặc RadioGroup chọn theme.
- Dùng Card để chia từng nhóm setting.

Phần 6: Prompt tổng hợp cho Claude Code

Khi bạn muốn Claude Code thực hiện toàn bộ quy trình từ đầu, dùng prompt này:

Khởi tạo một dự án Next.js admin dashboard mới bằng lệnh:

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

Sau khi init xong:
1. Chạy npx shadcn@latest add --all để thêm toàn bộ shadcn/ui components.
2. Chạy npx shadcn@latest add sidebar-07 để thêm block sidebar chuẩn.
3. Chuyển app/dashboard.tsx hoặc dashboard demo mà sidebar-07 tạo ra thành app/(private)/layout.tsx.
4. Tạo app/(private)/page.tsx làm dashboard overview mặc định.
5. Tạo các trang:
   - app/(private)/users/page.tsx
   - app/(private)/orders/page.tsx
   - app/(private)/analytics/page.tsx
   - app/(private)/settings/page.tsx
6. Dùng các component shadcn/ui phù hợp:
   - Sidebar, Card, Table, Data Table, Chart, Tabs
   - Dialog, Sheet, Dropdown Menu, Popover, Tooltip
   - Field, Input, Textarea, Select, Checkbox, Switch, Calendar
   - Alert, Sonner, Skeleton, Spinner, Empty, Pagination
7. Dùng lucide-react cho icon.
8. Tạo mock data rõ ràng trong src/lib/mock-data.ts.
9. Tạo helper format currency/date trong src/lib/format.ts.
10. Đảm bảo npm run dev chạy không lỗi.
11. Nếu có lỗi TypeScript, import path hoặc component composition, tự kiểm tra và sửa.

Ưu tiên giao diện admin thực dụng: sidebar rõ ràng, bảng dữ liệu dễ scan, form gọn, spacing nhất quán, responsive tốt.

Phần 7: Danh sách shadcn/ui components nên biết

Theo danh sách components chính thức hiện tại, shadcn/ui có các nhóm chính sau.

Hiển thị dữ liệu

Component	Dùng để làm gì
`Accordion`	Ẩn/hiện nội dung theo từng mục
`Alert`	Hiển thị cảnh báo hoặc thông báo
`Avatar`	Hiển thị ảnh đại diện
`Badge`	Hiển thị nhãn trạng thái
`Card`	Nhóm nội dung trong một khối
`Chart`	Hiển thị biểu đồ
`Data Table`	Bảng dữ liệu có sorting, filter, pagination
`Empty`	Trạng thái không có dữ liệu
`Progress`	Hiển thị tiến trình
`Skeleton`	Trạng thái loading
`Spinner`	Trạng thái đang xử lý
`Table`	Bảng dữ liệu đơn giản
`Typography`	Chuẩn hiển thị văn bản

Form và nhập liệu

Component	Dùng để làm gì
`Button`	Hành động chính và phụ
`Button Group`	Nhóm nhiều nút liên quan
`Calendar`	Chọn ngày
`Checkbox`	Chọn nhiều lựa chọn
`Combobox`	Chọn từ danh sách có tìm kiếm
`Date Picker`	Chọn ngày bằng popover calendar
`Field`	Bọc label, input và message
`Input`	Nhập text một dòng
`Input Group`	Ghép input với icon, button hoặc addon
`Input OTP`	Nhập mã xác thực
`Label`	Nhãn cho trường nhập liệu
`Native Select`	Select gốc của trình duyệt
`Radio Group`	Chọn một trong nhiều lựa chọn
`Select`	Dropdown chọn dữ liệu
`Slider`	Chọn giá trị bằng thanh trượt
`Switch`	Bật/tắt một lựa chọn
`Textarea`	Nhập text nhiều dòng
`Toggle`	Nút có trạng thái bật/tắt
`Toggle Group`	Nhóm toggle

Điều hướng và bố cục

Component	Dùng để làm gì
`Breadcrumb`	Hiển thị đường dẫn phân cấp
`Collapsible`	Thu gọn/mở rộng vùng nội dung
`Command`	Command palette hoặc search menu
`Direction`	Hỗ trợ hướng giao diện
`Item`	Mẫu item dùng trong list hoặc menu
`Menubar`	Menu ngang kiểu ứng dụng
`Navigation Menu`	Menu điều hướng chính
`Pagination`	Chuyển trang
`Resizable`	Chia vùng có thể kéo resize
`Scroll Area`	Vùng cuộn tuỳ chỉnh
`Separator`	Đường phân cách
`Sidebar`	Thanh điều hướng bên trái
`Tabs`	Chia nội dung theo tab

Overlay và phản hồi

Component	Dùng để làm gì
`Alert Dialog`	Xác nhận hành động nguy hiểm
`Context Menu`	Menu chuột phải
`Dialog`	Modal ở giữa màn hình
`Drawer`	Panel trượt, thường dùng trên mobile
`Dropdown Menu`	Menu xổ xuống
`Hover Card`	Card hiện khi hover
`Popover`	Nội dung nổi khi click
`Sheet`	Panel trượt từ cạnh màn hình
`Sonner`	Toast notification hiện đại
`Toast`	Toast notification cũ hơn
`Tooltip`	Chú thích khi hover

Phần 8: Kiểm tra trước khi tiếp tục

Chạy các lệnh sau:

npm run dev
npm run build

Nếu dự án có script lint:

npm run lint

Sau đó kiểm tra thủ công:

Sidebar hoạt động trên desktop và mobile
Header không đè lên content
Bảng users có search, filter và pagination
Dialog form submit được và có toast
Chart render đúng
Empty, loading và error states có giao diện rõ ràng

​Mục tiêu bài viết

​Phần 1: Khởi tạo dự án Next.js bằng shadcn CLI

​Phần 2: Chạy dự án

​Phần 3: Thêm toàn bộ shadcn/ui components

​Phần 4: Cấu trúc admin dashboard chuẩn

​Phần 5: Giao Claude Code dựng dashboard từng bước

​Phần 6: Prompt tổng hợp cho Claude Code

​Phần 7: Danh sách shadcn/ui components nên biết

​Hiển thị dữ liệu

​Form và nhập liệu

​Điều hướng và bố cục

​Overlay và phản hồi

​Phần 8: Kiểm tra trước khi tiếp tục

​Tài liệu tham khảo

Mục tiêu bài viết

Phần 1: Khởi tạo dự án Next.js bằng shadcn CLI

Phần 2: Chạy dự án

Phần 3: Thêm toàn bộ shadcn/ui components

Phần 4: Cấu trúc admin dashboard chuẩn

Phần 5: Giao Claude Code dựng dashboard từng bước

Phần 6: Prompt tổng hợp cho Claude Code

Phần 7: Danh sách shadcn/ui components nên biết

Hiển thị dữ liệu

Form và nhập liệu

Điều hướng và bố cục

Overlay và phản hồi

Phần 8: Kiểm tra trước khi tiếp tục

Tài liệu tham khảo