Hãy tưởng tượng bạn là một bếp trưởng. Để đảm bảo tất cả các nhà hàng trong chuỗi của bạn đều chế biến được những món ăn thơm ngon như nhau, bạn đã phát triển một loạt các “nước xốt bí mật”. Bạn muốn những loại nước xốt này được gửi đến từng chi nhánh, nhưng bạn không thể để những người qua đường tùy ý lấy chúng đi.

Trong thế giới phát triển phần mềm, những loại nước xốt bí mật này chính là các “gói riêng tư” (private packages) trong nội bộ công ty.

Khi các dự án tăng lên, chắc hẳn bạn đã từng gặp phải sự bực bội này: sao chép và dán cùng một thành phần UI hoặc hàm tiện ích (utility function) vào mọi dự án, hoặc vật lộn với Git Submodule cho đến khi bạn phải đặt câu hỏi về những lựa chọn trong cuộc sống của mình. Trên thực tế, tất cả những gì bạn cần là một “Kho thực phẩm riêng tử (Private NPM Registry)”. Hôm nay, chúng ta sẽ thảo luận về cách sử dụng pnpm để xuất bản các gói lên GitLab, để các thành viên trong nhóm có thể cài đặt chúng giống như các gói mã nguồn mở chỉ với một dòng lệnh duy nhất.

Tại sao bạn cần các gói riêng tư và Scope?

Trong vũ trụ Node.js, các gói riêng tư phải có một “họ”—đó chính là Scope.

Ví dụ: nếu công ty của bạn tên là @my-company, tên gói của bạn có thể trông như thế này: @my-company/ui-kit. Với cái họ này, khi pnpm nhìn thấy nó, nó sẽ không tìm kiếm một cách vô định trên npmjs.org. Thay vào đó, nó sẽ hướng thẳng đến các điểm điều phối công ty mà bạn đã xác định.

Quyết định then chốt: Group Level và Project Level

Trong GitLab, việc này giống như quyết định nơi cất giữ các loại gia vị của bạn:

Thiết lập “Hộ chiếu”: Access Token và các biến môi trường

Để vào kho lương thực dưới lòng đất, trước tiên bạn cần có một “thẻ truy cập”.

1. Truy cập vào Settings > Access Tokens của GitLab.
2. Đăng ký một Token, tích chọn các quyền read_api (để tải xuống) và write_package_registry (để xuất bản).
3. Quan trọng: Khi bạn đã có Token, đừng bao giờ mã hóa cứng (hardcode) nó trực tiếp vào mã hoặc tệp .npmrc của bạn! Điều đó giống như để chìa khóa két sắt ở ngay trên cửa.

Cách tiếp cận chuyên nghiệp nhất là ẩn nó trong các “biến môi trường”. Thêm dòng này vào terminal Mac hoặc Linux của bạn (ví dụ: ~/.zshrc):

export GITLAB_TOKEN="GitLab_Token_của_bạn"

Bằng cách này, hệ thống sẽ tự động đính kèm thông tin xác thực cho bạn, giúp việc này vừa an toàn vừa thuận tiện.

Cài đặt điều hướng: Bản chất của .npmrc

Tiếp theo, chúng ta sẽ tạo một bản đồ điều hướng, .npmrc, trong thư mục gốc của dự án để cho pnpm biết phải đi đâu:

# Đối với bất kỳ thứ gì bắt đầu bằng @my-company, hãy truy cập GitLab
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/

# Thiết lập xác thực thẻ truy cập (đọc biến môi trường chúng ta vừa thiết lập)
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"

Chỉ cần thay Group ID của công ty bạn vào, và con đường đã được trải sẵn!

Dặm cuối cùng trước khi xuất bản: Nghệ thuật đóng gói

Nhiều người vội vàng xuất bản sau khi thiết lập kết nối, để rồi vô tình tải lên các tệp thử nghiệm hoặc thậm chí là các cấu hình bí mật. Đây là lúc trường files trong package.json phát huy tác dụng.

Đây là khái niệm “allowlist” (danh sách trắng):

{
  "name": "@my-company/lib-1",
  "files": [
    "dist"
  ],
  "publishConfig": {
    "registry": "https://gitlab.com/api/v4/projects/<YOUR_PROJECT_ID>/packages/npm/"
  }
}

Trước khi xuất bản, bạn nên sử dụng lệnh pnpm pack để mở gói và kiểm tra nội dung cục bộ. Khi mọi thứ có vẻ ổn, hãy tự tin chạy pnpm publish!

Kết luận

Xây dựng một kho thực phẩm riêng tư không khó. Các yếu tố then chốt là:

1. Đăng ký một Token và bảo vệ nó bằng các biến môi trường.
2. Cấu hình bản đồ điều hướng .npmrc chính xác.
3. Sử dụng trường files trong package.json để vận chuyển chính xác.

Bằng cách thành thạo quy trình làm việc này, bạn có thể khiến việc tái sử dụng mã của công ty mình trở nên chuyên nghiệp, an toàn và tinh tế. Bây giờ, hãy đi xây dựng bếp trung tâm của riêng bạn thôi nào!

Reference

• package.json | npm Docs
• Package registry | GitLab Docs