Hướng dẫn publish create-template lên npm

Tài liệu này mô tả các bước chuẩn để đóng gói và phát hành CLI create-template lên npm Registry.

1. Chuẩn bị

1. Node & npm: đảm bảo đang dùng Node 18+ và npm 8+.
2. Quyền publish: tài khoản npm phải có quyền publish tới namespace/organization mong muốn.
3. Clean workspace: commit hoặc stash thay đổi trước khi build.

2. Kiểm tra và build

# Đứng ở root repo
cd /Users/quocvan/Documents/NamPhuongSo/Website-Template

# Cài đặt dependencies toàn repo
npm install

# Build CLI TypeScript -> dist/
npm run build

# Build & lint template web để đảm bảo không lỗi
npm run template:lint
npm run template:build

Sau khi build, thư mục cli/create-template/dist phải tồn tại với file index.js có shebang (#!/usr/bin/env node).

3. Cập nhật version

• Increment version trong cli/create-template/package.json theo chuẩn semver.
• Chạy lệnh tại root repo để npm workspace cập nhật đúng package:

cd /Users/quocvan/Documents/NamPhuongSo/Website-Template
npm version <major|minor|patch> --workspace @namphuongtechnologi/create-template

• Đồng thời cập nhật tag version trong package-lock.json (hoặc xoá lock file và chạy npm install).
• Commit thay đổi trước khi publish.

4. Đóng gói thử (tùy chọn)

# Đứng ở root repo
cd /Users/quocvan/Documents/NamPhuongSo/Website-Template

npm run pack
# Kết quả: file .tgz trong thư mục hiện tại

Có thể cài đặt gói .tgz này vào dự án khác để smoke test CLI:

npm install -g ./<ten-file>.tgz
create-template --help

5. Publish lên npm

# Đứng ở root repo
cd /Users/quocvan/Documents/NamPhuongSo/Website-Template

# Đăng nhập npm (nếu chưa)
npm login

# Publish với access public (workspace command, chạy tại root)
npm publish --workspace @namphuongtechnologi/create-template --access public

Nếu publish thất bại do tên gói đã tồn tại, cần tăng version hoặc đổi tên package.

Tùy chọn khác (publish trực tiếp trong package folder)

Nếu không muốn dùng workspace command, có thể đứng trong thư mục package rồi publish trực tiếp:

cd /Users/quocvan/Documents/NamPhuongSo/Website-Template/cli/create-template
npm publish --access public

6. Kiểm tra sau publish

• Truy cập https://www.npmjs.com/package/create-template (hoặc namespace tương ứng) để xác nhận version mới.
• Chạy npx create-template@latest --help để đảm bảo npm registry phân phối đúng binary.

7. Cập nhật tài liệu

• Ghi chú version mới trong repo (ví dụ changelog, README).
• Thông báo cho team về version vừa phát hành và các thay đổi quan trọng.

Tip: Nếu publish thất bại với lỗi 403 hoặc 404, kiểm tra quyền trên npm organization và đảm bảo package name trong package.json khớp với namespace được cấp quyền.