@anhlp/alp-core 0.0.1-beta.7 → 0.0.1-beta.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/library-edit.d.ts +51 -2
- package/dist/library-edit.js +160 -8
- package/dist/library.d.ts +14 -1
- package/dist/library.js +73 -5
- package/dist/models.d.ts +35 -0
- package/dist/models.js +17 -1
- package/dist/packs.d.ts +57 -0
- package/dist/packs.js +247 -0
- package/dist/permissions.d.ts +3 -2
- package/dist/permissions.js +6 -3
- package/dist/profiles.js +3 -3
- package/dist/providers.d.ts +2 -4
- package/dist/providers.js +20 -4
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/validation.js +2 -3
- package/package.json +18 -2
- package/src/library-edit.js +170 -8
- package/src/library.js +96 -6
- package/src/models.js +24 -0
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +4 -4
- package/src/providers.js +20 -5
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/upgrade.js +54 -6
- package/src/validation.js +3 -4
- package/templates/ALP.md +52 -52
- package/templates/agents/lead/AGENT.md +77 -74
- package/templates/agents/main/AGENT.md +153 -145
- package/templates/agents/oracle/AGENT.md +38 -37
- package/templates/agents/peer/AGENT.md +56 -52
- package/templates/agents/reviewer/AGENT.md +63 -65
- package/templates/agents/supervisor/AGENT.md +63 -63
- package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
- package/templates/packs/architecture/agents/architect/agent.json +5 -0
- package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
- package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
- package/templates/packs/architecture/pack.json +7 -0
- package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
- package/templates/packs/architecture/teams/blueprint/team.json +19 -0
- package/templates/packs/backend/pack.json +6 -0
- package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
- package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
- package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
- package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
- package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
- package/templates/packs/backend/skills/databases/SKILL.md +103 -0
- package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
- package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
- package/templates/packs/design/pack.json +6 -0
- package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
- package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
- package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
- package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
- package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
- package/templates/packs/frontend/pack.json +6 -0
- package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
- package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
- package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
- package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
- package/templates/packs/integration/pack.json +6 -0
- package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
- package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
- package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
- package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
- package/templates/packs/operations/pack.json +6 -0
- package/templates/packs/operations/skills/devops/SKILL.md +85 -0
- package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
- package/templates/packs/operations/skills/devops/references/containers.md +85 -0
- package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
- package/templates/packs/operations/skills/devops/references/observability.md +86 -0
- package/templates/packs/quality/pack.json +6 -0
- package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
- package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
- package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
- package/templates/role-skills.json +4 -4
- package/templates/skills/architecture-docs/SKILL.md +81 -0
- package/templates/skills/architecture-docs/references/adr.md +62 -0
- package/templates/skills/architecture-docs/references/diagrams.md +60 -0
- package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
- package/templates/skills/bug-loop/SKILL.md +41 -40
- package/templates/skills/bug-loop/references/test-proof.md +21 -19
- package/templates/skills/compact/SKILL.md +2 -2
- package/templates/skills/curate/SKILL.md +6 -5
- package/templates/skills/feature-architecture/SKILL.md +90 -0
- package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
- package/templates/skills/feature-architecture/references/feature-design.md +69 -0
- package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
- package/templates/skills/goal-griller/SKILL.md +27 -27
- package/templates/skills/prompt-leverage/SKILL.md +29 -27
- package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
- package/templates/skills/release-readiness/SKILL.md +83 -0
- package/templates/skills/release-readiness/references/checklist.md +40 -0
- package/templates/skills/release-readiness/references/verdict-template.md +53 -0
- package/templates/skills/safe-refactor/SKILL.md +84 -0
- package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
- package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
- package/templates/skills/security-review/SKILL.md +87 -0
- package/templates/skills/security-review/references/checklist.md +74 -0
- package/templates/skills/security-review/references/severity.md +61 -0
- package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
- package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
- package/templates/skills/skill-authoring/SKILL.md +84 -0
- package/templates/skills/skill-authoring/references/evaluation.md +45 -0
- package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
- package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
- package/templates/skills/smart-commits/SKILL.md +37 -36
- package/templates/skills/test-strategy/SKILL.md +83 -0
- package/templates/skills/test-strategy/references/contract-tests.md +46 -0
- package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
- package/templates/skills/xia/SKILL.md +40 -38
- package/templates/teams/cafe/HOUSE_RULES.md +1 -1
- package/templates/teams/cafe/team.json +1 -1
- package/templates/teams/pho/HOUSE_RULES.md +1 -1
- package/templates/teams/pho/team.json +1 -1
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Review UI
|
|
2
|
+
|
|
3
|
+
Đọc khi review một màn hình, component hay spec thiết kế đang có về mức khả dụng,
|
|
4
|
+
accessibility và tính nhất quán với design system.
|
|
5
|
+
|
|
6
|
+
## Phạm vi và cách làm
|
|
7
|
+
|
|
8
|
+
- Review bề mặt được nêu trong việc được giao (assignment). Không mở rộng ra toàn bộ ứng dụng.
|
|
9
|
+
- Dùng bằng chứng có sẵn: source (markup, style, token), ảnh chụp, file thiết kế trong repo,
|
|
10
|
+
và chạy ứng dụng cục bộ nếu lệnh chạy của dự án có sẵn và được phép.
|
|
11
|
+
- Kiểm tra chỉ bằng bàn phím, ở chiều rộng hẹp, ở zoom 200%, và trong từng theme được hỗ trợ khi bạn
|
|
12
|
+
chạy được UI. Nếu không chạy được, hãy nói rõ và review từ source; đánh dấu những mục chỉ kiểm được
|
|
13
|
+
khi chạy là chưa kiểm chứng.
|
|
14
|
+
- Reviewer chỉ đọc thì báo các phát hiện; họ không sửa file.
|
|
15
|
+
|
|
16
|
+
## Checklist
|
|
17
|
+
|
|
18
|
+
Thứ bậc và layout
|
|
19
|
+
- Một hành động chính cho mỗi view; hành động phá hủy tách riêng và có xác nhận hoặc hoàn tác được.
|
|
20
|
+
- Khoảng cách và kích thước lấy từ thang đo của dự án; không có giá trị lệch thang lạc vào.
|
|
21
|
+
- Căn theo một tập nhỏ các đường biên; mật độ nhất quán trong một view.
|
|
22
|
+
|
|
23
|
+
Typography
|
|
24
|
+
- Chữ nội dung đọc được (cỡ, chiều cao dòng, chiều dài dòng); chữ co giãn theo thiết lập người dùng.
|
|
25
|
+
- Cấp tiêu đề theo cấu trúc, không chỉ theo cỡ thị giác.
|
|
26
|
+
|
|
27
|
+
Màu và token
|
|
28
|
+
- Component dùng token semantic, không dùng giá trị thô.
|
|
29
|
+
- Tương phản của chữ và UI đạt ngưỡng trong mọi theme và trên mọi surface được dùng.
|
|
30
|
+
- Không có ý nghĩa nào chỉ truyền tải bằng màu.
|
|
31
|
+
|
|
32
|
+
Trạng thái
|
|
33
|
+
- Có hover, focus-visible, active, disabled, loading, lỗi, rỗng ở nơi áp dụng được.
|
|
34
|
+
- Focus thấy được trên mọi phần tử tương tác được; thứ tự focus hợp lý; focus được trả lại sau overlay.
|
|
35
|
+
|
|
36
|
+
Form
|
|
37
|
+
- Mọi input đều có nhãn thấy được và gắn kết được bằng chương trình; placeholder không phải là nhãn.
|
|
38
|
+
- Lỗi phải cụ thể, nằm cạnh field, và giữ lại dữ liệu người dùng đã nhập.
|
|
39
|
+
- Field bắt buộc được đánh dấu; loại input và gợi ý autocomplete phù hợp với dữ liệu.
|
|
40
|
+
|
|
41
|
+
Ngữ nghĩa accessibility
|
|
42
|
+
- Dùng phần tử native theo đúng vai trò của chúng (button, link, input) trước khi dùng vai trò tự tạo.
|
|
43
|
+
- Ảnh có chữ thay thế mang nghĩa hoặc được đánh dấu là trang trí.
|
|
44
|
+
- Control chỉ có icon thì có tên truy cập được.
|
|
45
|
+
- Kích thước đích ít nhất 24x24 CSS px; nội dung dùng được ở chiều rộng 320 CSS px.
|
|
46
|
+
- Tùy chọn giảm chuyển động được tôn trọng.
|
|
47
|
+
|
|
48
|
+
Tính nhất quán
|
|
49
|
+
- Cùng một pattern cho cùng một việc trên khắp sản phẩm (dialog, toast, bảng, trạng thái rỗng).
|
|
50
|
+
- Dùng lại component đang có thay vì tạo bản gần giống.
|
|
51
|
+
- Câu chữ và thuật ngữ nhất quán với phần còn lại của sản phẩm.
|
|
52
|
+
|
|
53
|
+
## Mức nghiêm trọng
|
|
54
|
+
|
|
55
|
+
| Mức | Nghĩa | Ví dụ |
|
|
56
|
+
|---|---|---|
|
|
57
|
+
| Blocker | Người dùng không hoàn thành được tác vụ, hoặc vi phạm một yêu cầu accessibility pháp lý | Bẫy bàn phím, field bắt buộc không nhãn, tương phản chữ 2:1 |
|
|
58
|
+
| Major | Làm được tác vụ nhưng dễ sai hoặc chậm với nhiều người dùng | Thiếu trạng thái lỗi, không có chỉ báo focus, hành động chính bị ẩn trên mobile |
|
|
59
|
+
| Minor | Không nhất quán hoặc gây vướng nhưng có cách lách | Khoảng cách lệch thang, kiểu nút trùng lặp, trạng thái rỗng yếu |
|
|
60
|
+
| Nit | Tinh chỉnh | Lệch căn chút ít, độ dày icon không khớp |
|
|
61
|
+
|
|
62
|
+
Xếp hạng theo tác động tới người dùng, không theo công sức sửa.
|
|
63
|
+
|
|
64
|
+
## Định dạng một phát hiện
|
|
65
|
+
|
|
66
|
+
```text
|
|
67
|
+
[Major] Settings > Save button has no visible focus state
|
|
68
|
+
Where: src/components/SettingsForm.tsx:84 (class .save-btn), dark theme
|
|
69
|
+
Evidence: outline: none in styles/buttons.css:12; no :focus-visible rule; tabbing shows no indicator
|
|
70
|
+
Guideline: focus visible, 3:1 indicator contrast
|
|
71
|
+
Fix: add focus-visible ring using token color-focus-ring (exists in tokens.css:40)
|
|
72
|
+
Verified: yes (keyboard, local run) | no (source only)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- Một phát hiện cho mỗi vấn đề; gom các lần lặp của cùng vấn đề thành một danh sách vị trí.
|
|
76
|
+
- Bằng chứng phải cụ thể: file và dòng, tỉ lệ tương phản đo được, đường dẫn ảnh chụp, hoặc đúng
|
|
77
|
+
các bước đã làm. "Trông không ổn" không phải bằng chứng.
|
|
78
|
+
- Gợi ý sửa nên dùng lại token và component đang có khi có thể.
|
|
79
|
+
|
|
80
|
+
## Hình thức báo cáo
|
|
81
|
+
|
|
82
|
+
Tóm tắt (bề mặt đã review, đã kiểm thế nào, cái gì không kiểm được), các phát hiện xếp theo
|
|
83
|
+
mức nghiêm trọng, rồi những điểm tốt nên giữ và các câu hỏi còn mở cho chủ sở hữu.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
{
|
|
2
|
+
"label": "Frontend",
|
|
3
|
+
"description": "Tính năng UI trong các framework component: cấu trúc, state, lấy dữ liệu, framework SSR, hiệu năng và khả năng tiếp cận.",
|
|
4
|
+
"skills": ["frontend-development"],
|
|
5
|
+
"assign": { "lead": ["frontend-development"], "peer": ["frontend-development"] }
|
|
6
|
+
}
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: frontend-development
|
|
3
|
+
description: "Dựng tính năng UI trong framework component của dự án (ví dụ ưu tiên React, cũng dùng cho Vue hay Svelte): cấu trúc component, state, lấy dữ liệu, routing và SSR, hiệu năng, và accessibility. Dùng khi thêm hoặc sửa màn hình, component, form, hay luồng dữ liệu phía client. Không dùng cho quyết định thiết kế thị giác (ui-design) hay công cụ test (web-testing)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Phát triển frontend
|
|
7
|
+
|
|
8
|
+
## Khi nào dùng
|
|
9
|
+
|
|
10
|
+
- Thêm hoặc sửa một trang, route, component, form, hay luồng dữ liệu phía client.
|
|
11
|
+
- Quyết định state nằm ở đâu, hoặc một màn hình tải, cache và làm mới dữ liệu thế nào.
|
|
12
|
+
- Sửa một vấn đề hiệu năng đã đo được về render, bundle, hoặc tải trang.
|
|
13
|
+
- Làm cho một UI dùng được bằng bàn phím và trình đọc màn hình.
|
|
14
|
+
- Một cố vấn (advisor) hay reviewer chỉ đọc được nhờ đánh giá code frontend (chỉ tư vấn).
|
|
15
|
+
|
|
16
|
+
## Không dùng cho
|
|
17
|
+
|
|
18
|
+
- Lựa chọn về layout, màu, typography, hay thiết kế thị giác: dùng ui-design.
|
|
19
|
+
- Test runner, e2e, công cụ kiểm thị giác hay tải: dùng web-testing.
|
|
20
|
+
- Quyết định test những gì cho một thay đổi: dùng test-strategy.
|
|
21
|
+
- Một test fail hay UI bị hồi quy mà chưa rõ nguyên nhân: dùng bug-loop.
|
|
22
|
+
- Endpoint phía server nằm sau UI: dùng backend-development.
|
|
23
|
+
- Chọn framework, thư viện state, hay hệ thống styling mới: quyết định của chủ sở hữu.
|
|
24
|
+
|
|
25
|
+
## Điều kiện tiên quyết
|
|
26
|
+
|
|
27
|
+
- Đường dẫn sở hữu và tiêu chí nghiệm thu trong brief; ALP.md và chỉ dẫn của dự án.
|
|
28
|
+
- Framework và phiên bản thực tế, router, thư viện lấy dữ liệu và state, cách
|
|
29
|
+
styling, và công cụ build, đọc từ `package.json`, lockfile, và các
|
|
30
|
+
file config. Không suy ra từ tên thư mục.
|
|
31
|
+
- Một hoặc hai màn hình hay component đang có, tương tự việc này. Chúng định ra
|
|
32
|
+
quy ước về bố trí file, đặt tên, tải dữ liệu, styling, và test.
|
|
33
|
+
- Spec thiết kế hoặc spec nghiệm thu cho UI, nếu có, và các component
|
|
34
|
+
design-system đang có của dự án.
|
|
35
|
+
- Các lệnh dev, lint, typecheck, và test của dự án.
|
|
36
|
+
|
|
37
|
+
## Quy trình
|
|
38
|
+
|
|
39
|
+
1. Diễn đạt lại tính năng thành các trạng thái người dùng thấy được: loading, rỗng, lỗi,
|
|
40
|
+
thành công, một phần, và bị từ chối quyền. Trạng thái chưa được đặc tả thì chuyển lên; không
|
|
41
|
+
tự nghĩ ra câu chữ hay hành vi sản phẩm.
|
|
42
|
+
2. Tìm component, hook, và hàm tiện ích đang có để dùng lại trước khi viết cái mới.
|
|
43
|
+
3. Phác cây component và quyết định từng phần state nằm ở đâu. Đọc
|
|
44
|
+
components-and-state.md.
|
|
45
|
+
4. Xác định nhu cầu dữ liệu: endpoint nào, tải khi nào, cache và làm mới thế nào,
|
|
46
|
+
và chuyện gì xảy ra khi lỗi hoặc khi phản hồi đã cũ. Đọc data-fetching.md.
|
|
47
|
+
5. Đặt phần việc vào đúng mô hình của framework (server hay client component, route
|
|
48
|
+
loader, page, island). Đọc frameworks.md; xem tài liệu cho đúng phiên bản mà
|
|
49
|
+
dự án đang dùng.
|
|
50
|
+
6. Dựng bằng HTML semantic và các component design-system đang có; nối hành vi bàn phím
|
|
51
|
+
và focus ngay khi làm. Đọc accessibility.md.
|
|
52
|
+
7. Xử lý mọi trạng thái từ bước 1 trong UI, gồm cả trạng thái disabled và đang chờ
|
|
53
|
+
cho các hành động, và chống submit hai lần.
|
|
54
|
+
8. Chỉ kiểm hiệu năng ở nơi nó đáng: danh sách lớn, component nặng, phụ thuộc mới,
|
|
55
|
+
ảnh. Đo trước khi tối ưu. Đọc performance.md.
|
|
56
|
+
9. Thêm hoặc cập nhật test bằng công cụ của dự án (xem web-testing về cách dùng công cụ).
|
|
57
|
+
10. Chạy lint, typecheck, và test; mở trang trên dev server và thử
|
|
58
|
+
từng trạng thái, ít nhất một lần chỉ bằng bàn phím.
|
|
59
|
+
11. Handoff: file đã đổi, trạng thái đã bao phủ, ảnh chụp hoặc ghi chú nếu dự án
|
|
60
|
+
dùng chúng, lệnh đã chạy kèm kết quả, câu hỏi còn mở về thiết kế hay sản phẩm.
|
|
61
|
+
|
|
62
|
+
Agent chỉ đọc thì review bước 1-8 dựa trên code hoặc đề xuất và báo lại các
|
|
63
|
+
phát hiện cùng thay đổi khuyến nghị, thay vì sửa file.
|
|
64
|
+
|
|
65
|
+
## Ràng buộc
|
|
66
|
+
|
|
67
|
+
- Trước hết hãy theo framework, phiên bản, và quy ước đang có của dự án. React,
|
|
68
|
+
Next.js, Vue, Nuxt, Svelte, SvelteKit, Angular, hay web component thuần chỉ là
|
|
69
|
+
ví dụ, không phải khuyến nghị.
|
|
70
|
+
- Không thêm phụ thuộc, bộ UI kit, thư viện state hay thư viện fetch, hay framework
|
|
71
|
+
mà không có quyết định của chủ sở hữu. Không tự động cài.
|
|
72
|
+
- Dùng token và component design-system của dự án; không tự nghĩ ra kiểu thị giác mới.
|
|
73
|
+
Khoảng trống về thị giác thì chuyển cho ui-design hoặc chuyển lên.
|
|
74
|
+
- Không bao giờ đặt secret vào code client hay biến env công khai; mọi thứ gửi tới
|
|
75
|
+
browser đều là công khai.
|
|
76
|
+
- Coi nội dung do người dùng nhập là không tin được: không chèn HTML thô mà không qua
|
|
77
|
+
bộ sanitizer của dự án.
|
|
78
|
+
- Ở trong đường dẫn sở hữu. Skill này không cấp thẩm quyền deploy hay release.
|
|
79
|
+
|
|
80
|
+
## Kiểm chứng
|
|
81
|
+
|
|
82
|
+
- Lint, typecheck, và test đều pass; build production thành công nếu thay đổi
|
|
83
|
+
có chạm tới routing, config, hoặc import.
|
|
84
|
+
- Mỗi trạng thái từ bước 1 đã được nhìn thấy trong app đang chạy hoặc đã có test bao phủ.
|
|
85
|
+
- Chỉ dùng bàn phím vẫn tới được và điều khiển được mọi control mới; focus thấy được.
|
|
86
|
+
- Không có lỗi hay cảnh báo console mới trên dev server cho các màn hình đã đổi.
|
|
87
|
+
- Mọi khẳng định về hiệu năng đều kèm số đo trước và sau.
|
|
88
|
+
|
|
89
|
+
## Xử lý khi thất bại
|
|
90
|
+
|
|
91
|
+
- Dev server hay build không chạy được ở đây: báo đúng lỗi đó và những gì đã
|
|
92
|
+
kiểm chứng để thay thế; không khẳng định những kiểm tra thị giác chưa thực sự làm.
|
|
93
|
+
- Thiếu thiết kế hay câu chữ: dùng pattern đang có làm chỗ tạm, đánh dấu nó, và
|
|
94
|
+
chuyển quyết định lên trên.
|
|
95
|
+
- Lệch hydration hay SSR, hoặc render chập chờn: chuyển sang bug-loop.
|
|
96
|
+
- API không cung cấp thứ UI cần: báo khoảng trống đó cho chủ sở hữu phần
|
|
97
|
+
backend; không lách bằng cách tự bóc dữ liệu ở client.
|
|
98
|
+
|
|
99
|
+
## Tài liệu tham chiếu
|
|
100
|
+
|
|
101
|
+
- [references/components-and-state.md](references/components-and-state.md) — đọc khi chia component, chọn chỗ đặt state, hoặc xử lý form (bước 3).
|
|
102
|
+
- [references/data-fetching.md](references/data-fetching.md) — đọc khi tải, cache, thay đổi, hoặc làm mới dữ liệu server, hoặc xử lý tranh chấp (bước 4).
|
|
103
|
+
- [references/frameworks.md](references/frameworks.md) — đọc khi chọn SSR, SSG, hay CSR, server hay client component, hoặc chỗ đặt routing (bước 5).
|
|
104
|
+
- [references/accessibility.md](references/accessibility.md) — đọc khi dựng control tương tác, form, dialog, hay widget tự tạo (bước 6).
|
|
105
|
+
- [references/performance.md](references/performance.md) — đọc khi một màn hình chậm, bundle phình ra, hoặc ảnh và danh sách quá nặng (bước 8).
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Accessibility
|
|
2
|
+
|
|
3
|
+
Đọc khi dựng control tương tác, form, dialog, hay widget tự tạo.
|
|
4
|
+
|
|
5
|
+
Nhắm tới WCAG 2.2 AA trừ khi dự án nêu mục tiêu khác. Trước hết hãy dùng các component
|
|
6
|
+
design-system đã đạt accessibility của dự án; chúng thường đã xử lý focus và ARIA.
|
|
7
|
+
|
|
8
|
+
## HTML semantic trước đã
|
|
9
|
+
|
|
10
|
+
- Dùng phần tử native đúng mục đích của nó: `button` cho hành động, `a href` cho
|
|
11
|
+
điều hướng, `input`/`select`/`textarea` cho dữ liệu, `label` cho nhãn, `table` cho
|
|
12
|
+
dữ liệu dạng bảng, danh sách cho danh sách.
|
|
13
|
+
- Không bao giờ dùng `div` hay `span` gắn click handler làm nút; nó thiếu hỗ trợ bàn phím
|
|
14
|
+
và vai trò.
|
|
15
|
+
- Một `h1` cho mỗi trang và tiêu đề theo thứ tự; có landmark (`header`, `nav`, `main`,
|
|
16
|
+
`footer`) để người dùng trình đọc màn hình nhảy được.
|
|
17
|
+
- Đặt `lang` cho trang và một tiêu đề tài liệu có nghĩa cho mỗi route.
|
|
18
|
+
|
|
19
|
+
## Bàn phím
|
|
20
|
+
|
|
21
|
+
- Mọi thứ điều khiển được bằng chuột đều điều khiển được bằng bàn phím: Tab và Shift+Tab để di chuyển,
|
|
22
|
+
Enter hoặc Space để kích hoạt, Escape để bỏ qua, các mũi tên bên trong widget phức hợp
|
|
23
|
+
(menu, tab, listbox) theo các pattern của ARIA Authoring Practices.
|
|
24
|
+
- Thứ tự Tab theo thứ tự thị giác. Tránh `tabindex` dương; chỉ dùng `tabindex="0"`
|
|
25
|
+
cho widget tự tạo cần focus được và `-1` cho các đích focus bằng chương trình.
|
|
26
|
+
- Không có bẫy bàn phím, trừ dialog dạng modal giữ focus trong lúc nó đang mở.
|
|
27
|
+
- Cung cấp link bỏ qua để tới nội dung chính trên những trang có phần điều hướng dài.
|
|
28
|
+
|
|
29
|
+
## Quản lý focus
|
|
30
|
+
|
|
31
|
+
- Focus phải thấy được; không bỏ viền mà không có một kiểu khác thấy được tương đương.
|
|
32
|
+
- Dialog: chuyển focus vào dialog khi mở, giữ nó trong lúc mở, đóng khi nhấn Escape,
|
|
33
|
+
trả focus về phần tử đã mở nó khi đóng. Ưu tiên phần tử `dialog` native hoặc
|
|
34
|
+
component dialog của dự án.
|
|
35
|
+
- Sau khi điều hướng ở client, chuyển focus tới tiêu đề của trang mới hoặc vùng chính,
|
|
36
|
+
hoặc dùng cơ chế thông báo route của framework.
|
|
37
|
+
- Sau một lỗi form, focus vào field không hợp lệ đầu tiên hoặc vào bản tóm tắt lỗi.
|
|
38
|
+
- Sau khi xóa một mục, chuyển focus tới một mục lân cận hợp lý.
|
|
39
|
+
|
|
40
|
+
## Chỉ dùng ARIA khi cần
|
|
41
|
+
|
|
42
|
+
- Không có ARIA còn tốt hơn ARIA sai. Chỉ dùng khi HTML native không diễn đạt được
|
|
43
|
+
vai trò, trạng thái, hay quan hệ.
|
|
44
|
+
- Những cách dùng chính đáng thường gặp: `aria-expanded` và `aria-controls` trên phần tử
|
|
45
|
+
mở ra nội dung, `aria-current` cho mục điều hướng hiện tại, `aria-describedby` cho gợi ý và
|
|
46
|
+
lỗi, vùng `aria-live` cho các thông báo trạng thái bất đồng bộ, `aria-label` cho nút
|
|
47
|
+
chỉ có icon.
|
|
48
|
+
- Widget tự tạo phải cài đặt đầy đủ pattern bàn phím của vai trò nó; chỉ thêm một
|
|
49
|
+
`role` thì không đủ.
|
|
50
|
+
- Không ẩn nội dung focus được bằng `aria-hidden`.
|
|
51
|
+
|
|
52
|
+
## Form
|
|
53
|
+
|
|
54
|
+
- Mọi input đều có nhãn gắn được bằng chương trình (nên có `label` thấy được). Placeholder
|
|
55
|
+
không phải nhãn.
|
|
56
|
+
- Đánh dấu field bắt buộc bằng chữ và bằng `required` hoặc `aria-required`.
|
|
57
|
+
- Gắn thông báo lỗi với field (`aria-describedby`) và đặt
|
|
58
|
+
`aria-invalid` khi không hợp lệ. Không dựa vào màu đơn thuần.
|
|
59
|
+
- Nhóm các control liên quan bằng `fieldset` và `legend`.
|
|
60
|
+
- Dùng đúng loại input và đúng giá trị `autocomplete`.
|
|
61
|
+
|
|
62
|
+
## Thị giác
|
|
63
|
+
|
|
64
|
+
- Tương phản chữ ít nhất 4.5:1 (3:1 với chữ lớn); tương phản của component UI và chỉ báo
|
|
65
|
+
focus ít nhất 3:1. Dùng token của dự án; báo token không đạt cho
|
|
66
|
+
ui-design chứ đừng tự nghĩ ra màu.
|
|
67
|
+
- Không truyền tải thông tin chỉ bằng màu; hãy thêm chữ, icon, hay họa tiết.
|
|
68
|
+
- Hỗ trợ zoom 200% và khung nhìn hẹp mà không mất nội dung và không phải cuộn
|
|
69
|
+
ngang để đọc chữ.
|
|
70
|
+
- Đích tương tác đủ lớn để bấm (ít nhất 24 nhân 24 CSS pixel).
|
|
71
|
+
- Tôn trọng `prefers-reduced-motion` với những hoạt họa không thiết yếu.
|
|
72
|
+
|
|
73
|
+
## Media và nội dung
|
|
74
|
+
|
|
75
|
+
- Ảnh mang nghĩa thì có chữ `alt` mô tả mục đích của nó; ảnh trang trí thì dùng
|
|
76
|
+
`alt=""`.
|
|
77
|
+
- Nút chỉ có icon thì có tên truy cập được.
|
|
78
|
+
- Video có phụ đề; audio có bản ghi lời khi dự án hỗ trợ.
|
|
79
|
+
- Chữ của link mô tả đích đến; tránh kiểu "bấm vào đây".
|
|
80
|
+
|
|
81
|
+
## Cách kiểm
|
|
82
|
+
|
|
83
|
+
- Vận hành tính năng chỉ bằng bàn phím.
|
|
84
|
+
- Chạy công cụ kiểm tự động của dự án (ví dụ công cụ dựa trên axe) nếu có;
|
|
85
|
+
công cụ tự động chỉ tìm ra một phần số vấn đề.
|
|
86
|
+
- Kiểm thử nhanh bằng trình đọc màn hình khi thay đổi có đưa vào một widget tự tạo.
|
package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Component và state
|
|
2
|
+
|
|
3
|
+
Đọc khi chia component, chọn chỗ đặt state, hoặc xử lý form.
|
|
4
|
+
|
|
5
|
+
Ví dụ dùng thuật ngữ React; cùng ý tưởng đó map sang Vue (props, emits, refs, computed,
|
|
6
|
+
composable) và Svelte (props, store, rune hoặc câu lệnh reactive). Hãy theo
|
|
7
|
+
pattern và bố trí file đang có của dự án.
|
|
8
|
+
|
|
9
|
+
## Cấu trúc component
|
|
10
|
+
|
|
11
|
+
- Một component, một việc. Chia khi một phần có state riêng, được dùng lại, hoặc làm
|
|
12
|
+
component cha khó đọc; không chia chỉ để file ngắn đi.
|
|
13
|
+
- Tách container tải dữ liệu khỏi component trình bày khi dự án làm vậy;
|
|
14
|
+
component trình bày nhận props và dễ test.
|
|
15
|
+
- Props chảy xuống, event chảy lên. Đặt tên callback theo ý định (`onSubmit`,
|
|
16
|
+
`onSelect`), không theo tên event của DOM.
|
|
17
|
+
- Ưu tiên composition (children, slot) hơn là nhiều props boolean bật tắt layout.
|
|
18
|
+
- Giữ component thuần khi render: không fetch, không subscribe, không thay đổi dữ liệu trong
|
|
19
|
+
thân render; dùng cơ chế effect hoặc lifecycle của framework.
|
|
20
|
+
- Dùng key ổn định từ ID của dữ liệu trong danh sách, không bao giờ dùng chỉ số mảng cho danh sách xếp lại được.
|
|
21
|
+
- Chỉ bóc logic dùng lại ra thành hook hoặc composable khi đã có chỗ dùng thứ hai.
|
|
22
|
+
|
|
23
|
+
## State nằm ở đâu
|
|
24
|
+
|
|
25
|
+
Chọn chỗ ở hẹp nhất mà vẫn chạy được:
|
|
26
|
+
|
|
27
|
+
| Loại | Chỗ ở |
|
|
28
|
+
| --- | --- |
|
|
29
|
+
| Giá trị chỉ một component dùng | state cục bộ của component |
|
|
30
|
+
| Giá trị dùng chung giữa các component cùng cấp | đưa lên component cha gần nhất |
|
|
31
|
+
| Giá trị suy ra được từ state hay props khác | tính nó ra; đừng lưu lại |
|
|
32
|
+
| Dữ liệu từ server | cache lấy dữ liệu của dự án, không phải state toàn cục |
|
|
33
|
+
| Đáng nằm trên URL (filter, tab, trang, ID đang chọn) | tham số route hoặc query string |
|
|
34
|
+
| Dữ liệu nhập trong form | state của form (cục bộ hoặc thư viện form của dự án) |
|
|
35
|
+
| Thực sự dùng toàn app (theme, session, locale) | context hoặc store của dự án |
|
|
36
|
+
|
|
37
|
+
- State bị trùng lặp sẽ lệch nhau. Nếu hai chỗ giữ cùng một sự thật, hãy giữ một nguồn và
|
|
38
|
+
suy ra chỗ kia.
|
|
39
|
+
- Tránh đồng bộ state bằng effect (`useEffect` copy props vào state); hãy suy ra
|
|
40
|
+
trong lúc render hoặc reset bằng key.
|
|
41
|
+
- Context render lại mọi consumer khi đổi; hãy tách context hoặc dùng store nếu một
|
|
42
|
+
giá trị đổi liên tục được dùng chung rộng khắp.
|
|
43
|
+
- Đặt lên URL những state đáng sống sót qua lần tải lại hoặc đáng chia sẻ được.
|
|
44
|
+
- Không thêm thư viện store toàn cục mà không có quyết định của chủ sở hữu.
|
|
45
|
+
|
|
46
|
+
## Effect và lifecycle
|
|
47
|
+
|
|
48
|
+
- Dùng effect để đồng bộ với thứ gì bên ngoài (subscription, timer, DOM
|
|
49
|
+
API), không để tính giá trị hay phản ứng với event của người dùng.
|
|
50
|
+
- Mọi subscription, listener, timer, hay observer đều phải được dọn.
|
|
51
|
+
- Xử lý việc effect bị gọi hai lần ở strict mode khi dev: effect phải an toàn khi chạy,
|
|
52
|
+
dọn, rồi chạy lại.
|
|
53
|
+
|
|
54
|
+
## Form
|
|
55
|
+
|
|
56
|
+
- Dùng cách làm form của dự án (form native, input có kiểm soát, hoặc thư viện form
|
|
57
|
+
của nó) một cách nhất quán.
|
|
58
|
+
- Mọi input đều có nhãn. Hiện lỗi validate ngay cạnh field và tóm tắt lại
|
|
59
|
+
khi submit; chuyển focus tới lỗi đầu tiên.
|
|
60
|
+
- Validate ở client để phản hồi nhanh; server vẫn là nơi có thẩm quyền.
|
|
61
|
+
- Vô hiệu hóa hoặc chặn hành động submit khi đang chờ để tránh submit hai lần;
|
|
62
|
+
hiện tiến trình.
|
|
63
|
+
- Giữ lại dữ liệu đã nhập khi submit thất bại.
|
|
64
|
+
- Coi phản hồi validate của server là nguồn của các lỗi theo field.
|
|
65
|
+
|
|
66
|
+
## Kiểu và hợp đồng
|
|
67
|
+
|
|
68
|
+
- Khai kiểu cho props và event bằng hệ kiểu của dự án (TypeScript, PropTypes, hoặc
|
|
69
|
+
kiểu riêng của framework).
|
|
70
|
+
- Chỉ chia sẻ kiểu của phản hồi API với backend qua cơ chế đang có của dự án
|
|
71
|
+
(kiểu được sinh ra, package dùng chung); không copy tay những kiểu rồi sẽ lệch nhau.
|
|
72
|
+
- Thu hẹp dữ liệu có thể null ngay tại biên để component nhận được giá trị đầy đủ hoặc một
|
|
73
|
+
trạng thái rỗng tường minh.
|
|
74
|
+
|
|
75
|
+
## Styling
|
|
76
|
+
|
|
77
|
+
- Dùng hệ thống styling của dự án (CSS module, utility class, CSS-in-JS, style có
|
|
78
|
+
phạm vi) và các design token. Không trộn thêm cách thứ hai.
|
|
79
|
+
- Tránh giá trị thần kỳ viết thẳng cho khoảng cách và màu khi đã có token.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Lấy dữ liệu
|
|
2
|
+
|
|
3
|
+
Đọc khi tải, cache, thay đổi, hoặc làm mới dữ liệu server, hoặc khi xử lý tranh chấp.
|
|
4
|
+
|
|
5
|
+
Dùng cơ chế đang có của dự án: loader hay server component của framework, một thư viện
|
|
6
|
+
query-cache (TanStack Query, SWR, Apollo, RTK Query là các ví dụ), hoặc fetch thuần
|
|
7
|
+
gói trong một client dùng chung. Không thêm cơ chế thứ hai.
|
|
8
|
+
|
|
9
|
+
## Mọi request đều có bốn trạng thái
|
|
10
|
+
|
|
11
|
+
- Loading: hiện skeleton hoặc spinner có kích thước như nội dung cuối để tránh dịch
|
|
12
|
+
layout. Với lần tải nhanh, hoãn chỉ báo một chút để nó không nháy.
|
|
13
|
+
- Lỗi: hiện một thông báo có ích và một hành động thử lại. Phân biệt "không tìm thấy",
|
|
14
|
+
"không được phép", "offline", và "lỗi server" khi API cho phép. Không hiện object
|
|
15
|
+
lỗi thô hay stack trace.
|
|
16
|
+
- Rỗng: một trạng thái riêng kèm hướng dẫn hoặc một hành động, không phải một vùng trắng.
|
|
17
|
+
- Thành công: render dữ liệu; giữ dữ liệu trước đó hiển thị trong lúc làm mới ở nền thay vì
|
|
18
|
+
nháy trở về trạng thái loading.
|
|
19
|
+
|
|
20
|
+
Cũng hãy tính tới dữ liệu một phần (một số mục bị lỗi) và dữ liệu cũ (hiện ra trong lúc
|
|
21
|
+
đang làm mới).
|
|
22
|
+
|
|
23
|
+
## Fetch ở đâu
|
|
24
|
+
|
|
25
|
+
- Ưu tiên tải ở cấp route hoặc phía server khi framework hỗ trợ, để dữ liệu
|
|
26
|
+
bắt đầu tải cùng lúc với điều hướng và tránh được thác nước request.
|
|
27
|
+
- Khởi động các request độc lập song song; không xâu chúng lại trong các component lồng nhau
|
|
28
|
+
trừ khi cái này phụ thuộc cái kia.
|
|
29
|
+
- Không fetch trong lúc render. Ở client component hãy dùng thư viện cache hoặc một effect
|
|
30
|
+
có dọn dẹp.
|
|
31
|
+
- Giữ API client trong một module: base URL, header hay cookie auth, parse JSON,
|
|
32
|
+
và chuẩn hóa lỗi.
|
|
33
|
+
|
|
34
|
+
## Cache
|
|
35
|
+
|
|
36
|
+
- Đặt key cho dữ liệu cache theo mọi thứ ảnh hưởng tới phản hồi (tài nguyên, ID, filter,
|
|
37
|
+
trang, người dùng hay tenant).
|
|
38
|
+
- Quyết định độ tươi cho từng tài nguyên: dữ liệu được coi là tươi trong bao lâu, và khi nào fetch lại
|
|
39
|
+
(khi focus, khi kết nối lại, theo chu kỳ, hoặc khi vô hiệu tường minh).
|
|
40
|
+
- Vô hiệu hoặc cập nhật các key bị ảnh hưởng sau một mutation; không để danh sách còn cũ
|
|
41
|
+
sau khi tạo hay xóa.
|
|
42
|
+
- Xóa cache riêng của người dùng khi logout hoặc đổi tài khoản.
|
|
43
|
+
- Tôn trọng các header cache HTTP mà backend đã đặt; không cache những phản hồi mang tính
|
|
44
|
+
cá nhân vào cache dùng chung.
|
|
45
|
+
|
|
46
|
+
## Tranh chấp (race condition)
|
|
47
|
+
|
|
48
|
+
- Một phản hồi đến trước nhưng chậm hơn không được ghi đè lên phản hồi mới hơn. Hãy hủy request
|
|
49
|
+
trước đó (AbortController hoặc cơ chế hủy của thư viện) hoặc bỏ qua kết quả có key
|
|
50
|
+
không còn khớp với dữ liệu nhập hiện tại.
|
|
51
|
+
- Debounce việc tìm kiếm khi đang gõ và hủy các request đang bay khi có dữ liệu nhập mới.
|
|
52
|
+
- Bỏ qua kết quả sau khi unmount; dọn subscription và abort các request đang bay.
|
|
53
|
+
- Chặn việc submit mutation hai lần: vô hiệu hóa khi đang chờ, và gửi một
|
|
54
|
+
idempotency key nếu API hỗ trợ.
|
|
55
|
+
|
|
56
|
+
## Mutation
|
|
57
|
+
|
|
58
|
+
- Hiện trạng thái đang chờ trên chính control đã khởi động mutation đó.
|
|
59
|
+
- Chỉ cập nhật lạc quan khi thất bại là hiếm và đảo lại được; hoàn tác khi lỗi
|
|
60
|
+
và nói cho người dùng biết.
|
|
61
|
+
- Khi server trả lỗi validate, hãy map chúng về từng field.
|
|
62
|
+
- Sau khi thành công, cập nhật hoặc vô hiệu cache, rồi chuyển focus hoặc thông báo
|
|
63
|
+
kết quả cho công nghệ trợ giúp.
|
|
64
|
+
|
|
65
|
+
## Lỗi và thử lại
|
|
66
|
+
|
|
67
|
+
- Chỉ tự động thử lại các lần đọc idempotent, với giới hạn nhỏ và có backoff. Không
|
|
68
|
+
tự động thử lại mutation trừ khi chúng idempotent.
|
|
69
|
+
- Xử lý 401 ở một chỗ duy nhất (refresh hoặc chuyển tới trang login theo quy ước của dự án).
|
|
70
|
+
- Dùng error boundary hoặc route lỗi của framework cho những lỗi bất ngờ, để một
|
|
71
|
+
widget vỡ không làm trắng cả trang.
|
|
72
|
+
- Báo lỗi qua hệ thống giám sát đang có của dự án, không kèm dữ liệu cá nhân hay
|
|
73
|
+
token.
|
|
74
|
+
|
|
75
|
+
## Bảo mật
|
|
76
|
+
|
|
77
|
+
- Không bao giờ nhúng secret hay API key riêng vào code client; hãy đi qua
|
|
78
|
+
backend.
|
|
79
|
+
- Chỉ gửi thông tin đăng nhập tới các origin của chính dự án.
|
|
80
|
+
- Không tin các kiểm tra phía client về phân quyền; server mới là nơi thực thi.
|
|
81
|
+
|
|
82
|
+
## Ghi chú về test
|
|
83
|
+
|
|
84
|
+
- Mock mạng ở tầng HTTP (công cụ mock request của dự án) chứ không
|
|
85
|
+
mock phần bên trong của thư viện cache.
|
|
86
|
+
- Test cả bốn trạng thái và một tình huống chậm-rồi-nhanh cho các input tìm kiếm.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Framework, render, và routing
|
|
2
|
+
|
|
3
|
+
Đọc khi chọn SSR, SSG, hay CSR, server hay client component, hoặc chỗ đặt
|
|
4
|
+
routing.
|
|
5
|
+
|
|
6
|
+
Quy ước của framework đổi giữa các bản major. Hãy xác định đúng framework
|
|
7
|
+
và phiên bản từ `package.json` và lockfile, theo quy ước của chính
|
|
8
|
+
phiên bản đó, và xem tài liệu chính thức của nó (hoặc tài liệu và type của package đã
|
|
9
|
+
cài) trước khi dựa vào một API. Nếu dự án trộn quy ước cũ và mới (ví
|
|
10
|
+
dụ vừa pages router vừa app router), hãy theo cái đang dùng ở vùng bạn
|
|
11
|
+
đang sửa và không tự ý chuyển đổi nó.
|
|
12
|
+
|
|
13
|
+
## Các chế độ render
|
|
14
|
+
|
|
15
|
+
| Chế độ | Render ở đâu | Phù hợp cho | Cái giá |
|
|
16
|
+
| --- | --- | --- | --- |
|
|
17
|
+
| CSR (phía client) | trong browser | màn hình dạng app sau khi đăng nhập | first paint chậm hơn, SEO tùy crawler |
|
|
18
|
+
| SSR (mỗi request) | trên server mỗi request | nội dung cá nhân hóa hay tươi mới, SEO | tốn server, có độ trễ mỗi request |
|
|
19
|
+
| SSG (lúc build) | một lần khi build | nội dung ổn định, tài liệu, marketing | phải build lại hoặc revalidate để cập nhật |
|
|
20
|
+
| Static tăng dần / có revalidate | khi build, làm mới theo chu kỳ hay theo trigger | nội dung phần lớn tĩnh nhưng có đổi | có khoảng thời gian dữ liệu cũ |
|
|
21
|
+
| Streaming / một phần | server stream từng phần khi sẵn sàng | phần chậm trên bộ khung nhanh | trạng thái loading phức tạp hơn |
|
|
22
|
+
|
|
23
|
+
- Theo đúng chế độ mà các route xung quanh đang dùng, trừ khi brief yêu cầu đổi.
|
|
24
|
+
- Đổi chế độ render của một route ảnh hưởng tới cache, hosting, và SEO; hãy chuyển
|
|
25
|
+
quyết định đó lên trên.
|
|
26
|
+
|
|
27
|
+
## Server component và client component
|
|
28
|
+
|
|
29
|
+
Áp dụng cho framework có tách server/client (React Server Component trong
|
|
30
|
+
app router của Next.js và tương tự; khái niệm tương đương ở Nuxt, SvelteKit, island của Astro).
|
|
31
|
+
|
|
32
|
+
- Server component: fetch dữ liệu, đọc config chỉ có ở server, render markup tĩnh,
|
|
33
|
+
không gửi JS của component. Chúng không dùng được state client, effect, hay API browser.
|
|
34
|
+
- Client component: tính tương tác, state, effect, API browser. Đánh dấu chúng theo
|
|
35
|
+
cách framework yêu cầu (ví dụ chỉ thị `"use client"`) ở vị trí càng thấp trong cây càng
|
|
36
|
+
tốt, để phần lớn markup vẫn được render ở server.
|
|
37
|
+
- Props truyền từ server sang client phải serialize được; không truyền hàm hay
|
|
38
|
+
instance của class.
|
|
39
|
+
- Không bao giờ import module chỉ dành cho server (client database, secret) vào code client.
|
|
40
|
+
Dùng cơ chế chặn server-only của framework nếu nó có.
|
|
41
|
+
- Server action hay form action là endpoint công khai: hãy validate dữ liệu nhập và kiểm tra
|
|
42
|
+
phân quyền trong chúng như với bất kỳ API nào.
|
|
43
|
+
|
|
44
|
+
## Hydration
|
|
45
|
+
|
|
46
|
+
- Server và client phải render ra cùng một markup ban đầu. Tránh dùng khi render các thứ như
|
|
47
|
+
`Date.now()`, giá trị ngẫu nhiên, `window`, hay định dạng phụ thuộc locale mà không có
|
|
48
|
+
dữ liệu nhập ổn định.
|
|
49
|
+
- Đọc các giá trị chỉ có ở browser sau khi mount, hoặc chỉ render chúng ở client qua
|
|
50
|
+
cơ chế của framework.
|
|
51
|
+
- Coi cảnh báo hydration là bug.
|
|
52
|
+
|
|
53
|
+
## Quy ước routing
|
|
54
|
+
|
|
55
|
+
- Theo hệ thống routing của dự án: dựa trên file (Next.js, Nuxt, SvelteKit, Remix
|
|
56
|
+
hay React Router ở chế độ framework) hoặc dựa trên config (React Router, Vue Router).
|
|
57
|
+
- Đặt phần tải dữ liệu ở nơi framework mong đợi (loader, server component,
|
|
58
|
+
hàm `load`, route guard) để tránh thác nước request ở client.
|
|
59
|
+
- Dùng component link của framework cho điều hướng nội bộ, để prefetch và
|
|
60
|
+
chuyển trang ở client hoạt động.
|
|
61
|
+
- Dùng cơ chế xử lý loading, lỗi, và không-tìm-thấy ở cấp route mà framework cung cấp.
|
|
62
|
+
- Giữ state thuộc URL (filter, phân trang, tab) trong tham số hoặc query string.
|
|
63
|
+
- Bảo vệ route ở server (middleware, loader) chứ không chỉ ở UI; chỉ redirect
|
|
64
|
+
ở client thì không bảo vệ được dữ liệu.
|
|
65
|
+
|
|
66
|
+
## Môi trường và config
|
|
67
|
+
|
|
68
|
+
- Biến env công khai (tiền tố như `NEXT_PUBLIC_` hay `VITE_`) được nhúng vào
|
|
69
|
+
bundle client; không bao giờ đặt secret vào chúng.
|
|
70
|
+
- Tôn trọng dạng output build của dự án (static export, Node server, edge runtime);
|
|
71
|
+
API lúc chạy khác nhau giữa chúng.
|
|
72
|
+
|
|
73
|
+
## Khi không chắc
|
|
74
|
+
|
|
75
|
+
- Tìm route đang có gần nhất làm cùng loại việc đó và làm theo nó.
|
|
76
|
+
- Nếu tài liệu của phiên bản đã cài trái với ký ức hay với ví dụ, hãy theo tài liệu
|
|
77
|
+
và ghi lại khác biệt đó trong handoff.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Hiệu năng frontend
|
|
2
|
+
|
|
3
|
+
Đọc khi một màn hình chậm, bundle phình ra, hoặc ảnh và danh sách quá nặng.
|
|
4
|
+
|
|
5
|
+
Đo trước, rồi đổi một thứ, rồi đo lại trong cùng điều kiện
|
|
6
|
+
(cùng chế độ build, cùng thiết bị hay cấu hình giới hạn, cùng lượng dữ liệu). Bản build dev
|
|
7
|
+
chậm hơn và nhiễu hơn bản production; muốn khẳng định điều gì thì hãy profile bản production.
|
|
8
|
+
|
|
9
|
+
## Đo cái gì
|
|
10
|
+
|
|
11
|
+
- Core Web Vitals cho trải nghiệm trang: Largest Contentful Paint (tải),
|
|
12
|
+
Interaction to Next Paint (độ đáp ứng), Cumulative Layout Shift (độ ổn định).
|
|
13
|
+
Dùng công cụ đang có của dự án (Lighthouse, panel performance của browser, một dashboard
|
|
14
|
+
RUM) và báo lại điều kiện đo.
|
|
15
|
+
- Chi phí render: profiler của framework (React DevTools Profiler, Vue DevTools) để
|
|
16
|
+
thấy component nào render, bao nhiêu lần, và mất bao lâu.
|
|
17
|
+
- Kích thước bundle: công cụ phân tích hoặc output thống kê của build cho các route bị ảnh hưởng.
|
|
18
|
+
- Mạng: biểu đồ thác nước của route; tìm những request nối tiếp nhau và payload lớn.
|
|
19
|
+
|
|
20
|
+
Dùng ngân sách mà dự án đã định ra. Đừng tự nghĩ ra một ngưỡng cố định; hãy báo
|
|
21
|
+
các con số trước và sau.
|
|
22
|
+
|
|
23
|
+
## Chi phí render
|
|
24
|
+
|
|
25
|
+
- Trước hết hãy bỏ những việc không cần: state đặt quá cao làm render lại cả vùng rộng,
|
|
26
|
+
dữ liệu suy ra bị tính lại trong lúc render trên dữ liệu nhập lớn, effect đặt state ở
|
|
27
|
+
mỗi lần render, và giá trị context bị tạo lại mỗi lần render.
|
|
28
|
+
- Đưa state xuống đúng chỗ nó được dùng, hoặc chia component ra để state đổi nhanh
|
|
29
|
+
chỉ render lại một nhánh nhỏ.
|
|
30
|
+
- Chỉ ghi nhớ (`memo`, `useMemo`, `useCallback`, giá trị computed) ở nơi
|
|
31
|
+
profiler cho thấy một chi phí đo được, hoặc ở nơi compiler hay luật lint của dự án
|
|
32
|
+
đã xử lý giúp. Ghi nhớ mà không đo thì thêm phức tạp và có thể che bug do
|
|
33
|
+
phụ thuộc đã cũ.
|
|
34
|
+
- Virtual hóa danh sách dài (hàng trăm dòng hoặc hơn) theo cách đang có của
|
|
35
|
+
dự án; phân trang khi chưa đáng để virtual hóa.
|
|
36
|
+
- Chỉ đưa phần tính toán nặng ra khỏi luồng chính (một web worker) khi đã đo.
|
|
37
|
+
- Hoãn các cập nhật không gấp bằng API transition hay lập lịch của framework khi
|
|
38
|
+
gõ chữ thấy có cảm giác trễ.
|
|
39
|
+
|
|
40
|
+
## Bundle và tải
|
|
41
|
+
|
|
42
|
+
- Chia theo route; lazy-load những component nặng, ít dùng (editor, biểu đồ, bản đồ)
|
|
43
|
+
đặt sau tương tác hoặc view thực sự cần chúng.
|
|
44
|
+
- Kiểm tra một phụ thuộc mới tốn bao nhiêu trước khi đề xuất nó; ưu tiên API của nền tảng và
|
|
45
|
+
các phụ thuộc đang có. Thêm một cái là quyết định của chủ sở hữu.
|
|
46
|
+
- Chỉ import những gì bạn dùng; tránh import kiểu barrel làm mất tác dụng tree shaking khi
|
|
47
|
+
bundler xử lý chúng không tốt.
|
|
48
|
+
- Đừng vô tình gửi code chỉ dành cho server, file dữ liệu lớn, hay source map
|
|
49
|
+
xuống client.
|
|
50
|
+
- Preload các tài nguyên quan trọng (ảnh LCP, font chính) khi số đo cho thấy có
|
|
51
|
+
độ trễ; đừng preload mọi thứ.
|
|
52
|
+
- Render ở server hay sinh tĩnh giúp cải thiện first paint cho các trang nội dung; xem
|
|
53
|
+
frameworks.md.
|
|
54
|
+
|
|
55
|
+
## Ảnh và media
|
|
56
|
+
|
|
57
|
+
- Phục vụ ảnh đã đúng kích thước, đã nén, ở các định dạng hiện đại, qua pipeline hay
|
|
58
|
+
component ảnh của dự án.
|
|
59
|
+
- Luôn đặt width và height (hoặc tỉ lệ khung) để tránh dịch layout.
|
|
60
|
+
- Lazy-load các ảnh nằm dưới màn hình đầu; không lazy-load ảnh LCP.
|
|
61
|
+
- Dùng `srcset` và `sizes` responsive để màn hình nhỏ tải file nhỏ.
|
|
62
|
+
- Ưu tiên CSS hoặc SVG cho icon và hình đơn giản.
|
|
63
|
+
|
|
64
|
+
## Độ ổn định layout và độ đáp ứng
|
|
65
|
+
|
|
66
|
+
- Dành sẵn chỗ cho nội dung bất đồng bộ, quảng cáo, và nội dung nhúng.
|
|
67
|
+
- Tránh chèn nội dung lên phía trên nội dung đang có sau khi tải xong.
|
|
68
|
+
- Tải font với một chiến lược hiển thị tránh chữ vô hình, dùng thiết lập font
|
|
69
|
+
của dự án.
|
|
70
|
+
- Giữ các handler nhập liệu ngắn gọn; chia nhỏ task dài; tránh giật layout (đọc
|
|
71
|
+
layout rồi ghi style trong một vòng lặp).
|
|
72
|
+
|
|
73
|
+
## Báo cáo
|
|
74
|
+
|
|
75
|
+
- Nêu rõ chỉ số, công cụ, chế độ build, thiết bị hay cấu hình giới hạn, lượng dữ liệu, và
|
|
76
|
+
giá trị trước và sau.
|
|
77
|
+
- Nếu một thay đổi không làm chỉ số đo được nhúc nhích, hãy hoàn tác nó chứ đừng giữ lại
|
|
78
|
+
cho chắc.
|