Các Prompt cho Astro.js
# Quy tắc Kiến trúc Astro v6 (Chế độ Nghiêm ngặt - Strict Mode)
## 1. Triết lý Cốt lõi
- Tuân thủ nguyên tắc “Ưu tiên HTML / Mặc định không dùng JavaScript” (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 một cách rõ ràng.
- JavaScript là một khoản chi phí hiệu năng → chỉ thêm vào khi nó thực sự tạo ra giá trị cho người dùng.
- Luôn tư duy theo mô hình “Kiến trúc Ốc đảo” (Islands Architecture):
- Toàn bộ trang là HTML tĩnh
- Các thành phần tương tác là những ốc đảo (islands) độc lập, tách biệt
- Không bao giờ coi toàn bộ trang web như một ứng dụng đơn trang (app)
- Trước khi viết bất kỳ dòng mã JavaScript nào, hãy luôn tự hỏi:
"Vấn đề này có thể giải quyết bằng HTML + CSS hoặc logic phía máy chủ (server-side) hay không?"
---
## 2. Mô hình Thành phần (Component Model)
- Sử dụng các thành phần `.astro` cho:
- Bố cục (Layout)
- Ghép nối thành phần (Composition)
- Giao diện người dùng tĩnh (Static UI)
- Lấy dữ liệu (Data fetching)
- Logic phía máy chủ (trong phần frontmatter)
- Các thành phần `.astro`:
- Chạy tại thời điểm biên dịch (build-time) hoặc phía máy chủ (server-side)
- Mặc định KHÔNG gửi kèm mã JavaScript xuống trình duyệt
- Phải giữ tính độc lập, không phụ thuộc vào framework cụ thể (framework-agnostic)
- TUYỆT ĐỐI KHÔNG sử dụng các hook của React/Vue/Svelte bên trong tệp `.astro`
---
## 3. Các Ốc đảo - Islands (Thành phần Tương tác)
- Chỉ sử dụng các thành phần từ framework (React, Vue, Svelte, v.v.) khi cần tính tương tác.
- Coi mỗi thành phần tương tác là một ốc đảo cô lập:
- Độc lập
- Tự chứa (Self-contained)
- Phạm vi tối thiểu
- TUYỆT ĐỐI KHÔNG:
- Hydrate (kích hoạt tương tác phía client) toàn bộ trang hoặc toàn bộ bố cục (layout)
- Bọc các cây giao diện lớn vào trong một ốc đảo duy nhất
- Tạo nhiều ốc đảo nhỏ trong các vòng lặp một cách không cần thiết
- Ưu tiên:
- Kết xuất (render) danh sách ở dạng tĩnh
- Chỉ hydrate đơn vị tương tác nhỏ nhất cần thiết
---
## 4. Chiến lược Hydration (Cực kỳ Quan trọng)
- Luôn định nghĩa rõ ràng cơ chế hydration bằng các chỉ thị `client:*`.
- Chọn mức độ ưu tiên THẤP NHẤT có thể:
- `client:load`
→ Chỉ dùng cho tính năng tương tác tối quan trọng, nằm ngay trong màn hình đầu tiên (above-the-fold)
- `client:idle`
→ Dùng cho giao diện thứ cấp sau khi trang đã tải xong
- `client:visible`
→ Dùng cho các thành phần nằm bên dưới màn hình đầu tiên (below-the-fold) hoặc các thành phần nặng
- `client:media`
→ Dùng cho giao diện đáp ứng (responsive) / hiển thị có điều kiện
- `client:only`
→ CHỈ dùng khi quá trình kết xuất phía máy chủ (SSR) bị lỗi (do truy cập trực tiếp `window`, `localStorage`, v.v.)
- Quy tắc mặc định:
❌ Không bao giờ chọn `client:load` làm mặc định
✅ Ưu tiên dùng `client:visible` hoặc `client:idle`
- Hydration là một ngân sách hiệu năng (performance budget):
- Mỗi ốc đảo đều làm tăng thêm dung lượng JS
- Giữ tổng lượng JS ở mức tối thiểu
📌 Astro KHÔNG tự động hydrate các thành phần trừ khi được chỉ định rõ ràng thông qua `client:*` :contentReference[oaicite:0]{index=0}
---
## 5. Logic Phía Máy chủ (Server) so với Phía Máy khách (Client)
- Ưu tiên xử lý logic phía máy chủ (bên trong phần frontmatter của `.astro`) cho:
- Lấy dữ liệu (Data fetching)
- Biến đổi dữ liệu (Transformations)
- Lọc / sắp xếp (Filtering / sorting)
- Tính toán các giá trị phái sinh (Derived values)
- Chỉ sử dụng trạng thái phía máy khách (client-side state) khi:
- Thao tác tương tác của người dùng bắt buộc cần đến nó
- Cần cập nhật dữ liệu theo thời gian thực
- Tránh:
- Lặp lại logic xử lý ở phía client
- Đẩy logic vốn thuộc về máy chủ vào bên trong các ốc đảo
---
## 6. Quản lý Trạng thái (State Management)
- Tránh dùng trạng thái phía client trừ khi thực sự cần thiết.
- Nếu cần dùng:
- Giới hạn phạm vi trạng thái nằm gọn bên trong ốc đảo đó
- KHÔNG tạo trạng thái toàn cục cho cả ứng dụng (global app state) trừ khi bắt buộc
- Đối với trạng thái chia sẻ giữa các ốc đảo (cross-island state):
- Sử dụng các kho lưu trữ chia sẻ gọn nhẹ (ví dụ: nano stores)
- Mặc định tránh dùng các hệ thống quản lý trạng thái toàn cục cồng kềnh
---
## 7. Ràng buộc Hiệu năng (Quy tắc Cứng)
- Giảm thiểu tối đa lượng JavaScript gửi xuống trình duyệt của người dùng:
- Astro chỉ tải mã JS cho những thành phần được hydrate :contentReference[oaicite:1]{index=1}
- Ưu tiên:
- Kết xuất tĩnh (Static rendering)
- Hydration từng phần (Partial hydration)
- Hydration trễ khi cần (Lazy hydration)
- Tránh:
- Hydrate các danh sách lớn
- Lặp lại các ốc đảo bên trong vòng lặp
- Lạm dụng `client:load`
- Mỗi ốc đảo:
- Có gói mã (bundle) riêng biệt
- Tải một cách độc lập
- Cần được giữ nhỏ gọn và tập trung đúng nhiệm vụ :contentReference[oaicite:2]{index=2}
---
## 8. Cấu trúc Tệp & Dự án
- `/pages`
- Các điểm vào của trang (SSG/SSR)
- Không chứa logic phía client
- `/components`
- Giao diện dùng chung
- Các ốc đảo (islands) được đặt tại đây
- `/layouts`
- Chỉ chứa các khung bọc (wrappers) tĩnh
- `/content`
- Dữ liệu Markdown / CMS
- Giữ cho các tệp `.astro` tập trung vào việc ghép nối bố cục (composition), không ôm đồm hành vi tương tác
---
## 9. Các Phản mẫu - Anti-Patterns (Nghiêm cấm Tuyệt đối)
- ❌ Sử dụng các hook trong tệp `.astro`
- ❌ Biến Astro thành kiến trúc ứng dụng đơn trang (SPA)
- ❌ Hydrate toàn bộ bố cục (layout) hoặc toàn bộ trang
- ❌ Sử dụng `client:load` ở khắp mọi nơi
- ❌ Duyệt mảng (map) danh sách thành hàng loạt thành phần được hydrate
- ❌ Sử dụng JS phía client để giải quyết các bài toán tĩnh
- ❌ Thay thế logic phía máy chủ bằng logic phía client
---
## 10. Các Khuôn mẫu Được Khuyến khích
- ✅ Kết xuất ưu tiên tĩnh (Static-first rendering)
- ✅ Các ốc đảo tối giản, cô lập
- ✅ Hydration trễ (`visible`, `idle`)
- ✅ Tính toán ở phía máy chủ
- ✅ Ưu tiên HTML + CSS trước khi dùng đến JS
- ✅ Nâng cấp lũy tiến (Progressive enhancement)
---
## 11. Khung Ra Quyết định (RẤT QUAN TRỌNG)
Đối với mọi tính năng:
1. Tính năng này có thể làm bằng HTML tĩnh không?
→ CÓ → Sử dụng `.astro`
2. Nó có đòi hỏi tương tác từ người dùng không?
→ KHÔNG → Giữ nguyên ở dạng tĩnh
3. Nó có bắt buộc phải dùng JS không?
→ CÓ → Tạo một ốc đảo (island)
4. Khi nào ốc đảo đó nên được tải?
→ Chọn chỉ thị `client:*` có độ ưu tiên THẤP NHẤT
---
## 12. Mô hình Tư duy (Bất di bất dịch)
- Astro KHÔNG PHẢI là:
- Next.js
- Một framework SPA
- Một hệ thống lấy React làm trung tâm (React-first)
- Astro CHÍNH LÀ:
- Trình kết xuất ưu tiên tĩnh (Static-first renderer)
- Hệ thống hydration từng phần (Partial hydration system)
- Kiến trúc đặt hiệu năng lên hàng đầu (Performance-first architecture)
- Hãy tư duy:
❌ “Xây dựng một ứng dụng (Build an app)”
✅ “Phân phối HTML + điểm xuyết một chút JS (Ship HTML + sprinkle JS)”