pkg là công cụ dòng lệnh giúp biên dịch ứng dụng Node.js cùng các module phụ thuộc thành tệp binary độc lập, cho phép chạy trên máy đích mà không cần cài đặt sn Node.js. Dưới đây là 10 gợi ý để sử dụng pkg một cách hiệu quả.

1. Cài đặt toàn cục và kiểm tra phiên bản

npm install -g pkg
pkg --version

2. Sử dụng lệnh đóng gói tối thiểu

Trỏ trực tiếp đến file khởi chạy hoặc file package.json:

pkg src/main.js
# hoặc
pkg package.json

3. Chọn nền tảng đích rõ ràng

Tham số --targets cho phép tạo binary cho nhiều hệ điều hành trong một lần chạy:

pkg package.json --targets node20-win-x64,node20-linux-x64,node20-macos-arm64

4. Định nghĩa thư mục đầu ra

Sử dụng --out-path để giữ cấu trúc dự án gọn gàng:

pkg package.json --out-path bin

5. Đóng gói tài nguyên tĩnh

Khai báo các tài nguyên như template, ảnh hoặc file cấu hình trong package.json:

{
  "pkg": {
    "assets": [
      "resources/**/*",
      "templates/*.html",
      "locales/*.json"
    ]
  }
}

Khi chạy binary, nên truy xuất tài nguyên qua __dirname thay vì đường dẫn tương đối từ thư mục làm việc hiện tại.

6. Xử lý module được require động

Nếu ứng dụng load module theo điều kiện, hãy khai báo rõ các file đó để pkg nhận diện:

{
  "pkg": {
    "scripts": [
      "src/drivers/**/*.js",
      "src/plugins/**/*.js"
    ]
  }
}

7. Giảm thiểu kích thước binary

• Chọn phiên bản Node runtime phù hợp, tránh target thừa.
• Loại bỏ source map và log gỡ lỗi khi build sản phẩm.
• Nén ảnh, font và các tài nguyên tĩnh trước khi đưa vào assets.

8. Gỡ lỗi đóng gói với chế độ chi tiết

pkg --debug package.json

Log chi tiết sẽ giúp xác định file bị thiếu hoặc đường dẫn không hợp lệ trong quá trình đóng gói.

9. Tập trung cấu hình trong package.json

{
  "name": "invoice-cli",
  "version": "1.0.0",
  "bin": "src/main.js",
  "pkg": {
    "targets": [
      "node20-linux-x64",
      "node20-win-x64"
    ],
    "assets": [
      "resources/**/*"
    ],
    "scripts": [
      "src/extensions/**/*.js"
    ]
  }
}

Sau khi cấu hình, chỉ cần chạy pkg package.json là đủ.

10. Tự động hóa bằng npm scripts

{
  "scripts": {
    "build:win": "pkg package.json --targets node20-win-x64 --out-path bin",
    "build:linux": "pkg package.json --targets node20-linux-x64 --out-path bin",
    "build:all": "pkg package.json --targets node20-win-x64,node20-linux-x64,node20-macos-arm64 --out-path bin"
  }
}

Chạy npm run build:all để tạo binary cho các nền tảng cần thiết một cách thống nhất.