Skip to content

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=true

App 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 publish

Biến CI/CD ​

BiếnGiá trịCờ
NPM_TOKENGranular 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 unpublish bị giới hạn sau 72 giờ và số version không dùng lại được. Mọi bản latest phải đi qua beta trướ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ặp 402 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_TOKEN không dùng được cho npmjs, chỉ dùng token riêng ở trên.

Troubleshooting nhanh ​

Triệu chứngNguyên nhân thường gặpCách xử lý
401/403 khi publishToken sai scope, hết hạn, hoặc không có quyền ghi vào @tasco-feTạo lại token granular với quyền Read and write cho scope
402 Payment RequiredPackage đang restricted trên org FreeĐặt access: public (cả publishConfig và .changeset/config.json)
404 Not Found khi publishOrg tasco-fe không tồn tại hoặc tài khoản tạo token không là thành viênKiểm tra bằng npm org ls tasco-fe
403 ... cannot publish over the previously published versionsVersion đã cóBump version mới bằng changeset
Job fail ngay ở before_scriptThiếu NPM_TOKENKhai 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/'