Commitlint

Commitlint enforces consistent, meaningful, and machine-readable commit messages by validating them against the Conventional Commits specification. In ServerCN projects, this improves:

Git history readability
Automated changelog generation
Semantic versioning workflows
CI/CD reliability
Team collaboration and code reviews

This component is designed for TypeScript + Express.js backends but works for any Node.js project.

Official Documentation

Installation

Install Commitlint using the ServerCN CLI:

npx servercn-cli add tooling commitlint

This command automatically:

Installs required Commitlint dependencies
Creates a strongly-typed configuration file
Prepares the project for Git hook integration

What Gets Installed

The component installs the following packages:

@commitlint/cli – The Commitlint command-line interface
@commitlint/config-conventional – Standard Conventional Commit rules

It also generates a configuration file:

commitlint.config.ts – Centralized rule definition

Commitlint Configuration

Below is the default configuration provided by ServerCN, with inline explanations for clarity.

commitlint.config.ts

export default {
  /**
   * Extends the official Conventional Commits rule set.
   * https://www.conventionalcommits.org/
   */
  extends: ["@commitlint/config-conventional"],
 
  rules: {
    /**
     * Restricts commit types to a predefined list.
     * This keeps commit history consistent and predictable.
     */
    "type-enum": [
      2, // Severity: 2 = error (commit will be rejected)
      "always",
      [
        "feat",      // New features
        "fix",       // Bug fixes
        "docs",      // Documentation changes only
        "style",     // Formatting, missing semicolons, etc (no logic change)
        "refactor",  // Code restructuring without behavior change
        "test",      // Adding or updating tests
        "chore",     // Tooling, config, or maintenance tasks
        "ci",        // CI/CD configuration changes
        "perf",      // Performance improvements
        "build",     // Build system or dependency changes
        "release",   // Release-related commits
        "workflow",  // GitHub Actions or workflow changes
        "security"   // Security patches and fixes
      ]
    ],
 
    /**
     * Allows longer commit bodies for detailed explanations.
     * Set to warning (0) instead of error to stay flexible.
     */
    "body-max-length": [0, "always", 500],
 
    /**
     * Prevents excessively long commit headers.
     * Helps keep logs readable in GitHub, GitLab, and CI tools.
     */
    "header-max-length": [0, "always", 200]
  }
};

Conventional Commit Format

All commit messages must follow this structure:

type(scope): subject
 
body
 
footer

Breakdown

type – Nature of the change (required)
scope – Affected module or area (optional)
subject – Short, imperative description (required)
body – Detailed explanation (optional)
footer – Breaking changes or issue references (optional)

Example

feat(auth): add refresh token rotation
 
Implements rotating refresh tokens to improve session security.
 
BREAKING CHANGE: old refresh tokens are now invalidated on use

Common Commit Types

feat: Introduces a new feature
fix: Fixes a bug
docs: Documentation-only changes
style: Formatting changes (no logic impact)
refactor: Code restructuring
test: Adding or updating tests
chore: Maintenance or tooling tasks
ci: CI/CD configuration
perf: Performance improvements
build: Build system or dependency changes
release: Release preparation or versioning
workflow: GitHub Actions or workflow changes
security: Security-related fixes

Husky Integration

Commitlint is most effective when enforced via Git hooks. ServerCN is designed to work seamlessly with Husky.

npx servercn-cli add tooling husky

This ensures:

Invalid commit messages are rejected immediately
Team-wide standards are enforced automatically
No invalid commits reach the repository

Best Practices

Keep the subject line under 72 characters when possible
Use the imperative mood ("add", not "added")
Always use a scope for backend modules (e.g. auth, user, db)
Use BREAKING CHANGE: in the footer for API-breaking updates

Summary

The ServerCN Commitlint component provides:

Strong commit discipline
Clear, extensible rules
Type-safe configuration
CI/CD-friendly enforcement

This makes it suitable for production-grade backend systems and team-based development.

Add More Tooling

npx servercn-cli add tooling commitlint husky eslint prettier lint-staged typescript