Skip to content

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êuGhi 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ệnhpnpm 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 semverroot 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.sh

Quy ướ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-versionv20.20.2
package.json → packageManagerpnpm@9.15.9
engines.node>=20.20.2
engines.pnpm>=9.15.9
Docker buildnode:${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-store dockerignore; pnpm tạo store trong layer build theo cùng store-dir.

5. EditorConfig ​

Baseline:

  • charset = utf-8, end_of_line = lf, indent_size = 2, space
  • insert_final_newline = true, trim_trailing_whitespace = true
  • *.md: không trim trailing whitespace
  • Makefile: tab

Khớp Prettier endOfLine: "lf".


6. Prettier ​

File: prettier.config.mjs.

OptionGiá trị tham chiếu
printWidth120
tabWidth2
semitrue
singleQuotefalse
trailingComma"es5"
arrowParens"always"
proseWrap"never"
endOfLine"lf"
Pluginprettier-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):

PackageVai trò
eslint, @eslint/jsCore + recommended
typescript-eslintTS recommended
eslint-plugin-react / react-hooksReact
eslint-plugin-jsx-a11ya11y
eslint-plugin-simple-import-sortsort import/export
eslint-plugin-unused-importsunused imports
eslint-plugin-prettierprettier/prettier (warn)
eslint-config-prettiercuối — tắt rule xung đột Prettier
globalsbrowser + node

Nguyên tắc:

  • prettier/prettier: warn (format chính vẫn pnpm format)
  • Gate check dùng eslint . --max-warnings 0 → treat warnings as fail
  • Tắt react/react-in-jsx-scope, react/prop-types vớ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.json

extensions.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 ​

FieldQuy ước
nameTên repo/workspace (vd. platform-ui) — không trùng package publish @minap/…
privatetrue với monorepo root
versionSoT semver cho monorepo (single-version lock)
type"module" khi tooling ESM

Scripts baseline nên có ​

ScriptViệc
format / format:checkPrettier
lint / lint:fixESLint
typechecktsc (hoặc tsc -b)
testunit (Vitest hoặc tương đương)
checkFull gate fail-fast (xem §10)
version:sync / version:checkMonorepo single-version (nếu áp dụng)
docker:build / docker:pushNế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
→ build

E2E 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ộ / --check fail 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ọi version:sync trướ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).

StageBaseViệc
deps / buildnode:20.20.2-bookworm-slimpnpm install/build (tiện toolchain)
runtimenode:20.20.2-alpine + apk add nginxNode 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_NAME mặc định theo image
  • production.tag-and-push.sh: push chỉ tag versioned lên registry; :latest chỉ local

Runtime hardening đã chứng minh trên catalog:

  • Entrypoint: loop chờ TCP :3000 bằng Node net.connect (Alpine Node thường không có curl/wget), timeout rồi fail
  • Nginx: absolute_redirect off khi map port host (tránh Location về :80 trong container)
  • Next sau proxy prefix: cân trailingSlash vớ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ùng store-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
  • playground Next catalog, VitePress component docs generator
  • check: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) ​

  1. Pin Node/pnpm + .npmrc + workspace (nếu cần)
  2. EditorConfig + Prettier + ESLint + VS Code
  3. Scripts format / lint / typecheck / test / check
  4. (Monorepo) sync-version + checklist release
  5. pnpm format lần đầu nếu đổi printWidth/rule
  6. (Optional) Docker/devOps khi có artifact chạy được

15. Liên kết ​

Tài liệuVai trò
/framework/08-directory-structureLayout hub / nested + Spec Kit
/framework/12-workspace-topologyMulti-root workspace
/repositoriesCatalog repo (platform-ui, …)
platform-ui/README.mdHướng dẫn vận hành cụ thể của UI kit

16. Lịch sử trích xuất ​

NgàyNguồnGhi chú
2026-11-20platform-ui (tooling + Docker catalog minap-docs-ui)Baseline đầu tiên trên platform-docs

docs/ = SoT duy nhất · văn xuôi tiếng Việt + thuật ngữ chuyên ngành English