Thiết lập monorepo

Làm một lần trên máy để phát triển core. Team sản phẩm chỉ dùng framework thì không cần — xem Chuẩn bị môi trường.

Công cụ

Công cụ	Phiên bản	Ghi chú
Node.js	24 (CI dùng node:24), tối thiểu 22.13	pnpm 11 không chạy trên Node cũ hơn 22.13
pnpm	11.7.0	Ghim ở packageManager; corepack enable tự dùng đúng bản
Git	Bản bất kỳ	Remote SSH cổng 2222

Máy có nhiều bản Node (nvm, fnm…) thì kiểm tra node -v trong đúng terminal sẽ chạy lệnh — sai bản Node là lỗi thường gặp nhất khi pnpm báo This version of pnpm requires at least Node.js v22.13.

Lấy code và cài

git clone ssh://git@gitlab.dnpwater.vn:2222/tasco/web-framework-core.git
cd web-framework-core
corepack enable
pnpm install
pnpm build

Mọi @tasco/* trong monorepo là workspace package nên pnpm install không cần token registry. Quyền cần có trên GitLab: Git workflow.

pnpm build build mọi package theo thứ tự phụ thuộc; chạy lại sau khi kéo code mới hoặc sau pnpm clean.

Cấu trúc

packages/
  theme/ utils/          TS thuần — token, lỗi, helper
  composables/           composable Nuxt
  ui/                    component C* (+ Storybook chạy cục bộ)
  nuxt-layer-base/       layer: plugin, middleware, BFF, IAM
  ai/ mcp/ cli/          AI, MCP server, create-tasco-app
  eslint-config/ tsconfig/
playground/              app Nuxt thử layer, đăng nhập giả
docs/                    VitePress — site này
scripts/                 docs-coverage, release-guard, port-antadmin
.changeset/              changeset chưa phát hành
.gitlab/                 template MR và issue

Vai trò từng package: Kiến trúc nội bộ.

Chạy khi phát triển

Việc	Lệnh	Địa chỉ
App thử layer	pnpm turbo run dev --filter=playground	http://localhost:3000
Site docs	pnpm turbo run dev --filter=docs	http://localhost:5173/v2/
Storybook (chỉ chạy cục bộ)	pnpm --filter @tasco/ui storybook	http://localhost:6006
Test một package	pnpm --filter @tasco/ui test	—
Test một file	pnpm --filter @tasco/utils test -- src/error.test.ts	—
Kiểm tra như CI	pnpm lint && pnpm typecheck && pnpm test && pnpm test:scripts && pnpm build	—

Playground và docs chạy qua turbo để package phụ thuộc được build trước. Chạy thẳng pnpm --filter playground dev khi package chưa build sẽ gặp TSCONFIG_ERROR — xem gotcha.

Playground

App Nuxt extends layer bằng workspace:*, bật sẵn auth.mock nên đăng nhập bằng tài khoản bất kỳ.

Trang	Để thử
/	Trang công khai (auth: false)
/orders	Danh sách dùng useTable + CTable, dữ liệu từ route giả server/api/orders.get.ts; cần quyền /orders/search
/admin	Chặn quyền: cần /admin/settings mà người dùng giả không có → trang 403
/ui-kit	Bày các component C*

Sửa component hay layer rồi thử ở đây trước khi mở MR; mô tả bước thử trong mục Test plan của MR.

Thử template CLI

node packages/cli/bin/create-tasco-app.mjs ../thu-app

App sinh ra ghim @tasco/* theo version hiện tại của CLI và cài từ registry — nó dùng bản đã phát hành, không dùng code đang sửa. Muốn thử thay đổi chưa phát hành thì dùng playground.

AI tooling trong repo core

.mcp.json ở gốc chạy @tasco/mcp thẳng từ source (node packages/mcp/bin/cli.mjs), nên phải pnpm --filter @tasco/mcp build trước. Skill /new-component và /doc-component có trong .claude/skills/. Chi tiết: MCP & AI review.

Sự cố thường gặp

Triệu chứng	Cách sửa
This version of pnpm requires at least Node.js v22.13	Chuyển sang Node 24 trong terminal đang dùng
[TSCONFIG_ERROR] Failed to load tsconfig '../packages/nuxt-layer-base/.nuxt/tsconfig.json'	pnpm build, rồi khởi động lại dev server (Vite giữ cache tsconfig hỏng)
ERR_PNPM_IGNORED_BUILDS sau khi thêm dependency	Quyết định true/false cho package đó trong allowBuilds của pnpm-workspace.yaml
Bảng API trong docs báo "Chưa có metadata…", hoặc docs không chạy vì thiếu component-meta.json	pnpm --filter @tasco/ui build
Trang tra cứu API trống hoặc cũ	Chạy lại dev docs — trang sinh mỗi lần dev/build

Liên quan

• Git workflow — nhánh, commit, MR.
• Test & coverage — chạy và viết test.
• CI/CD của core — CI chạy những gì.