Appearance
Baseline tooling repo frontend/Node (tham chiếu platform-ui)
Version: 1.0
Date: 2026-11-20
Status: Working baseline
Tài liệu này trích xuất cấu trúc thư mục, cấu hình, và thư viện tooling chung từ nested repo platform-ui (UI kit monorepo) để sao chép / chỉnh nhẹ khi bootstrap repo Node/TypeScript/React khác trong tổ chức MINAP.
Không thay Constitution hay Gate. Không bắt buộc mọi Application dùng đủ stack UI kit — chỉ tái sử dụng phần “engineering baseline” (Node pin, format/lint, version, Docker catalog nếu có).
SoT sống (code): repo platform-ui trên nhánh đang ship. Khi lệch, ưu tiên cập nhật trang này cho khớp thực tế trong platform-ui.
1. Mục tiêu tái sử dụng
| Mục tiêu | Ghi chú |
|---|---|
| Pin Node / pnpm thống nhất | .node-version + packageManager + engines |
| Format / lint / IDE đồng bộ | EditorConfig + Prettier + ESLint flat + .vscode |
| Gate local một lệnh | pnpm check (fail-fast); Agent chỉ báo Owner hoàn thành khi gate này (hoặc tương đương) pass |
| Version monorepo khóa một semver | root package.json = SoT; version:sync / version:check |
| Image catalog (nếu cần) | Dockerfile + docker/ + devOps/production.*.sh |
2. Cấu trúc thư mục (phần portable)
Chỉ liệt kê phần tooling / DevOps nên nhân bản. Domain packages/, playground, VitePress kit là đặc thù platform-ui.
text
<repo>/
├── .node-version # v20.20.2
├── .editorconfig
├── .npmrc # SoT pnpm (kể cả trong Docker)
├── .gitignore # whitelist .vscode/settings + extensions
├── .vscode/
│ ├── extensions.json
│ └── settings.json
├── package.json # private root; scripts check/format/lint; engines
├── pnpm-workspace.yaml # nếu monorepo
├── pnpm-lock.yaml
├── prettier.config.mjs
├── eslint.config.js # flat config
├── scripts/
│ └── sync-version.mjs # optional monorepo single-version
├── Dockerfile # optional — một image thì một file ở root
├── docker/ # optional — nginx.conf, entrypoint.sh
│ ├── nginx.conf
│ └── entrypoint.sh
└── devOps/ # optional
├── production.build.sh
└── production.tag-and-push.shQuy ước Docker (một service): giữ Dockerfile ở root + assets trong docker/. Chỉ tách Dockerfile.<name> + docker/<name>/ khi có nhiều hơn một image thật sự.
3. Pin runtime
| Cơ chế | Giá trị tham chiếu (platform-ui) |
|---|---|
.node-version | v20.20.2 |
package.json → packageManager | pnpm@9.15.9 |
engines.node | >=20.20.2 |
engines.pnpm | >=9.15.9 |
| Docker build | node:${NODE_VERSION}-bookworm-slim |
| Docker runtime (catalog) | node:${NODE_VERSION}-alpine + apk add nginx |
production.build.sh đọc .node-version (bỏ prefix v) rồi truyền --build-arg NODE_VERSION=….
4. .npmrc (SoT)
File root là SoT — Docker COPY sớm, không tạo .npmrc giả trong image.
ini
auto-install-peers=true
strict-peer-dependencies=false
engine-strict=false
store-dir=.pnpm-store- Local: store trong repo (gitignore
.pnpm-store/). - Docker:
.pnpm-storedockerignore; pnpm tạo store trong layer build theo cùngstore-dir.
5. EditorConfig
Baseline:
charset = utf-8,end_of_line = lf,indent_size = 2, spaceinsert_final_newline = true,trim_trailing_whitespace = true*.md: không trim trailing whitespaceMakefile: tab
Khớp Prettier endOfLine: "lf".
6. Prettier
File: prettier.config.mjs.
| Option | Giá trị tham chiếu |
|---|---|
printWidth | 120 |
tabWidth | 2 |
semi | true |
singleQuote | false |
trailingComma | "es5" |
arrowParens | "always" |
proseWrap | "never" |
endOfLine | "lf" |
| Plugin | prettier-plugin-tailwindcss (repo có Tailwind) |
Scripts:
pnpm format→prettier --write .pnpm format:check→prettier --check .
Lưu ý bootstrap: đổi rule Prettier trên repo đã có code → chạy pnpm format + commit riêng (tránh trộn với commit cấu hình).
Repo không Tailwind: bỏ plugin / tailwindConfig / tailwindFunctions.
7. ESLint (flat)
File: eslint.config.js — ESM + typescript-eslint.
Stack tham chiếu (React/TS):
| Package | Vai trò |
|---|---|
eslint, @eslint/js | Core + recommended |
typescript-eslint | TS recommended |
eslint-plugin-react / react-hooks | React |
eslint-plugin-jsx-a11y | a11y |
eslint-plugin-simple-import-sort | sort import/export |
eslint-plugin-unused-imports | unused imports |
eslint-plugin-prettier | prettier/prettier (warn) |
eslint-config-prettier | cuối — tắt rule xung đột Prettier |
globals | browser + node |
Nguyên tắc:
prettier/prettier: warn (format chính vẫnpnpm format)- Gate
checkdùngeslint . --max-warnings 0→ treat warnings as fail - Tắt
react/react-in-jsx-scope,react/prop-typesvới React 17+ - Repo không React: bỏ plugin React/jsx-a11y; giữ TS + Prettier + import-sort + unused-imports
8. VS Code (commit có chủ đích)
.gitignore:
gitignore
.vscode/*
!.vscode/extensions.json
!.vscode/settings.jsonextensions.json (recommendations): Prettier, ESLint, Tailwind CSS (nếu có), EditorConfig.
settings.json (ý chính):
- Default formatter: Prettier
editor.formatOnSave:false(tránh đua với ESLint fix)editor.codeActionsOnSave→source.fixAll.eslint:explicit- Formatter Prettier cho js/ts/json/markdown
9. package.json root
| Field | Quy ước |
|---|---|
name | Tên repo/workspace (vd. platform-ui) — không trùng package publish @minap/… |
private | true với monorepo root |
version | SoT semver cho monorepo (single-version lock) |
type | "module" khi tooling ESM |
Scripts baseline nên có
| Script | Việc |
|---|---|
format / format:check | Prettier |
lint / lint:fix | ESLint |
typecheck | tsc (hoặc tsc -b) |
test | unit (Vitest hoặc tương đương) |
check | Full gate fail-fast (xem §10) |
version:sync / version:check | Monorepo single-version (nếu áp dụng) |
docker:build / docker:push | Nếu có image |
Không dùng tên pipeline cho gate local — dành cho CI/CD thật (check → image → deploy).
10. Gate: pnpm check (nhanh) vs smoke (optional)
Tham chiếu platform-ui — check không gồm Playwright (giữ gate local nhanh):
text
version:check
→ format:check
→ eslint . --max-warnings 0
→ typecheck
→ check:boundary # repo-specific; bỏ nếu không có
→ test # Vitest unit
→ buildE2E smoke tách riêng:
text
pnpm test:smoke # Playwright
pnpm check:all # = check && test:smoke (trước release / CI đầy đủ)Orchestrator / implement Agent: không báo Owner “hoàn thành” / sẵn sàng accept nếu chưa có evidence pnpm check exit 0 (hoặc bộ lệnh tương đương của repo). check:all chỉ khi Owner/checklist yêu cầu smoke. Không thay Gate 4 QA.
Dùng chuỗi && (fail-fast). Không cần npm-run-all cho gate tuần tự này.
11. Single-version lock (monorepo)
- SoT: root
package.json→version - Workspace packages (+ app nội bộ như
playground) cùng semver - Nội bộ deps:
workspace:*(version không ảnh hưởng resolve trong monorepo) scripts/sync-version.mjs: ghi đồng bộ /--checkfail nếu lệch- Release: bump root →
pnpm version:sync→ commit - Docker build: gọi
version:check(không ghi file trên host) pack/ publish: có thể gọiversion:synctrước khi đóng gói
12. Docker catalog (khi repo ship docs/UI tĩnh + app)
Mẫu platform-ui → image minap-docs-ui (tên image ≠ tên repo).
| Stage | Base | Việc |
|---|---|---|
| deps / build | node:20.20.2-bookworm-slim | pnpm install/build (tiện toolchain) |
| runtime | node:20.20.2-alpine + apk add nginx | Node pin đúng SoT; Nginx bản apk (vd. 1.28.x trên Alpine của image) |
devOps:
production.build.sh:APP_VERSION=<pkgVersion>-<gitSha8>; tag local:latest;DOCKER_IMAGE_NAMEmặc định theo imageproduction.tag-and-push.sh: push chỉ tag versioned lên registry;:latestchỉ local
Runtime hardening đã chứng minh trên catalog:
- Entrypoint: loop chờ TCP
:3000bằng Nodenet.connect(Alpine Node thường không có curl/wget), timeout rồi fail - Nginx:
absolute_redirect offkhi map port host (tránhLocationvề:80trong container) - Next sau proxy prefix: cân
trailingSlashvới rule Nginx - HEALTHCHECK: docs
/và app prefix (vd./playground/), probe bằng Node nếu không có wget
.npmrc root = SoT trong Docker (COPY sớm).
13. Thư viện / toolchain — checklist copy
Bắt buộc gần như mọi repo Node/TS
- [ ]
.node-version,engines,packageManager(pnpm) - [ ]
.editorconfig - [ ]
.npmrc(+ gitignore store nếu dùngstore-dir) - [ ] Prettier +
format/format:check - [ ] ESLint flat +
lint+ gate--max-warnings 0 - [ ]
.vscode/extensions.json+settings.json(whitelist gitignore) - [ ]
pnpm check(tối thiểu: format + lint + typecheck + test)
Khi monorepo pnpm
- [ ]
pnpm-workspace.yaml - [ ]
version:sync/version:check+ root version SoT
Khi React + Tailwind
- [ ] ESLint React / hooks / jsx-a11y
- [ ]
prettier-plugin-tailwindcss+ VS Code Tailwind extension
Khi có catalog image
- [ ]
Dockerfile+docker/+devOps/production.build.sh+tag-and-push - [ ] Image name có chủ đích (có thể khác tên repo)
- [ ] Node runtime pin =
.node-version
Không copy nguyên xi từ platform-ui
- Package names
@minap/ui*/ publish surface kit playgroundNext catalog, VitePress component docs generatorcheck:boundary(chỉ enforce import playground →@minap/ui)- ADR / specs / work-items của feature UI kit
14. Thứ tự bootstrap gợi ý (repo mới)
- Pin Node/pnpm +
.npmrc+ workspace (nếu cần) - EditorConfig + Prettier + ESLint + VS Code
- Scripts
format/lint/typecheck/test/check - (Monorepo)
sync-version+ checklist release pnpm formatlần đầu nếu đổi printWidth/rule- (Optional) Docker/devOps khi có artifact chạy được
15. Liên kết
| Tài liệu | Vai trò |
|---|---|
| /framework/08-directory-structure | Layout hub / nested + Spec Kit |
| /framework/12-workspace-topology | Multi-root workspace |
| /repositories | Catalog repo (platform-ui, …) |
platform-ui/README.md | Hướng dẫn vận hành cụ thể của UI kit |
16. Lịch sử trích xuất
| Ngày | Nguồn | Ghi chú |
|---|---|---|
| 2026-11-20 | platform-ui (tooling + Docker catalog minap-docs-ui) | Baseline đầu tiên trên platform-docs |