Lời nhắc của Astro.js
# Quy tắc kiến trúc Astro v6 (Chế độ nghiêm ngặt)
## 1. Triết lý cốt lõi
- Thực hiện theo nguyên tắc “HTML-first/zero JavaScript by default” của Astro:
- Mọi thứ đều là HTML tĩnh trừ khi tính tương tác được yêu cầu rõ ràng.
- JavaScript là một chi phí → chỉ thêm khi nó tạo ra giá trị thực cho người dùng.
- Luôn tư duy “Kiến trúc đảo”:
- Trang này là HTML tĩnh
- Phần tương tác là những hòn đảo biệt lập
- Không bao giờ coi toàn bộ trang là một ứng dụng
- Trước khi viết bất kỳ JavaScript nào, hãy luôn hỏi:
"Có thể giải quyết vấn đề này bằng HTML + CSS hoặc logic phía máy chủ không?"
---
## 2. Model thành phần
- Sử dụng thành phần `.astro` cho:
- Bố cục
- Thành phần
- Giao diện người dùng tĩnh
- Tìm nạp dữ liệu
- Logic phía máy chủ (frontmatter)
- thành phần `.astro`:
- Chạy ở thời điểm xây dựng hoặc phía máy chủ
- KHÔNG gửi JavaScript theo mặc định
- Phải duy trì tính bất khả tri của khuôn khổ
- KHÔNG BAO GIỜ sử dụng hook React/Vue/Svelte bên trong `.astro`
---
## 3. Quần đảo (Thành phần tương tác)
- Chỉ sử dụng các thành phần framework (React, Vue, Svelte, v.v.) để tương tác.
- Coi mọi thành phần tương tác như một hòn đảo biệt lập:
- Độc lập
- Tự khép kín
- Phạm vi tối thiểu
- KHÔNG BAO GIỜ:
- Hydrat hóa toàn bộ trang hoặc bố cục
- Bao bọc những cây lớn trong một hòn đảo duy nhất
- Tạo nhiều đảo nhỏ theo vòng lặp không cần thiết
- Ưu tiên:
- Kết xuất danh sách tĩnh
- Chỉ cung cấp nước cho đơn vị tương tác tối thiểu
---
## 4. Chiến lược cấp nước (Quan trọng)
- Luôn xác định rõ ràng quá trình hydrat hóa bằng cách sử dụng lệnh `client:*`.
- Chọn mức độ ưu tiên THẤP NHẤT có thể:
- `client:load`
→ Chỉ dành cho tính tương tác quan trọng, trong màn hình đầu tiên
- `client:idle`
→ Dành cho giao diện người dùng phụ sau khi tải trang
- `client:visible`
→ Dành cho các thành phần dưới màn hình đầu tiên hoặc nặng
- `client:media`
→ Dành cho giao diện người dùng đáp ứng / có điều kiện
- `client:only`
→ CHỈ khi SSR bị hỏng (cửa sổ, localStorage, v.v.)
- Quy tắc mặc định:
❌ Không bao giờ mặc định là `client:load`
✅ Thích `client:visible` hoặc `client:idle`
- Hydrat hóa là một ngân sách hiệu suất:
- Đảo nào cũng thêm JS
- Giữ tổng số JS ở mức tối thiểu
✔️ Astro KHÔNG hydrat hóa các thành phần trừ khi được thông báo rõ ràng qua `client:*` :contentReference[oaicite:0]{index=0}
---
## 5. Logic máy chủ và máy khách
- Ưu tiên logic phía máy chủ (bên trong phần đầu `.astro`) cho:
- Tìm nạp dữ liệu
- Chuyển đổi
- Lọc/sắp xếp
- Giá trị dẫn xuất
- Chỉ sử dụng trạng thái phía client khi:
- Tương tác người dùng yêu cầu nó
- Cần cập nhật theo thời gian thực
- Tránh:
- Sao chép logic trên máy khách
- Di chuyển logic máy chủ vào các đảo
---
##6. Quản lý nhà nước
- Tránh trạng thái khách hàng trừ khi thực sự cần thiết.
- Nếu cần:
- Phạm vi trạng thái chỉ bên trong đảo
- KHÔNG tạo trạng thái ứng dụng toàn cầu trừ khi được yêu cầu
- Đối với bang xuyên đảo:
- Sử dụng các cửa hàng chia sẻ nhẹ (ví dụ: cửa hàng nano)
- Theo mặc định, tránh các hệ thống trạng thái toàn cầu nặng nề
---
## 7. Ràng buộc về hiệu suất (Quy tắc cứng)
- Giảm thiểu việc gửi JavaScript tới client:
- Astro chỉ tải JS cho các thành phần ngậm nước :contentReference[oaicite:1]{index=1}
- Ưu tiên:
- Kết xuất tĩnh
- Hydrat hóa một phần
- Lười hydrat hóa
- Tránh:
- Hydrating danh sách lớn
- Đảo lặp đi lặp lại trong vòng lặp
- Lạm dụng `client:load`
- Mỗi đảo:
- Có gói riêng
- Tải độc lập
- Nên duy trì ở quy mô nhỏ và tập trung :contentReference[oaicite:2]{index=2}
---
## 8. Cấu trúc tệp & dự án
- `/pages`
- Điểm vào (SSG/SSR)
- Không có logic khách hàng
- `/components`
- Giao diện người dùng được chia sẻ
- Quần đảo sống ở đây
- `/layouts`
- Chỉ có trình bao bọc tĩnh
- `/content`
- Dữ liệu Markdown / CMS
- Giữ các tệp `.astro` tập trung vào bố cục chứ không phải hành vi
---
## 9. Chống mẫu (Nghiêm cấm)
- ❌ Sử dụng hook trong `.astro`
- ❌ Biến Astro thành kiến trúc SPA
- ❌ Hydrat hóa toàn bộ bố cục/trang
- ❌ Sử dụng `client:load` ở mọi nơi
- ❌ Ánh xạ danh sách thành các thành phần ngậm nước
- ❌ Sử dụng client JS cho các vấn đề tĩnh
- ❌ Thay logic máy chủ bằng logic máy khách
---
## 10. Mẫu ưa thích
- ✅ Kết xuất tĩnh đầu tiên
- ✅ Đảo nhỏ, biệt lập
- ✅ Lười dưỡng ẩm (`visible`, `idle`)
- ✅ Tính toán phía máy chủ
- ✅ HTML + CSS trước JS
- ✅ Tiến bộ dần dần
---
## 11. Khung quyết định (RẤT QUAN TRỌNG)
Đối với mọi tính năng:
1. Đây có phải là HTML tĩnh không?
→ CÓ → Sử dụng `.astro`
2. Nó có yêu cầu tương tác không?
→ KHÔNG → Giữ yên
3. Nó có yêu cầu JS không?
→ CÓ → Tạo một hòn đảo
4. Khi nào nên tải?
→ Chọn mức độ ưu tiên THẤP NHẤT `client:*`
---
## 12. Mô hình tinh thần (Không thể thương lượng)
- Astro KHÔNG phải là:
- Next.js
- Khung SPA
- Hệ thống phản ứng đầu tiên
- Astro LÀ:
- Trình kết xuất tĩnh đầu tiên
- Hệ thống hydrat hóa một phần
- Kiến trúc ưu tiên hiệu suất
- Hãy suy nghĩ:
❌ “Xây dựng ứng dụng”
✅ “Ship HTML + rải JS”