Chuẩn bị môi trường

Làm một lần cho mỗi máy. Sau bước này, mọi dự án Tasco trên máy đều cài được @tasco/* từ GitLab Package Registry.

1. Node và pnpm

Công cụ	Phiên bản	Ghi chú
Node.js	^22.19.0 || ^24.11.0 || >=26.0.0	Khai trong engines của app sinh từ CLI
pnpm	11.x	Không cài tay — bật corepack, pnpm tự khớp bản ghim trong packageManager
Git	bất kỳ

node -v          # phải nằm trong dải trên
corepack enable  # pnpm dùng đúng bản ghim ở packageManager của từng dự án

Dùng npm hay yarn vẫn chạy, nhưng mọi tài liệu, script và CI mẫu đều viết theo pnpm.

2. Token đọc registry

Package @tasco/* nằm trong GitLab Package Registry ở cấp group tasco. Cần một token đọc:

• Loại: Group Deploy Token của group tasco (hoặc Group Access Token).
• Scope: read_package_registry — chỉ đọc, không cần quyền ghi.
• Xin token: nhắn team core. Token dùng chung cho cả group nên không phải thêm từng người vào project core.

Không commit token

Token chỉ nằm ở ~/.npmrc cá nhân hoặc biến môi trường NPM_TOKEN. File .npmrc trong dự án chỉ được phép tham chiếu ${NPM_TOKEN}.

Đặt token vào ~/.npmrc

# ~/.npmrc — dòng authToken PHẢI bắt đầu bằng //, không có https:
//gitlab.dnpwater.vn/api/v4/groups/tasco/-/packages/npm/:_authToken=<token-cua-ban>

Hoặc xuất biến môi trường trong shell profile:

export NPM_TOKEN=<token-cua-ban>

3. .npmrc của dự án

App tạo bằng CLI đã có sẵn file này; dự án có sẵn thì tự thêm:

# .npmrc — commit được vì không chứa token
@tasco:registry=https://gitlab.dnpwater.vn/api/v4/groups/tasco/-/packages/npm/
//gitlab.dnpwater.vn/api/v4/groups/tasco/-/packages/npm/:_authToken=${NPM_TOKEN}
auto-install-peers=true

Đường dẫn phải là group endpoint (/groups/tasco/-/packages/npm/). Instance endpoint (/api/v4/packages/npm/) trả 404 với người không phải member của project core — đây là nguyên nhân phổ biến nhất của lỗi cài đặt. Chi tiết và phần publish: Cấu hình .npmrc.

4. Kiểm tra

npm view @tasco/nuxt-layer-base version --registry https://gitlab.dnpwater.vn/api/v4/groups/tasco/-/packages/npm/

In ra số phiên bản là xong. Gặp lỗi thì tra bảng dưới.

Lỗi thường gặp

Hiện tượng	Nguyên nhân	Cách sửa
404 Not Found khi cài @tasco/*	.npmrc trỏ instance endpoint, hoặc token là PAT cá nhân của người chưa là member group	Trỏ group endpoint; dùng Group Deploy Token
401 Unauthorized	Dòng authToken viết https://… thay vì //…, hoặc NPM_TOKEN rỗng	Bỏ phần protocol; echo $NPM_TOKEN kiểm tra
ERR_PNPM_IGNORED_BUILDS	pnpm 11 chặn build script của dependency cho tới khi có quyết định tường minh	Chép khối allowBuilds trong pnpm-workspace.yaml của template CLI, hoặc chạy pnpm approve-builds
Cài xong nhưng thiếu kiểu TypeScript	Dự án chưa cài @tasco/ui	Thêm @tasco/ui vào dependencies (layer không re-export type)

Tiếp theo

• Dự án mới → Tạo app mới.
• Dự án đã có → Thêm vào dự án có sẵn.