blog.dopana

Quay lại

Bạn đã bao giờ tự hỏi tại sao một số dự án có file .npmrc ở thư mục gốc? Hoặc làm thế nào để cấu hình private registry cho công ty của bạn? File .npmrc là chìa khóa để kiểm soát cách các package manager như npm, pnpm, yarn và Bun hoạt động.

Trong bài viết này, chúng ta sẽ khám phá .npmrc hoạt động như thế nào, đặc biệt khi sử dụng Bun - một package manager mới siêu nhanh.

Tại sao .npmrc quan trọng?#

Hãy tưởng tượng bạn đang làm việc trong một dự án sử dụng các package private từ công ty. Nếu mỗi lần chạy npm install hoặc bun install đều phải nhập username và password, đó sẽ rất phiền phức. .npmrc giải quyết vấn đề này bằng cách lưu trữ cấu hình một cách trung tâm.

[!NOTE] .npmrc hoạt động như một file cấu hình cho package manager của bạn, tương tự như .env cho biến môi trường nhưng chuyên dụng cho npm/Bun.

.npmrc là gì?#

.npmrc là file cấu hình dạng key-value dùng để thiết lập các tùy chọn cho package manager (npm, pnpm, yarn, Bun). Nó có thể chứa:

  • URL của registry (để tải package từ đâu)
  • Token xác thực (để truy cập private registry)
  • Các cài đặt cài đặt như save-exact, engine-strict, v.v.

Thứ tự ưu tiên của .npmrc#

Package manager tìm kiếm .npmrc ở nhiều nơi với thứ tự ưu tiên từ thấp đến cao:

Default npmGlobal/etc/npmrcUser~/.npmrcProject./.npmrcCLI/EnvironmentNPM_CONFIG_REGISTRY

Điều này có nghĩa là:

  • Default: Cài đặt mặc định của npm
  • Global: File toàn hệ thống (thường ở /etc/npmrc)
  • User: File cá nhân ở home directory (~/.npmrc)
  • Project: File trong thư mục gốc dự án (./.npmrc) - nơi bạn nên cấu hình cho dự án
  • CLI/Environment: Flag command-line hoặc biến môi trường (ưu tiên cao nhất)

[!TIP] Nếu cùng một cấu hình xuất hiện ở nhiều nơi, cấu hình có ưu tiên cao hơn sẽ ghi đè cấu hình có ưu tiên thấp hơn.

Bun xử lý .npmrc như thế nào?#

Một trong những điểm mạnh của Bun là nó tương thích hoàn toàn với .npmrc tiêu chuẩn. Bạn có thể thay thế npm bằng Bun trong dự án Node.js hiện có mà không cần thay đổi cấu hình registry hay xác thực.

Các cài đặt được Bun hỗ trợ#

Bun hỗ trợ các directive .npmrc phổ biến:

  • Registry URLs: Cấu hình registry mặc định và scoped registry
  • Scoped registries: Gán riêng registry cho một scope cụ thể (ví dụ: @mycompany)
  • Authentication tokens: _authToken, _auth, username, _password, email
  • Project options: save-exact=true, link-workspace-packages

Bunfig.toml - Tùy chọn riêng của Bun#

Bun cũng có file cấu hình riêng gọi là bunfig.toml, nhưng nó vẫn tiếp tục tôn trọng .npmrc để đảm bảo tương thích giữa các công cụ khác nhau.

[!WARNING] Nếu bạn dùng cả .npmrc và bunfig.toml, hãy chắc chắn rằng chúng không cấu hình cùng một thứ theo cách mâu thuẫn.

Ví dụ thực tế#

Cấu hình cơ bản#

.npmrc
# Sử dụng registry mặc định
registry=https://registry.npmjs.org

# Luôn lưu phiên bản chính xác (không dùng ^ hoặc ~)
save-exact=true
ini

Cấu hình với private registry#

.npmrc
# Cấu hình registry cho scope của công ty
@mycompany:registry=https://npm.mycompany.com

# Token xác thực cho registry công ty
//npm.mycompany.com:_authToken=${NPM_TOKEN}

# Registry mặc định cho các package khác
registry=https://registry.npmjs.org
ini

Cấu hình cho GitHub Packages#

.npmrc
# GitHub Packages registry
@your-org:registry=https://npm.pkg.github.com

# Token GitHub cho xác thực
//npm.pkg.github.com:_authToken=${GITHUB_TOKEN}
ini

Cấu hình cho GitLab Package Registry#

.npmrc
# GitLab Package Registry
@your-group:registry=https://gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/

# Token GitLab
//gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/:_authToken=${GITLAB_TOKEN}
ini

Cách sử dụng với Bun#

Khi bạn có file .npmrc trong dự án, Bun sẽ tự động đọc nó khi chạy bun install:

# Bun sẽ đọc .npmrc và áp dụng cấu hình
bun install

# Xem cấu hình hiện tại của Bun
bun pm config
bash

Tại sao nên dùng save-exact=true?#

Khi save-exact=true được bật, package manager sẽ lưu phiên bản chính xác trong package.json thay vì dùng range (như ^1.2.3 hoặc ~1.2.3).

Ưu điểm:

  • Đảm bảo mọi người trong team cài đặt cùng phiên bản
  • Tránh lỗi khi một package cập nhật không tương thích
  • Dự đoán được chính xác dependencies trong production

Nhược điểm:

  • Phải tự cập nhật dependencies thủ động
  • Không tự động nhận được bản vá lỗi (patch updates)

Cấu hình trong CI/CD#

Trong môi trường CI/CD, bạn thường dùng biến môi trường thay vì lưu token trong file:

.github/workflows/ci.yml
env:
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
yaml
.npmrc
# Token sẽ được thay thế từ biến môi trường
//npm.mycompany.com:_authToken=${NPM_TOKEN}
ini

Xem cấu hình đang được sử dụng#

Để xem file .npmrc nào đang được sử dụng:

# Với npm
npm config list

# Với Bun
bun pm config
bash

Lời khuyên thực tế#

  1. Luôn sử dụng project-level .npmrc cho cấu hình cụ thể của dự án
  2. Không commit token vào git - dùng biến môi trường thay thế
  3. Dùng scoped registry cho private packages của công ty
  4. Kiểm tra cấu hình khi gặp lỗi authentication
  5. Đọc tài liệu của private registry của bạn (GitHub, GitLab, Azure Artifacts)

Kết luận#

.npmrc là một công cụ quan trọng để quản lý cách package manager hoạt động trong dự án của bạn. Với sự hỗ trợ của Bun, bạn có thể tiếp tục sử dụng file này mà không cần thay đổi cấu hình khi chuyển từ npm sang Bun.

Hiểu rõ thứ tự ưu tiên và cách cấu hình sẽ giúp bạn tránh nhiều vấn đề về authentication và dependency management trong tương lai.

References#