Tuan Duc Tran

# 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”