Giao diện
Cấu hình .npmrc và publish lên npmjs
Package @tasco-fe/* công khai trên npmjs.org (org tasco-fe, RFC 0004). Trang này nói về hai việc: cài (team sản phẩm) và publish (core CI).
Các bản 2.x
Bản 2.x (scope @tasco/*) vẫn nằm ở GitLab Package Registry nội bộ của project core, cần Deploy Token read_package_registry và .npmrc trỏ registry đó (hỏi team core địa chỉ). Chỉ cần khi app còn ở major 2; nâng lên 3.0 thì làm theo Migration.
A. Consumer — cài @tasco-fe/*
Không cần registry riêng, không cần token: package công khai nên pnpm install lấy thẳng từ npmjs. .npmrc của app chỉ cần các cài đặt của pnpm:
ini
auto-install-peers=trueApp còn dùng package riêng cần auth (ví dụ package nội bộ của team) thì token chỉ nằm ở ~/.npmrc cá nhân hoặc biến môi trường, không commit. Dòng _authToken phải bắt đầu bằng // (bỏ http:/https:) và cùng host/path với registry tương ứng, nếu không npm bỏ qua và request đi ẩn danh (401).
B. Publish — core CI
Job release trong .gitlab-ci.yml publish lên registry.npmjs.org bằng changeset publish, chỉ ở commit version (scripts/release-guard.mjs). Mỗi package khai publishConfig: { access: "public", registry: "https://registry.npmjs.org/" } và .changeset/config.json có access: "public".
yaml
release:
before_script:
- test -n "$NPM_TOKEN" || { echo "Thiếu biến CI/CD NPM_TOKEN."; exit 1; }
# Ghi vào ~/.npmrc của runner, không vào .npmrc của repo.
- umask 077 && printf '//registry.npmjs.org/:_authToken=%s\n' "$NPM_TOKEN" > "$HOME/.npmrc"
- pnpm install --frozen-lockfile
script:
- pnpm exec turbo run build --filter="./packages/*"
- pnpm changeset publishBiến CI/CD
| Biến | Giá trị | Cờ |
|---|---|---|
NPM_TOKEN | Granular access token của npmjs: quyền Read and write, giới hạn scope @tasco-fe, bật tuỳ chọn dùng cho tự động hoá (bỏ qua 2FA khi publish) | Masked + Protected |
Tạo token: npmjs.com → avatar → Access Tokens → Generate New Token → Granular Access Token. Đặt hạn dùng và gia hạn định kỳ; không dùng token kiểu Classic.
Gotcha
- Không gỡ được bản đã publish.
npm unpublishbị giới hạn sau 72 giờ và số version không dùng lại được. Mọi bảnlatestphải đi quabetatrước (xem Release). - Package scope cần
access: public. Org Free không publish được package private: thiếu cấu hình sẽ gặp402 Payment Required. - Biến Protected chỉ lộ ra trên nhánh/tag protected.
mainđã là protected branch. - Token chứa
$: tắt Expand variable reference (raw) cho biến. CI_JOB_TOKENkhông dùng được cho npmjs, chỉ dùng token riêng ở trên.
Troubleshooting nhanh
| Triệu chứng | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
401/403 khi publish | Token sai scope, hết hạn, hoặc không có quyền ghi vào @tasco-fe | Tạo lại token granular với quyền Read and write cho scope |
402 Payment Required | Package đang restricted trên org Free | Đặt access: public (cả publishConfig và .changeset/config.json) |
404 Not Found khi publish | Org tasco-fe không tồn tại hoặc tài khoản tạo token không là thành viên | Kiểm tra bằng npm org ls tasco-fe |
403 ... cannot publish over the previously published versions | Version đã có | Bump version mới bằng changeset |
Job fail ngay ở before_script | Thiếu NPM_TOKEN | Khai biến ở Settings → CI/CD → Variables |
Debug an toàn trong CI (không lộ token)
yaml
- 'echo "NPM_TOKEN length: ${#NPM_TOKEN}"' # 0 = chưa inject
- 'npm whoami --registry=https://registry.npmjs.org/'