Cách Cài Đặt Và Cấu Hình Commitlint Trong Dự Án Nuxt 3

Tuan Duc Tran

Khi làm việc trong nhóm hoặc với dự án lớn, việc tuân thủ một quy chuẩn commit là cực kỳ quan trọng. Nó giúp lịch sử commit trở nên rõ ràng, dễ đọc, và có thể tự động sinh changelog hoặc hỗ trợ CI/CD. Công cụ Commitlint chính là giải pháp để đảm bảo các commit luôn tuân thủ đúng format.

Bài viết này sẽ hướng dẫn bạn:

  1. Cài đặt @commitlint/cli và @commitlint/config-conventional
  2. Tạo file cấu hình commitlint.config.js
  3. Giải thích các rule đã tùy chỉnh
  4. Tích hợp vào Git hooks để commit được kiểm tra tự động.

1. Cài đặt Commitlint

Trước tiên, bạn cần cài đặt các gói cần thiết:

pnpm add -D @commitlint/cli @commitlint/config-conventional

2. Tạo file cấu hình commitlint.config.js

Trong thư mục gốc của dự án, tạo file commitlint.config.js với nội dung sau:

commitlint.config.js
/**
 * Commitlint configuration with custom rules for Nuxt 3 projects.
 * Supports conventional commits with optional leading emoji.
 */
 
const allowedTypes = [
  'feat',     // ✨ New features
  'fix',      // 🐛 Bug fixes
  'style',    // 🎨 UI/styling changes
  'refactor', // ♻️ Code refactoring
  'perf',     // ⚡ Performance improvements
  'test',     // 🧪 Tests
  'docs',     // 📝 Documentation
  'chore',    // 🔧 Build/tooling
  'deploy',   // 🚀 Deployment
  'enhance',  // 🌟 Enhancements
]
 
// Regex to match emoji (single or zero-width-joined)
const headerRegex = new RegExp(
  `^(\\p{Extended_Pictographic}(?:\\u200d\\p{Extended_Pictographic})* )?(${allowedTypes.join('|')}): .+$`,
  'u',
)
 
module.exports = {
  extends: ['@commitlint/config-conventional'],
 
  rules: {
    'subject-empty': [0],
    'type-empty': [0],
    'type-enum': [2, 'always', allowedTypes],
    'subject-min-length': [2, 'always', 1],
    'subject-max-length': [2, 'always', 100],
    'subject-case': [2, 'always', 'sentence-case'],
    'header-max-length': [2, 'always', 120],
    'header-pattern': [2, 'always', headerRegex],
  },
 
  plugins: [
    {
      rules: {
        'header-pattern': ({ header }) => {
          if (!headerRegex.test(header)) {
            return [
              false,
              `⛔ Commit message header must match format: [emoji] <type>: <description>
 
✅ Valid types: ${allowedTypes.join(', ')}
 
📌 Examples:
  feat: add GitHub activity heatmap component
  🎉 feat: add GitHub activity heatmap component
  🐛 fix: resolve scroll flicker issue
  🌟 enhance: improve mobile responsiveness
`,
            ]
          }
          return [true]
        },
      },
    },
  ],
}

3. Giải thích cấu hình

✅ Loại commit (allowedTypes)

  • feat: thêm tính năng mới ✨
  • fix: sửa lỗi 🐛
  • style: thay đổi giao diện 🎨
  • refactor: tái cấu trúc code ♻️
  • perf: cải thiện hiệu năng ⚡
  • test: viết hoặc cập nhật test 🧪
  • docs: cập nhật tài liệu 📝
  • chore: thay đổi build/tooling 🔧
  • deploy: triển khai 🚀
  • enhance: nâng cấp, tối ưu 🌟

✅ Cho phép emoji ở đầu

Regex headerRegex cho phép commit có dạng:

  • Không emoji: feat: add feature X
  • Có emoji: 🌟 enhance: improve UI

✅ Các rule chính

  • type-enum: chỉ chấp nhận các loại commit nằm trong allowedTypes.
  • subject-min-length / subject-max-length: mô tả phải ngắn gọn, từ 1 đến 100 ký tự.
  • header-max-length: toàn bộ header tối đa 120 ký tự.
  • subject-case: format mô tả theo kiểu sentence case (chữ cái đầu viết hoa, sau đó thường).
  • header-pattern: commit phải khớp regex, đảm bảo format [emoji] type: description.

4. Tích hợp Commitlint với Git Hooks

Để đảm bảo mọi commit đều được kiểm tra, bạn có thể tích hợp Commitlint với Husky.

Cài đặt Husky:

pnpm add -D husky

Khởi tạo Husky:

pnpm husky install

Thêm script vào package.json:

package.json
{
  "scripts": {
    "prepare": "husky install"
  }
}

Tạo hook commit-msg:

npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

Từ bây giờ, mỗi khi commit, Husky sẽ gọi Commitlint để kiểm tra commit message. Nếu không hợp lệ → commit bị từ chối.

5. Ví dụ commit hợp lệ

git commit -m "feat: add user authentication API"
git commit -m "🐛 fix: resolve token expiration issue"
git commit -m "🌟 enhance: improve mobile responsiveness"

Kết luận

Với cấu hình trên, bạn đã thiết lập Commitlint để:

  • Dùng chuẩn Conventional Commits
  • Hỗ trợ emoji mở đầu commit
  • Tùy chỉnh các loại commit phù hợp cho dự án Nuxt 3
  • Tích hợp với Husky để kiểm tra commit tự động.

Điều này giúp đảm bảo tính thống nhất, dễ đọc của lịch sử commit, đồng thời nâng cao chất lượng workflow của team.